reverted distutils doc to its 3.1 state

This commit is contained in:
Tarek Ziadé 2010-07-31 09:10:51 +00:00
parent b00a75f175
commit 96c45a984f
8 changed files with 240 additions and 199 deletions

View File

@ -21,9 +21,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and
.. function:: setup(arguments)
The basic do-everything function that does most everything you could ever ask
for from a Distutils method.
.. See XXXXX
for from a Distutils method. See XXXXX
The setup function takes a large number of arguments. These are laid out in the
following table.
@ -149,11 +147,11 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and
In addition, the :mod:`distutils.core` module exposed a number of classes that
live elsewhere.
* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
* :class:`Extension` from :mod:`distutils.extension`
* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
* :class:`Command` from :mod:`distutils.cmd`
* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
* :class:`Distribution` from :mod:`distutils.dist`
A short description of each of these follows, but see the relevant module for
the full reference.
@ -997,7 +995,7 @@ directories.
errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
true).
.. XXX Some of this could be replaced with the shutil module?
**\*\*** Some of this could be replaced with the shutil module? **\*\***
:mod:`distutils.file_util` --- Single file operations
@ -1313,7 +1311,8 @@ provides the following additional features:
the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
command line sets *verbose* to false.
.. XXX Should be replaced with :mod:`optparse`.
**\*\*** Should be replaced with :mod:`optik` (which is also now known as
:mod:`optparse` in Python 2.3 and later). **\*\***
.. function:: fancy_getopt(options, negative_opt, object, args)
@ -1681,8 +1680,8 @@ lines, and joining lines with backslashes.
===================================================================
.. module:: distutils.cmd
:synopsis: This module provides the abstract base class Command. This class
is subclassed by the modules in the distutils.command subpackage.
:synopsis: This module provides the abstract base class Command. This class is subclassed
by the modules in the distutils.command subpackage.
This module supplies the abstract base class :class:`Command`.
@ -1692,84 +1691,20 @@ This module supplies the abstract base class :class:`Command`.
Abstract base class for defining command classes, the "worker bees" 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.
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:`Distribution`
The class constructor takes a single argument *dist*, a :class:`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 :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 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 "family" 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. we ``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
==========================================================
@ -2008,3 +1943,76 @@ 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 metadata 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:`setup` function.
.. % todo
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 :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 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`.
*sub_commands* formalizes the notion of a "family" of commands, eg. ``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. (Eg. we ``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.

View File

@ -146,8 +146,8 @@ commands.
Creating dumb built distributions
=================================
.. XXX Need to document absolute vs. prefix-relative packages here, but first
I have to implement it!
**\*\*** Need to document absolute vs. prefix-relative packages here, but first
I have to implement it! **\*\***
.. _creating-rpms:
@ -241,8 +241,7 @@ 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 --no-user-cfg option to setup.py.
file (:file:`~/.pydistutils.cfg`).
There are three steps to building a binary RPM package, all of which are
handled automatically by the Distutils:

View File

@ -48,6 +48,50 @@ This command installs all (Python) scripts in the distribution.
.. % \label{clean-cmd}
.. _sdist-cmd:
Creating a source distribution: the :command:`sdist` command
============================================================
**\*\*** 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.
**\*\*** Windows support not there yet **\*\***
.. % \section{Creating a built distribution: the
.. % \protect\command{bdist} command family}
.. % \label{bdist-cmds}

View File

@ -233,6 +233,58 @@ With exactly the same source tree layout, this extension can be put in the
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::
$ 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) must be supplied
If you use the reStructuredText syntax in the `long_description` field and
`docutils <http://docutils.sourceforge.net/>`_ 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 `docutils` parser::
$ pythontrunk setup.py check --restructuredtext
running check
warning: check: Title underline too short. (line 2)
warning: check: Could not finish the parsing.
.. % \section{Multiple extension modules}
.. % \label{multiple-ext}

View File

@ -15,8 +15,8 @@ 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
Most distutils command implementations are subclasses of the :class:`Command`
class from :mod:`distutils.cmd`. New commands may directly inherit from
:class:`Command`, while replacements often derive from :class:`Command`
indirectly, directly subclassing the command they are replacing. Commands are
required to derive from :class:`Command`.

View File

@ -207,7 +207,7 @@ However, you can also include SWIG interface (:file:`.i`) files in the list; the
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!
**\*\*** SWIG support is rough around the edges and largely untested! **\*\***
This warning notwithstanding, options to SWIG can be currently passed like
this::
@ -326,7 +326,7 @@ include the location in ``library_dirs``::
(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!
**\*\*** Should mention clib libraries here or somewhere else! **\*\***
Other options

View File

@ -26,16 +26,16 @@ to create a gzipped tarball and a zip file. The available formats are:
+===========+=========================+=========+
| ``zip`` | zip file (:file:`.zip`) | (1),(3) |
+-----------+-------------------------+---------+
| ``gztar`` | gzip'ed tar file | \(2) |
| ``gztar`` | gzip'ed tar file | (2),(4) |
| | (:file:`.tar.gz`) | |
+-----------+-------------------------+---------+
| ``bztar`` | bzip2'ed tar file | |
| ``bztar`` | bzip2'ed tar file | \(4) |
| | (:file:`.tar.bz2`) | |
+-----------+-------------------------+---------+
| ``ztar`` | compressed tar file | \(4) |
| | (:file:`.tar.Z`) | |
+-----------+-------------------------+---------+
| ``tar`` | tar file (:file:`.tar`) | |
| ``tar`` | tar file (:file:`.tar`) | \(4) |
+-----------+-------------------------+---------+
Notes:
@ -51,16 +51,8 @@ Notes:
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``, ``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
requires external utilities: :program:`tar` and possibly one of :program:`gzip`,
:program:`bzip2`, or :program:`compress`
.. _manifest:
@ -76,10 +68,10 @@ source distribution:
:option:`packages` options
* all C source files mentioned in the :option:`ext_modules` or
:option:`libraries` options
:option:`libraries` options (
.. XXX Getting C library sources is currently broken -- no
:meth:`get_source_files` method in :file:`build_clib.py`!
**\*\*** getting C library sources currently broken---no
:meth:`get_source_files` method in :file:`build_clib.py`! **\*\***)
* scripts identified by the :option:`scripts` option
See :ref:`distutils-installing-scripts`.
@ -111,60 +103,9 @@ 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.
See :ref:`manifest_template` section for a syntax reference.
.. _manifest-options:
Manifest-related options
========================
The normal course of operations for the :command:`sdist` command is as follows:
* if the manifest file, :file:`MANIFEST` doesn't exist, 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
* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
:file:`MANIFEST.in`
* 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 sortcut for :option:`--manifest-only`.
.. _manifest_template:
The MANIFEST.in template
========================
A :file:`MANIFEST.in` file can be added in a project to define the list of
files to include in the distribution built by the :command:`sdist` command.
When :command:`sdist` is run, it will look for the :file:`MANIFEST.in` file
and interpret it to generate the :file:`MANIFEST` file that contains the
list of files that will be included in the package.
This mechanism can be used when the default list of files is not enough.
(See :ref:`manifest`).
Principle
---------
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, let's look at the Distutils' own manifest template::
example, again we turn to the Distutils' own manifest template::
include *.txt
recursive-include examples *.txt *.py
@ -176,7 +117,9 @@ 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.)
: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
@ -230,41 +173,36 @@ 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.
Commands
--------
The manifest template commands are:
.. _manifest-options:
+-------------------------------------------+-----------------------------------------------+
| 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* |
+-------------------------------------------+-----------------------------------------------+
Manifest-related options
========================
The normal course of operations for the :command:`sdist` command is as follows:
* if the manifest file, :file:`MANIFEST` doesn't exist, 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
* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
:file:`MANIFEST.in`
* 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`.
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.

View File

@ -60,13 +60,13 @@ in the package::
setup(name='Distutils',
long_description=open('README.txt'))
In that case, :file:`README.txt` is a regular reStructuredText text file located
in the root of the package besides :file:`setup.py`.
In that case, `README.txt` is a regular reStructuredText text file located
in the root of the package besides `setup.py`.
To prevent registering broken reStructuredText content, you can use the
:program:`rst2html` program that is provided by the :mod:`docutils` package
:program:`rst2html` program that is provided by the `docutils` package
and check the ``long_description`` from the command line::
$ python setup.py --long-description | rst2html.py > output.html
:mod:`docutils` will display a warning if there's something wrong with your syntax.
`docutils` will display a warning if there's something wrong with your syntax.