How to Build and Install Python Module using setuptools and Distutils

0)
Install python-setuptools
#sudo apt-get install python-setuptools

1)
http://docs.python.org/2/install/

The bulk of this document is about building and installing modules from standard source distributions.
Building and installing a module distribution using the Distutils is usually one simple command to run from a terminal.
#python setup.py install

2)
Running "python setup.py install" builds and installs all modules in one step.
You can also build everything in one step, and then install everything in a second step, by invoking the setup script twice:
#python setup.py build
#python setup.py install

3)
How building works
-------------------
The "build" command is responsible for putting the files to install into a build directory.
By default, this is "build" under the distribution root.

The default layout for the build tree is as follows:

--- build/ --- lib/
or
--- build/ --- lib./
               temp./

4)
How installation works
-----------------------
The work of the install command is relatively simple: all it has to do is copy everything under "build/lib" (or build/lib.plat) to your chosen installation directory.
If you don’t choose an installation directory—i.e., if you just run "python setup.py install" then the install command installs to the standard location for third-party Python modules. This location varies by platform and by how you built/installed Python itself

5)
Alternate installation: the user scheme
----------------------------------------
This scheme is designed to be the most convenient solution for users that don’t have write permission to the global site-packages directory or don’t want to install into it. It is enabled with a simple option:

#python setup.py install --user

Files will be installed into subdirectories of "site.USER_BASE" (Default value is ~/.local for UNIX).
This scheme installs pure Python modules and extension modules in the same location

http://docs.python.org/2/library/site.html#site.USER_BASE

6)
Custom Installation
--------------------
To create a custom installation scheme, you start with one of the alternate schemes and override some of the installation directories used for the various types of files.
Specifying the entire installation scheme every time you install a new module distribution would be very tedious. Thus, you can put these options into your Distutils config file

7)
Distutils Configuration Files
------------------------------
You can use Distutils configuration files to record personal or site preferences for any Distutils options. That is, any option to any command can be stored in one of two or three (depending on your platform) configuration files, which will be consulted before the command-line is parsed. This means that configuration files will override default values, and the command-line will in turn override configuration files. Furthermore, if multiple configuration files apply, values from “earlier” files are overridden by “later” files.

8)
Location and names of config files
-----------------------------------
Type of file : Location and filename
system : prefix/lib/pythonver/distutils/distutils.cfg
personal : $HOME/.pydistutils.cfg
local : setup.cfg <====

9)
Syntax of config files
-----------------------
The Distutils configuration files all have the same syntax. The config files are grouped into sections. There is one section for each 'Distutils command', plus a "global" section for global options that affect every command. Each section consists of one option per line, specified as "option=value".
And if it is used as the "setup.cfg" for a particular module distribution, it affects only that distribution.

10)
Writing the Setup Configuration File
-------------------------------------
http://docs.python.org/2/distutils/configfile.html

a)
Configuration files also let you provide default values for any command option, which the installer can then override either on the command-line or by editing the config file.

 In fact, "setup.cfg" are processed after the contents of the setup script, but before the command-line. This has several useful consequences:

* installers can override some of what you put in setup.py by editing setup.cfg
* you can provide non-standard defaults for options that are not easily set in setup.py
* installers can override anything in setup.cfg using the command-line options to setup.py

b)
The basic syntax of the configuration file is simple:

[command]
option=value
...

where command is one of the Distutils commands (e.g. build_py, install), and option is one of the options that command supports. Any number of options can be supplied for each command, and any number of command sections can be included in the file.

You can find out the list of options supported by a particular command with the universal --help option, e.g.
#python setup.py --help build_ext

11)
Tips for Configuration File
----------------------------
a)
Some configuration file sections
Some "python setup.py" commands
* metadata
* global
* files
* build_sphinx
* nosetests

b)
* Run "python setup.py --help-commands" to see all commands.
* Run "python setup.py cmd --help" to see all options of a command.
Example:
#python setup.py build_sphinx --help
#python setup.py nosetests --help

c)
https://github.com/openstack/nova/blob/master/setup.cfg
https://github.com/openstack/nova/blob/master/setup.py

https://github.com/openstack/horizon/blob/master/setup.cfg
https://github.com/openstack/horizon/blob/master/setup.py

https://github.com/openstack/cinder/blob/master/setup.cfg
https://github.com/openstack/cinder/blob/master/setup.py

https://github.com/openstack/glance/blob/master/setup.cfg
https://github.com/openstack/glance/blob/master/setup.py

https://github.com/openstack/swift/blob/master/setup.cfg
https://github.com/openstack/swift/blob/master/setup.py

12)
Getting Started With setuptools and setup.py
---------------------------------------------
a)
https://pythonhosted.org/an_example_pypi_project/setuptools.html
http://pythonhosted.org/setuptools/setuptools.html

b)
Example setup.py
import setuptools
setuptools.setup(setup_requires=['pbr'], pbr=True)

http://docs.openstack.org/developer/pbr/

pbr is a library for managing setuptools packaging needs in a consistent manner.pbr reads and then filters the setup.cfg data through a setup hook to fill in default values and provide more sensible behaviors, and then feeds the results in as the arguments to a call to setup.py - so the heavy lifting of handling python packaging needs is still being done by setuptools.

13)
manifest template, called MANIFEST.in
-----------------------------------------------------
http://docs.python.org/2/distutils/sourcedist.html

a)
The manifest template is just a list of instructions for how to generate your manifest file, MANIFEST, which is the exact list of files to include in your source distribution. The sdist command processes this template and generates a manifest based on its instructions and what it finds in the filesystem.

b)
MANIFEST.in tells Distutils what files to include in the source distribution but it does not directly affect what files are installed. For that you need to include the appropriate files in the setup.py file, generally either as package data or as additional files.