2,071 docs/deprecated/distutils/apiref.rst
View file

Large diffs are not rendered by default.

479 docs/deprecated/distutils/builtdist.rst
View file

Large diffs are not rendered by default.

106 docs/deprecated/distutils/commandref.rst
View file
@@ -0,0 +1,106 @@
.. _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 --- & any of the listed patterns |
+-------------------------------------------+-----------------------------------------------+
| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree |
| | matching --- & 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 "glob" 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 "regular filename
character" 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}}
144 docs/deprecated/distutils/configfile.rst
View file
@@ -0,0 +1,144 @@
.. _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 "in-place"---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
"set and forget" 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 "spec" 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 <gward@python.net>
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 "Installing Python Modules"
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.
340 docs/deprecated/distutils/examples.rst
View file
@@ -0,0 +1,340 @@
.. _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 <https://wiki.python.org/moin/Distutils/Cookbook>`_
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::

<root>/
setup.py
foo.py

(In all diagrams in this section, *<root>* 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::

<root>/
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.::

<root>/
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
::

<root>/
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::

<root>/
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::

<root>/
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::

<root>/
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::

<root>/
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 = """\
My description
==============

This is the description of the ``foobar`` package.
"""

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::

>>> from distutils.dist import DistributionMetadata
>>> metadata = DistributionMetadata()
>>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info'))
>>> metadata.name
'distribute'
>>> metadata.version
'0.6.8'
>>> 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::

>>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info'
>>> DistributionMetadata(pkg_info_path).name
'distribute'


.. % \section{Multiple extension modules}
.. % \label{multiple-ext}
.. % \section{Putting it all together}
.. _docutils: http://docutils.sourceforge.net
98 docs/deprecated/distutils/extending.rst
View file
@@ -0,0 +1,98 @@
.. _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):
"""Specialized Python source builder."""

# 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.


42 docs/deprecated/distutils/index.rst
View file
@@ -0,0 +1,42 @@
.. _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 <https://packaging.python.org/guides/tool-recommendations/>`__
in the Python Packaging User Guide for more information.

This document describes the Python Distribution Utilities ("Distutils") 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
214 docs/deprecated/distutils/introduction.rst
View file
@@ -0,0 +1,214 @@
.. _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 & 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 -->
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
"pure module."

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 "pure distribution."

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

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.
16 docs/deprecated/distutils/packageindex.rst
View file
@@ -0,0 +1,16 @@
: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
715 docs/deprecated/distutils/setupscript.rst
View file

Large diffs are not rendered by default.

242 docs/deprecated/distutils/sourcedist.rst
View file
@@ -0,0 +1,242 @@
.. _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 "build" 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
"include" and "exclude" 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`.
8 docs/deprecated/distutils/uploading.rst
View file
@@ -0,0 +1,8 @@
:orphan:

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

References to up to date PyPI documentation can be found at
:ref:`publishing-python-packages`.
1 docs/deprecated/index.rst
View file
@@ -16,5 +16,6 @@ objectives.
python3
python_eggs
easy_install
distutils/index
distutils-legacy
functionalities
7 netlify.toml
View file

This file was deleted.

1 runtime.txt
View file

This file was deleted.

2 setup.cfg
View file
@@ -2,7 +2,7 @@
license_files =
LICENSE
name = setuptools
version = 56.0.0
version = 56.1.0
author = Python Packaging Authority
author_email = distutils-sig@python.org
description = Easily download, build, install, upgrade, and uninstall Python packages
2 setuptools/_distutils/_msvccompiler.py
View file
@@ -248,7 +248,7 @@ def initialize(self, plat_name=None):
# Future releases of Python 3.x will include all past
# versions of vcruntime*.dll for compatibility.
self.compile_options = [
'/nologo', '/Ox', '/W3', '/GL', '/DNDEBUG', '/MD'
'/nologo', '/O2', '/W3', '/GL', '/DNDEBUG', '/MD'
]

self.compile_options_debug = [
7 setuptools/_distutils/ccompiler.py
View file
@@ -792,13 +792,20 @@ def has_function(self, funcname, includes=None, include_dirs=None,
objects = self.compile([fname], include_dirs=include_dirs)
except CompileError:
return False
finally:
os.remove(fname)

try:
self.link_executable(objects, "a.out",
libraries=libraries,
library_dirs=library_dirs)
except (LinkError, TypeError):
return False
else:
os.remove("a.out")
finally:
for fn in objects:
os.remove(fn)
return True

def find_library_file (self, dirs, lib, debug=0):
4 setuptools/_distutils/msvc9compiler.py
View file
@@ -399,13 +399,13 @@ def initialize(self, plat_name=None):

self.preprocess_options = None
if self.__arch == "x86":
self.compile_options = [ '/nologo', '/Ox', '/MD', '/W3',
self.compile_options = [ '/nologo', '/O2', '/MD', '/W3',
'/DNDEBUG']
self.compile_options_debug = ['/nologo', '/Od', '/MDd', '/W3',
'/Z7', '/D_DEBUG']
else:
# Win64
self.compile_options = [ '/nologo', '/Ox', '/MD', '/W3', '/GS-' ,
self.compile_options = [ '/nologo', '/O2', '/MD', '/W3', '/GS-' ,
'/DNDEBUG']
self.compile_options_debug = ['/nologo', '/Od', '/MDd', '/W3', '/GS-',
'/Z7', '/D_DEBUG']
4 setuptools/_distutils/msvccompiler.py
View file
@@ -283,13 +283,13 @@ def initialize(self):

self.preprocess_options = None
if self.__arch == "Intel":
self.compile_options = [ '/nologo', '/Ox', '/MD', '/W3', '/GX' ,
self.compile_options = [ '/nologo', '/O2', '/MD', '/W3', '/GX' ,
'/DNDEBUG']
self.compile_options_debug = ['/nologo', '/Od', '/MDd', '/W3', '/GX',
'/Z7', '/D_DEBUG']
else:
# Win64
self.compile_options = [ '/nologo', '/Ox', '/MD', '/W3', '/GS-' ,
self.compile_options = [ '/nologo', '/O2', '/MD', '/W3', '/GS-' ,
'/DNDEBUG']
self.compile_options_debug = ['/nologo', '/Od', '/MDd', '/W3', '/GS-',
'/Z7', '/D_DEBUG']
16 setuptools/_distutils/spawn.py
View file
@@ -40,7 +40,7 @@ def spawn(cmd, search_path=1, verbose=0, dry_run=0, env=None):
# in, protect our %-formatting code against horrible death
cmd = list(cmd)

log.info(' '.join(cmd))
log.info(subprocess.list2cmdline(cmd))
if dry_run:
return

@@ -60,13 +60,17 @@ def spawn(cmd, search_path=1, verbose=0, dry_run=0, env=None):
if _cfg_target:
_cfg_target_split = [int(x) for x in _cfg_target.split('.')]
if _cfg_target:
# ensure that the deployment target of build process is not less
# than that used when the interpreter was built. This ensures
# extension modules are built with correct compatibility values
# Ensure that the deployment target of the build process is not
# less than 10.3 if the interpreter was built for 10.3 or later.
# This ensures extension modules are built with correct
# compatibility values, specifically LDSHARED which can use
# '-undefined dynamic_lookup' which only works on >= 10.3.
cur_target = os.environ.get('MACOSX_DEPLOYMENT_TARGET', _cfg_target)
if _cfg_target_split > [int(x) for x in cur_target.split('.')]:
cur_target_split = [int(x) for x in cur_target.split('.')]
if _cfg_target_split[:2] >= [10, 3] and cur_target_split[:2] < [10, 3]:
my_msg = ('$MACOSX_DEPLOYMENT_TARGET mismatch: '
'now "%s" but "%s" during configure'
'now "%s" but "%s" during configure;'
'must use 10.3 or later'
% (cur_target, _cfg_target))
raise DistutilsPlatformError(my_msg)
env.update(MACOSX_DEPLOYMENT_TARGET=cur_target)
83 setuptools/dist.py
View file
@@ -16,6 +16,8 @@
from distutils.debug import DEBUG
from distutils.fancy_getopt import translate_longopt
import itertools
import textwrap
from typing import List, Optional, TYPE_CHECKING

from collections import defaultdict
from email import message_from_file
@@ -36,6 +38,9 @@
from setuptools.config import parse_configuration
import pkg_resources

if TYPE_CHECKING:
from email.message import Message

__import__('setuptools.extern.packaging.specifiers')
__import__('setuptools.extern.packaging.version')

@@ -67,53 +72,75 @@ def get_metadata_version(self):
return mv


def read_pkg_file(self, file):
"""Reads the metadata values from a file object."""
msg = message_from_file(file)
def rfc822_unescape(content: str) -> str:
"""Reverse RFC-822 escaping by removing leading whitespaces from content."""
lines = content.splitlines()
if len(lines) == 1:
return lines[0].lstrip()
return '\n'.join(
(lines[0].lstrip(),
textwrap.dedent('\n'.join(lines[1:]))))


def _read_field_from_msg(msg: "Message", field: str) -> Optional[str]:
"""Read Message header field."""
value = msg[field]
if value == 'UNKNOWN':
return None
return value


def _read_field(name):
value = msg[name]
if value == 'UNKNOWN':
return None
def _read_field_unescaped_from_msg(msg: "Message", field: str) -> Optional[str]:
"""Read Message header field and apply rfc822_unescape."""
value = _read_field_from_msg(msg, field)
if value is None:
return value
return rfc822_unescape(value)

def _read_list(name):
values = msg.get_all(name, None)
if values == []:
return None
return values

def _read_list_from_msg(msg: "Message", field: str) -> Optional[List[str]]:
"""Read Message header field and return all results as list."""
values = msg.get_all(field, None)
if values == []:
return None
return values


def read_pkg_file(self, file):
"""Reads the metadata values from a file object."""
msg = message_from_file(file)

self.metadata_version = StrictVersion(msg['metadata-version'])
self.name = _read_field('name')
self.version = _read_field('version')
self.description = _read_field('summary')
self.name = _read_field_from_msg(msg, 'name')
self.version = _read_field_from_msg(msg, 'version')
self.description = _read_field_from_msg(msg, 'summary')
# we are filling author only.
self.author = _read_field('author')
self.author = _read_field_from_msg(msg, 'author')
self.maintainer = None
self.author_email = _read_field('author-email')
self.author_email = _read_field_from_msg(msg, 'author-email')
self.maintainer_email = None
self.url = _read_field('home-page')
self.license = _read_field('license')
self.url = _read_field_from_msg(msg, 'home-page')
self.license = _read_field_from_msg(msg, 'license')

if 'download-url' in msg:
self.download_url = _read_field('download-url')
self.download_url = _read_field_from_msg(msg, 'download-url')
else:
self.download_url = None

self.long_description = _read_field('description')
self.description = _read_field('summary')
self.long_description = _read_field_unescaped_from_msg(msg, 'description')
self.description = _read_field_from_msg(msg, 'summary')

if 'keywords' in msg:
self.keywords = _read_field('keywords').split(',')
self.keywords = _read_field_from_msg(msg, 'keywords').split(',')

self.platforms = _read_list('platform')
self.classifiers = _read_list('classifier')
self.platforms = _read_list_from_msg(msg, 'platform')
self.classifiers = _read_list_from_msg(msg, 'classifier')

# PEP 314 - these fields only exist in 1.1
if self.metadata_version == StrictVersion('1.1'):
self.requires = _read_list('requires')
self.provides = _read_list('provides')
self.obsoletes = _read_list('obsoletes')
self.requires = _read_list_from_msg(msg, 'requires')
self.provides = _read_list_from_msg(msg, 'provides')
self.obsoletes = _read_list_from_msg(msg, 'obsoletes')
else:
self.requires = None
self.provides = None
2 setuptools/msvc.py
View file
@@ -193,7 +193,9 @@ def _msvc14_find_vc2017():
join(root, "Microsoft Visual Studio", "Installer", "vswhere.exe"),
"-latest",
"-prerelease",
"-requiresAny",
"-requires", "Microsoft.VisualStudio.Component.VC.Tools.x86.x64",
"-requires", "Microsoft.VisualStudio.Workload.WDExpress",
"-property", "installationPath",
"-products", "*",
]).decode(encoding="mbcs", errors="strict").strip()
2 setuptools/tests/server.py
View file
@@ -65,7 +65,7 @@ def __init__(
http.server.HTTPServer.__init__(
self, server_address, RequestHandlerClass)
threading.Thread.__init__(self)
self.setDaemon(True)
self.daemon = True
self.requests = []

def run(self):
40 setuptools/tests/test_dist.py
View file
@@ -10,6 +10,8 @@
check_package_data,
DistDeprecationWarning,
check_specifier,
rfc822_escape,
rfc822_unescape,
)
from setuptools import sic
from setuptools import Distribution
@@ -85,6 +87,9 @@ def __read_test_cases():
('Metadata version 1.1: Provides', params(
provides=['package'],
)),
('Metadata Version 1.0: Short long description', params(
long_description='Short long description',
)),
('Metadata version 1.1: Obsoletes', params(
obsoletes=['foo'],
)),
@@ -162,6 +167,7 @@ def test_read_metadata(name, attrs):
('metadata_version', dist_class.get_metadata_version),
('provides', dist_class.get_provides),
('description', dist_class.get_description),
('long_description', dist_class.get_long_description),
('download_url', dist_class.get_download_url),
('keywords', dist_class.get_keywords),
('platforms', dist_class.get_platforms),
@@ -336,3 +342,37 @@ def test_check_specifier():
attrs = {'name': 'foo', 'python_requires': ['>=3.0', '!=3.1']}
with pytest.raises(DistutilsSetupError):
dist = Distribution(attrs)


@pytest.mark.parametrize(
'content, result',
(
pytest.param(
"Just a single line",
None,
id="single_line",
),
pytest.param(
"Multiline\nText\nwithout\nextra indents\n",
None,
id="multiline",
),
pytest.param(
"Multiline\n With\n\nadditional\n indentation",
None,
id="multiline_with_indentation",
),
pytest.param(
" Leading whitespace",
"Leading whitespace",
id="remove_leading_whitespace",
),
pytest.param(
" Leading whitespace\nIn\n Multiline comment",
"Leading whitespace\nIn\n Multiline comment",
id="remove_leading_whitespace_multiline",
),
)
)
def test_rfc822_unescape(content, result):
assert (result or content) == rfc822_unescape(rfc822_escape(content))
4 towncrier_template.rst
View file
@@ -1,3 +1,7 @@
{% if top_line %}
{{ top_line }}
{{ top_underline * ((top_line)|length)}}
{% endif %}
{% for section, _ in sections.items() %}
{% set underline = underlines[0] %}{% if section %}{{section}}
{{ underline * section|length }}