Doc/packaging/tutorial.rst

==================
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