mirror of https://github.com/python/cpython
113 lines
2.9 KiB
ReStructuredText
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
|