setuptools is a rich and complex program. This tutorial will focus on the bare minimum basics you need to get setuptools running so you can:
- Register your package on pypi.
- Build egg, source, and window installer ‘distributables’.
- Upload these ‘distributables’ to pypi.
To install setuptools visit http://pypi.python.org/pypi/setuptools and follow the instructions for your operating system. Also, check out http://peak.telecommunity.com/DevCenter/EasyInstall for more instructions on how to install setup tools.
Currently (as of November, 2009), setuptools is pretty easy to install for Python version 2.3 through 2.6.
If you are having trouble setting up setuptools for your platform, you may want to check out the ‘bootstrap’ setuptools script at http://peak.telecommunity.com/dist/ez_setup.py.
You can run this like this:
$ python ez_setup.py
and it will install setuptools for whichever version of Python python refers to. For example on windows:
$ C:\Python24\python.exe ez_setup.py
will install a setuptools for your python24 distribution.
All the features of what can go into a setup.py file is beyond the scope of this simple tutorial. I’ll just focus on a very basic and common format needed to get this project onto pypi.
The contents of setup.py is just pure python:
import os from setuptools import setup # Utility function to read the README file. # Used for the long_description. It's nice, because now 1) we have a top level # README file and 2) it's easier to type in the README file than to put a raw # string in below ... def read(fname): return open(os.path.join(os.path.dirname(__file__), fname)).read() setup( name = "an_example_pypi_project", version = "0.0.4", author = "Andrew Carter", author_email = "email@example.com", description = ("An demonstration of how to create, document, and publish " "to the cheese shop a5 pypi.org."), license = "BSD", keywords = "example documentation tutorial", url = "http://packages.python.org/an_example_pypi_project", packages=['an_example_pypi_project', 'tests'], long_description=read('README'), classifiers=[ "Development Status :: 3 - Alpha", "Topic :: Utilities", "License :: OSI Approved :: BSD License", ], )
The directory structure, so far, should look like this:
some_root_dir/ |-- README |-- setup.py |-- an_example_pypi_project | |-- __init__.py | |-- useful_1.py | |-- useful_2.py |-- tests |-- |-- __init__.py |-- |-- runall.py |-- |-- test0.py
A nice idea stolen from http://pypi.python.org/pypi/Sphinx-PyPI-upload is to include a README text file which your code. This would be visible when someone, say, cloned your repo.
Using the simple read function, it is easy to include this in the long_description keyword arg for the setuptools.setup() function.
A really nice website is http://pypi.python.org/pypi?%3Aaction=list_classifiers which lists all the classifiers you can use in the setup call.
A sample of this website is:
Development Status :: 1 - Planning Development Status :: 2 - Pre-Alpha Development Status :: 3 - Alpha Development Status :: 4 - Beta Development Status :: 5 - Production/Stable Development Status :: 6 - Mature Development Status :: 7 - Inactive Environment :: Console Environment :: Console :: Curses Environment :: Console :: Framebuffer Environment :: Console :: Newt Environment :: Console :: svgalib
The basic usage of setup.py is:
$ python setup.py <some_command> <options>
To see all commands type:
$ python setup.py --help-commands
And you will get:
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 temporary files from 'build' command 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 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 upload upload binary package to PyPI 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_sphinx Upload Sphinx documentation to PyPI install_egg_info Install an .egg-info directory for the package alias define a shortcut to invoke one or more commands easy_install Find/get/install Python packages bdist_egg create an "egg" distribution test run unit tests after in-place build build_sphinx Build Sphinx documentation usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...] or: setup.py --help [cmd1 cmd2 ...] or: setup.py --help-commands or: setup.py cmd --help
In order to interact with pypi, you first need to setup an account. Go to http://pypi.python.org/pypi and click on Register.
Now, once registered, when you run setup.py commands that interact with pypi you’ll have to enter your username and password each time.
To get around this, place a .pypirc file in your $HOME directory on linux. On windows, an you’ll need to set a HOME environ var to point to the directory where this file lives.
The structure of a .pypirc file is pretty simple:
[pypirc] servers = pypi [server-login] username:your_awesome_username password:your_awesome_password
There’s probably away around having your plain text password in this file, but I don’t know of the solution and haven’t looked into it.
With your setup.py and .pypirc in place, registering your project is pretty simple. Just type:
$ python setup.py register
I would say more, but it is just that simple.
There are three major setup.py commands we will use:
A key point here is you need to run these commands with the version of python you want to support. We’ll cover this in the Putting It All Together With The Full Windows Script below.
You can run these commands by themselves and simply create the files but not upload them. However, for this project, we always marry these commands with the upload directive which will both build and upload the necessary files.
This project was build on a windows machine. To best understand how it all works and the other options used when using setup.py let’s just look at the .bat file I use to build the package and upload it to pypi:
set HOME=C:\Users\Owner\ cd C:\eclipse\workspace\HG_AN_EXAMPLE_PYPI_PROJECT C:\Python24\python.exe setup.py bdist_egg upload --identity="Andrew Carter" --sign --quiet C:\Python25\python.exe setup.py bdist_egg upload --identity="Andrew Carter" --sign --quiet C:\Python26\python.exe setup.py bdist_egg upload --identity="Andrew Carter" --sign --quiet C:\Python24\python.exe setup.py bdist_wininst --target-version=2.4 register upload --identity="Andrew Carter" --sign --quiet C:\Python25\python.exe setup.py bdist_wininst --target-version=2.5 register upload --identity="Andrew Carter" --sign --quiet C:\Python26\python.exe setup.py bdist_wininst --target-version=2.6 register upload --identity="Andrew Carter" --sign --quiet C:\Python26\python.exe setup.py sdist upload --identity="Andrew Carter" --sign pause
For linux, it would be pretty much the same commands, just changing around the directories to point to the correct python versions.
I use the set HOME=C:\Users\Owner\ instead of setting an environ variable on windows