05_packaging

Packaging your code

The first step of an integration process is being able to install the project with its dependencies. In Python it is done using a setup.py script written with setuptools. The script simply calls setuptools.setup function with the package description: package directory, name, description, author, license, version, dependencies, supported Python versions, . . .

Usage

This setup.py script is the entry point for installing and releasing your code. It will also be used later as an entry point for tests scripts.

python setup.py <command> [opts]
# Install the package
python setup.py install
# Install the package in a way that lets you edit the sources
python setup.py develop
# Build the package in a *build* directory
python setup.py build
# Upload your last revision to *PyPi* repository
python setup.py upload

Setuptools Documentation

https://setuptools.readthedocs.io/en/latest/

Writing the setup.py script

Writing the script is basically just giving the right information in the right format. Usually adapting an existing one is simple enough so it is provided in this exercise. Copy the first script from the raw folder as setup.py.

cp raw/first setup.py
cat setup.py
#! /usr/bin/env python
# -*- coding:utf-8 -*5
import os
from setuptools import setup, find_packages
...

Exercise

1. Open the setup.py script and look at the setup function arguments.

Package dependency

Instead of writing in a README file explaining which packages are required by your project, those packages can be automatically installed with setuptools. Dependencies should be listed using install_requires parameter. In the example below, argparse dependency will be installed with the package.

setup(
    ...,
    install_requires=['argparse'],
)

Depending on your needs, you can specify the version with ==, <, !=, ... operators.

Note

By default setuptools uses PyPi to find packages but can be configured to install third parties from many places, like an existing git repository or an http url.

Package version

Python package version is usually accessible at package_name.__version__. It should be consistent with the version in setup.py. Importing the package in setup.py script is a source of import and code coverage errors (cf. Do not import your package in setup.py). To prevent that, package __init__.py file can be read and parsed manually to find the version. Package version can be obtained using :

python setup.py --version

Exercise

1. Find where the version is stored and how it is retrieved in the setup.py script.

Semantic versioning

Versioning should help users follow features addition and know when incompatible changes have been introduced. Semantic Versioning gives you simple rules for changing your version numbers.

From http://semver.org/ summary : Given a version number MAJOR.MINOR.PATCH, increment the :

1. MAJOR version when you make incompatible API changes,
2. MINOR version when you add functionality in a backwards-compatible manner, and
3. PATCH version when you make backwards-compatible bug fixes. Additional labels for pre-release and build meta-data are available as extensions to the MAJOR.MINOR.PATCH format. Later on, remember to increment the version when you change the API. However, as the code is still in alpha so you should increment MINOR instead of MAJOR.

Home | Python Home | << Python Previous - Volume method definition | >> Python Next - Local test