:orphan:

``ez_setup`` distribution guide 
===============================

Using ``setuptools``...  Without bundling it!
---------------------------------------------

.. warning:: **ez_setup** is deprecated in favor of PIP with **PEP-518** support.

.. _ez_setup.py: https://bootstrap.pypa.io/ez_setup.py

.. _EasyInstall Installation Instructions: easy_install.html

.. _Custom Installation Locations: easy_install.html

Your users might not have ``setuptools`` installed on their machines, or even
if they do, it might not be the right version.  Fixing this is easy; just
download `ez_setup.py`_, and put it in the same directory as your ``setup.py``
script.  (Be sure to add it to your revision control system, too.)  Then add
these two lines to the very top of your setup script, before the script imports
anything from setuptools:

.. code-block:: python

    import ez_setup
    ez_setup.use_setuptools()

That's it.  The ``ez_setup`` module will automatically download a matching
version of ``setuptools`` from PyPI, if it isn't present on the target system.
Whenever you install an updated version of setuptools, you should also update
your projects' ``ez_setup.py`` files, so that a matching version gets installed
on the target machine(s).

(By the way, if you need to distribute a specific version of ``setuptools``,
you can specify the exact version and base download URL as parameters to the
``use_setuptools()`` function.  See the function's docstring for details.)


What Your Users Should Know
---------------------------

In general, a setuptools-based project looks just like any distutils-based
project -- as long as your users have an internet connection and are installing
to ``site-packages``, that is.  But for some users, these conditions don't
apply, and they may become frustrated if this is their first encounter with
a setuptools-based project.  To keep these users happy, you should review the
following topics in your project's installation instructions, if they are
relevant to your project and your target audience isn't already familiar with
setuptools and ``easy_install``.

Network Access
    If your project is using ``ez_setup``, you should inform users of the
    need to either have network access, or to preinstall the correct version of
    setuptools using the `EasyInstall installation instructions`_.  Those
    instructions also have tips for dealing with firewalls as well as how to
    manually download and install setuptools.

Custom Installation Locations
    You should inform your users that if they are installing your project to
    somewhere other than the main ``site-packages`` directory, they should
    first install setuptools using the instructions for `Custom Installation
    Locations`_, before installing your project.

Your Project's Dependencies
    If your project depends on other projects that may need to be downloaded
    from PyPI or elsewhere, you should list them in your installation
    instructions, or tell users how to find out what they are.  While most
    users will not need this information, any users who don't have unrestricted
    internet access may have to find, download, and install the other projects
    manually.  (Note, however, that they must still install those projects
    using ``easy_install``, or your project will not know they are installed,
    and your setup script will try to download them again.)

    If you want to be especially friendly to users with limited network access,
    you may wish to build eggs for your project and its dependencies, making
    them all available for download from your site, or at least create a page
    with links to all of the needed eggs.  In this way, users with limited
    network access can manually download all the eggs to a single directory,
    then use the ``-f`` option of ``easy_install`` to specify the directory
    to find eggs in.  Users who have full network access can just use ``-f``
    with the URL of your download page, and ``easy_install`` will find all the
    needed eggs using your links directly.  This is also useful when your
    target audience isn't able to compile packages (e.g. most Windows users)
    and your package or some of its dependencies include C code.

Revision Control System Users and Co-Developers
    Users and co-developers who are tracking your in-development code using
    a revision control system should probably read this manual's sections
    regarding such development.  Alternately, you may wish to create a
    quick-reference guide containing the tips from this manual that apply to
    your particular situation.  For example, if you recommend that people use
    ``setup.py develop`` when tracking your in-development code, you should let
    them know that this needs to be run after every update or commit.

    Similarly, if you remove modules or data files from your project, you
    should remind them to run ``setup.py clean --all`` and delete any obsolete
    ``.pyc`` or ``.pyo``.  (This tip applies to the distutils in general, not
    just setuptools, but not everybody knows about them; be kind to your users
    by spelling out your project's best practices rather than leaving them
    guessing.)

Creating System Packages
    Some users want to manage all Python packages using a single package
    manager, and sometimes that package manager isn't ``easy_install``!
    Setuptools currently supports ``bdist_rpm``, ``bdist_wininst``, and
    ``bdist_dumb`` formats for system packaging.  If a user has a locally-
    installed "bdist" packaging tool that internally uses the distutils
    ``install`` command, it should be able to work with ``setuptools``.  Some
    examples of "bdist" formats that this should work with include the
    ``bdist_nsi`` and ``bdist_msi`` formats for Windows.

    However, packaging tools that build binary distributions by running
    ``setup.py install`` on the command line or as a subprocess will require
    modification to work with setuptools.  They should use the
    ``--single-version-externally-managed`` option to the ``install`` command,
    combined with the standard ``--root`` or ``--record`` options.
    See the `install command`_ documentation below for more details.  The
    ``bdist_deb`` command is an example of a command that currently requires
    this kind of patching to work with setuptools.

    Please note that building system packages may require you to install
    some system software, for example ``bdist_rpm`` requires the ``rpmbuild``
    command to be installed.

    If you or your users have a problem building a usable system package for
    your project, please report the problem via the mailing list so that
    either the "bdist" tool in question or setuptools can be modified to
    resolve the issue.

Your users might not have ``setuptools`` installed on their machines, or even
if they do, it might not be the right version.  Fixing this is easy; just
download `ez_setup.py`_, and put it in the same directory as your ``setup.py``
script.  (Be sure to add it to your revision control system, too.)  Then add
these two lines to the very top of your setup script, before the script imports
anything from setuptools:

.. code-block:: python

    import ez_setup
    ez_setup.use_setuptools()

That's it.  The ``ez_setup`` module will automatically download a matching
version of ``setuptools`` from PyPI, if it isn't present on the target system.
Whenever you install an updated version of setuptools, you should also update
your projects' ``ez_setup.py`` files, so that a matching version gets installed
on the target machine(s).

(By the way, if you need to distribute a specific version of ``setuptools``,
you can specify the exact version and base download URL as parameters to the
``use_setuptools()`` function.  See the function's docstring for details.)

.. _install command:

``install`` - Run ``easy_install`` or old-style installation
============================================================

The setuptools ``install`` command is basically a shortcut to run the
``easy_install`` command on the current project.  However, for convenience
in creating "system packages" of setuptools-based projects, you can also
use this option:

``--single-version-externally-managed``
    This boolean option tells the ``install`` command to perform an "old style"
    installation, with the addition of an ``.egg-info`` directory so that the
    installed project will still have its metadata available and operate
    normally.  If you use this option, you *must* also specify the ``--root``
    or ``--record`` options (or both), because otherwise you will have no way
    to identify and remove the installed files.

This option is automatically in effect when ``install`` is invoked by another
distutils command, so that commands like ``bdist_wininst`` and ``bdist_rpm``
will create system packages of eggs.  It is also automatically in effect if
you specify the ``--root`` option.


``install_egg_info`` - Install an ``.egg-info`` directory in ``site-packages``
==============================================================================

Setuptools runs this command as part of ``install`` operations that use the
``--single-version-externally-managed`` options.  You should not invoke it
directly; it is documented here for completeness and so that distutils
extensions such as system package builders can make use of it.  This command
has only one option:

``--install-dir=DIR, -d DIR``
    The parent directory where the ``.egg-info`` directory will be placed.
    Defaults to the same as the ``--install-dir`` option specified for the
    ``install_lib`` command, which is usually the system ``site-packages``
    directory.

This command assumes that the ``egg_info`` command has been given valid options
via the command line or ``setup.cfg``, as it will invoke the ``egg_info``
command and use its options to locate the project's source ``.egg-info``
directory.