summaryrefslogtreecommitdiffstats
path: root/Doc/library/packaging.command.rst
diff options
context:
space:
mode:
authorÉric Araujo <merwok@netwok.org>2012-06-24 04:07:41 (GMT)
committerÉric Araujo <merwok@netwok.org>2012-06-24 04:07:41 (GMT)
commit859aad6a36262383b98ddd45fe3253a882b87ce8 (patch)
tree1cc50af4fc88c650fe997a2e72f5f26d92a1986c /Doc/library/packaging.command.rst
parentdc44f55cc9dc1d016799362c344958baab328ff4 (diff)
downloadcpython-859aad6a36262383b98ddd45fe3253a882b87ce8.zip
cpython-859aad6a36262383b98ddd45fe3253a882b87ce8.tar.gz
cpython-859aad6a36262383b98ddd45fe3253a882b87ce8.tar.bz2
Remove packaging from the standard library.
Distutils2 will live on on PyPI and be included in the stdlib when it is ready. See discussion starting at http://mail.python.org/pipermail/python-dev/2012-June/120430.html
Diffstat (limited to 'Doc/library/packaging.command.rst')
-rw-r--r--Doc/library/packaging.command.rst111
1 files changed, 0 insertions, 111 deletions
diff --git a/Doc/library/packaging.command.rst b/Doc/library/packaging.command.rst
deleted file mode 100644
index 6a85351..0000000
--- a/Doc/library/packaging.command.rst
+++ /dev/null
@@ -1,111 +0,0 @@
-:mod:`packaging.command` --- Standard Packaging commands
-========================================================
-
-.. module:: packaging.command
- :synopsis: Standard packaging commands.
-
-
-This subpackage contains one module for each standard Packaging command, such as
-:command:`build` or :command:`upload`. Each command is implemented as a
-separate module, with the command name as the name of the module and of the
-class defined therein.
-
-
-
-:mod:`packaging.command.cmd` --- Abstract base class for Packaging commands
-===========================================================================
-
-.. module:: packaging.command.cmd
- :synopsis: Abstract base class for commands.
-
-
-This module supplies the abstract base class :class:`Command`. This class is
-subclassed by the modules in the packaging.command subpackage.
-
-
-.. class:: Command(dist)
-
- Abstract base class for defining command classes, the "worker bees" of the
- Packaging. 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.
-
- The class constructor takes a single argument *dist*, a
- :class:`~packaging.dist.Distribution` instance.
-
-
-Creating a new Packaging command
---------------------------------
-
-This section outlines the steps to create a new Packaging command.
-
-.. XXX the following paragraph is focused on the stdlib; expand it to document
- how to write and register a command in third-party projects
-
-A new command lives in a module in the :mod:`packaging.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:`packaging/command/peel_banana.py`, then edit
-it so that it's implementing the class :class:`peel_banana`, a subclass of
-:class:`Command`. It 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, i.e. after any option assignments from the
- command line or from other commands have been done. Thus, this is the place
- 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`.
-
-
-Command classes may define this attribute:
-
-
-.. attribute:: Command.sub_commands
-
- *sub_commands* formalizes the notion of a "family" of commands,
- e.g. ``install_dist`` 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. ``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_dist` command.
-
-.. XXX document how to add a custom command to another one's subcommands