setuptools-0.6b3.zip

====================================================== Building and Distributing Packages with ``setuptools`` ====================================================== ``setuptools`` is a collection of enhancements to the Python ``distutils`` (for Python 2.3.5 and up on most platforms; 64-bit platforms require a minimum of Python 2.4) that allow you to more easily build and distribute Python packages, especially ones that have dependencies on other packages. Packages built and distributed using ``setuptools`` look to the user like ordinary Python packages based on the ``distutils``. Your users don't need to install or even know about setuptools in order to use them, and you don't have to include the entire setuptools package in your distributions. By including just a single `bootstrap module`_ (an 8K .py file), your package will automatically download and install ``setuptools`` if the user is building your package from source and doesn't have a suitable version already installed. .. _bootstrap module: http://peak.telecommunity.com/dist/ez_setup.py Feature Highlights: * Automatically find/download/install/upgrade dependencies at build time using the `EasyInstall tool <http://peak.telecommunity.com/DevCenter/EasyInstall>`_, which supports downloading via HTTP, FTP, Subversion, and SourceForge, and automatically scans web pages linked from PyPI to find download links. (It's the closest thing to CPAN currently available for Python.) * Create `Python Eggs <http://peak.telecommunity.com/DevCenter/PythonEggs>`_ - a single-file importable distribution format * Include data files inside your package directories, where your code can actually use them. (Python 2.4 distutils also supports this feature, but setuptools provides the feature for Python 2.3 packages also, and supports accessing data files in zipped packages too.) * Automatically include all packages in your source tree, without listing them individually in setup.py * Automatically include all relevant files in your source distributions, without needing to create a ``MANIFEST.in`` file, and without having to force regeneration of the ``MANIFEST`` file when your source tree changes. * Automatically generate wrapper scripts or Windows (console and GUI) .exe files for any number of "main" functions in your project. (Note: this is not a py2exe replacement; the .exe files rely on the local Python installation.) * Transparent Pyrex support, so that your setup.py can list ``.pyx`` files and still work even when the end-user doesn't have Pyrex installed (as long as you include the Pyrex-generated C in your source distribution) * Command aliases - create project-specific, per-user, or site-wide shortcut names for commonly used commands and options * PyPI upload support - upload your source distributions and eggs to PyPI * Deploy your project in "development mode", such that it's available on ``sys.path``, yet can still be edited directly from its source checkout. * Easily extend the distutils with new commands or ``setup()`` arguments, and distribute/reuse your extensions for multiple projects, without copying code. * Create extensible applications and frameworks that automatically discover extensions, using simple "entry points" declared in a project's setup script. In addition to the PyPI downloads, the development version of ``setuptools`` is available from the `Python SVN sandbox`_, and in-development versions of the `0.6 branch`_ are available as well. .. _0.6 branch: http://svn.python.org/projects/sandbox/branches/setuptools-0.6/#egg=setuptools-dev06 .. _Python SVN sandbox: http://svn.python.org/projects/sandbox/trunk/setuptools/#egg=setuptools-dev .. contents:: **Table of Contents** .. _ez_setup.py: `bootstrap module`_ ----------------- Developer's Guide ----------------- Installing ``setuptools`` ========================= Please follow the `EasyInstall Installation Instructions`_ to install the current stable version of setuptools. In particular, be sure to read the section on `Custom Installation Locations`_ if you are installing anywhere other than Python's ``site-packages`` directory. .. _EasyInstall Installation Instructions: http://peak.telecommunity.com/DevCenter/EasyInstall#installation-instructions .. _Custom Installation Locations: http://peak.telecommunity.com/DevCenter/EasyInstall#custom-installation-locations If you want the current in-development version of setuptools, you should first install a stable version, and then run:: ez_setup.py setuptools==dev This will download and install the latest development (i.e. unstable) version of setuptools from the Python Subversion sandbox. Basic Use ========= For basic use of setuptools, just import things from setuptools instead of the distutils. Here's a minimal setup script using setuptools:: from setuptools import setup, find_packages setup( name = "HelloWorld", version = "0.1", packages = find_packages(), ) As you can see, it doesn't take much to use setuptools in a project. Just by doing the above, this project will be able to produce eggs, upload to PyPI, and automatically include all packages in the directory where the setup.py lives. See the `Command Reference`_ section below to see what commands you can give to this setup script. Of course, before you release your project to PyPI, you'll want to add a bit more information to your setup script to help people find or learn about your project. And maybe your project will have grown by then to include a few dependencies, and perhaps some data files and scripts:: from setuptools import setup, find_packages setup( name = "HelloWorld", version = "0.1", packages = find_packages(), scripts = ['say_hello.py'], # Project uses reStructuredText, so ensure that the docutils get # installed or upgraded on the target machine install_requires = ['docutils>=0.3'], package_data = { # If any package contains *.txt or *.rst files, include them: '': ['*.txt', '*.rst'], # And include any *.msg files found in the 'hello' package, too: 'hello': ['*.msg'], } # metadata for upload to PyPI author = "Me", author_email = "me@example.com", description = "This is an Example Package", license = "PSF", keywords = "hello world example examples", url = "http://example.com/HelloWorld/", # project home page, if any # could also include long_description, download_url, classifiers, etc. ) In the sections that follow, we'll explain what most of these ``setup()`` arguments do (except for the metadata ones), and the various ways you might use them in your own project(s). Specifying Your Project's Version --------------------------------- Setuptools can work well with most versioning schemes; there are, however, a few special things to watch out for, in order to ensure that setuptools and EasyInstall can always tell what version of your package is newer than another version. Knowing these things will also help you correctly specify what versions of other projects your project depends on. A version consists of an alternating series of release numbers and pre-release or post-release tags. A release number is a series of digits punctuated by dots, such as ``2.4`` or ``0.5``. Each series of digits is treated numerically, so releases ``2.1`` and ``2.1.0`` are different ways to spell the same release number, denoting the first subrelease of release 2. But ``2.10`` is the *tenth* subrelease of release 2, and so is a different and newer release from ``2.1`` or ``2.1.0``. Leading zeros within a series of digits are also ignored, so ``2.01`` is the same as ``2.1``, and different from ``2.0.1``. Following a release number, you can have either a pre-release or post-release tag. Pre-release tags make a version be c