Simple mode

With a very simple tool that have only 1 python script file, the .py script file can be placed under the root folder.

└── tool-name
    ├── tool-name.py
    ├── LICENCE
    ├── README.md
    └── setup.py

Lib mode

But with a more complex tool with several python script files, .py script files must be place under a "lib" folder.

└── tool-name
    ├── tool-name
    │   ├── __init__.py
    │   ├── script.py
    │   └── main.py
    ├── LICENCE
    ├── README.md
    └── setup.py

And of course a __init__.py will be needed.

Description

• The distutils setup script is a python script!
• Keep it simple to avoid bug happening, exoticism is not needed.
• It describes project's metadatas

First line

First line of distutils setup script will always be the same:

from distutils.core import setup

This will import setup() function that will take some parameters.

Minimal parameters

Only 3 field are required:

• name: must be unique to publish on PyPI
• version: keeps track of different releases
• url: the home page address of the project (ex: github, bitbucket, website, PyPI page, ...)

More basic parameters (1/3)

• description: one-line summary of the project
• long_description: multi-line string in reStructuredText (PyPI will converts it to HTML and displays it on the package page)
• author: author name
• author_email: author email

More basic parameters (2/3)

• maintainer: maintainer name
• maintainer_email: maintainer email
• license: license name
• keywords: keywords
• classifiers: list of PyPI categories (more details in the next slides)

More basic parameters (3/3)

An a vey important field in order to differentiate the source code and all the others things around like documentation:

• py_modules or packages: describes where python source code is
  • py_modules: for an unique file python script
  • packages: for a multi-file python script

Additional meta-data can be found in the Python Doc.

There is also a PEP 314 describing a mechanism for adding metadata to Python packages.

Classifying the package

PyPI (formerly Python Package Index) contains thousands of Python libraries and tools. So a proper classification of metada will allow people to easily find the package.

To classify the package, use the classifiers parameter of the setup() function. This contains a list of strings.

All classifier strings must match with PyPi classifiers list.

Setup script example

from distutils.core import setup
setup(
    name = "chardet",
    packages = ["chardet"],
    version = "1.0.2",
    description = "Universal encoding detector",
    author = "Mark Pilgrim",
    author_email = "mark@diveintomark.org",
    url = "http://chardet.feedparser.org/",
    download_url = "http://chardet.feedparser.org/download/python3-chardet-1.0.1.tgz",
    keywords = ["encoding", "i18n", "xml"],
    classifiers = [
        "Programming Language :: Python",
        "Programming Language :: Python :: 3",
        "Development Status :: 4 - Beta",
        "Environment :: Other Environment",
        "Intended Audience :: Developers",
        "License :: OSI Approved :: GNU Library or Lesser General Public License (LGPL)",
        "Operating System :: OS Independent",
        "Topic :: Software Development :: Libraries :: Python Modules",
        "Topic :: Text Processing :: Linguistic",
        ],
    long_description = """\
Universal character encoding detector
-------------------------------------

Detects
 - ASCII, UTF-8, UTF-16 (2 variants), UTF-32 (4 variants)
 - Big5, GB2312, EUC-TW, HZ-GB-2312, ISO-2022-CN (Traditional and Simplified Chinese)
 - EUC-JP, SHIFT_JIS, ISO-2022-JP (Japanese)
 - EUC-KR, ISO-2022-KR (Korean)
 - KOI8-R, MacCyrillic, IBM855, IBM866, ISO-8859-5, windows-1251 (Cyrillic)
 - ISO-8859-2, windows-1250 (Hungarian)
 - ISO-8859-5, windows-1251 (Bulgarian)
 - windows-1252 (English)
 - ISO-8859-7, windows-1253 (Greek)
 - ISO-8859-8, windows-1255 (Visual and Logical Hebrew)
 - TIS-620 (Thai)

This version requires Python 3 or later; a Python 2 version is available separately.
"""
)

Specifying additional files with a Manifest (1/2)

By default, Distutils will only include the following files in the release package:

• README.txt
• setup.py
• files listed in packages or py_modules parameters

So to include a LICENCE file, a NOTICE file, use a different file extension like a README.md or docs/ documentation folder, a Manifest file will be needed.

Specifying additional files with a Manifest (2/2)

The Manifest file is called MANIFEST.in, placed in the project's root directory. This is not a python script. It allows to include or exclude files and directories.

include README.md
recursive-include docs *.html *.css

It maintains the directory structure.

Manifest format and commands.

Creating dumb built distributions (1/2)

Python docs

RPM packages

python setup.py bdist_rpm

or

python setup.py bdist --formats=rpm

Creating dumb built distributions (2/2)

Windows Installers

python setup.py bdist_wininst

or

python setup.py bdist --formats=wininst

PyPI

PyPI is the Python Package Index

• Easy distribution
• Doesn't need cloning and manual building

pip install something

Create a .pypirc configuration file (1/2)

To make life easier when uploading packages, create a ~/.pypirc file:

[distutils]
index-servers =
  pypi
  pypitest

[pypi]
repository=https://pypi.python.org/pypi
username=your_username
password=your_password

[pypitest]
repository=https://testpypi.python.org/pypi
username=your_username
password=your_password

Create a .pypirc configuration file (2/2)

Passwords can be omitted in ~/.pypirc and written when uploading.

Warning: in Python 3 % must be escaped in password by doubling them. Info: Spaces don't need to be escaped, there must be not quote.

Create an account

Register on the PyPI Live or Test user registration page.

Register the project and upload the distribution

Register the package project:

python setup.py register -r pypi

Upload the package distribution:

python setup.py sdist upload -r pypi

To make sure the package is set up correctly, package can be upload on PyPI's test server first:

python setup.py register -r pypitest
python setup.py sdist upload -r pypitest