2007-12-01 19:12:45 -04:00
|
|
|
.. _extending-distutils:
|
2007-08-15 11:28:01 -03:00
|
|
|
|
|
|
|
*******************
|
|
|
|
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.
|
|
|
|
|
Merged revisions 82793-82794,82807,82876,83432 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/release27-maint
................
r82793 | georg.brandl | 2010-07-11 10:56:18 +0200 (So, 11 Jul 2010) | 9 lines
Merged revisions 82790 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r82790 | georg.brandl | 2010-07-11 10:36:20 +0200 (So, 11 Jul 2010) | 1 line
#3214 followup: add link to ABC entry.
........
................
r82794 | georg.brandl | 2010-07-11 10:57:05 +0200 (So, 11 Jul 2010) | 9 lines
Merged revisions 82789 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r82789 | georg.brandl | 2010-07-11 10:33:16 +0200 (So, 11 Jul 2010) | 1 line
Silence makeindex.
........
................
r82807 | georg.brandl | 2010-07-11 12:29:37 +0200 (So, 11 Jul 2010) | 9 lines
Merged revisions 82806 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r82806 | georg.brandl | 2010-07-11 12:22:44 +0200 (So, 11 Jul 2010) | 1 line
#9223: link to Command class reference, and move Command interface docs nearer to class docs.
........
................
r82876 | georg.brandl | 2010-07-14 10:55:55 +0200 (Mi, 14 Jul 2010) | 13 lines
Merged revisions 82872,82874 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r82872 | georg.brandl | 2010-07-14 10:53:18 +0200 (Mi, 14 Jul 2010) | 1 line
Remove XXX from text.
........
r82874 | georg.brandl | 2010-07-14 10:54:40 +0200 (Mi, 14 Jul 2010) | 1 line
#9235: fix missing import of sys.
........
................
r83432 | georg.brandl | 2010-08-01 21:21:26 +0200 (So, 01 Aug 2010) | 13 lines
Merged revisions 83328,83341 via svnmerge from
svn+ssh://pythondev@svn.python.org/python/branches/py3k
........
r83328 | raymond.hettinger | 2010-07-31 12:14:41 +0200 (Sa, 31 Jul 2010) | 1 line
Document how to change OrderedDict update order from first to last.
........
r83341 | georg.brandl | 2010-07-31 13:40:07 +0200 (Sa, 31 Jul 2010) | 1 line
#9430: document timedelta str() and repr().
........
................
2010-08-01 19:19:17 -03:00
|
|
|
Most distutils command implementations are subclasses of the
|
|
|
|
:class:`distutils.cmd.Command` class. New commands may directly inherit from
|
2007-08-15 11:28:01 -03:00
|
|
|
: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.
|
|
|
|
|
|
|
|
|