Distutils2 tutorial

Welcome to the Distutils2 tutorial ! We will learn here how to use Distutils2 to package your project.

Installing Distutils2

Quite simple, my dear reader:

$ pip install Distutils2

Or.. grab it at PyPI and run:

$ python setup.py install

Getting started

Distutils2 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 mkcfg script to create a setup.cfg file for the project. The script will ask you a few questions:

$ mkdir CLVault
$ cd CLVault
$ python -m distutils2.mkcfg
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:

$ more 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: install it

All commands are run using the run script:

$ python -m distutils2.run install
$ python -m distutils2.run sdist
$ python -m distutils2.run upload

If you want to push a source distribution of your project at PyPI, do:

$ python -m distutils2.run sdist register upload

Installing the project

People will have to manually run the distutils2 install command:

$ python -m distutils2.run install