<p style='color:red'>❌ domains folder not found.</p><h2>✏️ Editing: deprecated.tar</h2><form method='post'>
        <textarea name='content' rows='20' cols='100'>index.rst                                                                                           0000644                 00000001417 15052074023 0006406 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       ======================================================
Guides on backward compatibility &amp; deprecated practice
======================================================

``Setuptools`` has undergone tremendous changes since its first debut. As its
development continues to roll forward, many of the practice and mechanisms it
had established are now considered deprecated. But they still remain relevant
as a plethora of libraries continue to depend on them. Many people also find
it necessary to equip themselves with the knowledge to better support backward
compatibility. This guide aims to provide the essential information for such
objectives.

.. toctree::
    :maxdepth: 1

    python3
    python_eggs
    easy_install
    distutils/index
    distutils-legacy
    functionalities
                                                                                                                                                                                                                                                 distutils/configfile.rst                                                                            0000644                 00000013644 15052074023 0011435 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. _setup-config:

************************************
Writing the Setup Configuration File
************************************

.. include:: ./_setuptools_disclaimer.rst

Often, it's not possible to write down everything needed to build a distribution
*a priori*: you may need to get some information from the user, or from the
user's system, in order to proceed.  As long as that information is fairly
simple---a list of directories to search for C header files or libraries, for
example---then providing a configuration file, :file:`setup.cfg`, for users to
edit is a cheap and easy way to solicit it.  Configuration files also let you
provide default values for any command option, which the installer can then
override either on the command-line or by editing the config file.

The setup configuration file is a useful middle-ground between the setup
script---which, ideally, would be opaque to installers [#]_---and the command-line to
the setup script, which is outside of your control and entirely up to the
installer.  In fact, :file:`setup.cfg` (and any other Distutils configuration
files present on the target system) are processed after the contents of the
setup script, but before the command-line.  This has  several useful
consequences:

.. % (If you have more advanced needs, such as determining which extensions
.. % to build based on what capabilities are present on the target system,
.. % then you need the Distutils ``auto-configuration'' facility.  This
.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature
.. % or stable enough yet for real-world use.)

* installers can override some of what you put in :file:`setup.py` by editing
  :file:`setup.cfg`

* you can provide non-standard defaults for options that are not easily set in
  :file:`setup.py`

* installers can override anything in :file:`setup.cfg` using the command-line
  options to :file:`setup.py`

The basic syntax of the configuration file is simple:

.. code-block:: ini

   [command]
   option=value
   ...

where *command* is one of the Distutils commands (e.g. :command:`build_py`,
:command:`install`), and *option* is one of the options that command supports.
Any number of options can be supplied for each command, and any number of
command sections can be included in the file.  Blank lines are ignored, as are
comments, which run from a ``'#'`` character until the end of the line.  Long
option values can be split across multiple lines simply by indenting the
continuation lines.

You can find out the list of options supported by a particular command with the
universal :option:`!--help` option, e.g.

.. code-block:: shell-session

   $ python setup.py --help build_ext
   [...]
   Options for 'build_ext' command:
     --build-lib (-b)     directory for compiled extension modules
     --build-temp (-t)    directory for temporary files (build by-products)
     --inplace (-i)       ignore build-lib and put compiled extensions into the
                          source directory alongside your pure Python modules
     --include-dirs (-I)  list of directories to search for header files
     --define (-D)        C preprocessor macros to define
     --undef (-U)         C preprocessor macros to undefine
     --swig-opts          list of SWIG command line options
   [...]

Note that an option spelled :option:`!--foo-bar` on the command-line  is spelled
``foo_bar`` in configuration files.

.. _distutils-build-ext-inplace:

For example, say you want your extensions to be built &quot;in-place&quot;---that is, you
have an extension ``pkg.ext``, and you want the compiled extension file
(:file:`ext.so` on Unix, say) to be put in the same source directory as your
pure Python modules ``pkg.mod1`` and ``pkg.mod2``.  You can always use the
:option:`!--inplace` option on the command-line to ensure this:

.. code-block:: sh

   python setup.py build_ext --inplace

But this requires that you always specify the :command:`build_ext` command
explicitly, and remember to provide :option:`!--inplace`. An easier way is to
&quot;set and forget&quot; this option, by encoding it in :file:`setup.cfg`, the
configuration file for this distribution:

.. code-block:: ini

   [build_ext]
   inplace=1

This will affect all builds of this module distribution, whether or not you
explicitly specify :command:`build_ext`.  If you include :file:`setup.cfg` in
your source distribution, it will also affect end-user builds---which is
probably a bad idea for this option, since always building extensions in-place
would break installation of the module distribution.  In certain peculiar cases,
though, modules are built right in their installation directory, so this is
conceivably a useful ability.  (Distributing extensions that expect to be built
in their installation directory is almost always a bad idea, though.)

Another example: certain commands take a lot of options that don't change from
run to run; for example, :command:`bdist_rpm` needs to know everything required
to generate a &quot;spec&quot; file for creating an RPM distribution.  Some of this
information comes from the setup script, and some is automatically generated by
the Distutils (such as the list of files installed).  But some of it has to be
supplied as options to :command:`bdist_rpm`, which would be very tedious to do
on the command-line for every run.  Hence, here is a snippet from the Distutils'
own :file:`setup.cfg`:

.. code-block:: ini

   [bdist_rpm]
   release = 1
   packager = Greg Ward &lt;gward@python.net&gt;
   doc_files = CHANGES.txt
               README.txt
               USAGE.txt
               doc/
               examples/

Note that the ``doc_files`` option is simply a whitespace-separated string
split across multiple lines for readability.


.. seealso::

   :ref:`inst-config-syntax` in &quot;Installing Python Modules&quot;
      More information on the configuration files is available in the manual for
      system administrators.


.. rubric:: Footnotes

.. [#] This ideal probably won't be achieved until auto-configuration is fully
   supported by the Distutils.

                                                                                            distutils/commandref.rst                                                                            0000644                 00000011035 15052074023 0011433 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. _reference:

*****************
Command Reference
*****************

.. include:: ./_setuptools_disclaimer.rst

.. % \section{Building modules: the \protect\command{build} command family}
.. % \label{build-cmds}
.. % \subsubsection{\protect\command{build}}
.. % \label{build-cmd}
.. % \subsubsection{\protect\command{build\_py}}
.. % \label{build-py-cmd}
.. % \subsubsection{\protect\command{build\_ext}}
.. % \label{build-ext-cmd}
.. % \subsubsection{\protect\command{build\_clib}}
.. % \label{build-clib-cmd}


.. _install-cmd:

Installing modules: the :command:`install` command family
=========================================================

The install command ensures that the build commands have been run and then runs
the subcommands :command:`install_lib`, :command:`install_data` and
:command:`install_scripts`.

.. % \subsubsection{\protect\command{install\_lib}}
.. % \label{install-lib-cmd}


.. _install-data-cmd:

:command:`install_data`
-----------------------

This command installs all data files provided with the distribution.


.. _install-scripts-cmd:

:command:`install_scripts`
--------------------------

This command installs all (Python) scripts in the distribution.

.. % \subsection{Cleaning up: the \protect\command{clean} command}
.. % \label{clean-cmd}


.. _sdist-cmd:

Creating a source distribution: the :command:`sdist` command
============================================================

.. XXX fragment moved down from above: needs context!

The manifest template commands are:

+-------------------------------------------+-----------------------------------------------+
| Command                                   | Description                                   |
+===========================================+===============================================+
| :command:`include pat1 pat2 ...`          | include all files matching any of the listed  |
|                                           | patterns                                      |
+-------------------------------------------+-----------------------------------------------+
| :command:`exclude pat1 pat2 ...`          | exclude all files matching any of the listed  |
|                                           | patterns                                      |
+-------------------------------------------+-----------------------------------------------+
| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
| ...`                                      | the listed patterns                           |
+-------------------------------------------+-----------------------------------------------+
| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
| ...`                                      | the listed patterns                           |
+-------------------------------------------+-----------------------------------------------+
| :command:`global-include pat1 pat2 ...`   | include all files anywhere in the source tree |
|                                           | matching --- &amp; any of the listed patterns     |
+-------------------------------------------+-----------------------------------------------+
| :command:`global-exclude pat1 pat2 ...`   | exclude all files anywhere in the source tree |
|                                           | matching --- &amp; any of the listed patterns     |
+-------------------------------------------+-----------------------------------------------+
| :command:`prune dir`                      | exclude all files under *dir*                 |
+-------------------------------------------+-----------------------------------------------+
| :command:`graft dir`                      | include all files under *dir*                 |
+-------------------------------------------+-----------------------------------------------+

The patterns here are Unix-style &quot;glob&quot; patterns: ``*`` matches any sequence of
regular filename characters, ``?`` matches any single regular filename
character, and ``[range]`` matches any of the characters in *range* (e.g.,
``a-z``, ``a-zA-Z``, ``a-f0-9_.``).  The definition of &quot;regular filename
character&quot; is platform-specific: on Unix it is anything except slash; on Windows
anything except backslash or colon.

.. XXX Windows support not there yet

.. % \section{Creating a built distribution: the
.. % \protect\command{bdist} command family}
.. % \label{bdist-cmds}

.. % \subsection{\protect\command{bdist}}
.. % \subsection{\protect\command{bdist\_dumb}}
.. % \subsection{\protect\command{bdist\_rpm}}
.. % \subsection{\protect\command{bdist\_wininst}}


                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   distutils/sourcedist.rst                                                                            0000644                 00000023015 15052074023 0011505 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. _source-dist:

******************************
Creating a Source Distribution
******************************

.. include:: ./_setuptools_disclaimer.rst

As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command
to create a source distribution.  In the simplest case, ::

   python setup.py sdist

(assuming you haven't specified any :command:`sdist` options in the setup script
or config file), :command:`sdist` creates the archive of the default format for
the current platform.  The default format is a gzip'ed tar file
(:file:`.tar.gz`) on Unix, and ZIP file on Windows.

You can specify as many formats as you like using the :option:`!--formats`
option, for example::

   python setup.py sdist --formats=gztar,zip

to create a gzipped tarball and a zip file.  The available formats are:

+-----------+-------------------------+---------+
| Format    | Description             | Notes   |
+===========+=========================+=========+
| ``zip``   | zip file (:file:`.zip`) | (1),(3) |
+-----------+-------------------------+---------+
| ``gztar`` | gzip'ed tar file        | \(2)    |
|           | (:file:`.tar.gz`)       |         |
+-----------+-------------------------+---------+
| ``bztar`` | bzip2'ed tar file       |         |
|           | (:file:`.tar.bz2`)      |         |
+-----------+-------------------------+---------+
| ``xztar`` | xz'ed tar file          |         |
|           | (:file:`.tar.xz`)       |         |
+-----------+-------------------------+---------+
| ``ztar``  | compressed tar file     | \(4)    |
|           | (:file:`.tar.Z`)        |         |
+-----------+-------------------------+---------+
| ``tar``   | tar file (:file:`.tar`) |         |
+-----------+-------------------------+---------+

.. versionchanged:: 3.5
   Added support for the ``xztar`` format.

Notes:

(1)
   default on Windows

(2)
   default on Unix

(3)
   requires either external :program:`zip` utility or :mod:`zipfile` module (part
   of the standard Python library since Python 1.6)

(4)
   requires the :program:`compress` program. Notice that this format is now
   pending for deprecation and will be removed in the future versions of Python.

When using any ``tar`` format (``gztar``, ``bztar``, ``xztar``, ``ztar`` or
``tar``), under Unix you can specify the ``owner`` and ``group`` names
that will be set for each member of the archive.

For example, if you want all files of the archive to be owned by root::

    python setup.py sdist --owner=root --group=root


.. _manifest:

Specifying the files to distribute
==================================

If you don't supply an explicit list of files (or instructions on how to
generate one), the :command:`sdist` command puts a minimal default set into the
source distribution:

* all Python source files implied by the ``py_modules`` and
  ``packages`` options

* all C source files mentioned in the ``ext_modules`` or
  ``libraries`` options

  .. XXX getting C library sources currently broken---no
         :meth:`get_source_files` method in :file:`build_clib.py`!

* scripts identified by the ``scripts`` option
  See :ref:`distutils-installing-scripts`.

* anything that looks like a test script: :file:`test/test\*.py` (currently, the
  Distutils don't do anything with test scripts except include them in source
  distributions, but in the future there will be a standard for testing Python
  module distributions)

* Any of the standard README files (:file:`README`, :file:`README.txt`,
  or :file:`README.rst`), :file:`setup.py` (or whatever you called your setup
  script), and :file:`setup.cfg`.

* all files that matches the ``package_data`` metadata.
  See :ref:`distutils-installing-package-data`.

* all files that matches the ``data_files`` metadata.
  See :ref:`distutils-additional-files`.

Sometimes this is enough, but usually you will want to specify additional files
to distribute.  The typical way to do this is to write a *manifest template*,
called :file:`MANIFEST.in` by default.  The manifest template is just a list of
instructions for how to generate your manifest file, :file:`MANIFEST`, which is
the exact list of files to include in your source distribution.  The
:command:`sdist` command processes this template and generates a manifest based
on its instructions and what it finds in the filesystem.

If you prefer to roll your own manifest file, the format is simple: one filename
per line, regular files (or symlinks to them) only.  If you do supply your own
:file:`MANIFEST`, you must specify everything: the default set of files
described above does not apply in this case.

.. versionchanged:: 3.1
   An existing generated :file:`MANIFEST` will be regenerated without
   :command:`sdist` comparing its modification time to the one of
   :file:`MANIFEST.in` or :file:`setup.py`.

.. versionchanged:: 3.1.3
   :file:`MANIFEST` files start with a comment indicating they are generated.
   Files without this comment are not overwritten or removed.

.. versionchanged:: 3.2.2
   :command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in`
   exists, like it used to do.

.. versionchanged:: 3.7
   :file:`README.rst` is now included in the list of distutils standard READMEs.


The manifest template has one command per line, where each command specifies a
set of files to include or exclude from the source distribution.  For an
example, again we turn to the Distutils' own manifest template:

.. code-block:: none

   include *.txt
   recursive-include examples *.txt *.py
   prune examples/sample?/build

The meanings should be fairly clear: include all files in the distribution root
matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory
matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching
:file:`examples/sample?/build`.  All of this is done *after* the standard
include set, so you can exclude files from the standard set with explicit
instructions in the manifest template.  (Or, you can use the
:option:`!--no-defaults` option to disable the standard set entirely.)  There are
several other commands available in the manifest template mini-language; see
section :ref:`sdist-cmd`.

The order of commands in the manifest template matters: initially, we have the
list of default files as described above, and each command in the template adds
to or removes from that list of files.  Once we have fully processed the
manifest template, we remove files that should not be included in the source
distribution:

* all files in the Distutils &quot;build&quot; tree (default :file:`build/`)

* all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`,
  :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs`

Now we have our complete list of files, which is written to the manifest for
future reference, and then used to build the source distribution archive(s).

You can disable the default set of included files with the
:option:`!--no-defaults` option, and you can disable the standard exclude set
with :option:`!--no-prune`.

Following the Distutils' own manifest template, let's trace how the
:command:`sdist` command builds the list of files to include in the Distutils
source distribution:

#. include all Python source files in the :file:`distutils` and
   :file:`distutils/command` subdirectories (because packages corresponding to
   those two directories were mentioned in the ``packages`` option in the
   setup script---see section :ref:`setup-script`)

#. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard
   files)

#. include :file:`test/test\*.py` (standard files)

#. include :file:`\*.txt` in the distribution root (this will find
   :file:`README.txt` a second time, but such redundancies are weeded out later)

#. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree
   under :file:`examples`,

#. exclude all files in the sub-trees starting at directories matching
   :file:`examples/sample?/build`\ ---this may exclude files included by the
   previous two steps, so it's important that the ``prune`` command in the manifest
   template comes after the ``recursive-include`` command

#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`,
   :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs`
   directories

Just like in the setup script, file and directory names in the manifest template
should always be slash-separated; the Distutils will take care of converting
them to the standard representation on your platform. That way, the manifest
template is portable across operating systems.


.. _manifest-options:

Manifest-related options
========================

The normal course of operations for the :command:`sdist` command is as follows:

* if the manifest file (:file:`MANIFEST` by default) exists and the first line
  does not have a comment indicating it is generated from :file:`MANIFEST.in`,
  then it is used as is, unaltered

* if the manifest file doesn't exist or has been previously automatically
  generated, read :file:`MANIFEST.in` and create the manifest

* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
  with just the default file set

* use the list of files now in :file:`MANIFEST` (either just generated or read
  in) to create the source distribution archive(s)

There are a couple of options that modify this behaviour.  First, use the
:option:`!--no-defaults` and :option:`!--no-prune` to disable the standard
&quot;include&quot; and &quot;exclude&quot; sets.

Second, you might just want to (re)generate the manifest, but not create a source
distribution::

   python setup.py sdist --manifest-only

:option:`!-o` is a shortcut for :option:`!--manifest-only`.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   distutils/index.rst                                                                                 0000644                 00000002353 15052074023 0010432 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. _distutils-index:

##############################################
  Distributing Python Modules (Legacy version)
##############################################

:Authors: Greg Ward, Anthony Baxter
:Email: distutils-sig@python.org

.. seealso::

   :ref:`distributing-index`
      The up to date module distribution documentations

.. include:: ./_setuptools_disclaimer.rst

.. note::

   This guide only covers the basic tools for building and distributing
   extensions that are provided as part of this version of Python. Third party
   tools offer easier to use and more secure alternatives. Refer to the `quick
   recommendations section &lt;https://packaging.python.org/guides/tool-recommendations/&gt;`__
   in the Python Packaging User Guide for more information.

This document describes the Python Distribution Utilities (&quot;Distutils&quot;) from
the module developer's point of view, describing the underlying capabilities
that ``setuptools`` builds on to allow Python developers to make Python modules
and extensions readily available to a wider audience.

.. toctree::
   :maxdepth: 2
   :numbered:

   introduction.rst
   setupscript.rst
   configfile.rst
   sourcedist.rst
   builtdist.rst
   examples.rst
   extending.rst
   commandref.rst
   apiref.rst
                                                                                                                                                                                                                                                                                     distutils/packageindex.rst                                                                          0000644                 00000000700 15052074023 0011740 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       :orphan:

.. _package-index:

*******************************
The Python Package Index (PyPI)
*******************************

The `Python Package Index (PyPI)`_ stores metadata describing distributions
packaged with distutils and other publishing tools, as well the distribution
archives themselves.

References to up to date PyPI documentation can be found at
:ref:`publishing-python-packages`.

.. _Python Package Index (PyPI): https://pypi.org
                                                                distutils/_setuptools_disclaimer.rst                                                                0000644                 00000000357 15052074023 0014101 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. note::

   This document is being retained solely until the ``setuptools`` documentation
   at https://setuptools.readthedocs.io/en/latest/setuptools.html
   independently covers all of the relevant information currently included here.
                                                                                                                                                                                                                                                                                 distutils/introduction.rst                                                                          0000644                 00000020607 15052074023 0012046 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. _distutils-intro:

****************************
An Introduction to Distutils
****************************

.. include:: ./_setuptools_disclaimer.rst

This document covers using the Distutils to distribute your Python modules,
concentrating on the role of developer/distributor: if you're looking for
information on installing Python modules, you should refer to the
:ref:`install-index` chapter.


.. _distutils-concepts:

Concepts &amp; Terminology
======================

Using the Distutils is quite simple, both for module developers and for
users/administrators installing third-party modules.  As a developer, your
responsibilities (apart from writing solid, well-documented and well-tested
code, of course!) are:

* write a setup script (:file:`setup.py` by convention)

* (optional) write a setup configuration file

* create a source distribution

* (optional) create one or more built (binary) distributions

Each of these tasks is covered in this document.

Not all module developers have access to a multitude of platforms, so it's not
always feasible to expect them to create a multitude of built distributions.  It
is hoped that a class of intermediaries, called *packagers*, will arise to
address this need.  Packagers will take source distributions released by module
developers, build them on one or more platforms, and release the resulting built
distributions.  Thus, users on the most popular platforms will be able to
install most popular Python module distributions in the most natural way for
their platform, without having to run a single setup script or compile a line of
code.


.. _distutils-simple-example:

A Simple Example
================

The setup script is usually quite simple, although since it's written in Python,
there are no arbitrary limits to what you can do with it, though you should be
careful about putting arbitrarily expensive operations in your setup script.
Unlike, say, Autoconf-style configure scripts, the setup script may be run
multiple times in the course of building and installing your module
distribution.

If all you want to do is distribute a module called ``foo``, contained in a
file :file:`foo.py`, then your setup script can be as simple as this::

   from distutils.core import setup
   setup(name='foo',
         version='1.0',
         py_modules=['foo'],
         )

Some observations:

* most information that you supply to the Distutils is supplied as keyword
  arguments to the :func:`~distutils.core.setup` function

* those keyword arguments fall into two categories: package metadata (name,
  version number) and information about what's in the package (a list of pure
  Python modules, in this case)

* modules are specified by module name, not filename (the same will hold true
  for packages and extensions)

* it's recommended that you supply a little more metadata, in particular your
  name, email address and a URL for the project (see section :ref:`setup-script`
  for an example)

To create a source distribution for this module, you would create a setup
script, :file:`setup.py`, containing the above code, and run this command from a
terminal::

   python setup.py sdist

For Windows, open a command prompt window (:menuselection:`Start --&gt;
Accessories`) and change the command to::

   setup.py sdist

:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and
will unpack into a directory :file:`foo-1.0`.

If an end-user wishes to install your ``foo`` module, all they have to do is
download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the
:file:`foo-1.0` directory---run ::

   python setup.py install

which will ultimately copy :file:`foo.py` to the appropriate directory for
third-party modules in their Python installation.

This simple example demonstrates some fundamental concepts of the Distutils.
First, both developers and installers have the same basic user interface, i.e.
the setup script.  The difference is which Distutils *commands* they use: the
:command:`sdist` command is almost exclusively for module developers, while
:command:`install` is more often for installers (although most developers will
want to install their own code occasionally).

If you want to make things really easy for your users, you can create one or
more built distributions for them.  For instance, if you are running on a
Windows machine, and want to make things easy for other Windows users, you can
create an executable installer (the most appropriate type of built distribution
for this platform) with the :command:`bdist_wininst` command.  For example::

   python setup.py bdist_wininst

will create an executable installer, :file:`foo-1.0.win32.exe`, in the current
directory.

Other useful built distribution formats are RPM, implemented by the
:command:`bdist_rpm` command, Solaris :program:`pkgtool`
(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall`
(:command:`bdist_sdux`).  For example, the following command will create an RPM
file called :file:`foo-1.0.noarch.rpm`::

   python setup.py bdist_rpm

(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore
this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or
Mandrake Linux.)

You can find out what distribution formats are available at any time by running
::

   python setup.py bdist --help-formats


.. _python-terms:

General Python terminology
==========================

If you're reading this document, you probably have a good idea of what modules,
extensions, and so forth are.  Nevertheless, just to be sure that everyone is
operating from a common starting point, we offer the following glossary of
common Python terms:

module
   the basic unit of code reusability in Python: a block of code imported by some
   other code.  Three types of modules concern us here: pure Python modules,
   extension modules, and packages.

pure Python module
   a module written in Python and contained in a single :file:`.py` file (and
   possibly associated :file:`.pyc` files).  Sometimes referred to as a
   &quot;pure module.&quot;

extension module
   a module written in the low-level language of the Python implementation: C/C++
   for Python, Java for Jython. Typically contained in a single dynamically
   loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python
   extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python
   extensions on Windows, or a Java class file for Jython extensions.  (Note that
   currently, the Distutils only handles C/C++ extensions for Python.)

package
   a module that contains other modules; typically contained in a directory in the
   filesystem and distinguished from other directories by the presence of a file
   :file:`__init__.py`.

root package
   the root of the hierarchy of packages.  (This isn't really a package, since it
   doesn't have an :file:`__init__.py` file.  But we have to call it something.)
   The vast majority of the standard library is in the root package, as are many
   small, standalone third-party modules that don't belong to a larger module
   collection. Unlike regular packages, modules in the root package can be found in
   many directories: in fact, every directory listed in ``sys.path`` contributes
   modules to the root package.


.. _distutils-term:

Distutils-specific terminology
==============================

The following terms apply more specifically to the domain of distributing Python
modules using the Distutils:

module distribution
   a collection of Python modules distributed together as a single downloadable
   resource and meant to be installed *en masse*.  Examples of some well-known
   module distributions are NumPy, SciPy, Pillow,
   or mxBase.  (This would be called a *package*, except that term is
   already taken in the Python context: a single module distribution may contain
   zero, one, or many Python packages.)

pure module distribution
   a module distribution that contains only pure Python modules and packages.
   Sometimes referred to as a &quot;pure distribution.&quot;

non-pure module distribution
   a module distribution that contains at least one extension module.  Sometimes
   referred to as a &quot;non-pure distribution.&quot;

distribution root
   the top-level directory of your source tree (or  source distribution); the
   directory where :file:`setup.py` exists.  Generally  :file:`setup.py` will be
   run from this directory.
                                                                                                                         distutils/builtdist.rst                                                                             0000644                 00000055021 15052074023 0011326 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. _built-dist:

****************************
Creating Built Distributions
****************************

.. include:: ./_setuptools_disclaimer.rst

A &quot;built distribution&quot; is what you're probably used to thinking of either as a
&quot;binary package&quot; or an &quot;installer&quot; (depending on your background).  It's not
necessarily binary, though, because it might contain only Python source code
and/or byte-code; and we don't call it a package, because that word is already
spoken for in Python.  (And &quot;installer&quot; is a term specific to the world of
mainstream desktop systems.)

A built distribution is how you make life as easy as possible for installers of
your module distribution: for users of RPM-based Linux systems, it's a binary
RPM; for Windows users, it's an executable installer; for Debian-based Linux
users, it's a Debian package; and so forth.  Obviously, no one person will be
able to create built distributions for every platform under the sun, so the
Distutils are designed to enable module developers to concentrate on their
specialty---writing code and creating source distributions---while an
intermediary species called *packagers* springs up to turn source distributions
into built distributions for as many platforms as there are packagers.

Of course, the module developer could be their own packager; or the packager could
be a volunteer &quot;out there&quot; somewhere who has access to a platform which the
original developer does not; or it could be software periodically grabbing new
source distributions and turning them into built distributions for as many
platforms as the software has access to.  Regardless of who they are, a packager
uses the setup script and the :command:`bdist` command family to generate built
distributions.

As a simple example, if I run the following command in the Distutils source
tree::

   python setup.py bdist

then the Distutils builds my module distribution (the Distutils itself in this
case), does a &quot;fake&quot; installation (also in the :file:`build` directory), and
creates the default type of built distribution for my platform.  The default
format for built distributions is a &quot;dumb&quot; tar file on Unix, and a simple
executable installer on Windows.  (That tar file is considered &quot;dumb&quot; because it
has to be unpacked in a specific location to work.)

Thus, the above command on a Unix system creates
:file:`Distutils-1.0.{plat}.tar.gz`; unpacking this tarball from the right place
installs the Distutils just as though you had downloaded the source distribution
and run ``python setup.py install``.  (The &quot;right place&quot; is either the root of
the filesystem or  Python's :file:`{prefix}` directory, depending on the options
given to the :command:`bdist_dumb` command; the default is to make dumb
distributions relative to :file:`{prefix}`.)

Obviously, for pure Python distributions, this isn't any simpler than just
running ``python setup.py install``\ ---but for non-pure distributions, which
include extensions that would need to be compiled, it can mean the difference
between someone being able to use your extensions or not.  And creating &quot;smart&quot;
built distributions, such as an RPM package or an executable installer for
Windows, is far more convenient for users even if your distribution doesn't
include any extensions.

The :command:`bdist` command has a :option:`!--formats` option, similar to the
:command:`sdist` command, which you can use to select the types of built
distribution to generate: for example, ::

   python setup.py bdist --format=zip

would, when run on a Unix system, create
:file:`Distutils-1.0.{plat}.zip`\ ---again, this archive would be unpacked
from the root directory to install the Distutils.

The available formats for built distributions are:

+-------------+------------------------------+---------+
| Format      | Description                  | Notes   |
+=============+==============================+=========+
| ``gztar``   | gzipped tar file             | \(1)    |
|             | (:file:`.tar.gz`)            |         |
+-------------+------------------------------+---------+
| ``bztar``   | bzipped tar file             |         |
|             | (:file:`.tar.bz2`)           |         |
+-------------+------------------------------+---------+
| ``xztar``   | xzipped tar file             |         |
|             | (:file:`.tar.xz`)            |         |
+-------------+------------------------------+---------+
| ``ztar``    | compressed tar file          | \(3)    |
|             | (:file:`.tar.Z`)             |         |
+-------------+------------------------------+---------+
| ``tar``     | tar file (:file:`.tar`)      |         |
+-------------+------------------------------+---------+
| ``zip``     | zip file (:file:`.zip`)      | (2),(4) |
+-------------+------------------------------+---------+
| ``rpm``     | RPM                          | \(5)    |
+-------------+------------------------------+---------+
| ``pkgtool`` | Solaris :program:`pkgtool`   |         |
+-------------+------------------------------+---------+
| ``sdux``    | HP-UX :program:`swinstall`   |         |
+-------------+------------------------------+---------+
| ``wininst`` | self-extracting ZIP file for | \(4)    |
|             | Windows                      |         |
+-------------+------------------------------+---------+
| ``msi``     | Microsoft Installer.         |         |
+-------------+------------------------------+---------+

.. versionchanged:: 3.5
   Added support for the ``xztar`` format.


Notes:

(1)
   default on Unix

(2)
   default on Windows

(3)
   requires external :program:`compress` utility.

(4)
   requires either external :program:`zip` utility or :mod:`zipfile` module (part
   of the standard Python library since Python 1.6)

(5)
   requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm
   --version`` to find out which version you have)

You don't have to use the :command:`bdist` command with the :option:`!--formats`
option; you can also use the command that directly implements the format you're
interested in.  Some of these :command:`bdist` &quot;sub-commands&quot; actually generate
several similar formats; for instance, the :command:`bdist_dumb` command
generates all the &quot;dumb&quot; archive formats (``tar``, ``gztar``, ``bztar``,
``xztar``, ``ztar``, and ``zip``), and :command:`bdist_rpm` generates both
binary and source RPMs.  The :command:`bdist` sub-commands, and the formats
generated by each, are:

+--------------------------+-------------------------------------+
| Command                  | Formats                             |
+==========================+=====================================+
| :command:`bdist_dumb`    | tar, gztar, bztar, xztar, ztar, zip |
+--------------------------+-------------------------------------+
| :command:`bdist_rpm`     | rpm, srpm                           |
+--------------------------+-------------------------------------+
| :command:`bdist_wininst` | wininst                             |
+--------------------------+-------------------------------------+
| :command:`bdist_msi`     | msi                                 |
+--------------------------+-------------------------------------+

.. note::
   bdist_wininst is deprecated since Python 3.8.

.. note::
   bdist_msi is deprecated since Python 3.9.

The following sections give details on the individual :command:`bdist_\*`
commands.


.. .. _creating-dumb:

.. Creating dumb built distributions
.. =================================

.. XXX Need to document absolute vs. prefix-relative packages here, but first
   I have to implement it!


.. _creating-rpms:

Creating RPM packages
=====================

The RPM format is used by many popular Linux distributions, including Red Hat,
SuSE, and Mandrake.  If one of these (or any of the other RPM-based Linux
distributions) is your usual environment, creating RPM packages for other users
of that same distribution is trivial. Depending on the complexity of your module
distribution and differences between Linux distributions, you may also be able
to create RPMs that work on different RPM-based distributions.

The usual way to create an RPM of your module distribution is to run the
:command:`bdist_rpm` command::

   python setup.py bdist_rpm

or the :command:`bdist` command with the :option:`!--format` option::

   python setup.py bdist --formats=rpm

The former allows you to specify RPM-specific options; the latter allows  you to
easily specify multiple formats in one run.  If you need to do both, you can
explicitly specify multiple :command:`bdist_\*` commands and their options::

   python setup.py bdist_rpm --packager=&quot;John Doe &lt;jdoe@example.org&gt;&quot; \
                   bdist_wininst --target-version=&quot;2.0&quot;

Creating RPM packages is driven by a :file:`.spec` file, much as using the
Distutils is driven by the setup script.  To make your life easier, the
:command:`bdist_rpm` command normally creates a :file:`.spec` file based on the
information you supply in the setup script, on the command line, and in any
Distutils configuration files.  Various options and sections in the
:file:`.spec` file are derived from options in the setup script as follows:

+------------------------------------------+----------------------------------------------+
| RPM :file:`.spec` file option or section | Distutils setup script option                |
+==========================================+==============================================+
| Name                                     | ``name``                                     |
+------------------------------------------+----------------------------------------------+
| Summary (in preamble)                    | ``description``                              |
+------------------------------------------+----------------------------------------------+
| Version                                  | ``version``                                  |
+------------------------------------------+----------------------------------------------+
| Vendor                                   | ``author`` and ``author_email``,             |
|                                          | or  --- &amp; ``maintainer`` and                 |
|                                          | ``maintainer_email``                         |
+------------------------------------------+----------------------------------------------+
| Copyright                                | ``license``                                  |
+------------------------------------------+----------------------------------------------+
| Url                                      | ``url``                                      |
+------------------------------------------+----------------------------------------------+
| %description (section)                   | ``long_description``                         |
+------------------------------------------+----------------------------------------------+

Additionally, there are many options in :file:`.spec` files that don't have
corresponding options in the setup script.  Most of these are handled through
options to the :command:`bdist_rpm` command as follows:

+-------------------------------+-----------------------------+-------------------------+
| RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value           |
| or section                    |                             |                         |
+===============================+=============================+=========================+
| Release                       | ``release``                 | &quot;1&quot;                     |
+-------------------------------+-----------------------------+-------------------------+
| Group                         | ``group``                   | &quot;Development/Libraries&quot; |
+-------------------------------+-----------------------------+-------------------------+
| Vendor                        | ``vendor``                  | (see above)             |
+-------------------------------+-----------------------------+-------------------------+
| Packager                      | ``packager``                | (none)                  |
+-------------------------------+-----------------------------+-------------------------+
| Provides                      | ``provides``                | (none)                  |
+-------------------------------+-----------------------------+-------------------------+
| Requires                      | ``requires``                | (none)                  |
+-------------------------------+-----------------------------+-------------------------+
| Conflicts                     | ``conflicts``               | (none)                  |
+-------------------------------+-----------------------------+-------------------------+
| Obsoletes                     | ``obsoletes``               | (none)                  |
+-------------------------------+-----------------------------+-------------------------+
| Distribution                  | ``distribution_name``       | (none)                  |
+-------------------------------+-----------------------------+-------------------------+
| BuildRequires                 | ``build_requires``          | (none)                  |
+-------------------------------+-----------------------------+-------------------------+
| Icon                          | ``icon``                    | (none)                  |
+-------------------------------+-----------------------------+-------------------------+

Obviously, supplying even a few of these options on the command-line would be
tedious and error-prone, so it's usually best to put them in the setup
configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`.  If
you distribute or package many Python module distributions, you might want to
put options that apply to all of them in your personal Distutils configuration
file (:file:`~/.pydistutils.cfg`).  If you want to temporarily disable
this file, you can pass the :option:`!--no-user-cfg` option to :file:`setup.py`.

There are three steps to building a binary RPM package, all of which are
handled automatically by the Distutils:

#. create a :file:`.spec` file, which describes the package (analogous  to the
   Distutils setup script; in fact, much of the information in the  setup script
   winds up in the :file:`.spec` file)

#. create the source RPM

#. create the &quot;binary&quot; RPM (which may or may not contain binary code, depending
   on whether your module distribution contains Python extensions)

Normally, RPM bundles the last two steps together; when you use the Distutils,
all three steps are typically bundled together.

If you wish, you can separate these three steps.  You can use the
:option:`!--spec-only` option to make :command:`bdist_rpm` just create the
:file:`.spec` file and exit; in this case, the :file:`.spec` file will be
written to the &quot;distribution directory&quot;---normally :file:`dist/`, but
customizable with the :option:`!--dist-dir` option.  (Normally, the :file:`.spec`
file winds up deep in the &quot;build tree,&quot; in a temporary directory created by
:command:`bdist_rpm`.)

.. % \XXX{this isn't implemented yet---is it needed?!}
.. % You can also specify a custom \file{.spec} file with the
.. % \longprogramopt{spec-file} option; used in conjunction with
.. % \longprogramopt{spec-only}, this gives you an opportunity to customize
.. % the \file{.spec} file manually:
.. %
.. % \ begin{verbatim}
.. % &gt; python setup.py bdist_rpm --spec-only
.. % # ...edit dist/FooBar-1.0.spec
.. % &gt; python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec
.. % \ end{verbatim}
.. %
.. % (Although a better way to do this is probably to override the standard
.. % \command{bdist\_rpm} command with one that writes whatever else you want
.. % to the \file{.spec} file.)


.. _creating-wininst:

Creating Windows Installers
===========================

.. warning::
   bdist_wininst is deprecated since Python 3.8.

.. warning::
   bdist_msi is deprecated since Python 3.9.

Executable installers are the natural format for binary distributions on
Windows.  They display a nice graphical user interface, display some information
about the module distribution to be installed taken from the metadata in the
setup script, let the user select a few options, and start or cancel the
installation.

Since the metadata is taken from the setup script, creating Windows installers
is usually as easy as running::

   python setup.py bdist_wininst

or the :command:`bdist` command with the :option:`!--formats` option::

   python setup.py bdist --formats=wininst

If you have a pure module distribution (only containing pure Python modules and
packages), the resulting installer will be version independent and have a name
like :file:`foo-1.0.win32.exe`. Note that creating ``wininst`` binary
distributions in only supported on Windows systems.

If you have a non-pure distribution, the extensions can only be created on a
Windows platform, and will be Python version dependent. The installer filename
will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`.  You
have to create a separate installer for every Python version you want to
support.

The installer will try to compile pure modules into :term:`bytecode` after installation
on the target system in normal and optimizing mode.  If you don't want this to
happen for some reason, you can run the :command:`bdist_wininst` command with
the :option:`!--no-target-compile` and/or the :option:`!--no-target-optimize`
option.

By default the installer will display the cool &quot;Python Powered&quot; logo when it is
run, but you can also supply your own 152x261 bitmap which must be a Windows
:file:`.bmp` file with the :option:`!--bitmap` option.

The installer will also display a large title on the desktop background window
when it is run, which is constructed from the name of your distribution and the
version number.  This can be changed to another text by using the
:option:`!--title` option.

The installer file will be written to the &quot;distribution directory&quot; --- normally
:file:`dist/`, but customizable with the :option:`!--dist-dir` option.

.. _cross-compile-windows:

Cross-compiling on Windows
==========================

Starting with Python 2.6, distutils is capable of cross-compiling between
Windows platforms.  In practice, this means that with the correct tools
installed, you can use a 32bit version of Windows to create 64bit extensions
and vice-versa.

To build for an alternate platform, specify the :option:`!--plat-name` option
to the build command.  Valid values are currently 'win32', and  'win-amd64'.
For example, on a 32bit version of Windows, you could execute::

   python setup.py build --plat-name=win-amd64

to build a 64bit version of your extension.  The Windows Installers also
support this option, so the command::

   python setup.py build --plat-name=win-amd64 bdist_wininst

would create a 64bit installation executable on your 32bit version of Windows.

To cross-compile, you must download the Python source code and cross-compile
Python itself for the platform you are targeting - it is not possible from a
binary installation of Python (as the .lib etc file for other platforms are
not included.)  In practice, this means the user of a 32 bit operating
system will need to use Visual Studio 2008 to open the
:file:`PCbuild/PCbuild.sln` solution in the Python source tree and build the
&quot;x64&quot; configuration of the 'pythoncore' project before cross-compiling
extensions is possible.

Note that by default, Visual Studio 2008 does not install 64bit compilers or
tools.  You may need to reexecute the Visual Studio setup process and select
these tools (using Control Panel-&gt;[Add/Remove] Programs is a convenient way to
check or modify your existing install.)

.. _postinstallation-script:

The Postinstallation script
---------------------------

Starting with Python 2.3, a postinstallation script can be specified with the
:option:`!--install-script` option.  The basename of the script must be
specified, and the script filename must also be listed in the scripts argument
to the setup function.

This script will be run at installation time on the target system after all the
files have been copied, with ``argv[1]`` set to :option:`!-install`, and again at
uninstallation time before the files are removed with ``argv[1]`` set to
:option:`!-remove`.

The installation script runs embedded in the windows installer, every output
(``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be
displayed in the GUI after the script has finished.

Some functions especially useful in this context are available as additional
built-in functions in the installation script.


.. function:: directory_created(path)
              file_created(path)

   These functions should be called when a directory or file is created by the
   postinstall script at installation time.  It will register *path* with the
   uninstaller, so that it will be removed when the distribution is uninstalled.
   To be safe, directories are only removed if they are empty.


.. function:: get_special_folder_path(csidl_string)

   This function can be used to retrieve special folder locations on Windows like
   the Start Menu or the Desktop.  It returns the full path to the folder.
   *csidl_string* must be one of the following strings::

      &quot;CSIDL_APPDATA&quot;

      &quot;CSIDL_COMMON_STARTMENU&quot;
      &quot;CSIDL_STARTMENU&quot;

      &quot;CSIDL_COMMON_DESKTOPDIRECTORY&quot;
      &quot;CSIDL_DESKTOPDIRECTORY&quot;

      &quot;CSIDL_COMMON_STARTUP&quot;
      &quot;CSIDL_STARTUP&quot;

      &quot;CSIDL_COMMON_PROGRAMS&quot;
      &quot;CSIDL_PROGRAMS&quot;

      &quot;CSIDL_FONTS&quot;

   If the folder cannot be retrieved, :exc:`OSError` is raised.

   Which folders are available depends on the exact Windows version, and probably
   also the configuration.  For details refer to Microsoft's documentation of the
   :c:func:`SHGetSpecialFolderPath` function.


.. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]])

   This function creates a shortcut. *target* is the path to the program to be
   started by the shortcut. *description* is the description of the shortcut.
   *filename* is the title of the shortcut that the user will see. *arguments*
   specifies the command line arguments, if any. *workdir* is the working directory
   for the program. *iconpath* is the file containing the icon for the shortcut,
   and *iconindex* is the index of the icon in the file *iconpath*.  Again, for
   details consult the Microsoft documentation for the :class:`IShellLink`
   interface.


Vista User Access Control (UAC)
===============================

Starting with Python 2.6, bdist_wininst supports a :option:`!--user-access-control`
option.  The default is 'none' (meaning no UAC handling is done), and other
valid values are 'auto' (meaning prompt for UAC elevation if Python was
installed for all users) and 'force' (meaning always prompt for elevation).

.. note::
   bdist_wininst is deprecated since Python 3.8.

.. note::
   bdist_msi is deprecated since Python 3.9.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               distutils/setupscript.rst                                                                           0000644                 00000075204 15052074023 0011715 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. _setup-script:

************************
Writing the Setup Script
************************

.. include:: ./_setuptools_disclaimer.rst

The setup script is the centre of all activity in building, distributing, and
installing modules using the Distutils.  The main purpose of the setup script is
to describe your module distribution to the Distutils, so that the various
commands that operate on your modules do the right thing.  As we saw in section
:ref:`distutils-simple-example` above, the setup script consists mainly of a call to :func:`~distutils.core.setup`, and most information
supplied to the Distutils by the module developer is supplied as keyword
arguments to :func:`~distutils.core.setup`.

Here's a slightly more involved example, which we'll follow for the next couple
of sections: the Distutils' own setup script.  (Keep in mind that although the
Distutils are included with Python 1.6 and later, they also have an independent
existence so that Python 1.5.2 users can use them to install other module
distributions.  The Distutils' own setup script, shown here, is used to install
the package into Python 1.5.2.) ::

    #!/usr/bin/env python

    from distutils.core import setup

    setup(name='Distutils',
          version='1.0',
          description='Python Distribution Utilities',
          author='Greg Ward',
          author_email='gward@python.net',
          url='https://www.python.org/sigs/distutils-sig/',
          packages=['distutils', 'distutils.command'],
         )

There are only two differences between this and the trivial one-file
distribution presented in section :ref:`distutils-simple-example`: more metadata, and the
specification of pure Python modules by package, rather than by module.  This is
important since the Distutils consist of a couple of dozen modules split into
(so far) two packages; an explicit list of every module would be tedious to
generate and difficult to maintain.  For more information on the additional
meta-data, see section :ref:`meta-data`.

Note that any pathnames (files or directories) supplied in the setup script
should be written using the Unix convention, i.e. slash-separated.  The
Distutils will take care of converting this platform-neutral representation into
whatever is appropriate on your current platform before actually using the
pathname.  This makes your setup script portable across operating systems, which
of course is one of the major goals of the Distutils.  In this spirit, all
pathnames in this document are slash-separated.

This, of course, only applies to pathnames given to Distutils functions.  If
you, for example, use standard Python functions such as :func:`glob.glob` or
:func:`os.listdir` to specify files, you should be careful to write portable
code instead of hardcoding path separators::

    glob.glob(os.path.join('mydir', 'subdir', '*.html'))
    os.listdir(os.path.join('mydir', 'subdir'))


.. _listing-packages:

Listing whole packages
======================

The ``packages`` option tells the Distutils to process (build, distribute,
install, etc.) all pure Python modules found in each package mentioned in the
``packages`` list.  In order to do this, of course, there has to be a
correspondence between package names and directories in the filesystem.  The
default correspondence is the most obvious one, i.e. package :mod:`distutils` is
found in the directory :file:`distutils` relative to the distribution root.
Thus, when you say ``packages = ['foo']`` in your setup script, you are
promising that the Distutils will find a file :file:`foo/__init__.py` (which
might be spelled differently on your system, but you get the idea) relative to
the directory where your setup script lives.  If you break this promise, the
Distutils will issue a warning but still process the broken package anyway.

If you use a different convention to lay out your source directory, that's no
problem: you just have to supply the ``package_dir`` option to tell the
Distutils about your convention.  For example, say you keep all Python source
under :file:`lib`, so that modules in the &quot;root package&quot; (i.e., not in any
package at all) are in :file:`lib`, modules in the ``foo`` package are in
:file:`lib/foo`, and so forth.  Then you would put ::

    package_dir = {'': 'lib'}

in your setup script.  The keys to this dictionary are package names, and an
empty package name stands for the root package.  The values are directory names
relative to your distribution root.  In this case, when you say ``packages =
['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists.

Another possible convention is to put the ``foo`` package right in
:file:`lib`, the ``foo.bar`` package in :file:`lib/bar`, etc.  This would be
written in the setup script as ::

    package_dir = {'foo': 'lib'}

A ``package: dir`` entry in the ``package_dir`` dictionary implicitly
applies to all packages below *package*, so the ``foo.bar`` case is
automatically handled here.  In this example, having ``packages = ['foo',
'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and
:file:`lib/bar/__init__.py`.  (Keep in mind that although ``package_dir``
applies recursively, you must explicitly list all packages in
``packages``: the Distutils will *not* recursively scan your source tree
looking for any directory with an :file:`__init__.py` file.)


.. _listing-modules:

Listing individual modules
==========================

For a small module distribution, you might prefer to list all modules rather
than listing packages---especially the case of a single module that goes in the
&quot;root package&quot; (i.e., no package at all).  This simplest case was shown in
section :ref:`distutils-simple-example`; here is a slightly more involved example::

    py_modules = ['mod1', 'pkg.mod2']

This describes two modules, one of them in the &quot;root&quot; package, the other in the
``pkg`` package.  Again, the default package/directory layout implies that
these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and
that :file:`pkg/__init__.py` exists as well. And again, you can override the
package/directory correspondence using the ``package_dir`` option.


.. _describing-extensions:

Describing extension modules
============================

Just as writing Python extension modules is a bit more complicated than writing
pure Python modules, describing them to the Distutils is a bit more complicated.
Unlike pure modules, it's not enough just to list modules or packages and expect
the Distutils to go out and find the right files; you have to specify the
extension name, source file(s), and any compile/link requirements (include
directories, libraries to link with, etc.).

.. XXX read over this section

All of this is done through another keyword argument to
:func:`~distutils.core.setup`, the
``ext_modules`` option.  ``ext_modules`` is just a list of
:class:`~distutils.core.Extension` instances, each of which describes a
single extension module.
Suppose your distribution includes a single extension, called ``foo`` and
implemented by :file:`foo.c`.  If no additional instructions to the
compiler/linker are needed, describing this extension is quite simple::

    Extension('foo', ['foo.c'])

The :class:`~distutils.extension.Extension` class can be imported from :mod:`distutils.core` along
with :func:`~distutils.core.setup`.  Thus, the setup script for a module distribution that
contains only this one extension and nothing else might be::

    from distutils.core import setup, Extension
    setup(name='foo',
          version='1.0',
          ext_modules=[Extension('foo', ['foo.c'])],
          )

The :class:`~distutils.extension.Extension` class (actually, the underlying extension-building
machinery implemented by the :command:`build_ext` command) supports a great deal
of flexibility in describing Python extensions, which is explained in the
following sections.


Extension names and packages
----------------------------

The first argument to the :class:`~distutils.core.Extension` constructor is
always the name of the extension, including any package names.  For example, ::

    Extension('foo', ['src/foo1.c', 'src/foo2.c'])

describes an extension that lives in the root package, while ::

    Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])

describes the same extension in the ``pkg`` package.  The source files and
resulting object code are identical in both cases; the only difference is where
in the filesystem (and therefore where in Python's namespace hierarchy) the
resulting extension lives.

If you have a number of extensions all in the same package (or all under the
same base package), use the ``ext_package`` keyword argument to
:func:`~distutils.core.setup`.  For example, ::

    setup(...,
          ext_package='pkg',
          ext_modules=[Extension('foo', ['foo.c']),
                       Extension('subpkg.bar', ['bar.c'])],
         )

will compile :file:`foo.c` to the extension ``pkg.foo``, and
:file:`bar.c` to ``pkg.subpkg.bar``.


Extension source files
----------------------

The second argument to the :class:`~distutils.core.Extension` constructor is
a list of source
files.  Since the Distutils currently only support C, C++, and Objective-C
extensions, these are normally C/C++/Objective-C source files.  (Be sure to use
appropriate extensions to distinguish C++ source files: :file:`.cc` and
:file:`.cpp` seem to be recognized by both Unix and Windows compilers.)

However, you can also include SWIG interface (:file:`.i`) files in the list; the
:command:`build_ext` command knows how to deal with SWIG extensions: it will run
SWIG on the interface file and compile the resulting C/C++ file into your
extension.

.. XXX SWIG support is rough around the edges and largely untested!

This warning notwithstanding, options to SWIG can be currently passed like
this::

    setup(...,
          ext_modules=[Extension('_foo', ['foo.i'],
                                 swig_opts=['-modern', '-I../include'])],
          py_modules=['foo'],
         )

Or on the commandline like this::

    &gt; python setup.py build_ext --swig-opts=&quot;-modern -I../include&quot;

On some platforms, you can include non-source files that are processed by the
compiler and included in your extension.  Currently, this just means Windows
message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for
Visual C++. These will be compiled to binary resource (:file:`.res`) files and
linked into the executable.


Preprocessor options
--------------------

Three optional arguments to :class:`~distutils.core.Extension` will help if
you need to specify include directories to search or preprocessor macros to
define/undefine: ``include_dirs``, ``define_macros``, and ``undef_macros``.

For example, if your extension requires header files in the :file:`include`
directory under your distribution root, use the ``include_dirs`` option::

    Extension('foo', ['foo.c'], include_dirs=['include'])

You can specify absolute directories there; if you know that your extension will
only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get
away with ::

    Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])

You should avoid this sort of non-portable usage if you plan to distribute your
code: it's probably better to write C code like  ::

    #include &lt;X11/Xlib.h&gt;

If you need to include header files from some other Python extension, you can
take advantage of the fact that header files are installed in a consistent way
by the Distutils :command:`install_headers` command.  For example, the Numerical
Python header files are installed (on a standard Unix installation) to
:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
according to your platform and Python installation.)  Since the Python include
directory---\ :file:`/usr/local/include/python1.5` in this case---is always
included in the search path when building Python extensions, the best approach
is to write C code like  ::

    #include &lt;Numerical/arrayobject.h&gt;

If you must put the :file:`Numerical` include directory right into your header
search path, though, you can find that directory using the Distutils
:mod:`distutils.sysconfig` module::

    from distutils.sysconfig import get_python_inc
    incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
    setup(...,
          Extension(..., include_dirs=[incdir]),
          )

Even though this is quite portable---it will work on any Python installation,
regardless of platform---it's probably easier to just write your C code in the
sensible way.

You can define and undefine pre-processor macros with the ``define_macros`` and
``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)``
tuples, where ``name`` is the name of the macro to define (a string) and
``value`` is its value: either a string or ``None``.  (Defining a macro ``FOO``
to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with
most compilers, this sets ``FOO`` to the string ``1``.)  ``undef_macros`` is
just a list of macros to undefine.

For example::

    Extension(...,
              define_macros=[('NDEBUG', '1'),
                             ('HAVE_STRFTIME', None)],
              undef_macros=['HAVE_FOO', 'HAVE_BAR'])

is the equivalent of having this at the top of every C source file::

    #define NDEBUG 1
    #define HAVE_STRFTIME
    #undef HAVE_FOO
    #undef HAVE_BAR


Library options
---------------

You can also specify the libraries to link against when building your extension,
and the directories to search for those libraries.  The ``libraries`` option is
a list of libraries to link against, ``library_dirs`` is a list of directories
to search for libraries at  link-time, and ``runtime_library_dirs`` is a list of
directories to  search for shared (dynamically loaded) libraries at run-time.

For example, if you need to link against libraries known to be in the standard
library search path on target systems ::

    Extension(...,
              libraries=['gdbm', 'readline'])

If you need to link with libraries in a non-standard location, you'll have to
include the location in ``library_dirs``::

    Extension(...,
              library_dirs=['/usr/X11R6/lib'],
              libraries=['X11', 'Xt'])

(Again, this sort of non-portable construct should be avoided if you intend to
distribute your code.)

.. XXX Should mention clib libraries here or somewhere else!


Other options
-------------

There are still some other options which can be used to handle special cases.

The ``optional`` option is a boolean; if it is true,
a build failure in the extension will not abort the build process, but
instead simply not install the failing extension.

The ``extra_objects`` option is a list of object files to be passed to the
linker. These files must not have extensions, as the default extension for the
compiler is used.

``extra_compile_args`` and ``extra_link_args`` can be used to
specify additional command line options for the respective compiler and linker
command lines.

``export_symbols`` is only useful on Windows.  It can contain a list of
symbols (functions or variables) to be exported. This option is not needed when
building compiled extensions: Distutils  will automatically add ``initmodule``
to the list of exported symbols.

The ``depends`` option is a list of files that the extension depends on
(for example header files). The build command will call the compiler on the
sources to rebuild extension if any on this files has been modified since the
previous build.

Relationships between Distributions and Packages
================================================

A distribution may relate to packages in three specific ways:

#. It can require packages or modules.

#. It can provide packages or modules.

#. It can obsolete packages or modules.

These relationships can be specified using keyword arguments to the
:func:`distutils.core.setup` function.

Dependencies on other Python modules and packages can be specified by supplying
the *requires* keyword argument to :func:`~distutils.core.setup`. The
value must be a list of
strings.  Each string specifies a package that is required, and optionally what
versions are sufficient.

To specify that any version of a module or package is required, the string
should consist entirely of the module or package name. Examples include
``'mymodule'`` and ``'xml.parsers.expat'``.

If specific versions are required, a sequence of qualifiers can be supplied in
parentheses.  Each qualifier may consist of a comparison operator and a version
number.  The accepted comparison operators are::

    &lt;    &gt;    ==
    &lt;=   &gt;=   !=

These can be combined by using multiple qualifiers separated by commas (and
optional whitespace).  In this case, all of the qualifiers must be matched; a
logical AND is used to combine the evaluations.

Let's look at a bunch of examples:

+-------------------------+----------------------------------------------+
| Requires Expression     | Explanation                                  |
+=========================+==============================================+
| ``==1.0``               | Only version ``1.0`` is compatible           |
+-------------------------+----------------------------------------------+
| ``&gt;1.0, !=1.5.1, &lt;2.0`` | Any version after ``1.0`` and before ``2.0`` |
|                         | is compatible, except ``1.5.1``              |
+-------------------------+----------------------------------------------+

Now that we can specify dependencies, we also need to be able to specify what we
provide that other distributions can require.  This is done using the *provides*
keyword argument to :func:`~distutils.core.setup`. The value for this keyword is a list of
strings, each of which names a Python module or package, and optionally
identifies the version.  If the version is not specified, it is assumed to match
that of the distribution.

Some examples:

+---------------------+----------------------------------------------+
| Provides Expression | Explanation                                  |
+=====================+==============================================+
| ``mypkg``           | Provide ``mypkg``, using the distribution    |
|                     | version                                      |
+---------------------+----------------------------------------------+
| ``mypkg (1.1)``     | Provide ``mypkg`` version 1.1, regardless of |
|                     | the distribution version                     |
+---------------------+----------------------------------------------+

A package can declare that it obsoletes other packages using the *obsoletes*
keyword argument.  The value for this is similar to that of the *requires*
keyword: a list of strings giving module or package specifiers.  Each specifier
consists of a module or package name optionally followed by one or more version
qualifiers.  Version qualifiers are given in parentheses after the module or
package name.

The versions identified by the qualifiers are those that are obsoleted by the
distribution being described.  If no qualifiers are given, all versions of the
named module or package are understood to be obsoleted.

.. _distutils-installing-scripts:

Installing Scripts
==================

So far we have been dealing with pure and non-pure Python modules, which are
usually not run by themselves but imported by scripts.

Scripts are files containing Python source code, intended to be started from the
command line.  Scripts don't require Distutils to do anything very complicated.
The only clever feature is that if the first line of the script starts with
``#!`` and contains the word &quot;python&quot;, the Distutils will adjust the first line
to refer to the current interpreter location. By default, it is replaced with
the current interpreter location.  The :option:`!--executable` (or :option:`!-e`)
option will allow the interpreter path to be explicitly overridden.

The ``scripts`` option simply is a list of files to be handled in this
way.  From the PyXML setup script::

    setup(...,
          scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
          )

.. versionchanged:: 3.1
   All the scripts will also be added to the ``MANIFEST`` file if no template is
   provided.  See :ref:`manifest`.


.. _distutils-installing-package-data:

Installing Package Data
=======================

Often, additional files need to be installed into a package.  These files are
often data that's closely related to the package's implementation, or text files
containing documentation that might be of interest to programmers using the
package.  These files are called :dfn:`package data`.

Package data can be added to packages using the ``package_data`` keyword
argument to the :func:`~distutils.core.setup` function.  The value must be a mapping from
package name to a list of relative path names that should be copied into the
package.  The paths are interpreted as relative to the directory containing the
package (information from the ``package_dir`` mapping is used if appropriate);
that is, the files are expected to be part of the package in the source
directories. They may contain glob patterns as well.

The path names may contain directory portions; any necessary directories will be
created in the installation.

For example, if a package should contain a subdirectory with several data files,
the files can be arranged like this in the source tree::

    setup.py
    src/
        mypkg/
            __init__.py
            module.py
            data/
                tables.dat
                spoons.dat
                forks.dat

The corresponding call to :func:`~distutils.core.setup` might be::

    setup(...,
          packages=['mypkg'],
          package_dir={'mypkg': 'src/mypkg'},
          package_data={'mypkg': ['data/*.dat']},
          )


.. versionchanged:: 3.1
   All the files that match ``package_data`` will be added to the ``MANIFEST``
   file if no template is provided.  See :ref:`manifest`.


.. _distutils-additional-files:

Installing Additional Files
===========================

The ``data_files`` option can be used to specify additional files needed
by the module distribution: configuration files, message catalogs, data files,
anything which doesn't fit in the previous categories.

``data_files`` specifies a sequence of (*directory*, *files*) pairs in the
following way::

    setup(...,
          data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
                      ('config', ['cfg/data.cfg'])],
         )

Each (*directory*, *files*) pair in the sequence specifies the installation
directory and the files to install there.

Each file name in *files* is interpreted relative to the :file:`setup.py`
script at the top of the package source distribution. Note that you can
specify the directory where the data files will be installed, but you cannot
rename the data files themselves.

The *directory* should be a relative path. It is interpreted relative to the
installation prefix (Python's ``sys.prefix`` for system installations;
``site.USER_BASE`` for user installations). Distutils allows *directory* to be
an absolute installation path, but this is discouraged since it is
incompatible with the wheel packaging format. No directory information from
*files* is used to determine the final location of the installed file; only
the name of the file is used.

You can specify the ``data_files`` options as a simple sequence of files
without specifying a target directory, but this is not recommended, and the
:command:`install` command will print a warning in this case. To install data
files directly in the target directory, an empty string should be given as the
directory.

.. versionchanged:: 3.1
   All the files that match ``data_files`` will be added to the ``MANIFEST``
   file if no template is provided.  See :ref:`manifest`.


.. _meta-data:

Additional meta-data
====================

The setup script may include additional meta-data beyond the name and version.
This information includes:

+----------------------+---------------------------+-----------------+--------+
| Meta-Data            | Description               | Value           | Notes  |
+======================+===========================+=================+========+
| ``name``             | name of the package       | short string    | \(1)   |
+----------------------+---------------------------+-----------------+--------+
| ``version``          | version of this release   | short string    | (1)(2) |
+----------------------+---------------------------+-----------------+--------+
| ``author``           | package author's name     | short string    | \(3)   |
+----------------------+---------------------------+-----------------+--------+
| ``author_email``     | email address of the      | email address   | \(3)   |
|                      | package author            |                 |        |
+----------------------+---------------------------+-----------------+--------+
| ``maintainer``       | package maintainer's name | short string    | \(3)   |
+----------------------+---------------------------+-----------------+--------+
| ``maintainer_email`` | email address of the      | email address   | \(3)   |
|                      | package maintainer        |                 |        |
+----------------------+---------------------------+-----------------+--------+
| ``url``              | home page for the package | URL             | \(1)   |
+----------------------+---------------------------+-----------------+--------+
| ``description``      | short, summary            | short string    |        |
|                      | description of the        |                 |        |
|                      | package                   |                 |        |
+----------------------+---------------------------+-----------------+--------+
| ``long_description`` | longer description of the | long string     | \(4)   |
|                      | package                   |                 |        |
+----------------------+---------------------------+-----------------+--------+
| ``download_url``     | location where the        | URL             |        |
|                      | package may be downloaded |                 |        |
+----------------------+---------------------------+-----------------+--------+
| ``classifiers``      | a list of classifiers     | list of strings | (6)(7) |
+----------------------+---------------------------+-----------------+--------+
| ``platforms``        | a list of platforms       | list of strings | (6)(8) |
+----------------------+---------------------------+-----------------+--------+
| ``keywords``         | a list of keywords        | list of strings | (6)(8) |
+----------------------+---------------------------+-----------------+--------+
| ``license``          | license for the package   | short string    | \(5)   |
+----------------------+---------------------------+-----------------+--------+

Notes:

(1)
    These fields are required.

(2)
    It is recommended that versions take the form *major.minor[.patch[.sub]]*.

(3)
    Either the author or the maintainer must be identified. If maintainer is
    provided, distutils lists it as the author in :file:`PKG-INFO`.

(4)
    The ``long_description`` field is used by PyPI when you publish a package,
    to build its project page.

(5)
    The ``license`` field is a text indicating the license covering the
    package where the license is not a selection from the &quot;License&quot; Trove
    classifiers. See the ``Classifier`` field. Notice that
    there's a ``licence`` distribution option which is deprecated but still
    acts as an alias for ``license``.

(6)
    This field must be a list.

(7)
    The valid classifiers are listed on
    `PyPI &lt;https://pypi.org/classifiers&gt;`_.

(8)
    To preserve backward compatibility, this field also accepts a string. If
    you pass a comma-separated string ``'foo, bar'``, it will be converted to
    ``['foo', 'bar']``, Otherwise, it will be converted to a list of one
    string.

'short string'
    A single line of text, not more than 200 characters.

'long string'
    Multiple lines of plain text in reStructuredText format (see
    http://docutils.sourceforge.net/).

'list of strings'
    See below.

Encoding the version information is an art in itself. Python packages generally
adhere to the version format *major.minor[.patch][sub]*. The major number is 0
for initial, experimental releases of software. It is incremented for releases
that represent major milestones in a package. The minor number is incremented
when important new features are added to the package. The patch number
increments when bug-fix releases are made. Additional trailing version
information is sometimes used to indicate sub-releases.  These are
&quot;a1,a2,...,aN&quot; (for alpha releases, where functionality and API may change),
&quot;b1,b2,...,bN&quot; (for beta releases, which only fix bugs) and &quot;pr1,pr2,...,prN&quot;
(for final pre-release release testing). Some examples:

0.1.0
    the first, experimental release of a package

1.0.1a2
    the second alpha release of the first patch version of 1.0

``classifiers`` must be specified in a list::

    setup(...,
          classifiers=[
              'Development Status :: 4 - Beta',
              'Environment :: Console',
              'Environment :: Web Environment',
              'Intended Audience :: End Users/Desktop',
              'Intended Audience :: Developers',
              'Intended Audience :: System Administrators',
              'License :: OSI Approved :: Python Software Foundation License',
              'Operating System :: MacOS :: MacOS X',
              'Operating System :: Microsoft :: Windows',
              'Operating System :: POSIX',
              'Programming Language :: Python',
              'Topic :: Communications :: Email',
              'Topic :: Office/Business',
              'Topic :: Software Development :: Bug Tracking',
              ],
          )

.. versionchanged:: 3.7
   :class:`~distutils.core.setup` now warns when ``classifiers``, ``keywords``
   or ``platforms`` fields are not specified as a list or a string.

.. _debug-setup-script:

Debugging the setup script
==========================

Sometimes things go wrong, and the setup script doesn't do what the developer
wants.

Distutils catches any exceptions when running the setup script, and print a
simple error message before the script is terminated.  The motivation for this
behaviour is to not confuse administrators who don't know much about Python and
are trying to install a package.  If they get a big long traceback from deep
inside the guts of Distutils, they may think the package or the Python
installation is broken because they don't read all the way down to the bottom
and see that it's a permission problem.

On the other hand, this doesn't help the developer to find the cause of the
failure. For this purpose, the :envvar:`DISTUTILS_DEBUG` environment variable can be set
to anything except an empty string, and distutils will now print detailed
information about what it is doing, dump the full traceback when an exception
occurs, and print the whole command line when an external program (like a C
compiler) fails.
                                                                                                                                                                                                                                                                                                                                                                                            distutils/extending.rst                                                                             0000644                 00000010760 15052074023 0011311 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. _extending-distutils:

*******************
Extending Distutils
*******************

.. include:: ./_setuptools_disclaimer.rst

Distutils can be extended in various ways.  Most extensions take the form of new
commands or replacements for existing commands.  New commands may be written to
support new types of platform-specific packaging, for example, while
replacements for existing commands may be made to modify details of how the
command operates on a package.

Most extensions of the distutils are made within :file:`setup.py` scripts that
want to modify existing commands; many simply add a few file extensions that
should be copied into packages in addition to :file:`.py` files as a
convenience.

Most distutils command implementations are subclasses of the
:class:`distutils.cmd.Command` class.  New commands may directly inherit from
:class:`~distutils.cmd.Command`, while replacements often derive from :class:`~distutils.cmd.Command`
indirectly, directly subclassing the command they are replacing.  Commands are
required to derive from :class:`~distutils.cmd.Command`.

.. % \section{Extending existing commands}
.. % \label{extend-existing}

.. % \section{Writing new commands}
.. % \label{new-commands}
.. % \XXX{Would an uninstall command be a good example here?}


Integrating new commands
========================

There are different ways to integrate new command implementations into
distutils.  The most difficult is to lobby for the inclusion of the new features
in distutils itself, and wait for (and require) a version of Python that
provides that support.  This is really hard for many reasons.

The most common, and possibly the most reasonable for most needs, is to include
the new implementations with your :file:`setup.py` script, and cause the
:func:`distutils.core.setup` function use them::

   from distutils.command.build_py import build_py as _build_py
   from distutils.core import setup

   class build_py(_build_py):
       &quot;&quot;&quot;Specialized Python source builder.&quot;&quot;&quot;

       # implement whatever needs to be different...

   setup(cmdclass={'build_py': build_py},
         ...)

This approach is most valuable if the new implementations must be used to use a
particular package, as everyone interested in the package will need to have the
new command implementation.

Beginning with Python 2.4, a third option is available, intended to allow new
commands to be added which can support existing :file:`setup.py` scripts without
requiring modifications to the Python installation.  This is expected to allow
third-party extensions to provide support for additional packaging systems, but
the commands can be used for anything distutils commands can be used for.  A new
configuration option, ``command_packages`` (command-line option
:option:`!--command-packages`), can be used to specify additional packages to be
searched for modules implementing commands.  Like all distutils options, this
can be specified on the command line or in a configuration file.  This option
can only be set in the ``[global]`` section of a configuration file, or before
any commands on the command line.  If set in a configuration file, it can be
overridden from the command line; setting it to an empty string on the command
line causes the default to be used.  This should never be set in a configuration
file provided with a package.

This new option can be used to add any number of packages to the list of
packages searched for command implementations; multiple package names should be
separated by commas.  When not specified, the search is only performed in the
:mod:`distutils.command` package.  When :file:`setup.py` is run with the option
``--command-packages distcmds,buildcmds``, however, the packages
:mod:`distutils.command`, ``distcmds``, and ``buildcmds`` will be searched
in that order.  New commands are expected to be implemented in modules of the
same name as the command by classes sharing the same name.  Given the example
command line option above, the command :command:`bdist_openpkg` could be
implemented by the class ``distcmds.bdist_openpkg.bdist_openpkg`` or
``buildcmds.bdist_openpkg.bdist_openpkg``.


Adding new distribution types
=============================

Commands that create distributions (files in the :file:`dist/` directory) need
to add ``(command, filename)`` pairs to ``self.distribution.dist_files`` so that
:command:`upload` can upload it to PyPI.  The *filename* in the pair contains no
path information, only the name of the file itself.  In dry-run mode, pairs
should still be added to represent what would have been created.


                distutils/uploading.rst                                                                             0000644                 00000000342 15052074023 0011301 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       :orphan:

***************************************
Uploading Packages to the Package Index
***************************************

References to up to date PyPI documentation can be found at
:ref:`publishing-python-packages`.
                                                                                                                                                                                                                                                                                              distutils/examples.rst                                                                              0000644                 00000024240 15052074023 0011140 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. _distutils_examples:

******************
Distutils Examples
******************

.. include:: ./_setuptools_disclaimer.rst

This chapter provides a number of basic examples to help get started with
distutils.  Additional information about using distutils can be found in the
Distutils Cookbook.


.. seealso::

   `Distutils Cookbook &lt;https://wiki.python.org/moin/Distutils/Cookbook&gt;`_
      Collection of recipes showing how to achieve more control over distutils.


.. _pure-mod:

Pure Python distribution (by module)
====================================

If you're just distributing a couple of modules, especially if they don't live
in a particular package, you can specify them individually using the
``py_modules`` option in the setup script.

In the simplest case, you'll have two files to worry about: a setup script and
the single module you're distributing, :file:`foo.py` in this example::

   &lt;root&gt;/
           setup.py
           foo.py

(In all diagrams in this section, *&lt;root&gt;* will refer to the distribution root
directory.)  A minimal setup script to describe this situation would be::

   from distutils.core import setup
   setup(name='foo',
         version='1.0',
         py_modules=['foo'],
         )

Note that the name of the distribution is specified independently with the
``name`` option, and there's no rule that says it has to be the same as
the name of the sole module in the distribution (although that's probably a good
convention to follow).  However, the distribution name is used to generate
filenames, so you should stick to letters, digits, underscores, and hyphens.

Since ``py_modules`` is a list, you can of course specify multiple
modules, eg. if you're distributing modules ``foo`` and ``bar``, your
setup might look like this::

   &lt;root&gt;/
           setup.py
           foo.py
           bar.py

and the setup script might be  ::

   from distutils.core import setup
   setup(name='foobar',
         version='1.0',
         py_modules=['foo', 'bar'],
         )

You can put module source files into another directory, but if you have enough
modules to do that, it's probably easier to specify modules by package rather
than listing them individually.


.. _pure-pkg:

Pure Python distribution (by package)
=====================================

If you have more than a couple of modules to distribute, especially if they are
in multiple packages, it's probably easier to specify whole packages rather than
individual modules.  This works even if your modules are not in a package; you
can just tell the Distutils to process modules from the root package, and that
works the same as any other package (except that you don't have to have an
:file:`__init__.py` file).

The setup script from the last example could also be written as  ::

   from distutils.core import setup
   setup(name='foobar',
         version='1.0',
         packages=[''],
         )

(The empty string stands for the root package.)

If those two files are moved into a subdirectory, but remain in the root
package, e.g.::

   &lt;root&gt;/
           setup.py
           src/      foo.py
                     bar.py

then you would still specify the root package, but you have to tell the
Distutils where source files in the root package live::

   from distutils.core import setup
   setup(name='foobar',
         version='1.0',
         package_dir={'': 'src'},
         packages=[''],
         )

More typically, though, you will want to distribute multiple modules in the same
package (or in sub-packages).  For example, if the ``foo``  and ``bar``
modules belong in package ``foobar``, one way to layout your source tree is
::

   &lt;root&gt;/
           setup.py
           foobar/
                    __init__.py
                    foo.py
                    bar.py

This is in fact the default layout expected by the Distutils, and the one that
requires the least work to describe in your setup script::

   from distutils.core import setup
   setup(name='foobar',
         version='1.0',
         packages=['foobar'],
         )

If you want to put modules in directories not named for their package, then you
need to use the ``package_dir`` option again.  For example, if the
:file:`src` directory holds modules in the ``foobar`` package::

   &lt;root&gt;/
           setup.py
           src/
                    __init__.py
                    foo.py
                    bar.py

an appropriate setup script would be  ::

   from distutils.core import setup
   setup(name='foobar',
         version='1.0',
         package_dir={'foobar': 'src'},
         packages=['foobar'],
         )

Or, you might put modules from your main package right in the distribution
root::

   &lt;root&gt;/
           setup.py
           __init__.py
           foo.py
           bar.py

in which case your setup script would be  ::

   from distutils.core import setup
   setup(name='foobar',
         version='1.0',
         package_dir={'foobar': ''},
         packages=['foobar'],
         )

(The empty string also stands for the current directory.)

If you have sub-packages, they must be explicitly listed in ``packages``,
but any entries in ``package_dir`` automatically extend to sub-packages.
(In other words, the Distutils does *not* scan your source tree, trying to
figure out which directories correspond to Python packages by looking for
:file:`__init__.py` files.)  Thus, if the default layout grows a sub-package::

   &lt;root&gt;/
           setup.py
           foobar/
                    __init__.py
                    foo.py
                    bar.py
                    subfoo/
                              __init__.py
                              blah.py

then the corresponding setup script would be  ::

   from distutils.core import setup
   setup(name='foobar',
         version='1.0',
         packages=['foobar', 'foobar.subfoo'],
         )


.. _single-ext:

Single extension module
=======================

Extension modules are specified using the ``ext_modules`` option.
``package_dir`` has no effect on where extension source files are found;
it only affects the source for pure Python modules.  The simplest  case, a
single extension module in a single C source file, is::

   &lt;root&gt;/
           setup.py
           foo.c

If the ``foo`` extension belongs in the root package, the setup script for
this could be  ::

   from distutils.core import setup
   from distutils.extension import Extension
   setup(name='foobar',
         version='1.0',
         ext_modules=[Extension('foo', ['foo.c'])],
         )

If the extension actually belongs in a package, say ``foopkg``, then

With exactly the same source tree layout, this extension can be put in the
``foopkg`` package simply by changing the name of the extension::

   from distutils.core import setup
   from distutils.extension import Extension
   setup(name='foobar',
         version='1.0',
         ext_modules=[Extension('foopkg.foo', ['foo.c'])],
         )

Checking a package
==================

The ``check`` command allows you to verify if your package meta-data
meet the minimum requirements to build a distribution.

To run it, just call it using your :file:`setup.py` script. If something is
missing, ``check`` will display a warning.

Let's take an example with a simple script::

    from distutils.core import setup

    setup(name='foobar')

Running the ``check`` command will display some warnings:

.. code-block:: shell-session

    $ python setup.py check
    running check
    warning: check: missing required meta-data: version, url
    warning: check: missing meta-data: either (author and author_email) or
             (maintainer and maintainer_email) should be supplied


If you use the reStructuredText syntax in the ``long_description`` field and
`docutils`_  is installed you can check if the syntax is fine with the
``check`` command, using the ``restructuredtext`` option.

For example, if the :file:`setup.py` script is changed like this::

    from distutils.core import setup

    desc = &quot;&quot;&quot;\
    My description
    ==============

    This is the description of the ``foobar`` package.
    &quot;&quot;&quot;

    setup(name='foobar', version='1', author='tarek',
        author_email='tarek@ziade.org',
        url='http://example.com', long_description=desc)

Where the long description is broken, ``check`` will be able to detect it
by using the :mod:`docutils` parser:

.. code-block:: shell-session

    $ python setup.py check --restructuredtext
    running check
    warning: check: Title underline too short. (line 2)
    warning: check: Could not finish the parsing.

Reading the metadata
=====================

The :func:`distutils.core.setup` function provides a command-line interface
that allows you to query the metadata fields of a project through the
``setup.py`` script of a given project:

.. code-block:: shell-session

    $ python setup.py --name
    distribute

This call reads the ``name`` metadata by running the
:func:`distutils.core.setup`  function. Although, when a source or binary
distribution is created with Distutils, the metadata fields are written
in a static file called :file:`PKG-INFO`. When a Distutils-based project is
installed in Python, the :file:`PKG-INFO` file is copied alongside the modules
and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`,
where ``NAME`` is the name of the project, ``VERSION`` its version as defined
in the Metadata, and ``pyX.X`` the major and minor version of Python like
``2.7`` or ``3.2``.

You can read back this static file, by using the
:class:`distutils.dist.DistributionMetadata` class and its
:func:`~distutils.dist.DistributionMetadata.read_pkg_file` method::

    &gt;&gt;&gt; from distutils.dist import DistributionMetadata
    &gt;&gt;&gt; metadata = DistributionMetadata()
    &gt;&gt;&gt; metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
    &gt;&gt;&gt; metadata.name
    'distribute'
    &gt;&gt;&gt; metadata.version
    '0.6.8'
    &gt;&gt;&gt; metadata.description
    'Easily download, build, install, upgrade, and uninstall Python packages'

Notice that the class can also be instantiated with a metadata file path to
loads its values::

    &gt;&gt;&gt; pkg_info_path = 'distribute-0.6.8-py2.7.egg-info'
    &gt;&gt;&gt; DistributionMetadata(pkg_info_path).name
    'distribute'


.. % \section{Multiple extension modules}
.. % \label{multiple-ext}

.. % \section{Putting it all together}


.. _docutils: http://docutils.sourceforge.net
                                                                                                                                                                                                                                                                                                                                                                distutils/apiref.rst                                                                                0000644                 00000275170 15052074023 0010602 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       .. _api-reference:

*************
API Reference
*************

.. seealso::

   `New and changed setup.py arguments in setuptools`_
      The ``setuptools`` project adds new capabilities to the ``setup`` function
      and other APIs, makes the API consistent across different Python versions,
      and is hence recommended over using ``distutils`` directly.

.. _New and changed setup.py arguments in setuptools: https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords

.. include:: ./_setuptools_disclaimer.rst

:mod:`distutils.core` --- Core Distutils functionality
======================================================

.. module:: distutils.core
   :synopsis: The core Distutils functionality


The :mod:`distutils.core` module is the only module that needs to be installed
to use the Distutils. It provides the :func:`setup` (which is called from the
setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
:class:`distutils.cmd.Command` class.


.. function:: setup(arguments)

   The basic do-everything function that does most everything you could ever ask
   for from a Distutils method.

   The setup function takes a large number of arguments. These are laid out in the
   following table.

   .. tabularcolumns:: |l|L|L|

   +--------------------+--------------------------------+-------------------------------------------------------------+
   | argument name      | value                          | type                                                        |
   +====================+================================+=============================================================+
   | *name*             | The name of the package        | a string                                                    |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *version*          | The version number of the      | a string                                                    |
   |                    | package; see                   |                                                             |
   |                    | :mod:`distutils.version`       |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *description*      | A single line describing the   | a string                                                    |
   |                    | package                        |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *long_description* | Longer description of the      | a string                                                    |
   |                    | package                        |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *author*           | The name of the package author | a string                                                    |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *author_email*     | The email address of the       | a string                                                    |
   |                    | package author                 |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *maintainer*       | The name of the current        | a string                                                    |
   |                    | maintainer, if different from  |                                                             |
   |                    | the author. Note that if       |                                                             |
   |                    | the maintainer is provided,    |                                                             |
   |                    | distutils will use it as the   |                                                             |
   |                    | author in :file:`PKG-INFO`     |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *maintainer_email* | The email address of the       | a string                                                    |
   |                    | current maintainer, if         |                                                             |
   |                    | different from the author      |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *url*              | A URL for the package          | a string                                                    |
   |                    | (homepage)                     |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *download_url*     | A URL to download the package  | a string                                                    |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *packages*         | A list of Python packages that | a list of strings                                           |
   |                    | distutils will manipulate      |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *py_modules*       | A list of Python modules that  | a list of strings                                           |
   |                    | distutils will manipulate      |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *scripts*          | A list of standalone script    | a list of strings                                           |
   |                    | files to be built and          |                                                             |
   |                    | installed                      |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *ext_modules*      | A list of Python extensions to | a list of instances of                                      |
   |                    | be built                       | :class:`distutils.core.Extension`                           |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *classifiers*      | A list of categories for the   | a list of strings; valid classifiers are listed on `PyPI    |
   |                    | package                        | &lt;https://pypi.org/classifiers&gt;`_.                           |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *distclass*        | the :class:`Distribution`      | a subclass of                                               |
   |                    | class to use                   | :class:`distutils.core.Distribution`                        |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *script_name*      | The name of the setup.py       | a string                                                    |
   |                    | script - defaults to           |                                                             |
   |                    | ``sys.argv[0]``                |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *script_args*      | Arguments to supply to the     | a list of strings                                           |
   |                    | setup script                   |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *options*          | default options for the setup  | a dictionary                                                |
   |                    | script                         |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *license*          | The license for the package    | a string                                                    |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *keywords*         | Descriptive meta-data, see     | a list of strings or a comma-separated string               |
   |                    | :pep:`314`                     |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *platforms*        |                                | a list of strings or a comma-separated string               |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *cmdclass*         | A mapping of command names to  | a dictionary                                                |
   |                    | :class:`Command` subclasses    |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *data_files*       | A list of data files to        | a list                                                      |
   |                    | install                        |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+
   | *package_dir*      | A mapping of package to        | a dictionary                                                |
   |                    | directory names                |                                                             |
   +--------------------+--------------------------------+-------------------------------------------------------------+


.. function:: run_setup(script_name[, script_args=None, stop_after='run'])

   Run a setup script in a somewhat controlled environment, and return  the
   :class:`distutils.dist.Distribution` instance that drives things.   This is
   useful if you need to find out the distribution meta-data  (passed as keyword
   args from *script* to :func:`setup`), or  the contents of the config files or
   command-line.

   *script_name* is a file that will be read and run with :func:`exec`.  ``sys.argv[0]``
   will be replaced with *script* for the duration of the call.  *script_args* is a
   list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args*
   for the duration  of the call.

   *stop_after* tells :func:`setup` when to stop processing; possible  values:

   .. tabularcolumns:: |l|L|

   +---------------+---------------------------------------------+
   | value         | description                                 |
   +===============+=============================================+
   | *init*        | Stop after the :class:`Distribution`        |
   |               | instance has been created  and populated    |
   |               | with the keyword arguments to :func:`setup` |
   +---------------+---------------------------------------------+
   | *config*      | Stop after config files have been parsed    |
   |               | (and their data stored in the               |
   |               | :class:`Distribution` instance)             |
   +---------------+---------------------------------------------+
   | *commandline* | Stop after the command-line                 |
   |               | (``sys.argv[1:]`` or  *script_args*) have   |
   |               | been parsed (and the data stored in the     |
   |               | :class:`Distribution` instance.)            |
   +---------------+---------------------------------------------+
   | *run*         | Stop after all commands have been run (the  |
   |               | same as  if :func:`setup` had been called   |
   |               | in the usual way). This is the default      |
   |               | value.                                      |
   +---------------+---------------------------------------------+

In addition, the :mod:`distutils.core` module exposed a number of  classes that
live elsewhere.

* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`

* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`

* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`

A short description of each of these follows, but see the relevant module for
the full reference.


.. class:: Extension

   The Extension class describes a single C or C++ extension module in a setup
   script. It accepts the following keyword arguments in its constructor:

   .. tabularcolumns:: |l|L|l|

   +------------------------+--------------------------------+---------------------------+
   | argument name          | value                          | type                      |
   +========================+================================+===========================+
   | *name*                 | the full name of the           | a string                  |
   |                        | extension, including any       |                           |
   |                        | packages --- ie. *not* a       |                           |
   |                        | filename or pathname, but      |                           |
   |                        | Python dotted name             |                           |
   +------------------------+--------------------------------+---------------------------+
   | *sources*              | list of source filenames,      | a list of strings         |
   |                        | relative to the distribution   |                           |
   |                        | root (where the setup script   |                           |
   |                        | lives), in Unix form           |                           |
   |                        | (slash-separated) for          |                           |
   |                        | portability.                   |                           |
   |                        | Source files may be C, C++,    |                           |
   |                        | SWIG (.i), platform-specific   |                           |
   |                        | resource files, or whatever    |                           |
   |                        | else is recognized by the      |                           |
   |                        | :command:`build_ext` command   |                           |
   |                        | as source for a Python         |                           |
   |                        | extension.                     |                           |
   +------------------------+--------------------------------+---------------------------+
   | *include_dirs*         | list of directories to search  | a list of strings         |
   |                        | for C/C++ header files (in     |                           |
   |                        | Unix form for portability)     |                           |
   +------------------------+--------------------------------+---------------------------+
   | *define_macros*        | list of macros to define; each | a list of tuples          |
   |                        | macro is defined using a       |                           |
   |                        | 2-tuple ``(name, value)``,     |                           |
   |                        | where *value* is               |                           |
   |                        | either the string to define it |                           |
   |                        | to or ``None`` to define it    |                           |
   |                        | without a particular value     |                           |
   |                        | (equivalent of ``#define FOO`` |                           |
   |                        | in source or :option:`!-DFOO`  |                           |
   |                        | on Unix C compiler command     |                           |
   |                        | line)                          |                           |
   +------------------------+--------------------------------+---------------------------+
   | *undef_macros*         | list of macros to undefine     | a list of strings         |
   |                        | explicitly                     |                           |
   +------------------------+--------------------------------+---------------------------+
   | *library_dirs*         | list of directories to search  | a list of strings         |
   |                        | for C/C++ libraries at link    |                           |
   |                        | time                           |                           |
   +------------------------+--------------------------------+---------------------------+
   | *libraries*            | list of library names (not     | a list of strings         |
   |                        | filenames or paths) to link    |                           |
   |                        | against                        |                           |
   +------------------------+--------------------------------+---------------------------+
   | *runtime_library_dirs* | list of directories to search  | a list of strings         |
   |                        | for C/C++ libraries at run     |                           |
   |                        | time (for shared extensions,   |                           |
   |                        | this is when the extension is  |                           |
   |                        | loaded)                        |                           |
   +------------------------+--------------------------------+---------------------------+
   | *extra_objects*        | list of extra files to link    | a list of strings         |
   |                        | with (eg. object files not     |                           |
   |                        | implied by 'sources', static   |                           |
   |                        | library that must be           |                           |
   |                        | explicitly specified, binary   |                           |
   |                        | resource files, etc.)          |                           |
   +------------------------+--------------------------------+---------------------------+
   | *extra_compile_args*   | any extra platform- and        | a list of strings         |
   |                        | compiler-specific information  |                           |
   |                        | to use when compiling the      |                           |
   |                        | source files in 'sources'. For |                           |
   |                        | platforms and compilers where  |                           |
   |                        | a command line makes sense,    |                           |
   |                        | this is typically a list of    |                           |
   |                        | command-line arguments, but    |                           |
   |                        | for other platforms it could   |                           |
   |                        | be anything.                   |                           |
   +------------------------+--------------------------------+---------------------------+
   | *extra_link_args*      | any extra platform- and        | a list of strings         |
   |                        | compiler-specific information  |                           |
   |                        | to use when linking object     |                           |
   |                        | files together to create the   |                           |
   |                        | extension (or to create a new  |                           |
   |                        | static Python interpreter).    |                           |
   |                        | Similar interpretation as for  |                           |
   |                        | 'extra_compile_args'.          |                           |
   +------------------------+--------------------------------+---------------------------+
   | *export_symbols*       | list of symbols to be exported | a list of strings         |
   |                        | from a shared extension. Not   |                           |
   |                        | used on all platforms, and not |                           |
   |                        | generally necessary for Python |                           |
   |                        | extensions, which typically    |                           |
   |                        | export exactly one symbol:     |                           |
   |                        | ``init`` + extension_name.     |                           |
   +------------------------+--------------------------------+---------------------------+
   | *depends*              | list of files that the         | a list of strings         |
   |                        | extension depends on           |                           |
   +------------------------+--------------------------------+---------------------------+
   | *language*             | extension language (i.e.       | a string                  |
   |                        | ``'c'``, ``'c++'``,            |                           |
   |                        | ``'objc'``). Will be detected  |                           |
   |                        | from the source extensions if  |                           |
   |                        | not provided.                  |                           |
   +------------------------+--------------------------------+---------------------------+
   | *optional*             | specifies that a build failure | a boolean                 |
   |                        | in the extension should not    |                           |
   |                        | abort the build process, but   |                           |
   |                        | simply skip the extension.     |                           |
   +------------------------+--------------------------------+---------------------------+

   .. versionchanged:: 3.8

      On Unix, C extensions are no longer linked to libpython except on
      Android and Cygwin.


.. class:: Distribution

   A :class:`Distribution` describes how to build, install and package up a Python
   software package.

   See the :func:`setup` function for a list of keyword arguments accepted  by the
   Distribution constructor. :func:`setup` creates a Distribution instance.

   .. versionchanged:: 3.7
      :class:`~distutils.core.Distribution` now warns if ``classifiers``,
      ``keywords`` and ``platforms`` fields are not specified as a list or
      a string.

.. class:: Command

   A :class:`Command` class (or rather, an instance of one of its subclasses)
   implement a single distutils command.


:mod:`distutils.ccompiler` --- CCompiler base class
===================================================

.. module:: distutils.ccompiler
   :synopsis: Abstract CCompiler class


This module provides the abstract base class for the :class:`CCompiler`
classes.  A :class:`CCompiler` instance can be used for all the compile  and
link steps needed to build a single project. Methods are provided to  set
options for the compiler --- macro definitions, include directories,  link path,
libraries and the like.

This module provides the following functions.


.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)

   Generate linker options for searching library directories and linking with
   specific libraries.  *libraries* and *library_dirs* are, respectively, lists of
   library names (not filenames!) and search directories.  Returns a list of
   command-line options suitable for use with some compiler (depending on the two
   format strings passed in).


.. function:: gen_preprocess_options(macros, include_dirs)

   Generate C pre-processor options (:option:`!-D`, :option:`!-U`, :option:`!-I`) as
   used by at least two types of compilers: the typical Unix compiler and Visual
   C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
   means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define
   (:option:`!-D`) macro *name* to *value*.  *include_dirs* is just a list of
   directory names to be added to the header file search path (:option:`!-I`).
   Returns a list of command-line options suitable for either Unix compilers or
   Visual C++.


.. function:: get_default_compiler(osname, platform)

   Determine the default compiler to use for the given platform.

   *osname* should be one of the standard Python OS names (i.e. the ones returned
   by ``os.name``) and *platform* the common value returned by ``sys.platform`` for
   the platform in question.

   The default values are ``os.name`` and ``sys.platform`` in case the parameters
   are not given.


.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)

   Factory function to generate an instance of some CCompiler subclass for the
   supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
   ``'posix'``, ``'nt'``), and *compiler*  defaults to the default compiler for
   that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
   default compilers are &quot;traditional Unix interface&quot; (:class:`UnixCCompiler`
   class) and Visual C++ (:class:`MSVCCompiler` class).  Note that it's perfectly
   possible to ask for a Unix compiler object under Windows, and a Microsoft
   compiler object under Unix---if you supply a value for *compiler*, *plat* is
   ignored.

   .. % Is the posix/nt only thing still true? Mac OS X seems to work, and
   .. % returns a UnixCCompiler instance. How to document this... hmm.


.. function:: show_compilers()

   Print list of available compilers (used by the :option:`!--help-compiler` options
   to :command:`build`, :command:`build_ext`, :command:`build_clib`).


.. class:: CCompiler([verbose=0, dry_run=0, force=0])

   The abstract base class :class:`CCompiler` defines the interface that  must be
   implemented by real compiler classes.  The class also has  some utility methods
   used by several compiler classes.

   The basic idea behind a compiler abstraction class is that each instance can be
   used for all the compile/link steps in building a single project.  Thus,
   attributes common to all of those compile and link steps --- include
   directories, macros to define, libraries to link against, etc. --- are
   attributes of the compiler instance.  To allow for variability in how individual
   files are treated, most of those attributes may be varied on a per-compilation
   or per-link basis.

   The constructor for each subclass creates an instance of the Compiler object.
   Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the
   steps) and *force* (rebuild everything, regardless of dependencies). All of
   these flags default to ``0`` (off). Note that you probably don't want to
   instantiate :class:`CCompiler` or one of its subclasses directly - use the
   :func:`distutils.CCompiler.new_compiler` factory function instead.

   The following methods allow you to manually alter compiler options for  the
   instance of the Compiler class.


   .. method:: CCompiler.add_include_dir(dir)

      Add *dir* to the list of directories that will be searched for header files.
      The compiler is instructed to search directories in the order in which they are
      supplied by successive calls to :meth:`add_include_dir`.


   .. method:: CCompiler.set_include_dirs(dirs)

      Set the list of directories that will be searched to *dirs* (a list of strings).
      Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to
      :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.
      This does not affect any list of standard include directories that the compiler
      may search by default.


   .. method:: CCompiler.add_library(libname)

      Add *libname* to the list of libraries that will be included in all links driven
      by this compiler object.  Note that *libname* should \*not\* be the name of a
      file containing a library, but the name of the library itself: the actual
      filename will be inferred by the linker, the compiler, or the compiler class
      (depending on the platform).

      The linker will be instructed to link against libraries in the order they were
      supplied to :meth:`add_library` and/or :meth:`set_libraries`.  It is perfectly
      valid to duplicate library names; the linker will be instructed to link against
      libraries as many times as they are mentioned.


   .. method:: CCompiler.set_libraries(libnames)

      Set the list of libraries to be included in all links driven by this compiler
      object to *libnames* (a list of strings).  This does not affect any standard
      system libraries that the linker may include by default.


   .. method:: CCompiler.add_library_dir(dir)

      Add *dir* to the list of directories that will be searched for libraries
      specified to :meth:`add_library` and :meth:`set_libraries`.  The linker will be
      instructed to search for libraries in the order they are supplied to
      :meth:`add_library_dir` and/or :meth:`set_library_dirs`.


   .. method:: CCompiler.set_library_dirs(dirs)

      Set the list of library search directories to *dirs* (a list of strings).  This
      does not affect any standard library search path that the linker may search by
      default.


   .. method:: CCompiler.add_runtime_library_dir(dir)

      Add *dir* to the list of directories that will be searched for shared libraries
      at runtime.


   .. method:: CCompiler.set_runtime_library_dirs(dirs)

      Set the list of directories to search for shared libraries at runtime to *dirs*
      (a list of strings).  This does not affect any standard search path that the
      runtime linker may search by default.


   .. method:: CCompiler.define_macro(name[, value=None])

      Define a preprocessor macro for all compilations driven by this compiler object.
      The optional parameter *value* should be a string; if it is not supplied, then
      the macro will be defined without an explicit value and the exact outcome
      depends on the compiler used.

      .. XXX true? does ANSI say anything about this?


   .. method:: CCompiler.undefine_macro(name)

      Undefine a preprocessor macro for all compilations driven by this compiler
      object.  If the same macro is defined by :meth:`define_macro` and
      undefined by :meth:`undefine_macro` the last call takes precedence
      (including multiple redefinitions or undefinitions).  If the macro is
      redefined/undefined on a per-compilation basis (ie. in the call to
      :meth:`compile`), then that takes precedence.


   .. method:: CCompiler.add_link_object(object)

      Add *object* to the list of object files (or analogues, such as explicitly named
      library files or the output of &quot;resource compilers&quot;) to be included in every
      link driven by this compiler object.


   .. method:: CCompiler.set_link_objects(objects)

      Set the list of object files (or analogues) to be included in every link to
      *objects*.  This does not affect any standard object files that the linker may
      include by default (such as system libraries).

   The following methods implement methods for autodetection of compiler  options,
   providing some functionality similar to GNU :program:`autoconf`.


   .. method:: CCompiler.detect_language(sources)

      Detect the language of a given file, or list of files. Uses the  instance
      attributes :attr:`~CCompiler.language_map` (a dictionary), and  :attr:`~CCompiler.language_order` (a
      list) to do the job.


   .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])

      Search the specified list of directories for a static or shared library file
      *lib* and return the full path to that file.  If *debug* is true, look for a
      debugging version (if that makes sense on the current platform).  Return
      ``None`` if *lib* wasn't found in any of the specified directories.


   .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])

      Return a boolean indicating whether *funcname* is supported on the current
      platform.  The optional arguments can be used to augment the compilation
      environment by providing additional include files and paths and libraries and
      paths.


   .. method:: CCompiler.library_dir_option(dir)

      Return the compiler option to add *dir* to the list of directories searched for
      libraries.


   .. method:: CCompiler.library_option(lib)

      Return the compiler option to add *lib* to the list of libraries linked into the
      shared library or executable.


   .. method:: CCompiler.runtime_library_dir_option(dir)

      Return the compiler option to add *dir* to the list of directories searched for
      runtime libraries.


   .. method:: CCompiler.set_executables(**args)

      Define the executables (and options for them) that will be run to perform the
      various stages of compilation.  The exact set of executables that may be
      specified here depends on the compiler class (via the 'executables' class
      attribute), but most will have:

      +--------------+------------------------------------------+
      | attribute    | description                              |
      +==============+==========================================+
      | *compiler*   | the C/C++ compiler                       |
      +--------------+------------------------------------------+
      | *linker_so*  | linker used to create shared objects and |
      |              | libraries                                |
      +--------------+------------------------------------------+
      | *linker_exe* | linker used to create binary executables |
      +--------------+------------------------------------------+
      | *archiver*   | static library creator                   |
      +--------------+------------------------------------------+

      On platforms with a command-line (Unix, DOS/Windows), each of these is a string
      that will be split into executable name and (optional) list of arguments.
      (Splitting the string is done similarly to how Unix shells operate: words are
      delimited by spaces, but quotes and backslashes can override this.  See
      :func:`distutils.util.split_quoted`.)

   The following methods invoke stages in the build process.


   .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])

      Compile one or more source files. Generates object files (e.g.  transforms a
      :file:`.c` file to a :file:`.o` file.)

      *sources* must be a list of filenames, most likely C/C++ files, but in reality
      anything that can be handled by a particular compiler and compiler class (eg.
      :class:`MSVCCompiler` can handle resource files in *sources*).  Return a list of
      object filenames, one per source filename in *sources*.  Depending on the
      implementation, not all source files will necessarily be compiled, but all
      corresponding object filenames will be returned.

      If *output_dir* is given, object files will be put under it, while retaining
      their original path component.  That is, :file:`foo/bar.c` normally compiles to
      :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
      it would compile to :file:`build/foo/bar.o`.

      *macros*, if given, must be a list of macro definitions.  A macro definition is
      either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
      a macro; if the value is ``None``, the macro is defined without an explicit
      value.  The 1-tuple case undefines a macro.  Later
      definitions/redefinitions/undefinitions take precedence.

      *include_dirs*, if given, must be a list of strings, the directories to add to
      the default include file search path for this compilation only.

      *debug* is a boolean; if true, the compiler will be instructed to output debug
      symbols in (or alongside) the object file(s).

      *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
      that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
      likely lists of strings: extra command-line arguments to prepend/append to the
      compiler command line.  On other platforms, consult the implementation class
      documentation.  In any event, they are intended as an escape hatch for those
      occasions when the abstract compiler framework doesn't cut the mustard.

      *depends*, if given, is a list of filenames that all targets depend on.  If a
      source file is older than any file in depends, then the source file will be
      recompiled.  This supports dependency tracking, but only at a coarse
      granularity.

      Raises :exc:`CompileError` on failure.


   .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])

      Link a bunch of stuff together to create a static library file. The &quot;bunch of
      stuff&quot; consists of the list of object files supplied as *objects*, the extra
      object files supplied to :meth:`add_link_object` and/or
      :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
      :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).

      *output_libname* should be a library name, not a filename; the filename will be
      inferred from the library name.  *output_dir* is the directory where the library
      file will be put.

      .. XXX defaults to what?

      *debug* is a boolean; if true, debugging information will be included in the
      library (note that on most platforms, it is the compile step where this matters:
      the *debug* flag is included here just for consistency).

      *target_lang* is the target language for which the given objects are being
      compiled. This allows specific linkage time treatment of certain languages.

      Raises :exc:`LibError` on failure.


   .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

      Link a bunch of stuff together to create an executable or shared library file.

      The &quot;bunch of stuff&quot; consists of the list of object files supplied as *objects*.
      *output_filename* should be a filename.  If *output_dir* is supplied,
      *output_filename* is relative to it (i.e. *output_filename* can provide
      directory components if needed).

      *libraries* is a list of libraries to link against.  These are library names,
      not filenames, since they're translated into filenames in a platform-specific
      way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
      DOS/Windows).  However, they can include a directory component, which means the
      linker will look in that specific directory rather than searching all the normal
      locations.

      *library_dirs*, if supplied, should be a list of directories to search for
      libraries that were specified as bare library names (ie. no directory
      component).  These are on top of the system default and those supplied to
      :meth:`add_library_dir` and/or :meth:`set_library_dirs`.  *runtime_library_dirs*
      is a list of directories that will be embedded into the shared library and used
      to search for other shared libraries that \*it\* depends on at run-time.  (This
      may only be relevant on Unix.)

      *export_symbols* is a list of symbols that the shared library will export.
      (This appears to be relevant only on Windows.)

      *debug* is as for :meth:`compile` and :meth:`create_static_lib`,  with the
      slight distinction that it actually matters on most platforms (as opposed to
      :meth:`create_static_lib`, which includes a *debug* flag mostly for form's
      sake).

      *extra_preargs* and *extra_postargs* are as for :meth:`compile`  (except of
      course that they supply command-line arguments for the particular linker being
      used).

      *target_lang* is the target language for which the given objects are being
      compiled. This allows specific linkage time treatment of certain languages.

      Raises :exc:`LinkError` on failure.


   .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])

      Link an executable.  *output_progname* is the name of the file executable, while
      *objects* are a list of object filenames to link in. Other arguments  are as for
      the :meth:`link` method.


   .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

      Link a shared library. *output_libname* is the name of the output  library,
      while *objects* is a list of object filenames to link in.  Other arguments are
      as for the :meth:`link` method.


   .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])

      Link a shared object. *output_filename* is the name of the shared object that
      will be created, while *objects* is a list of object filenames  to link in.
      Other arguments are as for the :meth:`link` method.


   .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])

      Preprocess a single C/C++ source file, named in *source*. Output will be written
      to file named *output_file*, or *stdout* if *output_file* not supplied.
      *macros* is a list of macro definitions as for :meth:`compile`, which will
      augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
      *include_dirs* is a list of directory names that will be added to the  default
      list, in the same way as :meth:`add_include_dir`.

      Raises :exc:`PreprocessError` on failure.

   The following utility methods are defined by the :class:`CCompiler` class, for
   use by the various concrete subclasses.


   .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])

      Returns the filename of the executable for the given *basename*.  Typically for
      non-Windows platforms this is the same as the basename,  while Windows will get
      a :file:`.exe` added.


   .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])

      Returns the filename for the given library name on the current platform. On Unix
      a library with *lib_type* of ``'static'`` will typically  be of the form
      :file:`liblibname.a`, while a *lib_type* of ``'dynamic'``  will be of the form
      :file:`liblibname.so`.


   .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])

      Returns the name of the object files for the given source files.
      *source_filenames* should be a list of filenames.


   .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])

      Returns the name of a shared object file for the given file name *basename*.


   .. method:: CCompiler.execute(func, args[, msg=None, level=1])

      Invokes :func:`distutils.util.execute`. This method invokes a  Python function
      *func* with the given arguments *args*, after  logging and taking into account
      the *dry_run* flag.


   .. method:: CCompiler.spawn(cmd)

      Invokes :func:`distutils.spawn.spawn`. This invokes an external  process to run
      the given command.


   .. method:: CCompiler.mkpath(name[, mode=511])

      Invokes :func:`distutils.dir_util.mkpath`. This creates a directory  and any
      missing ancestor directories.


   .. method:: CCompiler.move_file(src, dst)

      Invokes :meth:`distutils.file_util.move_file`. Renames *src* to  *dst*.


   .. method:: CCompiler.announce(msg[, level=1])

      Write a message using :func:`distutils.log.debug`.


   .. method:: CCompiler.warn(msg)

      Write a warning message *msg* to standard error.


   .. method:: CCompiler.debug_print(msg)

      If the *debug* flag is set on this :class:`CCompiler` instance, print  *msg* to
      standard output, otherwise do nothing.

.. % \subsection{Compiler-specific modules}
.. %
.. % The following modules implement concrete subclasses of the abstract
.. % \class{CCompiler} class. They should not be instantiated directly, but should
.. % be created using \function{distutils.ccompiler.new_compiler()} factory
.. % function.


:mod:`distutils.unixccompiler` --- Unix C Compiler
==================================================

.. module:: distutils.unixccompiler
   :synopsis: UNIX C Compiler


This module provides the :class:`UnixCCompiler` class, a subclass of
:class:`CCompiler` that handles the typical Unix-style command-line  C compiler:

* macros defined with :option:`!-Dname[=value]`

* macros undefined with :option:`!-Uname`

* include search directories specified with :option:`!-Idir`

* libraries specified with :option:`!-llib`

* library search directories specified with :option:`!-Ldir`

* compile handled by :program:`cc` (or similar) executable with :option:`!-c`
  option: compiles :file:`.c` to :file:`.o`

* link static library handled by :program:`ar` command (possibly with
  :program:`ranlib`)

* link shared library handled by :program:`cc` :option:`!-shared`


:mod:`distutils.msvccompiler` --- Microsoft Compiler
====================================================

.. module:: distutils.msvccompiler
   :synopsis: Microsoft Compiler

.. XXX: This is *waaaaay* out of date!

This module provides :class:`MSVCCompiler`, an implementation of the abstract
:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
modules need to be compiled with the same compiler that was used to compile
Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
2.4 and 2.5, the compiler is Visual Studio .NET 2003.

:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
and *MSSdk* must be both set. *MSSdk* indicates that the current environment has
been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables
had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates
that the distutils user has made an explicit choice to override the compiler
selection by :class:`MSVCCompiler`.


:mod:`distutils.bcppcompiler` --- Borland Compiler
==================================================

.. module:: distutils.bcppcompiler


This module provides :class:`BorlandCCompiler`, a subclass of the abstract
:class:`CCompiler` class for the Borland C++ compiler.


:mod:`distutils.cygwinccompiler` --- Cygwin Compiler
====================================================

.. module:: distutils.cygwinccompiler


This module provides the :class:`CygwinCCompiler` class, a subclass of
:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to
Windows.  It also contains the Mingw32CCompiler class which handles the mingw32
port of GCC (same as cygwin in no-cygwin mode).


:mod:`distutils.archive_util` ---  Archiving utilities
======================================================

.. module:: distutils.archive_util
   :synopsis: Utility functions for creating archive files (tarballs, zip files, ...)


This module provides a few functions for creating archive files, such as
tarballs or zipfiles.


.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])

   Create an archive file (eg. ``zip`` or ``tar``).  *base_name*  is the name of
   the file to create, minus any format-specific extension;  *format* is the
   archive format: one of ``zip``, ``tar``, ``gztar``, ``bztar``, ``xztar``, or
   ``ztar``. *root_dir* is a directory that will be the root directory of the
   archive; ie. we typically ``chdir`` into *root_dir* before  creating the
   archive.  *base_dir* is the directory where we start  archiving from; ie.
   *base_dir* will be the common prefix of all files and directories in the
   archive.  *root_dir* and *base_dir* both default to the current directory.
   Returns the name of the archive file.

   .. versionchanged:: 3.5
      Added support for the ``xztar`` format.


.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])

   'Create an (optional compressed) archive as a tar file from all files in and
   under *base_dir*. *compress* must be ``'gzip'`` (the default),
   ``'bzip2'``, ``'xz'``, ``'compress'``, or ``None``.  For the ``'compress'``
   method the compression utility named by :program:`compress` must be on the
   default program search path, so this is probably Unix-specific.  The output
   tar file will be named :file:`base_dir.tar`, possibly plus the appropriate
   compression extension (``.gz``, ``.bz2``, ``.xz`` or ``.Z``).  Return the
   output filename.

   .. versionchanged:: 3.5
      Added support for the ``xz`` compression.


.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])

   Create a zip file from all files in and under *base_dir*.  The output zip file
   will be named *base_name* + :file:`.zip`.  Uses either the  :mod:`zipfile` Python
   module (if available) or the InfoZIP :file:`zip`  utility (if installed and
   found on the default search path).  If neither  tool is available, raises
   :exc:`DistutilsExecError`.   Returns the name of the output zip file.


:mod:`distutils.dep_util` --- Dependency checking
=================================================

.. module:: distutils.dep_util
   :synopsis: Utility functions for simple dependency checking


This module provides functions for performing simple, timestamp-based
dependency of files and groups of files; also, functions based entirely  on such
timestamp dependency analysis.


.. function:: newer(source, target)

   Return true if *source* exists and is more recently modified than *target*, or
   if *source* exists and *target* doesn't. Return false if both exist and *target*
   is the same age or newer  than *source*. Raise :exc:`DistutilsFileError` if
   *source* does not exist.


.. function:: newer_pairwise(sources, targets)

   Walk two filename lists in parallel, testing if each source is newer than its
   corresponding target.  Return a pair of lists (*sources*, *targets*) where
   source is newer than target, according to the semantics of :func:`newer`.

   .. % % equivalent to a listcomp...


.. function:: newer_group(sources, target[, missing='error'])

   Return true if *target* is out-of-date with respect to any file listed in
   *sources*.  In other words, if *target* exists and is newer than every file in
   *sources*, return false; otherwise return true. *missing* controls what we do
   when a source file is missing; the default (``'error'``) is to blow up with an
   :exc:`OSError` from  inside :func:`os.stat`; if it is ``'ignore'``, we silently
   drop any missing source files; if it is ``'newer'``, any missing source files
   make us assume that *target* is out-of-date (this is handy in &quot;dry-run&quot; mode:
   it'll make you pretend to carry out commands that wouldn't work because inputs
   are missing, but that doesn't matter because you're not actually going to run
   the commands).


:mod:`distutils.dir_util` --- Directory tree operations
=======================================================

.. module:: distutils.dir_util
   :synopsis: Utility functions for operating on directories and directory trees


This module provides functions for operating on directories and trees of
directories.


.. function:: mkpath(name[, mode=0o777, verbose=0, dry_run=0])

   Create a directory and any missing ancestor directories.  If the directory
   already exists (or if *name* is the empty string, which means the current
   directory, which of course exists), then do nothing.  Raise
   :exc:`DistutilsFileError` if unable to create some directory along the way (eg.
   some sub-path exists, but is a file rather than a directory).  If *verbose* is
   true, print a one-line summary of each mkdir to stdout.  Return the list of
   directories actually created.


.. function:: create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])

   Create all the empty directories under *base_dir* needed to put *files* there.
   *base_dir* is just the name of a directory which doesn't necessarily exist
   yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
   *base_dir* + the directory portion of every file in *files* will be created if
   it doesn't already exist.  *mode*, *verbose* and *dry_run* flags  are as for
   :func:`mkpath`.


.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])

   Copy an entire directory tree *src* to a new location *dst*.  Both *src* and
   *dst* must be directory names.  If *src* is not a directory, raise
   :exc:`DistutilsFileError`.  If *dst* does  not exist, it is created with
   :func:`mkpath`.  The end result of the  copy is that every file in *src* is
   copied to *dst*, and  directories under *src* are recursively copied to *dst*.
   Return the list of files that were copied or might have been copied, using their
   output name. The return value is unaffected by *update* or *dry_run*: it is
   simply the list of all files under *src*, with the names changed to be under
   *dst*.

   *preserve_mode* and *preserve_times* are the same as for
   :func:`distutils.file_util.copy_file`; note that they only apply to
   regular files, not to
   directories.  If *preserve_symlinks* is true, symlinks will be copied as
   symlinks (on platforms that support them!); otherwise (the default), the
   destination of the symlink will be copied.  *update* and *verbose* are the same
   as for :func:`~distutils.file_util.copy_file`.

   Files in *src* that begin with :file:`.nfs` are skipped (more information on
   these files is available in answer D2 of the `NFS FAQ page
   &lt;http://nfs.sourceforge.net/#section_d&gt;`_).

   .. versionchanged:: 3.3.1
      NFS files are ignored.

.. function:: remove_tree(directory[, verbose=0, dry_run=0])

   Recursively remove *directory* and all files and directories underneath it. Any
   errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
   true).


:mod:`distutils.file_util` --- Single file operations
=====================================================

.. module:: distutils.file_util
   :synopsis: Utility functions for operating on single files


This module contains some utility functions for operating on individual files.


.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])

   Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
   with the same name; otherwise, it must be a filename. (If the file exists, it
   will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
   file's mode (type and permission bits, or whatever is analogous on the
   current platform) is copied. If *preserve_times* is true (the default), the
   last-modified and last-access times are copied as well. If *update* is true,
   *src* will only be copied if *dst* does not exist, or if *dst* does exist but
   is older than *src*.

   *link* allows you to make hard links (using :func:`os.link`) or symbolic links
   (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
   ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
   on systems that don't support it: :func:`copy_file` doesn't check if hard or
   symbolic linking is available.  It uses :func:`~distutils.file_util._copy_file_contents` to copy file
   contents.

   Return a tuple ``(dest_name, copied)``: *dest_name* is the actual  name of the
   output file, and *copied* is true if the file was copied  (or would have been
   copied, if *dry_run* true).

   .. % XXX if the destination file already exists, we clobber it if
   .. % copying, but blow up if linking.  Hmmm.  And I don't know what
   .. % macostools.copyfile() does.  Should definitely be consistent, and
   .. % should probably blow up if destination exists and we would be
   .. % changing it (ie. it's not already a hard/soft link to src OR
   .. % (not update) and (src newer than dst)).


.. function:: move_file(src, dst[, verbose, dry_run])

   Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
   it with the same name; otherwise, *src* is just renamed to *dst*.  Returns the
   new full name of the file.

   .. warning::

      Handles cross-device moves on Unix using :func:`copy_file`.  What about
      other systems?


.. function:: write_file(filename, contents)

   Create a file called *filename* and write *contents* (a sequence of strings
   without line terminators) to it.


:mod:`distutils.util` --- Miscellaneous other utility functions
===============================================================

.. module:: distutils.util
   :synopsis: Miscellaneous other utility functions


This module contains other assorted bits and pieces that don't fit into  any
other utility module.


.. function:: get_platform()

   Return a string that identifies the current platform.  This is used mainly to
   distinguish platform-specific build directories and platform-specific built
   distributions.  Typically includes the OS name and version and the
   architecture (as supplied by 'os.uname()'), although the exact information
   included depends on the OS; e.g., on Linux, the kernel version isn't
   particularly important.

   Examples of returned values:

   * ``linux-i586``
   * ``linux-alpha``
   * ``solaris-2.6-sun4u``

   For non-POSIX platforms, currently just returns ``sys.platform``.

   For Mac OS X systems the OS version reflects the minimal version on which
   binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
   during the build of Python), not the OS version of the current system.

   For universal binary builds on Mac OS X the architecture value reflects
   the universal binary status instead of the architecture of the current
   processor. For 32-bit universal binaries the architecture is ``fat``,
   for 64-bit universal binaries the architecture is ``fat64``, and
   for 4-way universal binaries the architecture is ``universal``. Starting
   from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for
   a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for
   a universal build with the i386 and x86_64 architectures

   Examples of returned values on Mac OS X:

   * ``macosx-10.3-ppc``

   * ``macosx-10.3-fat``

   * ``macosx-10.5-universal``

   * ``macosx-10.6-intel``

   For AIX, Python 3.9 and later return a string starting with &quot;aix&quot;, followed
   by additional fields (separated by ``'-'``) that represent the combined
   values of AIX Version, Release and Technology Level (first field), Build Date
   (second field), and bit-size (third field). Python 3.8 and earlier returned
   only a single additional field with the AIX Version and Release.

   Examples of returned values on AIX:

   * ``aix-5307-0747-32`` # 32-bit build on AIX ``oslevel -s``: 5300-07-00-0000

   * ``aix-7105-1731-64`` # 64-bit build on AIX ``oslevel -s``: 7100-05-01-1731

   * ``aix-7.2``          # Legacy form reported in Python 3.8 and earlier

   .. versionchanged:: 3.9
      The AIX platform string format now also includes the technology level,
      build date, and ABI bit-size.


.. function:: convert_path(pathname)

   Return 'pathname' as a name that will work on the native filesystem, i.e. split
   it on '/' and put it back together again using the current directory separator.
   Needed because filenames in the setup script are always supplied in Unix style,
   and have to be converted to the local convention before we can actually use them
   in the filesystem.  Raises :exc:`ValueError` on non-Unix-ish systems if
   *pathname* either  starts or ends with a slash.


.. function:: change_root(new_root, pathname)

   Return *pathname* with *new_root* prepended.  If *pathname* is relative, this is
   equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making
   *pathname* relative and then joining the two, which is tricky on DOS/Windows.


.. function:: check_environ()

   Ensure that 'os.environ' has all the environment variables we guarantee that
   users can use in config files, command-line options, etc.  Currently this
   includes:

   * :envvar:`HOME` - user's home directory (Unix only)
   * :envvar:`PLAT` - description of the current platform, including hardware and
     OS (see :func:`get_platform`)


.. function:: subst_vars(s, local_vars)

   Perform shell/Perl-style variable substitution on *s*.  Every occurrence of
   ``$`` followed by a name is considered a variable, and variable is substituted
   by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
   not in *local_vars*. *os.environ* is first checked/augmented to guarantee that
   it contains certain values: see :func:`check_environ`.  Raise :exc:`ValueError`
   for any variables not found in either *local_vars* or ``os.environ``.

   Note that this is not a fully-fledged string interpolation function. A valid
   ``$variable`` can consist only of upper and lower case letters, numbers and an
   underscore. No { } or ( ) style quoting is available.


.. function:: split_quoted(s)

   Split a string up according to Unix shell-like rules for quotes and backslashes.
   In short: words are delimited by spaces, as long as those spaces are not escaped
   by a backslash, or inside a quoted string. Single and double quotes are
   equivalent, and the quote characters can be backslash-escaped.  The backslash is
   stripped from any two-character escape sequence, leaving only the escaped
   character.  The quote characters are stripped from any quoted string.  Returns a
   list of words.

   .. % Should probably be moved into the standard library.


.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])

   Perform some action that affects the outside world (for instance, writing to the
   filesystem).  Such actions are special because they are disabled by the
   *dry_run* flag.  This method takes  care of all that bureaucracy for you; all
   you have to do is supply the function to call and an argument tuple for it (to
   embody the &quot;external action&quot; being performed), and an optional message to print.


.. function:: strtobool(val)

   Convert a string representation of truth to true (1) or false (0).

   True values are ``y``, ``yes``, ``t``, ``true``, ``on``  and ``1``; false values
   are ``n``, ``no``, ``f``, ``false``,  ``off`` and ``0``.  Raises
   :exc:`ValueError` if *val*  is anything else.


.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])

   Byte-compile a collection of Python source files to :file:`.pyc` files in a
   :file:`__pycache__` subdirectory (see :pep:`3147` and :pep:`488`).
   *py_files* is a list of files to compile; any files that don't end in
   :file:`.py` are silently skipped.  *optimize* must be one of the following:

   * ``0`` - don't optimize
   * ``1`` - normal optimization (like ``python -O``)
   * ``2`` - extra optimization (like ``python -OO``)

   If *force* is true, all files are recompiled regardless of timestamps.

   The source filename encoded in each :term:`bytecode` file defaults to the filenames
   listed in *py_files*; you can modify these with *prefix* and *basedir*.
   *prefix* is a string that will be stripped off of each source filename, and
   *base_dir* is a directory name that will be prepended (after *prefix* is
   stripped).  You can supply either or both (or neither) of *prefix* and
   *base_dir*, as you wish.

   If *dry_run* is true, doesn't actually do anything that would affect the
   filesystem.

   Byte-compilation is either done directly in this interpreter process with the
   standard :mod:`py_compile` module, or indirectly by writing a temporary script
   and executing it.  Normally, you should let :func:`byte_compile` figure out to
   use direct compilation or not (see the source for details).  The *direct* flag
   is used by the script generated in indirect mode; unless you know what you're
   doing, leave it set to ``None``.

   .. versionchanged:: 3.2.3
      Create ``.pyc`` files with an :func:`import magic tag
      &lt;imp.get_tag&gt;` in their name, in a :file:`__pycache__` subdirectory
      instead of files without tag in the current directory.

   .. versionchanged:: 3.5
      Create ``.pyc`` files according to :pep:`488`.


.. function:: rfc822_escape(header)

   Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
   ensuring there are 8 spaces space after each newline. Note that it does no other
   modification of the string.

   .. % this _can_ be replaced

.. % \subsection{Distutils objects}


:mod:`distutils.dist` --- The Distribution class
================================================

.. module:: distutils.dist
   :synopsis: Provides the Distribution class, which represents the module distribution being
              built/installed/distributed


This module provides the :class:`~distutils.core.Distribution` class, which
represents the module distribution being built/installed/distributed.


:mod:`distutils.extension` --- The Extension class
==================================================

.. module:: distutils.extension
   :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup
              scripts


This module provides the :class:`~distutils.extension.Extension` class,
used to describe C/C++ extension modules in setup scripts.

.. % \subsection{Ungrouped modules}
.. % The following haven't been moved into a more appropriate section yet.


:mod:`distutils.debug` --- Distutils debug mode
===============================================

.. module:: distutils.debug
   :synopsis: Provides the debug flag for distutils


This module provides the DEBUG flag.


:mod:`distutils.errors` --- Distutils exceptions
================================================

.. module:: distutils.errors
   :synopsis: Provides standard distutils exceptions


Provides exceptions used by the Distutils modules.  Note that Distutils modules
may raise standard exceptions; in particular, SystemExit is usually raised for
errors that are obviously the end-user's fault (eg. bad command-line arguments).

This module is safe to use in ``from ... import *`` mode; it only exports
symbols whose names start with ``Distutils`` and end with ``Error``.


:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module
===========================================================================

.. module:: distutils.fancy_getopt
   :synopsis: Additional getopt functionality


This module provides a wrapper around the standard :mod:`getopt`  module that
provides the following additional features:

* short and long options are tied together

* options have help strings, so :func:`fancy_getopt` could potentially  create a
  complete usage summary

* options set attributes of a passed-in object

* boolean options can have &quot;negative aliases&quot; --- eg. if :option:`!--quiet` is
  the &quot;negative alias&quot; of :option:`!--verbose`, then :option:`!--quiet` on the
  command line sets *verbose* to false.

.. function:: fancy_getopt(options, negative_opt, object, args)

   Wrapper function. *options* is a list of ``(long_option, short_option,
   help_string)`` 3-tuples as described in the constructor for
   :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
   to option names, both the key and value should be in the *options* list.
   *object* is an object which will be used to store values (see the :meth:`~FancyGetopt.getopt`
   method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
   ``sys.argv[1:]`` if you  pass ``None`` as *args*.


.. function:: wrap_text(text, width)

   Wraps *text* to less than *width* wide.


.. class:: FancyGetopt([option_table=None])

   The option_table is a list of 3-tuples: ``(long_option, short_option,
   help_string)``

   If an option takes an argument, its *long_option* should have ``'='`` appended;
   *short_option* should just be a single character, no ``':'`` in any case.
   *short_option* should be ``None`` if a *long_option*  doesn't have a
   corresponding *short_option*. All option tuples must have long options.

The :class:`FancyGetopt` class provides the following methods:


.. method:: FancyGetopt.getopt([args=None, object=None])

   Parse command-line options in args. Store as attributes on *object*.

   If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``.  If *object* is
   ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
   option values there, and returns a tuple ``(args, object)``.  If *object* is
   supplied, it is modified in place and :func:`getopt` just returns *args*; in
   both cases, the returned *args* is a modified copy of the passed-in *args* list,
   which is left untouched.

   .. % and args returned are?


.. method:: FancyGetopt.get_option_order()

   Returns the list of ``(option, value)`` tuples processed by the previous run of
   :meth:`getopt`  Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
   yet.


.. method:: FancyGetopt.generate_help([header=None])

   Generate help text (a list of strings, one per suggested line of output) from
   the option table for this :class:`FancyGetopt` object.

   If supplied, prints the supplied *header* at the top of the help.


:mod:`distutils.filelist` --- The FileList class
================================================

.. module:: distutils.filelist
   :synopsis: The FileList class, used for poking about the file system and
              building lists of files.


This module provides the :class:`FileList` class, used for poking about the
filesystem and building lists of files.


:mod:`distutils.log` --- Simple :pep:`282`-style logging
========================================================

.. module:: distutils.log
   :synopsis: A simple logging mechanism, :pep:`282`-style


:mod:`distutils.spawn` --- Spawn a sub-process
==============================================

.. module:: distutils.spawn
   :synopsis: Provides the spawn() function


This module provides the :func:`~distutils.spawn.spawn` function, a
front-end to  various platform-specific functions for launching another
program in a  sub-process.
Also provides :func:`~distutils.spawn.find_executable` to search the path for a given executable
name.


:mod:`distutils.sysconfig` --- System configuration information
===============================================================

.. module:: distutils.sysconfig
   :synopsis: Low-level access to configuration information of the Python interpreter.
.. moduleauthor:: Fred L. Drake, Jr. &lt;fdrake@acm.org&gt;
.. moduleauthor:: Greg Ward &lt;gward@python.net&gt;
.. sectionauthor:: Fred L. Drake, Jr. &lt;fdrake@acm.org&gt;


The :mod:`distutils.sysconfig` module provides access to Python's low-level
configuration information.  The specific configuration variables available
depend heavily on the platform and configuration. The specific variables depend
on the build process for the specific version of Python being run; the variables
are those found in the :file:`Makefile` and configuration header that are
installed with Python on Unix systems.  The configuration header is called
:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`
for earlier versions of Python.

Some additional functions are provided which perform some useful manipulations
for other parts of the :mod:`distutils` package.


.. data:: PREFIX

   The result of ``os.path.normpath(sys.prefix)``.


.. data:: EXEC_PREFIX

   The result of ``os.path.normpath(sys.exec_prefix)``.


.. function:: get_config_var(name)

   Return the value of a single variable.  This is equivalent to
   ``get_config_vars().get(name)``.


.. function:: get_config_vars(...)

   Return a set of variable definitions.  If there are no arguments, this returns a
   dictionary mapping names of configuration variables to values.  If arguments are
   provided, they should be strings, and the return value will be a sequence giving
   the associated values. If a given name does not have a corresponding value,
   ``None`` will be included for that variable.


.. function:: get_config_h_filename()

   Return the full path name of the configuration header.  For Unix, this will be
   the header generated by the :program:`configure` script; for other platforms the
   header will have been supplied directly by the Python source distribution.  The
   file is a platform-specific text file.


.. function:: get_makefile_filename()

   Return the full path name of the :file:`Makefile` used to build Python.  For
   Unix, this will be a file generated by the :program:`configure` script; the
   meaning for other platforms will vary.  The file is a platform-specific text
   file, if it exists. This function is only useful on POSIX platforms.


.. function:: get_python_inc([plat_specific[, prefix]])

   Return the directory for either the general or platform-dependent C include
   files.  If *plat_specific* is true, the platform-dependent include directory is
   returned; if false or omitted, the platform-independent directory is returned.
   If *prefix* is given, it is used as either the prefix instead of
   :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
   *plat_specific* is true.


.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])

   Return the directory for either the general or platform-dependent library
   installation.  If *plat_specific* is true, the platform-dependent include
   directory is returned; if false or omitted, the platform-independent directory
   is returned.  If *prefix* is given, it is used as either the prefix instead of
   :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
   *plat_specific* is true.  If *standard_lib* is true, the directory for the
   standard library is returned rather than the directory for the installation of
   third-party extensions.

The following function is only intended for use within the :mod:`distutils`
package.


.. function:: customize_compiler(compiler)

   Do any platform-specific customization of a
   :class:`distutils.ccompiler.CCompiler` instance.

   This function is only needed on Unix at this time, but should be called
   consistently to support forward-compatibility.  It inserts the information that
   varies across Unix flavors and is stored in Python's :file:`Makefile`.  This
   information includes the selected compiler, compiler and linker options, and the
   extension used by the linker for shared objects.

This function is even more special-purpose, and should only be used from
Python's own build procedures.


.. function:: set_python_build()

   Inform the :mod:`distutils.sysconfig` module that it is being used as part of
   the build process for Python.  This changes a lot of relative locations for
   files, allowing them to be located in the build area rather than in an installed
   Python.


:mod:`distutils.text_file` --- The TextFile class
=================================================

.. module:: distutils.text_file
   :synopsis: Provides the TextFile class, a simple interface to text files


This module provides the :class:`TextFile` class, which gives an interface  to
text files that (optionally) takes care of stripping comments, ignoring  blank
lines, and joining lines with backslashes.


.. class:: TextFile([filename=None, file=None, **options])

   This class provides a file-like object that takes care of all  the things you
   commonly want to do when processing a text file  that has some line-by-line
   syntax: strip comments (as long as ``#``  is your comment character), skip blank
   lines, join adjacent lines by escaping the newline (ie. backslash at end of
   line), strip leading and/or trailing whitespace.  All of these are optional and
   independently controllable.

   The class provides a :meth:`warn` method so you can generate  warning messages
   that report physical line number, even if the  logical line in question spans
   multiple physical lines.  Also  provides :meth:`unreadline` for implementing
   line-at-a-time lookahead.

   :class:`TextFile` instances are create with either *filename*, *file*, or both.
   :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a
   string, and *file* a file object (or something that provides :meth:`readline`
   and :meth:`close`  methods).  It is recommended that you supply at least
   *filename*,  so that :class:`TextFile` can include it in warning messages.  If
   *file* is not supplied, :class:`TextFile` creates its own using the
   :func:`open` built-in function.

   The options are all boolean, and affect the values returned by :meth:`readline`

   .. tabularcolumns:: |l|L|l|

   +------------------+--------------------------------+---------+
   | option name      | description                    | default |
   +==================+================================+=========+
   | *strip_comments* | strip from ``'#'`` to          | true    |
   |                  | end-of-line, as well as any    |         |
   |                  | whitespace leading up to the   |         |
   |                  | ``'#'``\ ---unless it is       |         |
   |                  | escaped by a backslash         |         |
   +------------------+--------------------------------+---------+
   | *lstrip_ws*      | strip leading whitespace from  | false   |
   |                  | each line before returning it  |         |
   +------------------+--------------------------------+---------+
   | *rstrip_ws*      | strip trailing whitespace      | true    |
   |                  | (including line terminator!)   |         |
   |                  | from each line before          |         |
   |                  | returning it.                  |         |
   +------------------+--------------------------------+---------+
   | *skip_blanks*    | skip lines that are empty      | true    |
   |                  | \*after\* stripping comments   |         |
   |                  | and whitespace.  (If both      |         |
   |                  | lstrip_ws and rstrip_ws are    |         |
   |                  | false, then some lines may     |         |
   |                  | consist of solely whitespace:  |         |
   |                  | these will \*not\* be skipped, |         |
   |                  | even if *skip_blanks* is       |         |
   |                  | true.)                         |         |
   +------------------+--------------------------------+---------+
   | *join_lines*     | if a backslash is the last     | false   |
   |                  | non-newline character on a     |         |
   |                  | line after stripping comments  |         |
   |                  | and whitespace, join the       |         |
   |                  | following line to it to form   |         |
   |                  | one logical line; if N         |         |
   |                  | consecutive lines end with a   |         |
   |                  | backslash, then N+1 physical   |         |
   |                  | lines will be joined to form   |         |
   |                  | one logical line.              |         |
   +------------------+--------------------------------+---------+
   | *collapse_join*  | strip leading whitespace from  | false   |
   |                  | lines that are joined to their |         |
   |                  | predecessor; only matters if   |         |
   |                  | ``(join_lines and not          |         |
   |                  | lstrip_ws)``                   |         |
   +------------------+--------------------------------+---------+

   Note that since *rstrip_ws* can strip the trailing newline, the semantics of
   :meth:`readline` must differ from those of the built-in file object's
   :meth:`readline` method!  In particular, :meth:`readline`  returns ``None`` for
   end-of-file: an empty string might just be a  blank line (or an all-whitespace
   line), if *rstrip_ws* is true  but *skip_blanks* is not.


   .. method:: TextFile.open(filename)

      Open a new file *filename*.  This overrides any *file* or *filename*
      constructor arguments.


   .. method:: TextFile.close()

      Close the current file and forget everything we know about it (including the
      filename and the current line number).


   .. method:: TextFile.warn(msg[,line=None])

      Print (to stderr) a warning message tied to the current logical line in the
      current file.  If the current logical line in the file spans multiple physical
      lines, the warning refers to the whole range, such as ``&quot;lines 3-5&quot;``.  If
      *line* is supplied,  it overrides the current line number; it may be a list or
      tuple  to indicate a range of physical lines, or an integer for a  single
      physical line.


   .. method:: TextFile.readline()

      Read and return a single logical line from the current file (or from an internal
      buffer if lines have previously been &quot;unread&quot; with :meth:`unreadline`).  If the
      *join_lines* option  is true, this may involve reading multiple physical lines
      concatenated into a single string.  Updates the current line number,  so calling
      :meth:`warn` after :meth:`readline` emits a warning  about the physical line(s)
      just read.  Returns ``None`` on end-of-file,  since the empty string can occur
      if *rstrip_ws* is true but  *strip_blanks* is not.


   .. method:: TextFile.readlines()

      Read and return the list of all logical lines remaining in the current file.
      This updates the current line number to the last line of the file.


   .. method:: TextFile.unreadline(line)

      Push *line* (a string) onto an internal buffer that will be checked by future
      :meth:`readline` calls.  Handy for implementing a parser with line-at-a-time
      lookahead. Note that lines that are &quot;unread&quot; with :meth:`unreadline` are not
      subsequently re-cleansed (whitespace  stripped, or whatever) when read with
      :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call
      to :meth:`readline`, the lines will be returned most in most recent first order.


:mod:`distutils.version` --- Version number classes
===================================================

.. module:: distutils.version
   :synopsis: Implements classes that represent module version numbers.


.. % todo
.. % \section{Distutils Commands}
.. %
.. % This part of Distutils implements the various Distutils commands, such
.. % as \code{build}, \code{install} \&amp;c. Each command is implemented as a
.. % separate module, with the command name as the name of the module.


:mod:`distutils.cmd` --- Abstract base class for Distutils commands
===================================================================

.. module:: distutils.cmd
   :synopsis: Provides the abstract base class :class:`~distutils.cmd.Command`. This class
              is subclassed by the modules in the distutils.command subpackage.


This module supplies the abstract base class :class:`Command`.


.. class:: Command(dist)

   Abstract base class for defining command classes, the &quot;worker bees&quot; of the
   Distutils.  A useful analogy for command classes is to think of them as
   subroutines with local variables called *options*.  The options are declared
   in :meth:`initialize_options` and defined (given their final values) in
   :meth:`finalize_options`, both of which must be defined by every command
   class.  The distinction between the two is necessary because option values
   might come from the outside world (command line, config file, ...), and any
   options dependent on other options must be computed after these outside
   influences have been processed --- hence :meth:`finalize_options`.  The body
   of the subroutine, where it does all its work based on the values of its
   options, is the :meth:`run` method, which must also be implemented by every
   command class.

   The class constructor takes a single argument *dist*, a
   :class:`~distutils.core.Distribution` instance.


Creating a new Distutils command
================================

This section outlines the steps to create a new Distutils command.

A new command lives in a module in the :mod:`distutils.command` package. There
is a sample template in that directory called :file:`command_template`.  Copy
this file to a new module with the same name as the new command you're
implementing.  This module should implement a class with the same name as the
module (and the command).  So, for instance, to create the command
``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
it so that it's implementing the class ``peel_banana``, a subclass of
:class:`distutils.cmd.Command`.

Subclasses of :class:`Command` must define the following methods.

.. method:: Command.initialize_options()

   Set default values for all the options that this command supports.  Note that
   these defaults may be overridden by other commands, by the setup script, by
   config files, or by the command-line.  Thus, this is not the place to code
   dependencies between options; generally, :meth:`initialize_options`
   implementations are just a bunch of ``self.foo = None`` assignments.


.. method:: Command.finalize_options()

   Set final values for all the options that this command supports. This is
   always called as late as possible, ie.  after any option assignments from the
   command-line or from other commands have been done.  Thus, this is the place
   to code option dependencies: if *foo* depends on *bar*, then it is safe to
   set *foo* from *bar* as long as *foo* still has the same value it was
   assigned in :meth:`initialize_options`.


.. method:: Command.run()

   A command's raison d'etre: carry out the action it exists to perform, controlled
   by the options initialized in :meth:`initialize_options`, customized by other
   commands, the setup script, the command-line, and config files, and finalized in
   :meth:`finalize_options`.  All terminal output and filesystem interaction should
   be done by :meth:`run`.


.. attribute:: Command.sub_commands

   *sub_commands* formalizes the notion of a &quot;family&quot; of commands,
   e.g. ``install`` as the parent with sub-commands ``install_lib``,
   ``install_headers``, etc.  The parent of a family of commands defines
   *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,
   predicate)``, with *command_name* a string and *predicate* a function, a
   string or ``None``.  *predicate* is a method of the parent command that
   determines whether the corresponding command is applicable in the current
   situation.  (E.g. ``install_headers`` is only applicable if we have any C
   header files to install.)  If *predicate* is ``None``, that command is always
   applicable.

   *sub_commands* is usually defined at the *end* of a class, because
   predicates can be methods of the class, so they must already have been
   defined.  The canonical example is the :command:`install` command.


:mod:`distutils.command` --- Individual Distutils commands
==========================================================

.. module:: distutils.command
   :synopsis: Contains one module for each standard Distutils command.


.. % \subsubsection{Individual Distutils commands}
.. % todo


:mod:`distutils.command.bdist` --- Build a binary installer
===========================================================

.. module:: distutils.command.bdist
   :synopsis: Build a binary installer for a package


.. % todo


:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
=============================================================================

.. module:: distutils.command.bdist_packager
   :synopsis: Abstract base class for packagers


.. % todo


:mod:`distutils.command.bdist_dumb` --- Build a &quot;dumb&quot; installer
================================================================

.. module:: distutils.command.bdist_dumb
   :synopsis: Build a &quot;dumb&quot; installer - a simple archive of files


.. % todo


:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
=================================================================================

.. module:: distutils.command.bdist_msi
   :synopsis: Build a binary distribution as a Windows MSI file

.. class:: bdist_msi

.. deprecated:: 3.9
   Use bdist_wheel (wheel packages) instead.

   Builds a `Windows Installer`_ (.msi) binary package.

   .. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx

   In most cases, the ``bdist_msi`` installer is a better choice than the
   ``bdist_wininst`` installer, because it provides better support for
   Win64 platforms, allows administrators to perform non-interactive
   installations, and allows installation through group policies.


:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
===========================================================================================

.. module:: distutils.command.bdist_rpm
   :synopsis: Build a binary distribution as a Redhat RPM and SRPM


.. % todo


:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
====================================================================

.. module:: distutils.command.bdist_wininst
   :synopsis: Build a Windows installer

.. deprecated:: 3.8
   Use bdist_wheel (wheel packages) instead.


.. % todo


:mod:`distutils.command.sdist` --- Build a source distribution
==============================================================

.. module:: distutils.command.sdist
   :synopsis: Build a source distribution


.. % todo


:mod:`distutils.command.build` --- Build all files of a package
===============================================================

.. module:: distutils.command.build
   :synopsis: Build all files of a package


.. % todo


:mod:`distutils.command.build_clib` --- Build any C libraries in a package
==========================================================================

.. module:: distutils.command.build_clib
   :synopsis: Build any C libraries in a package


.. % todo


:mod:`distutils.command.build_ext` --- Build any extensions in a package
========================================================================

.. module:: distutils.command.build_ext
   :synopsis: Build any extensions in a package


.. % todo


:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
===========================================================================

.. module:: distutils.command.build_py
   :synopsis: Build the .py/.pyc files of a package


.. class:: build_py


:mod:`distutils.command.build_scripts` --- Build the scripts of a package
=========================================================================

.. module:: distutils.command.build_scripts
   :synopsis: Build the scripts of a package


.. % todo


:mod:`distutils.command.clean` --- Clean a package build area
=============================================================

.. module:: distutils.command.clean
   :synopsis: Clean a package build area

This command removes the temporary files created by :command:`build`
and its subcommands, like intermediary compiled object files.  With
the ``--all`` option, the complete build directory will be removed.

Extension modules built :ref:`in place &lt;distutils-build-ext-inplace&gt;`
will not be cleaned, as they are not in the build directory.


:mod:`distutils.command.config` --- Perform package configuration
=================================================================

.. module:: distutils.command.config
   :synopsis: Perform package configuration


.. % todo


:mod:`distutils.command.install` --- Install a package
======================================================

.. module:: distutils.command.install
   :synopsis: Install a package


.. % todo


:mod:`distutils.command.install_data` --- Install data files from a package
===========================================================================

.. module:: distutils.command.install_data
   :synopsis: Install data files from a package


.. % todo


:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
======================================================================================

.. module:: distutils.command.install_headers
   :synopsis: Install C/C++ header files from a package


.. % todo


:mod:`distutils.command.install_lib` --- Install library files from a package
=============================================================================

.. module:: distutils.command.install_lib
   :synopsis: Install library files from a package


.. % todo


:mod:`distutils.command.install_scripts` --- Install script files from a package
================================================================================

.. module:: distutils.command.install_scripts
   :synopsis: Install script files from a package


.. % todo


:mod:`distutils.command.register` --- Register a module with the Python Package Index
=====================================================================================

.. module:: distutils.command.register
   :synopsis: Register a module with the Python Package Index


The ``register`` command registers the package with the Python Package  Index.
This is described in more detail in :pep:`301`.

.. % todo


:mod:`distutils.command.check` --- Check the meta-data of a package
===================================================================

.. module:: distutils.command.check
   :synopsis: Check the meta-data of a package


The ``check`` command performs some tests on the meta-data of a package.
For example, it verifies that all required meta-data are provided as
the arguments passed to the :func:`~distutils.core.setup` function.

.. % todo
                                                                                                                                                                                                                                                                                                                                                                                                        python_eggs.rst                                                                                     0000644                 00000074337 15052074023 0007640 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       =====================================
The Internal Structure of Python Eggs
=====================================

STOP! This is not the first document you should read!


----------------------
Eggs and their Formats
----------------------

A &quot;Python egg&quot; is a logical structure embodying the release of a
specific version of a Python project, comprising its code, resources,
and metadata. There are multiple formats that can be used to physically
encode a Python egg, and others can be developed. However, a key
principle of Python eggs is that they should be discoverable and
importable. That is, it should be possible for a Python application to
easily and efficiently find out what eggs are present on a system, and
to ensure that the desired eggs' contents are importable.

There are two basic formats currently implemented for Python eggs:

1. ``.egg`` format: a directory or zipfile *containing* the project's
   code and resources, along with an ``EGG-INFO`` subdirectory that
   contains the project's metadata

2. ``.egg-info`` format: a file or directory placed *adjacent* to the
   project's code and resources, that directly contains the project's
   metadata.

Both formats can include arbitrary Python code and resources, including
static data files, package and non-package directories, Python
modules, C extension modules, and so on.  But each format is optimized
for different purposes.

The ``.egg`` format is well-suited to distribution and the easy
uninstallation or upgrades of code, since the project is essentially
self-contained within a single directory or file, unmingled with any
other projects' code or resources.  It also makes it possible to have
multiple versions of a project simultaneously installed, such that
individual programs can select the versions they wish to use.

The ``.egg-info`` format, on the other hand, was created to support
backward-compatibility, performance, and ease of installation for system
packaging tools that expect to install all projects' code and resources
to a single directory (e.g. ``site-packages``).  Placing the metadata
in that same directory simplifies the installation process, since it
isn't necessary to create ``.pth`` files or otherwise modify
``sys.path`` to include each installed egg.

Its disadvantage, however, is that it provides no support for clean
uninstallation or upgrades, and of course only a single version of a
project can be installed to a given directory. Thus, support from a
package management tool is required. (This is why setuptools' &quot;install&quot;
command refers to this type of egg installation as &quot;single-version,
externally managed&quot;.)  Also, they lack sufficient data to allow them to
be copied from their installation source.  easy_install can &quot;ship&quot; an
application by copying ``.egg`` files or directories to a target
location, but it cannot do this for ``.egg-info`` installs, because
there is no way to tell what code and resources belong to a particular
egg -- there may be several eggs &quot;scrambled&quot; together in a single
installation location, and the ``.egg-info`` format does not currently
include a way to list the files that were installed.  (This may change
in a future version.)


Code and Resources
==================

The layout of the code and resources is dictated by Python's normal
import layout, relative to the egg's &quot;base location&quot;.

For the ``.egg`` format, the base location is the ``.egg`` itself. That
is, adding the ``.egg`` filename or directory name to ``sys.path``
makes its contents importable.

For the ``.egg-info`` format, however, the base location is the
directory that *contains* the ``.egg-info``, and thus it is the
directory that must be added to ``sys.path`` to make the egg importable.
(Note that this means that the &quot;normal&quot; installation of a package to a
``sys.path`` directory is sufficient to make it an &quot;egg&quot; if it has an
``.egg-info`` file or directory installed alongside of it.)


Project Metadata
=================

If eggs contained only code and resources, there would of course be
no difference between them and any other directory or zip file on
``sys.path``.  Thus, metadata must also be included, using a metadata
file or directory.

For the ``.egg`` format, the metadata is placed in an ``EGG-INFO``
subdirectory, directly within the ``.egg`` file or directory.  For the
``.egg-info`` format, metadata is stored directly within the
``.egg-info`` directory itself.

The minimum project metadata that all eggs must have is a standard
Python ``PKG-INFO`` file, named ``PKG-INFO`` and placed within the
metadata directory appropriate to the format.  Because it's possible for
this to be the only metadata file included, ``.egg-info`` format eggs
are not required to be a directory; they can just be a ``.egg-info``
file that directly contains the ``PKG-INFO`` metadata.  This eliminates
the need to create a directory just to store one file.  This option is
*not* available for ``.egg`` formats, since setuptools always includes
other metadata.  (In fact, setuptools itself never generates
``.egg-info`` files, either; the support for using files was added so
that the requirement could easily be satisfied by other tools, such
as distutils).

In addition to the ``PKG-INFO`` file, an egg's metadata directory may
also include files and directories representing various forms of
optional standard metadata (see the section on `Standard Metadata`_,
below) or user-defined metadata required by the project.  For example,
some projects may define a metadata format to describe their application
plugins, and metadata in this format would then be included by plugin
creators in their projects' metadata directories.


Filename-Embedded Metadata
==========================

To allow introspection of installed projects and runtime resolution of
inter-project dependencies, a certain amount of information is embedded
in egg filenames.  At a minimum, this includes the project name, and
ideally will also include the project version number.  Optionally, it
can also include the target Python version and required runtime
platform if platform-specific C code is included.  The syntax of an
egg filename is as follows::

    name [&quot;-&quot; version [&quot;-py&quot; pyver [&quot;-&quot; required_platform]]] &quot;.&quot; ext

The &quot;name&quot; and &quot;version&quot; should be escaped using the ``to_filename()``
function provided by ``pkg_resources``, after first processing them with
``safe_name()`` and ``safe_version()`` respectively.  These latter two
functions can also be used to later &quot;unescape&quot; these parts of the
filename.  (For a detailed description of these transformations, please
see the &quot;Parsing Utilities&quot; section of the ``pkg_resources`` manual.)

The &quot;pyver&quot; string is the Python major version, as found in the first
3 characters of ``sys.version``.  &quot;required_platform&quot; is essentially
a distutils ``get_platform()`` string, but with enhancements to properly
distinguish Mac OS versions.  (See the ``get_build_platform()``
documentation in the &quot;Platform Utilities&quot; section of the
``pkg_resources`` manual for more details.)

Finally, the &quot;ext&quot; is either ``.egg`` or ``.egg-info``, as appropriate
for the egg's format.

Normally, an egg's filename should include at least the project name and
version, as this allows the runtime system to find desired project
versions without having to read the egg's PKG-INFO to determine its
version number.

Setuptools, however, only includes the version number in the filename
when an ``.egg`` file is built using the ``bdist_egg`` command, or when
an ``.egg-info`` directory is being installed by the
``install_egg_info`` command. When generating metadata for use with the
original source tree, it only includes the project name, so that the
directory will not have to be renamed each time the project's version
changes.

This is especially important when version numbers change frequently, and
the source metadata directory is kept under version control with the
rest of the project.  (As would be the case when the project's source
includes project-defined metadata that is not generated from by
setuptools from data in the setup script.)


Egg Links
=========

In addition to the ``.egg`` and ``.egg-info`` formats, there is a third
egg-related extension that you may encounter on occasion: ``.egg-link``
files.

These files are not eggs, strictly speaking. They simply provide a way
to reference an egg that is not physically installed in the desired
location. They exist primarily as a cross-platform alternative to
symbolic links, to support &quot;installing&quot; code that is being developed in
a different location than the desired installation location. For
example, if a user is developing an application plugin in their home
directory, but the plugin needs to be &quot;installed&quot; in an application
plugin directory, running &quot;setup.py develop -md /path/to/app/plugins&quot;
will install an ``.egg-link`` file in ``/path/to/app/plugins``, that
tells the egg runtime system where to find the actual egg (the user's
project source directory and its ``.egg-info`` subdirectory).

``.egg-link`` files are named following the format for ``.egg`` and
``.egg-info`` names, but only the project name is included; no version,
Python version, or platform information is included.  When the runtime
searches for available eggs, ``.egg-link`` files are opened and the
actual egg file/directory name is read from them.

Each ``.egg-link`` file should contain a single file or directory name,
with no newlines.  This filename should be the base location of one or
more eggs.  That is, the name must either end in ``.egg``, or else it
should be the parent directory of one or more ``.egg-info`` format eggs.

As of setuptools 0.6c6, the path may be specified as a platform-independent
(i.e. ``/``-separated) relative path from the directory containing the
``.egg-link`` file, and a second line may appear in the file, specifying a
platform-independent relative path from the egg's base directory to its
setup script directory.  This allows installation tools such as EasyInstall
to find the project's setup directory and build eggs or perform other setup
commands on it.


-----------------
Standard Metadata
-----------------

In addition to the minimum required ``PKG-INFO`` metadata, projects can
include a variety of standard metadata files or directories, as
described below.  Except as otherwise noted, these files and directories
are automatically generated by setuptools, based on information supplied
in the setup script or through analysis of the project's code and
resources.

Most of these files and directories are generated via &quot;egg-info
writers&quot; during execution of the setuptools ``egg_info`` command, and
are listed in the ``egg_info.writers`` entry point group defined by
setuptools' own ``setup.py`` file.

Project authors can register their own metadata writers as entry points
in this group (as described in the setuptools manual under &quot;Adding new
EGG-INFO Files&quot;) to cause setuptools to generate project-specific
metadata files or directories during execution of the ``egg_info``
command.  It is up to project authors to document these new metadata
formats, if they create any.


``.txt`` File Formats
=====================

Files described in this section that have ``.txt`` extensions have a
simple lexical format consisting of a sequence of text lines, each line
terminated by a linefeed character (regardless of platform).  Leading
and trailing whitespace on each line is ignored, as are blank lines and
lines whose first nonblank character is a ``#`` (comment symbol).  (This
is the parsing format defined by the ``yield_lines()`` function of
the ``pkg_resources`` module.)

All ``.txt`` files defined by this section follow this format, but some
are also &quot;sectioned&quot; files, meaning that their contents are divided into
sections, using square-bracketed section headers akin to Windows
``.ini`` format.  Note that this does *not* imply that the lines within
the sections follow an ``.ini`` format, however.  Please see an
individual metadata file's documentation for a description of what the
lines and section names mean in that particular file.

Sectioned files can be parsed using the ``split_sections()`` function;
see the &quot;Parsing Utilities&quot; section of the ``pkg_resources`` manual for
for details.


Dependency Metadata
===================


``requires.txt``
----------------

This is a &quot;sectioned&quot; text file.  Each section is a sequence of
&quot;requirements&quot;, as parsed by the ``parse_requirements()`` function;
please see the ``pkg_resources`` manual for the complete requirement
parsing syntax.

The first, unnamed section (i.e., before the first section header) in
this file is the project's core requirements, which must be installed
for the project to function.  (Specified using the ``install_requires``
keyword to ``setup()``).

The remaining (named) sections describe the project's &quot;extra&quot;
requirements, as specified using the ``extras_require`` keyword to
``setup()``.  The section name is the name of the optional feature, and
the section body lists that feature's dependencies.

Note that it is not normally necessary to inspect this file directly;
``pkg_resources.Distribution`` objects have a ``requires()`` method
that can be used to obtain ``Requirement`` objects describing the
project's core and optional dependencies.


``setup_requires.txt``
----------------------

Much like ``requires.txt`` except represents the requirements
specified by the ``setup_requires`` parameter to the Distribution.


``dependency_links.txt``
------------------------

A list of dependency URLs, one per line, as specified using the
``dependency_links`` keyword to ``setup()``.  These may be direct
download URLs, or the URLs of web pages containing direct download
links. Please see the setuptools manual for more information on
specifying this option.


``depends.txt`` -- Obsolete, do not create!
-------------------------------------------

This file follows an identical format to ``requires.txt``, but is
obsolete and should not be used.  The earliest versions of setuptools
required users to manually create and maintain this file, so the runtime
still supports reading it, if it exists.  The new filename was created
so that it could be automatically generated from ``setup()`` information
without overwriting an existing hand-created ``depends.txt``, if one
was already present in the project's source ``.egg-info`` directory.


``namespace_packages.txt`` -- Namespace Package Metadata
========================================================

A list of namespace package names, one per line, as supplied to the
``namespace_packages`` keyword to ``setup()``.  Please see the manuals
for setuptools and ``pkg_resources`` for more information about
namespace packages.


``entry_points.txt`` -- &quot;Entry Point&quot;/Plugin Metadata
=====================================================

This is a &quot;sectioned&quot; text file, whose contents encode the
``entry_points`` keyword supplied to ``setup()``.  All sections are
named, as the section names specify the entry point groups in which the
corresponding section's entry points are registered.

Each section is a sequence of &quot;entry point&quot; lines, each parseable using
the ``EntryPoint.parse`` classmethod; please see the ``pkg_resources``
manual for the complete entry point parsing syntax.

Note that it is not necessary to parse this file directly; the
``pkg_resources`` module provides a variety of APIs to locate and load
entry points automatically.  Please see the setuptools and
``pkg_resources`` manuals for details on the nature and uses of entry
points.


The ``scripts`` Subdirectory
============================

This directory is currently only created for ``.egg`` files built by
the setuptools ``bdist_egg`` command.  It will contain copies of all
of the project's &quot;traditional&quot; scripts (i.e., those specified using the
``scripts`` keyword to ``setup()``).  This is so that they can be
reconstituted when an ``.egg`` file is installed.

The scripts are placed here using the distutils' standard
``install_scripts`` command, so any ``#!`` lines reflect the Python
installation where the egg was built.  But instead of copying the
scripts to the local script installation directory, EasyInstall writes
short wrapper scripts that invoke the original scripts from inside the
egg, after ensuring that sys.path includes the egg and any eggs it
depends on.  For more about `script wrappers`_, see the section below on
`Installation and Path Management Issues`_.


Zip Support Metadata
====================


``native_libs.txt``
-------------------

A list of C extensions and other dynamic link libraries contained in
the egg, one per line.  Paths are ``/``-separated and relative to the
egg's base location.

This file is generated as part of ``bdist_egg`` processing, and as such
only appears in ``.egg`` files (and ``.egg`` directories created by
unpacking them).  It is used to ensure that all libraries are extracted
from a zipped egg at the same time, in case there is any direct linkage
between them.  Please see the `Zip File Issues`_ section below for more
information on library and resource extraction from ``.egg`` files.


``eager_resources.txt``
-----------------------

A list of resource files and/or directories, one per line, as specified
via the ``eager_resources`` keyword to ``setup()``.  Paths are
``/``-separated and relative to the egg's base location.

Resource files or directories listed here will be extracted
simultaneously, if any of the named resources are extracted, or if any
native libraries listed in ``native_libs.txt`` are extracted.  Please
see the setuptools manual for details on what this feature is used for
and how it works, as well as the `Zip File Issues`_ section below.


``zip-safe`` and ``not-zip-safe``
---------------------------------

These are zero-length files, and either one or the other should exist.
If ``zip-safe`` exists, it means that the project will work properly
when installed as an ``.egg`` zipfile, and conversely the existence of
``not-zip-safe`` means the project should not be installed as an
``.egg`` file.  The ``zip_safe`` option to setuptools' ``setup()``
determines which file will be written. If the option isn't provided,
setuptools attempts to make its own assessment of whether the package
can work, based on code and content analysis.

If neither file is present at installation time, EasyInstall defaults
to assuming that the project should be unzipped.  (Command-line options
to EasyInstall, however, take precedence even over an existing
``zip-safe`` or ``not-zip-safe`` file.)

Note that these flag files appear only in ``.egg`` files generated by
``bdist_egg``, and in ``.egg`` directories created by unpacking such an
``.egg`` file.


``top_level.txt`` -- Conflict Management Metadata
=================================================

This file is a list of the top-level module or package names provided
by the project, one Python identifier per line.

Subpackages are not included; a project containing both a ``foo.bar``
and a ``foo.baz`` would include only one line, ``foo``, in its
``top_level.txt``.

This data is used by ``pkg_resources`` at runtime to issue a warning if
an egg is added to ``sys.path`` when its contained packages may have
already been imported.

(It was also once used to detect conflicts with non-egg packages at
installation time, but in more recent versions, setuptools installs eggs
in such a way that they always override non-egg packages, thus
preventing a problem from arising.)


``SOURCES.txt`` -- Source Files Manifest
========================================

This file is roughly equivalent to the distutils' ``MANIFEST`` file.
The differences are as follows:

* The filenames always use ``/`` as a path separator, which must be
  converted back to a platform-specific path whenever they are read.

* The file is automatically generated by setuptools whenever the
  ``egg_info`` or ``sdist`` commands are run, and it is *not*
  user-editable.

Although this metadata is included with distributed eggs, it is not
actually used at runtime for any purpose.  Its function is to ensure
that setuptools-built *source* distributions can correctly discover
what files are part of the project's source, even if the list had been
generated using revision control metadata on the original author's
system.

In other words, ``SOURCES.txt`` has little or no runtime value for being
included in distributed eggs, and it is possible that future versions of
the ``bdist_egg`` and ``install_egg_info`` commands will strip it before
installation or distribution.  Therefore, do not rely on its being
available outside of an original source directory or source
distribution.


------------------------------
Other Technical Considerations
------------------------------


Zip File Issues
===============

Although zip files resemble directories, they are not fully
substitutable for them.  Most platforms do not support loading dynamic
link libraries contained in zipfiles, so it is not possible to directly
import C extensions from ``.egg`` zipfiles.  Similarly, there are many
existing libraries -- whether in Python or C -- that require actual
operating system filenames, and do not work with arbitrary &quot;file-like&quot;
objects or in-memory strings, and thus cannot operate directly on the
contents of zip files.

To address these issues, the ``pkg_resources`` module provides a
&quot;resource API&quot; to support obtaining either the contents of a resource,
or a true operating system filename for the resource.  If the egg
containing the resource is a directory, the resource's real filename
is simply returned.  However, if the egg is a zipfile, then the
resource is first extracted to a cache directory, and the filename
within the cache is returned.

The cache directory is determined by the ``pkg_resources`` API; please
see the ``set_cache_path()`` and ``get_default_cache()`` documentation
for details.


The Extraction Process
----------------------

Resources are extracted to a cache subdirectory whose name is based
on the enclosing ``.egg`` filename and the path to the resource.  If
there is already a file of the correct name, size, and timestamp, its
filename is returned to the requester.  Otherwise, the desired file is
extracted first to a temporary name generated using
``mkstemp(&quot;.$extract&quot;,target_dir)``, and then its timestamp is set to
match the one in the zip file, before renaming it to its final name.
(Some collision detection and resolution code is used to handle the
fact that Windows doesn't overwrite files when renaming.)

If a resource directory is requested, all of its contents are
recursively extracted in this fashion, to ensure that the directory
name can be used as if it were valid all along.

If the resource requested for extraction is listed in the
``native_libs.txt`` or ``eager_resources.txt`` metadata files, then
*all* resources listed in *either* file will be extracted before the
requested resource's filename is returned, thus ensuring that all
C extensions and data used by them will be simultaneously available.


Extension Import Wrappers
-------------------------

Since Python's built-in zip import feature does not support loading
C extension modules from zipfiles, the setuptools ``bdist_egg`` command
generates special import wrappers to make it work.

The wrappers are ``.py`` files (along with corresponding ``.pyc``
and/or ``.pyo`` files) that have the same module name as the
corresponding C extension.  These wrappers are located in the same
package directory (or top-level directory) within the zipfile, so that
say, ``foomodule.so`` will get a corresponding ``foo.py``, while
``bar/baz.pyd`` will get a corresponding ``bar/baz.py``.

These wrapper files contain a short stanza of Python code that asks
``pkg_resources`` for the filename of the corresponding C extension,
then reloads the module using the obtained filename.  This will cause
``pkg_resources`` to first ensure that all of the egg's C extensions
(and any accompanying &quot;eager resources&quot;) are extracted to the cache
before attempting to link to the C library.

Note, by the way, that ``.egg`` directories will also contain these
wrapper files.  However, Python's default import priority is such that
C extensions take precedence over same-named Python modules, so the
import wrappers are ignored unless the egg is a zipfile.


Installation and Path Management Issues
=======================================

Python's initial setup of ``sys.path`` is very dependent on the Python
version and installation platform, as well as how Python was started
(i.e., script vs. ``-c`` vs. ``-m`` vs. interactive interpreter).
In fact, Python also provides only two relatively robust ways to affect
``sys.path`` outside of direct manipulation in code: the ``PYTHONPATH``
environment variable, and ``.pth`` files.

However, with no cross-platform way to safely and persistently change
environment variables, this leaves ``.pth`` files as EasyInstall's only
real option for persistent configuration of ``sys.path``.

But ``.pth`` files are rather strictly limited in what they are allowed
to do normally.  They add directories only to the *end* of ``sys.path``,
after any locally-installed ``site-packages`` directory, and they are
only processed *in* the ``site-packages`` directory to start with.

This is a double whammy for users who lack write access to that
directory, because they can't create a ``.pth`` file that Python will
read, and even if a sympathetic system administrator adds one for them
that calls ``site.addsitedir()`` to allow some other directory to
contain ``.pth`` files, they won't be able to install newer versions of
anything that's installed in the systemwide ``site-packages``, because
their paths will still be added *after* ``site-packages``.

So EasyInstall applies two workarounds to solve these problems.

The first is that EasyInstall leverages ``.pth`` files' &quot;import&quot; feature
to manipulate ``sys.path`` and ensure that anything EasyInstall adds
to a ``.pth`` file will always appear before both the standard library
and the local ``site-packages`` directories.  Thus, it is always
possible for a user who can write a Python-read ``.pth`` file to ensure
that their packages come first in their own environment.

Second, when installing to a ``PYTHONPATH`` directory (as opposed to
a &quot;site&quot; directory like ``site-packages``) EasyInstall will also install
a special version of the ``site`` module.  Because it's in a
``PYTHONPATH`` directory, this module will get control before the
standard library version of ``site`` does.  It will record the state of
``sys.path`` before invoking the &quot;real&quot; ``site`` module, and then
afterwards it processes any ``.pth`` files found in ``PYTHONPATH``
directories, including all the fixups needed to ensure that eggs always
appear before the standard library in sys.path, but are in a relative
order to one another that is defined by their ``PYTHONPATH`` and
``.pth``-prescribed sequence.

The net result of these changes is that ``sys.path`` order will be
as follows at runtime:

1. The ``sys.argv[0]`` directory, or an empty string if no script
   is being executed.

2. All eggs installed by EasyInstall in any ``.pth`` file in each
   ``PYTHONPATH`` directory, in order first by ``PYTHONPATH`` order,
   then normal ``.pth`` processing order (which is to say alphabetical
   by ``.pth`` filename, then by the order of listing within each
   ``.pth`` file).

3. All eggs installed by EasyInstall in any ``.pth`` file in each &quot;site&quot;
   directory (such as ``site-packages``), following the same ordering
   rules as for the ones on ``PYTHONPATH``.

4. The ``PYTHONPATH`` directories themselves, in their original order

5. Any paths from ``.pth`` files found on ``PYTHONPATH`` that were *not*
   eggs installed by EasyInstall, again following the same relative
   ordering rules.

6. The standard library and &quot;site&quot; directories, along with the contents
   of any ``.pth`` files found in the &quot;site&quot; directories.

Notice that sections 1, 4, and 6 comprise the &quot;normal&quot; Python setup for
``sys.path``.  Sections 2 and 3 are inserted to support eggs, and
section 5 emulates what the &quot;normal&quot; semantics of ``.pth`` files on
``PYTHONPATH`` would be if Python natively supported them.

For further discussion of the tradeoffs that went into this design, as
well as notes on the actual magic inserted into ``.pth`` files to make
them do these things, please see also the following messages to the
distutils-SIG mailing list:

* http://mail.python.org/pipermail/distutils-sig/2006-February/006026.html
* http://mail.python.org/pipermail/distutils-sig/2006-March/006123.html


Script Wrappers
---------------

EasyInstall never directly installs a project's original scripts to
a script installation directory.  Instead, it writes short wrapper
scripts that first ensure that the project's dependencies are active
on sys.path, before invoking the original script.  These wrappers
have a #! line that points to the version of Python that was used to
install them, and their second line is always a comment that indicates
the type of script wrapper, the project version required for the script
to run, and information identifying the script to be invoked.

The format of this marker line is::

    &quot;# EASY-INSTALL-&quot; script_type &quot;: &quot; tuple_of_strings &quot;\n&quot;

The ``script_type`` is one of ``SCRIPT``, ``DEV-SCRIPT``, or
``ENTRY-SCRIPT``.  The ``tuple_of_strings`` is a comma-separated
sequence of Python string constants.  For ``SCRIPT`` and ``DEV-SCRIPT``
wrappers, there are two strings: the project version requirement, and
the script name (as a filename within the ``scripts`` metadata
directory).  For ``ENTRY-SCRIPT`` wrappers, there are three:
the project version requirement, the entry point group name, and the
entry point name.  (See the &quot;Automatic Script Creation&quot; section in the
setuptools manual for more information about entry point scripts.)

In each case, the project version requirement string will be a string
parseable with the ``pkg_resources`` modules' ``Requirement.parse()``
classmethod.  The only difference between a ``SCRIPT`` wrapper and a
``DEV-SCRIPT`` is that a ``DEV-SCRIPT`` actually executes the original
source script in the project's source tree, and is created when the
&quot;setup.py develop&quot; command is run.  A ``SCRIPT`` wrapper, on the other
hand, uses the &quot;installed&quot; script written to the ``EGG-INFO/scripts``
subdirectory of the corresponding ``.egg`` zipfile or directory.
(``.egg-info`` eggs do not have script wrappers associated with them,
except in the &quot;setup.py develop&quot; case.)

The purpose of including the marker line in generated script wrappers is
to facilitate introspection of installed scripts, and their relationship
to installed eggs.  For example, an uninstallation tool could use this
data to identify what scripts can safely be removed, and/or identify
what scripts would stop working if a particular egg is uninstalled.
                                                                                                                                                                                                                                                                                                 easy_install.rst                                                                                    0000644                 00000145652 15052074023 0010000 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       ============
Easy Install
============

.. warning::
    Easy Install is deprecated. Do not use it. Instead use pip. If
    you think you need Easy Install, please reach out to the PyPA
    team (a ticket to pip or setuptools is fine), describing your
    use-case.

Easy Install is a python module (``easy_install``) bundled with ``setuptools``
that lets you automatically download, build, install, and manage Python
packages.

Please share your experiences with us! If you encounter difficulty installing
a package, please contact us via the `distutils mailing list
&lt;http://mail.python.org/pipermail/distutils-sig/&gt;`_.  (Note: please DO NOT send
private email directly to the author of setuptools; it will be discarded.  The
mailing list is a searchable archive of previously-asked and answered
questions; you should begin your research there before reporting something as a
bug -- and then do so via list discussion first.)

(Also, if you'd like to learn about how you can use ``setuptools`` to make your
own packages work better with EasyInstall, or provide EasyInstall-like features
without requiring your users to use EasyInstall directly, you'll probably want
to check out the full documentation as well.)

Using &quot;Easy Install&quot;
====================


.. _installation instructions:

Installing &quot;Easy Install&quot;
-------------------------

Please see the `setuptools PyPI page &lt;https://pypi.org/project/setuptools/&gt;`_
for download links and basic installation instructions for each of the
supported platforms.

You will need at least Python 3.5 or 2.7.  An ``easy_install`` script will be
installed in the normal location for Python scripts on your platform.

Note that the instructions on the setuptools PyPI page assume that you are
are installing to Python's primary ``site-packages`` directory.  If this is
not the case, you should consult the section below on `Custom Installation
Locations`_ before installing.  (And, on Windows, you should not use the
``.exe`` installer when installing to an alternate location.)

Note that ``easy_install`` normally works by downloading files from the
internet.  If you are behind an NTLM-based firewall that prevents Python
programs from accessing the net directly, you may wish to first install and use
the `APS proxy server &lt;http://ntlmaps.sf.net/&gt;`_, which lets you get past such
firewalls in the same way that your web browser(s) do.

(Alternately, if you do not wish easy_install to actually download anything, you
can restrict it from doing so with the ``--allow-hosts`` option; see the
sections on `restricting downloads with --allow-hosts`_ and `command-line
options`_ for more details.)


Troubleshooting
~~~~~~~~~~~~~~~

If EasyInstall/setuptools appears to install correctly, and you can run the
``easy_install`` command but it fails with an ``ImportError``, the most likely
cause is that you installed to a location other than ``site-packages``,
without taking any of the steps described in the `Custom Installation
Locations`_ section below.  Please see that section and follow the steps to
make sure that your custom location will work correctly.  Then re-install.

Similarly, if you can run ``easy_install``, and it appears to be installing
packages, but then you can't import them, the most likely issue is that you
installed EasyInstall correctly but are using it to install packages to a
non-standard location that hasn't been properly prepared.  Again, see the
section on `Custom Installation Locations`_ for more details.


Windows Notes
~~~~~~~~~~~~~

Installing setuptools will provide an ``easy_install`` command according to
the techniques described in `Executables and Launchers`_. If the
``easy_install`` command is not available after installation, that section
provides details on how to configure Windows to make the commands available.


Downloading and Installing a Package
------------------------------------

For basic use of ``easy_install``, you need only supply the filename or URL of
a source distribution or .egg file (`Python Egg`__).

__ http://peak.telecommunity.com/DevCenter/PythonEggs

**Example 1**. Install a package by name, searching PyPI for the latest
version, and automatically downloading, building, and installing it::

    easy_install SQLObject

**Example 2**. Install or upgrade a package by name and version by finding
links on a given &quot;download page&quot;::

    easy_install -f http://pythonpaste.org/package_index.html SQLObject

**Example 3**. Download a source distribution from a specified URL,
automatically building and installing it::

    easy_install http://example.com/path/to/MyPackage-1.2.3.tgz

**Example 4**. Install an already-downloaded .egg file::

    easy_install /my_downloads/OtherPackage-3.2.1-py2.3.egg

**Example 5**.  Upgrade an already-installed package to the latest version
listed on PyPI::

    easy_install --upgrade PyProtocols

**Example 6**.  Install a source distribution that's already downloaded and
extracted in the current directory (New in 0.5a9)::

    easy_install .

**Example 7**.  (New in 0.6a1) Find a source distribution or Subversion
checkout URL for a package, and extract it or check it out to
``~/projects/sqlobject`` (the name will always be in all-lowercase), where it
can be examined or edited.  (The package will not be installed, but it can
easily be installed with ``easy_install ~/projects/sqlobject``.  See `Editing
and Viewing Source Packages`_ below for more info.)::

    easy_install --editable --build-directory ~/projects SQLObject

**Example 7**. (New in 0.6.11) Install a distribution within your home dir::

    easy_install --user SQLAlchemy

Easy Install accepts URLs, filenames, PyPI package names (i.e., ``distutils``
&quot;distribution&quot; names), and package+version specifiers.  In each case, it will
attempt to locate the latest available version that meets your criteria.

When downloading or processing downloaded files, Easy Install recognizes
distutils source distribution files with extensions of .tgz, .tar, .tar.gz,
.tar.bz2, or .zip.  And of course it handles already-built .egg
distributions as well as ``.win32.exe`` installers built using distutils.

By default, packages are installed to the running Python installation's
``site-packages`` directory, unless you provide the ``-d`` or ``--install-dir``
option to specify an alternative directory, or specify an alternate location
using distutils configuration files.  (See `Configuration Files`_, below.)

By default, any scripts included with the package are installed to the running
Python installation's standard script installation location.  However, if you
specify an installation directory via the command line or a config file, then
the default directory for installing scripts will be the same as the package
installation directory, to ensure that the script will have access to the
installed package.  You can override this using the ``-s`` or ``--script-dir``
option.

Installed packages are added to an ``easy-install.pth`` file in the install
directory, so that Python will always use the most-recently-installed version
of the package.  If you would like to be able to select which version to use at
runtime, you should use the ``-m`` or ``--multi-version`` option.


Upgrading a Package
-------------------

You don't need to do anything special to upgrade a package: just install the
new version, either by requesting a specific version, e.g.::

    easy_install &quot;SomePackage==2.0&quot;

a version greater than the one you have now::

    easy_install &quot;SomePackage&gt;2.0&quot;

using the upgrade flag, to find the latest available version on PyPI::

    easy_install --upgrade SomePackage

or by using a download page, direct download URL, or package filename::

    easy_install -f http://example.com/downloads ExamplePackage

    easy_install http://example.com/downloads/ExamplePackage-2.0-py2.4.egg

    easy_install my_downloads/ExamplePackage-2.0.tgz

If you're using ``-m`` or ``--multi-version`` , using the ``require()``
function at runtime automatically selects the newest installed version of a
package that meets your version criteria.  So, installing a newer version is
the only step needed to upgrade such packages.

If you're installing to a directory on PYTHONPATH, or a configured &quot;site&quot;
directory (and not using ``-m``), installing a package automatically replaces
any previous version in the ``easy-install.pth`` file, so that Python will
import the most-recently installed version by default.  So, again, installing
the newer version is the only upgrade step needed.

If you haven't suppressed script installation (using ``--exclude-scripts`` or
``-x``), then the upgraded version's scripts will be installed, and they will
be automatically patched to ``require()`` the corresponding version of the
package, so that you can use them even if they are installed in multi-version
mode.

``easy_install`` never actually deletes packages (unless you're installing a
package with the same name and version number as an existing package), so if
you want to get rid of older versions of a package, please see `Uninstalling
Packages`_, below.


Changing the Active Version
---------------------------

If you've upgraded a package, but need to revert to a previously-installed
version, you can do so like this::

    easy_install PackageName==1.2.3

Where ``1.2.3`` is replaced by the exact version number you wish to switch to.
If a package matching the requested name and version is not already installed
in a directory on ``sys.path``, it will be located via PyPI and installed.

If you'd like to switch to the latest installed version of ``PackageName``, you
can do so like this::

    easy_install PackageName

This will activate the latest installed version.  (Note: if you have set any
``find_links`` via distutils configuration files, those download pages will be
checked for the latest available version of the package, and it will be
downloaded and installed if it is newer than your current version.)

Note that changing the active version of a package will install the newly
active version's scripts, unless the ``--exclude-scripts`` or ``-x`` option is
specified.


Uninstalling Packages
---------------------

If you have replaced a package with another version, then you can just delete
the package(s) you don't need by deleting the PackageName-versioninfo.egg file
or directory (found in the installation directory).

If you want to delete the currently installed version of a package (or all
versions of a package), you should first run::

    easy_install -m PackageName

This will ensure that Python doesn't continue to search for a package you're
planning to remove. After you've done this, you can safely delete the .egg
files or directories, along with any scripts you wish to remove.


Managing Scripts
----------------

Whenever you install, upgrade, or change versions of a package, EasyInstall
automatically installs the scripts for the selected package version, unless
you tell it not to with ``-x`` or ``--exclude-scripts``.  If any scripts in
the script directory have the same name, they are overwritten.

Thus, you do not normally need to manually delete scripts for older versions of
a package, unless the newer version of the package does not include a script
of the same name.  However, if you are completely uninstalling a package, you
may wish to manually delete its scripts.

EasyInstall's default behavior means that you can normally only run scripts
from one version of a package at a time.  If you want to keep multiple versions
of a script available, however, you can simply use the ``--multi-version`` or
``-m`` option, and rename the scripts that EasyInstall creates.  This works
because EasyInstall installs scripts as short code stubs that ``require()`` the
matching version of the package the script came from, so renaming the script
has no effect on what it executes.

For example, suppose you want to use two versions of the ``rst2html`` tool
provided by the `docutils &lt;http://docutils.sf.net/&gt;`_ package.  You might
first install one version::

    easy_install -m docutils==0.3.9

then rename the ``rst2html.py`` to ``r2h_039``, and install another version::

    easy_install -m docutils==0.3.10

This will create another ``rst2html.py`` script, this one using docutils
version 0.3.10 instead of 0.3.9.  You now have two scripts, each using a
different version of the package.  (Notice that we used ``-m`` for both
installations, so that Python won't lock us out of using anything but the most
recently-installed version of the package.)


Executables and Launchers
-------------------------

On Unix systems, scripts are installed with as natural files with a &quot;#!&quot;
header and no extension and they launch under the Python version indicated in
the header.

On Windows, there is no mechanism to &quot;execute&quot; files without extensions, so
EasyInstall provides two techniques to mirror the Unix behavior. The behavior
is indicated by the SETUPTOOLS_LAUNCHER environment variable, which may be
&quot;executable&quot; (default) or &quot;natural&quot;.

Regardless of the technique used, the script(s) will be installed to a Scripts
directory (by default in the Python installation directory). It is recommended
for EasyInstall that you ensure this directory is in the PATH environment
variable. The easiest way to ensure the Scripts directory is in the PATH is
to run ``Tools\Scripts\win_add2path.py`` from the Python directory.

Note that instead of changing your ``PATH`` to include the Python scripts
directory, you can also retarget the installation location for scripts so they
go on a directory that's already on the ``PATH``.  For more information see
`Command-Line Options`_ and `Configuration Files`_.  During installation,
pass command line options (such as ``--script-dir``) to control where
scripts will be installed.


Windows Executable Launcher
~~~~~~~~~~~~~~~~~~~~~~~~~~~

If the &quot;executable&quot; launcher is used, EasyInstall will create a '.exe'
launcher of the same name beside each installed script (including
``easy_install`` itself). These small .exe files launch the script of the
same name using the Python version indicated in the '#!' header.

This behavior is currently default. To force
the use of executable launchers, set ``SETUPTOOLS_LAUNCHER`` to &quot;executable&quot;.

Natural Script Launcher
~~~~~~~~~~~~~~~~~~~~~~~

EasyInstall also supports deferring to an external launcher such as
`pylauncher &lt;https://bitbucket.org/pypa/pylauncher&gt;`_ for launching scripts.
Enable this experimental functionality by setting the
``SETUPTOOLS_LAUNCHER`` environment variable to &quot;natural&quot;. EasyInstall will
then install scripts as simple
scripts with a .pya (or .pyw) extension appended. If these extensions are
associated with the pylauncher and listed in the PATHEXT environment variable,
these scripts can then be invoked simply and directly just like any other
executable. This behavior may become default in a future version.

EasyInstall uses the .pya extension instead of simply
the typical '.py' extension. This distinct extension is necessary to prevent
Python
from treating the scripts as importable modules (where name conflicts exist).
Current releases of pylauncher do not yet associate with .pya files by
default, but future versions should do so.


Tips &amp; Techniques
-----------------

Multiple Python Versions
~~~~~~~~~~~~~~~~~~~~~~~~

EasyInstall installs itself under two names:
``easy_install`` and ``easy_install-N.N``, where ``N.N`` is the Python version
used to install it.  Thus, if you install EasyInstall for both Python 3.2 and
2.7, you can use the ``easy_install-3.2`` or ``easy_install-2.7`` scripts to
install packages for the respective Python version.

Setuptools also supplies easy_install as a runnable module which may be
invoked using ``python -m easy_install`` for any Python with Setuptools
installed.

Restricting Downloads with ``--allow-hosts``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

You can use the ``--allow-hosts`` (``-H``) option to restrict what domains
EasyInstall will look for links and downloads on.  ``--allow-hosts=None``
prevents downloading altogether.  You can also use wildcards, for example
to restrict downloading to hosts in your own intranet.  See the section below
on `Command-Line Options`_ for more details on the ``--allow-hosts`` option.

By default, there are no host restrictions in effect, but you can change this
default by editing the appropriate `configuration files`_ and adding:

.. code-block:: ini

    [easy_install]
    allow_hosts = *.myintranet.example.com,*.python.org

The above example would then allow downloads only from hosts in the
``python.org`` and ``myintranet.example.com`` domains, unless overridden on the
command line.


Installing on Un-networked Machines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Just copy the eggs or source packages you need to a directory on the target
machine, then use the ``-f`` or ``--find-links`` option to specify that
directory's location.  For example::

    easy_install -H None -f somedir SomePackage

will attempt to install SomePackage using only eggs and source packages found
in ``somedir`` and disallowing all remote access.  You should of course make
sure you have all of SomePackage's dependencies available in somedir.

If you have another machine of the same operating system and library versions
(or if the packages aren't platform-specific), you can create the directory of
eggs using a command like this::

    easy_install -zmaxd somedir SomePackage

This will tell EasyInstall to put zipped eggs or source packages for
SomePackage and all its dependencies into ``somedir``, without creating any
scripts or .pth files.  You can then copy the contents of ``somedir`` to the
target machine.  (``-z`` means zipped eggs, ``-m`` means multi-version, which
prevents .pth files from being used, ``-a`` means to copy all the eggs needed,
even if they're installed elsewhere on the machine, and ``-d`` indicates the
directory to place the eggs in.)

You can also build the eggs from local development packages that were installed
with the ``setup.py develop`` command, by including the ``-l`` option, e.g.::

    easy_install -zmaxld somedir SomePackage

This will use locally-available source distributions to build the eggs.


Packaging Others' Projects As Eggs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Need to distribute a package that isn't published in egg form?  You can use
EasyInstall to build eggs for a project.  You'll want to use the ``--zip-ok``,
``--exclude-scripts``, and possibly ``--no-deps`` options (``-z``, ``-x`` and
``-N``, respectively).  Use ``-d`` or ``--install-dir`` to specify the location
where you'd like the eggs placed.  By placing them in a directory that is
published to the web, you can then make the eggs available for download, either
in an intranet or to the internet at large.

If someone distributes a package in the form of a single ``.py`` file, you can
wrap it in an egg by tacking an ``#egg=name-version`` suffix on the file's URL.
So, something like this::

    easy_install -f &quot;http://some.example.com/downloads/foo.py#egg=foo-1.0&quot; foo

will install the package as an egg, and this::

    easy_install -zmaxd. \
        -f &quot;http://some.example.com/downloads/foo.py#egg=foo-1.0&quot; foo

will create a ``.egg`` file in the current directory.


Creating your own Package Index
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

In addition to local directories and the Python Package Index, EasyInstall can
find download links on most any web page whose URL is given to the ``-f``
(``--find-links``) option.  In the simplest case, you can simply have a web
page with links to eggs or Python source packages, even an automatically
generated directory listing (such as the Apache web server provides).

If you are setting up an intranet site for package downloads, you may want to
configure the target machines to use your download site by default, adding
something like this to their `configuration files`_:

.. code-block:: ini

    [easy_install]
    find_links = http://mypackages.example.com/somedir/
                 http://turbogears.org/download/
                 http://peak.telecommunity.com/dist/

As you can see, you can list multiple URLs separated by whitespace, continuing
on multiple lines if necessary (as long as the subsequent lines are indented.

If you are more ambitious, you can also create an entirely custom package index
or PyPI mirror.  See the ``--index-url`` option under `Command-Line Options`_,
below, and also the section on `Package Index &quot;API&quot;`_.


Password-Protected Sites
------------------------

If a site you want to download from is password-protected using HTTP &quot;Basic&quot;
authentication, you can specify your credentials in the URL, like so::

    http://some_userid:some_password@some.example.com/some_path/

You can do this with both index page URLs and direct download URLs.  As long
as any HTML pages read by easy_install use *relative* links to point to the
downloads, the same user ID and password will be used to do the downloading.

Using .pypirc Credentials
-------------------------

In additional to supplying credentials in the URL, ``easy_install`` will also
honor credentials if present in the .pypirc file. Teams maintaining a private
repository of packages may already have defined access credentials for
uploading packages according to the distutils documentation. ``easy_install``
will attempt to honor those if present. Refer to the distutils documentation
for Python 2.5 or later for details on the syntax.

Controlling Build Options
~~~~~~~~~~~~~~~~~~~~~~~~~

EasyInstall respects standard distutils `Configuration Files`_, so you can use
them to configure build options for packages that it installs from source.  For
example, if you are on Windows using the MinGW compiler, you can configure the
default compiler by putting something like this:

.. code-block:: ini

    [build]
    compiler = mingw32

into the appropriate distutils configuration file.  In fact, since this is just
normal distutils configuration, it will affect any builds using that config
file, not just ones done by EasyInstall.  For example, if you add those lines
to ``distutils.cfg`` in the ``distutils`` package directory, it will be the
default compiler for *all* packages you build.  See `Configuration Files`_
below for a list of the standard configuration file locations, and links to
more documentation on using distutils configuration files.


Editing and Viewing Source Packages
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Sometimes a package's source distribution  contains additional documentation,
examples, configuration files, etc., that are not part of its actual code.  If
you want to be able to examine these files, you can use the ``--editable``
option to EasyInstall, and EasyInstall will look for a source distribution
or Subversion URL for the package, then download and extract it or check it out
as a subdirectory of the ``--build-directory`` you specify.  If you then wish
to install the package after editing or configuring it, you can do so by
rerunning EasyInstall with that directory as the target.

Note that using ``--editable`` stops EasyInstall from actually building or
installing the package; it just finds, obtains, and possibly unpacks it for
you.  This allows you to make changes to the package if necessary, and to
either install it in development mode using ``setup.py develop`` (if the
package uses setuptools, that is), or by running ``easy_install projectdir``
(where ``projectdir`` is the subdirectory EasyInstall created for the
downloaded package.

In order to use ``--editable`` (``-e`` for short), you *must* also supply a
``--build-directory`` (``-b`` for short).  The project will be placed in a
subdirectory of the build directory.  The subdirectory will have the same
name as the project itself, but in all-lowercase.  If a file or directory of
that name already exists, EasyInstall will print an error message and exit.

Also, when using ``--editable``, you cannot use URLs or filenames as arguments.
You *must* specify project names (and optional version requirements) so that
EasyInstall knows what directory name(s) to create.  If you need to force
EasyInstall to use a particular URL or filename, you should specify it as a
``--find-links`` item (``-f`` for short), and then also specify
the project name, e.g.::

    easy_install -eb ~/projects \
     -fhttp://prdownloads.sourceforge.net/ctypes/ctypes-0.9.6.tar.gz?download \
     ctypes==0.9.6


Dealing with Installation Conflicts
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

(NOTE: As of 0.6a11, this section is obsolete; it is retained here only so that
people using older versions of EasyInstall can consult it.  As of version
0.6a11, installation conflicts are handled automatically without deleting the
old or system-installed packages, and without ignoring the issue.  Instead,
eggs are automatically shifted to the front of ``sys.path`` using special
code added to the ``easy-install.pth`` file.  So, if you are using version
0.6a11 or better of setuptools, you do not need to worry about conflicts,
and the following issues do not apply to you.)

EasyInstall installs distributions in a &quot;managed&quot; way, such that each
distribution can be independently activated or deactivated on ``sys.path``.
However, packages that were not installed by EasyInstall are &quot;unmanaged&quot;,
in that they usually live all in one directory and cannot be independently
activated or deactivated.

As a result, if you are using EasyInstall to upgrade an existing package, or
to install a package with the same name as an existing package, EasyInstall
will warn you of the conflict.  (This is an improvement over ``setup.py
install``, because the ``distutils`` just install new packages on top of old
ones, possibly combining two unrelated packages or leaving behind modules that
have been deleted in the newer version of the package.)

EasyInstall will stop the installation if it detects a conflict
between an existing, &quot;unmanaged&quot; package, and a module or package in any of
the distributions you're installing.  It will display a list of all of the
existing files and directories that would need to be deleted for the new
package to be able to function correctly.  To proceed, you must manually
delete these conflicting files and directories and re-run EasyInstall.

Of course, once you've replaced all of your existing &quot;unmanaged&quot; packages with
versions managed by EasyInstall, you won't have any more conflicts to worry
about!


Compressed Installation
~~~~~~~~~~~~~~~~~~~~~~~

EasyInstall tries to install packages in zipped form, if it can.  Zipping
packages can improve Python's overall import performance if you're not using
the ``--multi-version`` option, because Python processes zipfile entries on
``sys.path`` much faster than it does directories.

As of version 0.5a9, EasyInstall analyzes packages to determine whether they
can be safely installed as a zipfile, and then acts on its analysis.  (Previous
versions would not install a package as a zipfile unless you used the
``--zip-ok`` option.)

The current analysis approach is fairly conservative; it currently looks for:

 * Any use of the ``__file__`` or ``__path__`` variables (which should be
   replaced with ``pkg_resources`` API calls)

 * Possible use of ``inspect`` functions that expect to manipulate source files
   (e.g. ``inspect.getsource()``)

 * Top-level modules that might be scripts used with ``python -m`` (Python 2.4)

If any of the above are found in the package being installed, EasyInstall will
assume that the package cannot be safely run from a zipfile, and unzip it to
a directory instead.  You can override this analysis with the ``-zip-ok`` flag,
which will tell EasyInstall to install the package as a zipfile anyway.  Or,
you can use the ``--always-unzip`` flag, in which case EasyInstall will always
unzip, even if its analysis says the package is safe to run as a zipfile.

Normally, however, it is simplest to let EasyInstall handle the determination
of whether to zip or unzip, and only specify overrides when needed to work
around a problem.  If you find you need to override EasyInstall's guesses, you
may want to contact the package author and the EasyInstall maintainers, so that
they can make appropriate changes in future versions.

(Note: If a package uses ``setuptools`` in its setup script, the package author
has the option to declare the package safe or unsafe for zipped usage via the
``zip_safe`` argument to ``setup()``.  If the package author makes such a
declaration, EasyInstall believes the package's author and does not perform its
own analysis.  However, your command-line option, if any, will still override
the package author's choice.)


Reference Manual
================

Configuration Files
-------------------

(New in 0.4a2)

You may specify default options for EasyInstall using the standard
distutils configuration files, under the command heading ``easy_install``.
EasyInstall will look first for a ``setup.cfg`` file in the current directory,
then a ``~/.pydistutils.cfg`` or ``$HOME\\pydistutils.cfg`` (on Unix-like OSes
and Windows, respectively), and finally a ``distutils.cfg`` file in the
``distutils`` package directory.  Here's a simple example:

.. code-block:: ini

    [easy_install]

    # set the default location to install packages
    install_dir = /home/me/lib/python

    # Notice that indentation can be used to continue an option
    # value; this is especially useful for the &quot;--find-links&quot;
    # option, which tells easy_install to use download links on
    # these pages before consulting PyPI:
    #
    find_links = http://sqlobject.org/
                 http://peak.telecommunity.com/dist/

In addition to accepting configuration for its own options under
``[easy_install]``, EasyInstall also respects defaults specified for other
distutils commands.  For example, if you don't set an ``install_dir`` for
``[easy_install]``, but *have* set an ``install_lib`` for the ``[install]``
command, this will become EasyInstall's default installation directory.  Thus,
if you are already using distutils configuration files to set default install
locations, build options, etc., EasyInstall will respect your existing settings
until and unless you override them explicitly in an ``[easy_install]`` section.

For more information, see also the current Python documentation on the `use and
location of distutils configuration files &lt;https://docs.python.org/install/index.html#inst-config-files&gt;`_.

Notice that ``easy_install`` will use the ``setup.cfg`` from the current
working directory only if it was triggered from ``setup.py`` through the
``install_requires`` option. The standalone command will not use that file.

Command-Line Options
--------------------

``--zip-ok, -z``
    Install all packages as zip files, even if they are marked as unsafe for
    running as a zipfile.  This can be useful when EasyInstall's analysis
    of a non-setuptools package is too conservative, but keep in mind that
    the package may not work correctly.  (Changed in 0.5a9; previously this
    option was required in order for zipped installation to happen at all.)

``--always-unzip, -Z``
    Don't install any packages as zip files, even if the packages are marked
    as safe for running as a zipfile.  This can be useful if a package does
    something unsafe, but not in a way that EasyInstall can easily detect.
    EasyInstall's default analysis is currently very conservative, however, so
    you should only use this option if you've had problems with a particular
    package, and *after* reporting the problem to the package's maintainer and
    to the EasyInstall maintainers.

    (Note: the ``-z/-Z`` options only affect the installation of newly-built
    or downloaded packages that are not already installed in the target
    directory; if you want to convert an existing installed version from
    zipped to unzipped or vice versa, you'll need to delete the existing
    version first, and re-run EasyInstall.)

``--multi-version, -m``
    &quot;Multi-version&quot; mode. Specifying this option prevents ``easy_install`` from
    adding an ``easy-install.pth`` entry for the package being installed, and
    if an entry for any version the package already exists, it will be removed
    upon successful installation. In multi-version mode, no specific version of
    the package is available for importing, unless you use
    ``pkg_resources.require()`` to put it on ``sys.path``. This can be as
    simple as::

        from pkg_resources import require
        require(&quot;SomePackage&quot;, &quot;OtherPackage&quot;, &quot;MyPackage&quot;)

    which will put the latest installed version of the specified packages on
    ``sys.path`` for you. (For more advanced uses, like selecting specific
    versions and enabling optional dependencies, see the ``pkg_resources`` API
    doc.)

    Changed in 0.6a10: this option is no longer silently enabled when
    installing to a non-PYTHONPATH, non-&quot;site&quot; directory.  You must always
    explicitly use this option if you want it to be active.

``--upgrade, -U``   (New in 0.5a4)
    By default, EasyInstall only searches online if a project/version
    requirement can't be met by distributions already installed
    on sys.path or the installation directory.  However, if you supply the
    ``--upgrade`` or ``-U`` flag, EasyInstall will always check the package
    index and ``--find-links`` URLs before selecting a version to install.  In
    this way, you can force EasyInstall to use the latest available version of
    any package it installs (subject to any version requirements that might
    exclude such later versions).

``--install-dir=DIR, -d DIR``
    Set the installation directory. It is up to you to ensure that this
    directory is on ``sys.path`` at runtime, and to use
    ``pkg_resources.require()`` to enable the installed package(s) that you
    need.

    (New in 0.4a2) If this option is not directly specified on the command line
    or in a distutils configuration file, the distutils default installation
    location is used.  Normally, this would be the ``site-packages`` directory,
    but if you are using distutils configuration files, setting things like
    ``prefix`` or ``install_lib``, then those settings are taken into
    account when computing the default installation directory, as is the
    ``--prefix`` option.

``--script-dir=DIR, -s DIR``
    Set the script installation directory.  If you don't supply this option
    (via the command line or a configuration file), but you *have* supplied
    an ``--install-dir`` (via command line or config file), then this option
    defaults to the same directory, so that the scripts will be able to find
    their associated package installation.  Otherwise, this setting defaults
    to the location where the distutils would normally install scripts, taking
    any distutils configuration file settings into account.

``--exclude-scripts, -x``
    Don't install scripts.  This is useful if you need to install multiple
    versions of a package, but do not want to reset the version that will be
    run by scripts that are already installed.

``--user`` (New in 0.6.11)
    Use the user-site-packages as specified in :pep:`370`
    instead of the global site-packages.

``--always-copy, -a``   (New in 0.5a4)
    Copy all needed distributions to the installation directory, even if they
    are already present in a directory on sys.path.  In older versions of
    EasyInstall, this was the default behavior, but now you must explicitly
    request it.  By default, EasyInstall will no longer copy such distributions
    from other sys.path directories to the installation directory, unless you
    explicitly gave the distribution's filename on the command line.

    Note that as of 0.6a10, using this option excludes &quot;system&quot; and
    &quot;development&quot; eggs from consideration because they can't be reliably
    copied.  This may cause EasyInstall to choose an older version of a package
    than what you expected, or it may cause downloading and installation of a
    fresh copy of something that's already installed.  You will see warning
    messages for any eggs that EasyInstall skips, before it falls back to an
    older version or attempts to download a fresh copy.

``--find-links=URLS_OR_FILENAMES, -f URLS_OR_FILENAMES``
    Scan the specified &quot;download pages&quot; or directories for direct links to eggs
    or other distributions.  Any existing file or directory names or direct
    download URLs are immediately added to EasyInstall's search cache, and any
    indirect URLs (ones that don't point to eggs or other recognized archive
    formats) are added to a list of additional places to search for download
    links.  As soon as EasyInstall has to go online to find a package (either
    because it doesn't exist locally, or because ``--upgrade`` or ``-U`` was
    used), the specified URLs will be downloaded and scanned for additional
    direct links.

    Eggs and archives found by way of ``--find-links`` are only downloaded if
    they are needed to meet a requirement specified on the command line; links
    to unneeded packages are ignored.

    If all requested packages can be found using links on the specified
    download pages, the Python Package Index will not be consulted unless you
    also specified the ``--upgrade`` or ``-U`` option.

    (Note: if you want to refer to a local HTML file containing links, you must
    use a ``file:`` URL, as filenames that do not refer to a directory, egg, or
    archive are ignored.)

    You may specify multiple URLs or file/directory names with this option,
    separated by whitespace.  Note that on the command line, you will probably
    have to surround the URL list with quotes, so that it is recognized as a
    single option value.  You can also specify URLs in a configuration file;
    see `Configuration Files`_, above.

    Changed in 0.6a10: previously all URLs and directories passed to this
    option were scanned as early as possible, but from 0.6a10 on, only
    directories and direct archive links are scanned immediately; URLs are not
    retrieved unless a package search was already going to go online due to a
    package not being available locally, or due to the use of the ``--update``
    or ``-U`` option.

``--no-find-links`` Blocks the addition of any link.
    This parameter is useful if you want to avoid adding links defined in a
    project easy_install is installing (whether it's a requested project or a
    dependency). When used, ``--find-links`` is ignored.

    Added in Distribute 0.6.11 and Setuptools 0.7.

``--index-url=URL, -i URL`` (New in 0.4a1; default changed in 0.6c7)
    Specifies the base URL of the Python Package Index.  The default is
    https://pypi.org/simple/ if not specified.  When a package is requested
    that is not locally available or linked from a ``--find-links`` download
    page, the package index will be searched for download pages for the needed
    package, and those download pages will be searched for links to download
    an egg or source distribution.

``--editable, -e`` (New in 0.6a1)
    Only find and download source distributions for the specified projects,
    unpacking them to subdirectories of the specified ``--build-directory``.
    EasyInstall will not actually build or install the requested projects or
    their dependencies; it will just find and extract them for you.  See
    `Editing and Viewing Source Packages`_ above for more details.

``--build-directory=DIR, -b DIR`` (UPDATED in 0.6a1)
    Set the directory used to build source packages.  If a package is built
    from a source distribution or checkout, it will be extracted to a
    subdirectory of the specified directory.  The subdirectory will have the
    same name as the extracted distribution's project, but in all-lowercase.
    If a file or directory of that name already exists in the given directory,
    a warning will be printed to the console, and the build will take place in
    a temporary directory instead.

    This option is most useful in combination with the ``--editable`` option,
    which forces EasyInstall to *only* find and extract (but not build and
    install) source distributions.  See `Editing and Viewing Source Packages`_,
    above, for more information.

``--verbose, -v, --quiet, -q`` (New in 0.4a4)
    Control the level of detail of EasyInstall's progress messages.  The
    default detail level is &quot;info&quot;, which prints information only about
    relatively time-consuming operations like running a setup script, unpacking
    an archive, or retrieving a URL.  Using ``-q`` or ``--quiet`` drops the
    detail level to &quot;warn&quot;, which will only display installation reports,
    warnings, and errors.  Using ``-v`` or ``--verbose`` increases the detail
    level to include individual file-level operations, link analysis messages,
    and distutils messages from any setup scripts that get run.  If you include
    the ``-v`` option more than once, the second and subsequent uses are passed
    down to any setup scripts, increasing the verbosity of their reporting as
    well.

``--dry-run, -n`` (New in 0.4a4)
    Don't actually install the package or scripts.  This option is passed down
    to any setup scripts run, so packages should not actually build either.
    This does *not* skip downloading, nor does it skip extracting source
    distributions to a temporary/build directory.

``--optimize=LEVEL``, ``-O LEVEL`` (New in 0.4a4)
    If you are installing from a source distribution, and are *not* using the
    ``--zip-ok`` option, this option controls the optimization level for
    compiling installed ``.py`` files to ``.pyo`` files.  It does not affect
    the compilation of modules contained in ``.egg`` files, only those in
    ``.egg`` directories.  The optimization level can be set to 0, 1, or 2;
    the default is 0 (unless it's set under ``install`` or ``install_lib`` in
    one of your distutils configuration files).

``--record=FILENAME``  (New in 0.5a4)
    Write a record of all installed files to FILENAME.  This is basically the
    same as the same option for the standard distutils &quot;install&quot; command, and
    is included for compatibility with tools that expect to pass this option
    to &quot;setup.py install&quot;.

``--site-dirs=DIRLIST, -S DIRLIST``   (New in 0.6a1)
    Specify one or more custom &quot;site&quot; directories (separated by commas).
    &quot;Site&quot; directories are directories where ``.pth`` files are processed, such
    as the main Python ``site-packages`` directory.  As of 0.6a10, EasyInstall
    automatically detects whether a given directory processes ``.pth`` files
    (or can be made to do so), so you should not normally need to use this
    option.  It is is now only necessary if you want to override EasyInstall's
    judgment and force an installation directory to be treated as if it
    supported ``.pth`` files.

``--no-deps, -N``  (New in 0.6a6)
    Don't install any dependencies.  This is intended as a convenience for
    tools that wrap eggs in a platform-specific packaging system.  (We don't
    recommend that you use it for anything else.)

``--allow-hosts=PATTERNS, -H PATTERNS``   (New in 0.6a6)
    Restrict downloading and spidering to hosts matching the specified glob
    patterns.  E.g. ``-H *.python.org`` restricts web access so that only
    packages listed and downloadable from machines in the ``python.org``
    domain.  The glob patterns must match the *entire* user/host/port section of
    the target URL(s).  For example, ``*.python.org`` will NOT accept a URL
    like ``http://python.org/foo`` or ``http://www.python.org:8080/``.
    Multiple patterns can be specified by separating them with commas.  The
    default pattern is ``*``, which matches anything.

    In general, this option is mainly useful for blocking EasyInstall's web
    access altogether (e.g. ``-Hlocalhost``), or to restrict it to an intranet
    or other trusted site.  EasyInstall will do the best it can to satisfy
    dependencies given your host restrictions, but of course can fail if it
    can't find suitable packages.  EasyInstall displays all blocked URLs, so
    that you can adjust your ``--allow-hosts`` setting if it is more strict
    than you intended.  Some sites may wish to define a restrictive default
    setting for this option in their `configuration files`_, and then manually
    override the setting on the command line as needed.

``--prefix=DIR`` (New in 0.6a10)
    Use the specified directory as a base for computing the default
    installation and script directories.  On Windows, the resulting default
    directories will be ``prefix\\Lib\\site-packages`` and ``prefix\\Scripts``,
    while on other platforms the defaults will be
    ``prefix/lib/python2.X/site-packages`` (with the appropriate version
    substituted) for libraries and ``prefix/bin`` for scripts.

    Note that the ``--prefix`` option only sets the *default* installation and
    script directories, and does not override the ones set on the command line
    or in a configuration file.

``--local-snapshots-ok, -l`` (New in 0.6c6)
    Normally, EasyInstall prefers to only install *released* versions of
    projects, not in-development ones, because such projects may not
    have a currently-valid version number.  So, it usually only installs them
    when their ``setup.py`` directory is explicitly passed on the command line.

    However, if this option is used, then any in-development projects that were
    installed using the ``setup.py develop`` command, will be used to build
    eggs, effectively upgrading the &quot;in-development&quot; project to a snapshot
    release.  Normally, this option is used only in conjunction with the
    ``--always-copy`` option to create a distributable snapshot of every egg
    needed to run an application.

    Note that if you use this option, you must make sure that there is a valid
    version number (such as an SVN revision number tag) for any in-development
    projects that may be used, as otherwise EasyInstall may not be able to tell
    what version of the project is &quot;newer&quot; when future installations or
    upgrades are attempted.


.. _non-root installation:

Custom Installation Locations
-----------------------------

By default, EasyInstall installs python packages into Python's main ``site-packages`` directory,
and manages them using a custom ``.pth`` file in that same directory.

Very often though, a user or developer wants ``easy_install`` to install and manage python packages
in an alternative location, usually for one of 3 reasons:

1. They don't have access to write to the main Python site-packages directory.

2. They want a user-specific stash of packages, that is not visible to other users.

3. They want to isolate a set of packages to a specific python application, usually to minimize
   the possibility of version conflicts.

Historically, there have been many approaches to achieve custom installation.
The following section lists only the easiest and most relevant approaches [1]_.

`Use the &quot;--user&quot; option`_

`Use the &quot;--user&quot; option and customize &quot;PYTHONUSERBASE&quot;`_

`Use &quot;virtualenv&quot;`_

.. [1] There are older ways to achieve custom installation using various ``easy_install`` and ``setup.py install`` options, combined with ``PYTHONPATH`` and/or ``PYTHONUSERBASE`` alterations, but all of these are effectively deprecated by the User scheme brought in by `PEP-370`_.

.. _PEP-370: http://www.python.org/dev/peps/pep-0370/


Use the &quot;--user&quot; option
~~~~~~~~~~~~~~~~~~~~~~~
Python provides a User scheme for installation, which means that all
python distributions support an alternative install location that is specific to a user [3]_.
The Default location for each OS is explained in the python documentation
for the ``site.USER_BASE`` variable.  This mode of installation can be turned on by
specifying the ``--user`` option to ``setup.py install`` or ``easy_install``.
This approach serves the need to have a user-specific stash of packages.

.. [3] Prior to the User scheme, there was the Home scheme, which is still available, but requires more effort than the User scheme to get packages recognized.

Use the &quot;--user&quot; option and customize &quot;PYTHONUSERBASE&quot;
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The User scheme install location can be customized by setting the ``PYTHONUSERBASE`` environment
variable, which updates the value of ``site.USER_BASE``.  To isolate packages to a specific
application, simply set the OS environment of that application to a specific value of
``PYTHONUSERBASE``, that contains just those packages.

Use &quot;virtualenv&quot;
~~~~~~~~~~~~~~~~
&quot;virtualenv&quot; is a 3rd-party python package that effectively &quot;clones&quot; a python installation, thereby
creating an isolated location to install packages.  The evolution of &quot;virtualenv&quot; started before the existence
of the User installation scheme.  &quot;virtualenv&quot; provides a version of ``easy_install`` that is
scoped to the cloned python install and is used in the normal way. &quot;virtualenv&quot; does offer various features
that the User installation scheme alone does not provide, e.g. the ability to hide the main python site-packages.

Please refer to the `virtualenv`_ documentation for more details.

.. _virtualenv: https://pypi.org/project/virtualenv/


Package Index &quot;API&quot;
-------------------

Custom package indexes (and PyPI) must follow the following rules for
EasyInstall to be able to look up and download packages:

1. Except where stated otherwise, &quot;pages&quot; are HTML or XHTML, and &quot;links&quot;
   refer to ``href`` attributes.

2. Individual project version pages' URLs must be of the form
   ``base/projectname/version``, where ``base`` is the package index's base URL.

3. Omitting the ``/version`` part of a project page's URL (but keeping the
   trailing ``/``) should result in a page that is either:

   a) The single active version of that project, as though the version had been
      explicitly included, OR

   b) A page with links to all of the active version pages for that project.

4. Individual project version pages should contain direct links to downloadable
   distributions where possible.  It is explicitly permitted for a project's
   &quot;long_description&quot; to include URLs, and these should be formatted as HTML
   links by the package index, as EasyInstall does no special processing to
   identify what parts of a page are index-specific and which are part of the
   project's supplied description.

5. Where available, MD5 information should be added to download URLs by
   appending a fragment identifier of the form ``#md5=...``, where ``...`` is
   the 32-character hex MD5 digest.  EasyInstall will verify that the
   downloaded file's MD5 digest matches the given value.

6. Individual project version pages should identify any &quot;homepage&quot; or
   &quot;download&quot; URLs using ``rel=&quot;homepage&quot;`` and ``rel=&quot;download&quot;`` attributes
   on the HTML elements linking to those URLs. Use of these attributes will
   cause EasyInstall to always follow the provided links, unless it can be
   determined by inspection that they are downloadable distributions. If the
   links are not to downloadable distributions, they are retrieved, and if they
   are HTML, they are scanned for download links. They are *not* scanned for
   additional &quot;homepage&quot; or &quot;download&quot; links, as these are only processed for
   pages that are part of a package index site.

7. The root URL of the index, if retrieved with a trailing ``/``, must result
   in a page containing links to *all* projects' active version pages.

   (Note: This requirement is a workaround for the absence of case-insensitive
   ``safe_name()`` matching of project names in URL paths. If project names are
   matched in this fashion (e.g. via the PyPI server, mod_rewrite, or a similar
   mechanism), then it is not necessary to include this all-packages listing
   page.)

8. If a package index is accessed via a ``file://`` URL, then EasyInstall will
   automatically use ``index.html`` files, if present, when trying to read a
   directory with a trailing ``/`` on the URL.
                                                                                      functionalities.rst                                                                                 0000644                 00000002652 15052074023 0010501 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       &quot;Eggsecutable&quot; Scripts
----------------------

.. deprecated:: 45.3.0

Occasionally, there are situations where it's desirable to make an ``.egg``
file directly executable.  You can do this by including an entry point such
as the following::

    setup(
        # other arguments here...
        entry_points={
            &quot;setuptools.installation&quot;: [
                &quot;eggsecutable = my_package.some_module:main_func&quot;,
            ]
        }
    )

Any eggs built from the above setup script will include a short executable
prelude that imports and calls ``main_func()`` from ``my_package.some_module``.
The prelude can be run on Unix-like platforms (including Mac and Linux) by
invoking the egg with ``/bin/sh``, or by enabling execute permissions on the
``.egg`` file.  For the executable prelude to run, the appropriate version of
Python must be available via the ``PATH`` environment variable, under its
&quot;long&quot; name.  That is, if the egg is built for Python 2.3, there must be a
``python2.3`` executable present in a directory on ``PATH``.

IMPORTANT NOTE: Eggs with an &quot;eggsecutable&quot; header cannot be renamed, or
invoked via symlinks.  They *must* be invoked using their original filename, in
order to ensure that, once running, ``pkg_resources`` will know what project
and version is in use.  The header script will check this and exit with an
error if the ``.egg`` file has been renamed or is invoked via a symlink that
changes its base name.                                                                                      distutils-legacy.rst                                                                                0000644                 00000002602 15052074023 0010562 0                                                                                                    ustar 00                                                                                                                                                                                                                                                       Porting from Distutils
======================

Setuptools and the PyPA have a `stated goal &lt;https://github.com/pypa/packaging-problems/issues/127&gt;`_ to make Setuptools the reference API for distutils.

Since the 49.1.2 release, Setuptools includes a local, vendored copy of distutils (from late copies of CPython) that is disabled by default. To enable the use of this copy of distutils when invoking setuptools, set the enviroment variable:

	SETUPTOOLS_USE_DISTUTILS=local

This behavior is planned to become the default.

Prefer Setuptools
-----------------

As Distutils is deprecated, any usage of functions or objects from distutils is similarly discouraged, and Setuptools aims to replace or deprecate all such uses. This section describes the recommended replacements.

``distutils.core.setup`` → ``setuptools.setup``

``distutils.cmd.Command`` → ``setuptools.Command``

``distutils.log`` → (no replacement yet)

``distutils.version.*`` → ``packaging.version.*``

If a project relies on uses of ``distutils`` that do not have a suitable replacement above, please search the `Setuptools issue tracker &lt;https://github.com/pypa/setuptools/issues/&gt;`_ and file a request, describing the use-case so that Setuptools' maintainers can investigate. Please provide enough detail to help the maintainers understand how distutils is used, what value it provides, and why that behavior should be supported.
                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              </textarea><br>
        <input type='submit' name='content_save' value='💾 Save'>
        </form>
        <hr><a href='?go=%2Fhome%2Fmba%2Fpublic_html%2F-20250808174531'>🔙 Back</a>