python/05_packaging.md

+## 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.
+```bash
+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
+# Upload your last revision to \texttt{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.
+```bash
+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 2
+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 from many places, like an existing git repository or an [http url](http://python-packaging.readthedocs.io/en/latest/dependencies.html).
+
+#### Package version
+
+Python package version is usually accessible at `package_name.__version__` 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. [Don’t
+import your package in setup.py](https://stackoverflow.com/q/11279096/395687)).
+To prevent that, package `__init__.py` file can be read and parsed manually
+to find the version.
+Package version can be obtained using :
+```bash
+python setup.py --version
+```
+
+### Exercise 3
+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/](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](home) | [Python Home](python/01_preamble) | [<< Python Previous - Local test](python/04_local_test) | [>> Python Next - Local test](python/06_local_test)
\ No newline at end of file