Merged revisions 82805-82806,83523-83527,83536,83538,83542,83546-83548,83550-83555,83558,83560 via svnmerge from
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.
........
diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst
index 366c713..2401da3 100644
--- a/Doc/distutils/apiref.rst
+++ b/Doc/distutils/apiref.rst
@@ -147,11 +147,11 @@
In addition, the :mod:`distutils.core` module exposed a number of classes that
live elsewhere.
-* :class:`Extension` from :mod:`distutils.extension`
+* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
-* :class:`Command` from :mod:`distutils.cmd`
+* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
-* :class:`Distribution` from :mod:`distutils.dist`
+* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
A short description of each of these follows, but see the relevant module for
the full reference.
@@ -1679,8 +1679,8 @@
===================================================================
.. 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`.
@@ -1690,20 +1690,84 @@
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`
+ 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
==========================================================
@@ -1942,76 +2006,3 @@
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.