Using and creating Python packages
http://ianbicking.org/docs/setuptools-presentation
Ian Bicking http://blog.ianbicking.org
$ sudo python setup.py install
Global installation; for local installation (or if you don't have root):
$ python setup.py --install-lib=./app-packages
Make sure you update $PYTHONPATH! Other --install-* options control location of scripts, headers, etc.
Normal installation
$ easy_install.py Package $ easy_install.py http://sample.host/Package-X.Y.tar.gz $ easy_install.py http://svn.sample.host/Package/trunk
Development installation
$ easy_install.py --editable --build <DIR> Package $ # or just download and unpack the package $ cd <DIR>/Package $ sudo python setup.py develop
Isolated (version-specific) installation
$ easy_install.py -m Package==X.Y $ python >>> import pkg_resources >>> require('Package==X.Y')
$ easy_install.py kid Searching for kid Reading http://www.python.org/pypi/kid/ Reading http://lesscode.org/projects/kid/ Best match: kid 0.6.3 Downloading http://lesscode.org/dist/kid/kid-0.6.3.tar.gz Running kid-0.6.3/setup.py -q bdist_egg --dist-dir /tmp/easy_install-gsePfU/kid-0.6.3/egg-dist-tmp-WojETA zip_safe flag not set; analyzing archive contents... kid.importer: module references __file__ kid.test.__init__: module references __file__ Adding kid 0.6.3 to easy-install.pth file Installing kid script to /usr/bin Installing kidc script to /usr/bin Installed /usr/lib/python2.4/site-packages/kid-0.6.3-py2.4.egg Processing dependencies for kid
$ easy_install.py --editable \ --build-directory ~/co \ --find-links=http://pythonpaste.org/package_index.html \ Paste Reading http://pythonpaste.org/package_index.html Searching for Paste Best match: Paste [unknown version] Downloading http://svn.pythonpaste.org/Paste/trunk#egg=Paste Doing subversion checkout from http://svn.pythonpaste.org/Paste/trunk to /tmp/easy_install-d75rz8/trunk Processing trunk Extracted editable version of Paste to /home/ianb/co/paste If it uses setuptools in its setup script, you can activate it in "development" mode by going to that directory and running:: /usr/bin/python2.4 setup.py --develop See the setuptools documentation for the "develop" command for more info.
Things to note:
$ cd ~/co/paste $ sudo python setup.py develop running develop running egg_info writing requirements to ./Paste.egg-info/requires.txt writing ./Paste.egg-info/PKG-INFO writing top-level names to ./Paste.egg-info/top_level.txt running build_ext Creating /usr/lib/python2.3/site-packages/Paste.egg-link (link to .) Adding Paste 0.0 to easy-install.pth file Installing paster script to /usr/bin Installed /home/ianb/co/paste
More things to note:
Use "multi-version":
$ sudo python setup.py easy_install --multi-version
From a repository:
$ svn co http://svn.saddi.com/flup/trunk flup $ cd flup $ # fix setup.py to use setuptools $ sudo python setup.py egg_info --tag-svn-revision \ develop -m ..... Because this distribution was installed --multi-version or --install-dir, before you can import modules from this package in an application, you will need to 'import pkg_resources' and then use a 'require()' call similar to one of these examples, in order to select the desired version: pkg_resources.require("flup") # latest installed version pkg_resources.require("flup==0.5-r1802") # this exact version pkg_resources.require("flup>=0.5-r1802") # this version or higher
Distutils features:
Setuptools' extra features:
Setuptools' extra features:
Nevermind features...
Lay your files out like this:
MyPackage/ setup.py ez_setup.py mypackage/ __init__.py other_stuff.py data/ mydata.xml tests/ docs/
A typical setup.py:
from ez_setup import use_setuptools use_setuptools() from setuptools import setup, find_packages setup(name="MyPackage", version="0.1dev", description="My Package, now featuring 10% more packaging!", long_description="""\ This is a boxy package... """, author="Ian Bicking", author_email="ianb@colorstudy.com", url="http://sample.host/mypackage.html", ...
More arguments:
... packages=find_packages(exclude='tests'), package_data={'mypackage': ['data/*.xml']}, install_requires=['Paper>=1.0', 'UPSCode'], )
This boilerplate installs setuptools when the user (who is running setup.py) hasn't installed setuptools:
from ez_setup import use_setuptools use_setuptools()
ez_setup.py comes with setuptools, you include it directly in your archive.
These values can be edited through PyPI, if you need to correct the information on a released version.
You list all the packages that should be installed, including subpackages, like ['mypackage', ...].
find_packages() does this for you. The exclude argument keeps it from auto-detecting things that look like packages.
If you have optional requirements, you can use "features", which are not explained here.
What fun you and your new package will have!
$ python setup.py --help-commands Standard commands: build build everything needed to install build_py "build" pure Python modules (copy to build directory) build_ext build C/C++ extensions (compile/link to build directory) build_clib build C/C++ libraries used by Python extensions build_scripts "build" scripts (copy and fixup #! line) clean clean up output of 'build' command ...
The build* commands build C code. C is not Python. These are not the codes you are looking for.
Or really: I write Python, and building C code isn't broken, and install runs these commands for you, so I know nothing of this.
$ python setup.py --help-commands Standard commands: ... install install everything from build directory install_lib install all Python modules (extensions and pure Python) install_headers install C/C++ header files install_scripts install scripts (Python or otherwise) install_data install data files ...
Install the library; more on that later. The other install* commands are for installing just pieces of the package, which is used in intermediate steps you are unlikely to use independently.
$ python setup.py --help-commands Standard commands: ... sdist create a source distribution (tarball, zip file, etc.) register register the distribution with the Python package index bdist create a built (binary) distribution bdist_dumb create a "dumb" built distribution bdist_rpm create an RPM distribution bdist_wininst create an executable installer for MS Windows ...
$ python setup.py --help-commands ... Extra commands: rotate delete older distributions, keeping N newest files develop install package in 'development mode' setopt set an option in setup.cfg or another config file saveopts save supplied options to setup.cfg or other config file egg_info create a distribution's .egg-info directory upload upload binary package to PyPI alias define a shortcut to invoke one or more commands bdist_egg create an "egg" distribution test run unit tests after in-place build easy_install Find/get/install Python packages
All these commands come from setuptools.
Command-line options to setup.py can also go in setup.cfg, distutils.cfg, and other locations.