mirror of
https://github.com/python/cpython.git
synced 2025-10-30 21:21:22 +00:00
4009c9edfc
svn+ssh://svn.python.org/python/branches/py3k ........ r82805 | georg.brandl | 2010-07-11 11:42:10 +0200 (So, 11 Jul 2010) | 1 line #7935: cross-reference to ast.literal_eval() from eval() docs. ........ 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. ........ r83523 | georg.brandl | 2010-08-02 14:06:18 +0200 (Mo, 02 Aug 2010) | 1 line #9209 and #7781: fix two crashes in pstats interactive browser. ........ r83524 | georg.brandl | 2010-08-02 14:20:23 +0200 (Mo, 02 Aug 2010) | 1 line #9428: fix running scripts from profile/cProfile with their own name and the right namespace. Same fix as for trace.py in #1690103. ........ r83525 | georg.brandl | 2010-08-02 14:36:24 +0200 (Mo, 02 Aug 2010) | 1 line Get rid of spurious "threading" entries in trace output. ........ r83526 | georg.brandl | 2010-08-02 14:40:22 +0200 (Mo, 02 Aug 2010) | 1 line Fix softspace relic. ........ r83527 | georg.brandl | 2010-08-02 14:48:46 +0200 (Mo, 02 Aug 2010) | 1 line #3821: beginnings of a trace.py unittest. ........ r83536 | georg.brandl | 2010-08-02 19:49:25 +0200 (Mo, 02 Aug 2010) | 1 line #8578: mention danger of not incref'ing weak referenced object. ........ r83538 | georg.brandl | 2010-08-02 20:10:13 +0200 (Mo, 02 Aug 2010) | 1 line #6928: fix class docs w.r.t. new metaclasses. ........ r83542 | georg.brandl | 2010-08-02 20:56:54 +0200 (Mo, 02 Aug 2010) | 1 line Move test_SimpleHTTPServer into test_httpservers. ........ r83546 | georg.brandl | 2010-08-02 21:16:34 +0200 (Mo, 02 Aug 2010) | 1 line #7973: Fix distutils options spelling. ........ r83547 | georg.brandl | 2010-08-02 21:19:26 +0200 (Mo, 02 Aug 2010) | 1 line #7386: add example that shows that trailing path separators are stripped. ........ r83548 | georg.brandl | 2010-08-02 21:23:34 +0200 (Mo, 02 Aug 2010) | 1 line #8172: how does one use a property? ........ r83550 | georg.brandl | 2010-08-02 21:32:43 +0200 (Mo, 02 Aug 2010) | 1 line #9451: strengthen warning about __*__ special name usage. ........ r83551 | georg.brandl | 2010-08-02 21:35:06 +0200 (Mo, 02 Aug 2010) | 1 line Remove XXX comment that was displayed. ........ r83552 | georg.brandl | 2010-08-02 21:36:36 +0200 (Mo, 02 Aug 2010) | 1 line #9438: clarify that constant names also cannot be assigned as attributes. ........ r83553 | georg.brandl | 2010-08-02 21:39:17 +0200 (Mo, 02 Aug 2010) | 1 line Remove redundant information. ........ r83554 | georg.brandl | 2010-08-02 21:43:05 +0200 (Mo, 02 Aug 2010) | 1 line #7280: note about nasmw.exe. ........ r83555 | georg.brandl | 2010-08-02 21:44:48 +0200 (Mo, 02 Aug 2010) | 1 line #8861: remove unused variable. ........ r83558 | georg.brandl | 2010-08-02 22:05:19 +0200 (Mo, 02 Aug 2010) | 1 line #8648: document UTF-7 codec functions. ........ r83560 | georg.brandl | 2010-08-02 22:16:18 +0200 (Mo, 02 Aug 2010) | 1 line #9087: update json docstrings -- unicode and long do not exist anymore. ........
96 lines
4.4 KiB
ReStructuredText
96 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:`distutils.cmd.Command` class. 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.
|
|
|
|
|