cpython/Doc/packaging/tutorial.rst

113 lines
2.9 KiB
ReStructuredText

==================
Packaging tutorial
==================
Welcome to the Packaging tutorial! We will learn how to use Packaging
to package your project.
.. TODO merge with introduction.rst
Getting started
---------------
Packaging works with the *setup.cfg* file. It contains all the metadata for
your project, as defined in PEP 345, but also declare what your project
contains.
Let's say you have a project called *CLVault* containing one package called
*clvault*, and a few scripts inside. You can use the *pysetup* script to create
a *setup.cfg* file for the project. The script will ask you a few questions::
$ mkdir CLVault
$ cd CLVault
$ pysetup create
Project name [CLVault]:
Current version number: 0.1
Package description:
>Command-line utility to store and retrieve passwords
Author name: Tarek Ziade
Author e-mail address: tarek@ziade.org
Project Home Page: http://bitbucket.org/tarek/clvault
Do you want to add a package ? (y/n): y
Package name: clvault
Do you want to add a package ? (y/n): n
Do you want to set Trove classifiers? (y/n): y
Please select the project status:
1 - Planning
2 - Pre-Alpha
3 - Alpha
4 - Beta
5 - Production/Stable
6 - Mature
7 - Inactive
Status: 3
What license do you use: GPL
Matching licenses:
1) License :: OSI Approved :: GNU General Public License (GPL)
2) License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)
Type the number of the license you wish to use or ? to try again:: 1
Do you want to set other trove identifiers (y/n) [n]: n
Wrote "setup.cfg".
A setup.cfg file is created, containing the metadata of your project and the
list of the packages it contains::
$ cat setup.cfg
[metadata]
name = CLVault
version = 0.1
author = Tarek Ziade
author_email = tarek@ziade.org
description = Command-line utility to store and retrieve passwords
home_page = http://bitbucket.org/tarek/clvault
classifier = Development Status :: 3 - Alpha
License :: OSI Approved :: GNU General Public License (GPL)
[files]
packages = clvault
Our project will depend on the *keyring* project. Let's add it in the
[metadata] section::
[metadata]
...
requires_dist =
keyring
Running commands
----------------
You can run useful commands on your project once the setup.cfg file is ready:
- sdist: creates a source distribution
- register: register your project to PyPI
- upload: upload the distribution to PyPI
- install_dist: install it
All commands are run using the run script::
$ pysetup run install_dist
$ pysetup run sdist
$ pysetup run upload
If you want to push a source distribution of your project to PyPI, do::
$ pysetup run sdist register upload
Installing the project
----------------------
The project can be installed by manually running the packaging install command::
$ pysetup run install_dist