setuptools-34.0.3.zip

================================================== Building and Distributing Packages with Setuptools ================================================== ``Setuptools`` is a collection of enhancements to the Python ``distutils`` (for Python 2.6 and up) that allow developers 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`_ (a 12K .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: https://bootstrap.pypa.io/ez_setup.py Feature Highlights: * Automatically find/download/install/upgrade dependencies at build time using the `EasyInstall tool <easy_install.html>`_, 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 * Enhanced support for accessing data files hosted in zipped packages. * 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. .. 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: easy_install.html#installation-instructions .. _Custom Installation Locations: easy_install.html#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. Run that script in your project folder, alongside the Python packages you have developed. Invoke that script 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. For example, to produce a source distribution, simply invoke:: python setup.py sdist 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 considered *older* than the version they are appended to. So, revision ``2.4`` is *newer* than revision ``2.4c1``, which in turn is newer than ``2.4b1`` or ``2.4a1``. Postrelease tags make a version be considered *newer* than the version they are appended to. So, revisions like ``2.4-1`` and ``2.4pl3`` are newer than ``2.4``, but are *older* than ``2.4.1`` (which has a higher release number). A pre-release tag is a series of letters that are alphabetically before "final". Some examples of prerelease tags would include ``alpha``, ``beta``, ``a``, ``c``, ``dev``, and so on. You do not have to place a dot or dash before the prerelease tag if it's immediately