mirror of
https://github.com/python/cpython.git
synced 2024-11-28 08:20:55 +01:00
d8654cf758
svn+ssh://pythondev@svn.python.org/python/trunk ........ r59260 | lars.gustaebel | 2007-12-01 22:02:12 +0100 (Sat, 01 Dec 2007) | 5 lines Issue #1531: Read fileobj from the current offset, do not seek to the start. (will backport to 2.5) ........ r59262 | georg.brandl | 2007-12-01 23:24:47 +0100 (Sat, 01 Dec 2007) | 4 lines Document PyEval_* functions from ceval.c. Credits to Michael Sloan from GHOP. ........ r59263 | georg.brandl | 2007-12-01 23:27:56 +0100 (Sat, 01 Dec 2007) | 2 lines Add a few refcount data entries. ........ r59264 | georg.brandl | 2007-12-01 23:38:48 +0100 (Sat, 01 Dec 2007) | 4 lines Add test suite for cmd module. Written by Michael Schneider for GHOP. ........ r59265 | georg.brandl | 2007-12-01 23:42:46 +0100 (Sat, 01 Dec 2007) | 3 lines Add examples to the ElementTree documentation. Written by h4wk.cz for GHOP. ........ r59266 | georg.brandl | 2007-12-02 00:12:45 +0100 (Sun, 02 Dec 2007) | 3 lines Add "Using Python on Windows" document, by Robert Lehmann. Written for GHOP. ........ r59271 | georg.brandl | 2007-12-02 15:34:34 +0100 (Sun, 02 Dec 2007) | 3 lines Add example to mmap docs. Written for GHOP by Rafal Rawicki. ........ r59272 | georg.brandl | 2007-12-02 15:37:29 +0100 (Sun, 02 Dec 2007) | 2 lines Convert bdb.rst line endings to Unix style. ........ r59274 | georg.brandl | 2007-12-02 15:58:50 +0100 (Sun, 02 Dec 2007) | 4 lines Add more entries to the glossary. Written by Jeff Wheeler for GHOP. ........
97 lines
4.4 KiB
ReStructuredText
97 lines
4.4 KiB
ReStructuredText
.. _extending-distutils:
|
|
|
|
*******************
|
|
Extending Distutils
|
|
*******************
|
|
|
|
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:`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`.
|
|
|
|
.. % \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, :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
|
|
:option:`--command-packages` :option:`distcmds,buildcmds`, however, the packages
|
|
:mod:`distutils.command`, :mod:`distcmds`, and :mod:`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 :class:`distcmds.bdist_openpkg.bdist_openpkg` or
|
|
:class:`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.
|
|
|
|
|