reverted distutils doc to its 3.1 state
This commit is contained in:
Tarek Ziadé
parent
b00a75f175
commit
96c45a984f
|
|
@ -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`
|
||||
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.
|
||||
|
|
|
|||
|
|
@ -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:
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
|
|
|||
|
|
@ -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}
|
||||
|
||||
|
|
|
|||
|
|
@ -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`.
|
||||
|
|
|
|||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Reference in New Issue