diff options
| -rw-r--r-- | Doc/distutils/apiref.rst | 159 | ||||
| -rw-r--r-- | Doc/distutils/extending.rst | 4 | ||||
| -rw-r--r-- | Doc/glossary.rst | 2 | ||||
| -rw-r--r-- | Doc/library/functions.rst | 2 | ||||
| -rw-r--r-- | Lib/distutils/tests/test_build_py.py | 16 | ||||
| -rw-r--r-- | Misc/NEWS | 8 |
6 files changed, 100 insertions, 91 deletions
diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index a7dc68e..dc5bcf2 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -21,7 +21,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and .. function:: setup(arguments) The basic do-everything function that does most everything you could ever ask - for from a Distutils method. See XXXXX + for from a Distutils method. The setup function takes a large number of arguments. These are laid out in the following table. @@ -147,11 +147,11 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and 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. @@ -1678,8 +1678,8 @@ lines, and joining lines with backslashes. =================================================================== .. 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`. @@ -1689,20 +1689,84 @@ This module supplies the abstract base class :class:`Command`. 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. - - The class constructor takes a single argument *dist*, a :class:`Distribution` + 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` 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. ``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,6 +2006,7 @@ This is described in more detail in :pep:`301`. .. % todo + :mod:`distutils.command.check` --- Check the meta-data of a package =================================================================== @@ -1954,63 +2019,3 @@ 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. diff --git a/Doc/distutils/extending.rst b/Doc/distutils/extending.rst index 972ff02..5a70d03 100644 --- a/Doc/distutils/extending.rst +++ b/Doc/distutils/extending.rst @@ -15,8 +15,8 @@ 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 +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`. diff --git a/Doc/glossary.rst b/Doc/glossary.rst index ec8af62..d14455b 100644 --- a/Doc/glossary.rst +++ b/Doc/glossary.rst @@ -247,7 +247,7 @@ Glossary processing, remembering the location execution state (including local variables and pending try-statements). When the generator resumes, it picks-up where it left-off (in contrast to functions which start fresh on - every invocation. + every invocation). .. index:: single: generator expression diff --git a/Doc/library/functions.rst b/Doc/library/functions.rst index 8b7eef5..134c19c 100644 --- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -580,7 +580,7 @@ are always available. They are listed here in alphabetical order. Two objects with non-overlapping lifetimes may have the same :func:`id` value. - .. impl-detail:: This is the address of the object. + .. impl-detail:: This is the address of the object in memory. .. function:: input([prompt]) diff --git a/Lib/distutils/tests/test_build_py.py b/Lib/distutils/tests/test_build_py.py index da3232c..4e46339 100644 --- a/Lib/distutils/tests/test_build_py.py +++ b/Lib/distutils/tests/test_build_py.py @@ -57,11 +57,15 @@ class BuildPyTestCase(support.TempdirManager, self.assertEqual(len(cmd.get_outputs()), 3) pkgdest = os.path.join(destination, "pkg") files = os.listdir(pkgdest) - self.assertTrue("__init__.py" in files) - self.assertTrue("__init__.pyc" in files) - self.assertTrue("README.txt" in files) - - def test_empty_package_dir (self): + self.assertIn("__init__.py", files) + self.assertIn("README.txt", files) + # XXX even with -O, distutils writes pyc, not pyo; bug? + if sys.dont_write_bytecode: + self.assertNotIn("__init__.pyc", files) + else: + self.assertIn("__init__.pyc", files) + + def test_empty_package_dir(self): # See SF 1668596/1720897. cwd = os.getcwd() @@ -109,7 +113,7 @@ class BuildPyTestCase(support.TempdirManager, finally: sys.dont_write_bytecode = old_dont_write_bytecode - self.assertTrue('byte-compiling is disabled' in self.logs[0][1]) + self.assertIn('byte-compiling is disabled', self.logs[0][1]) def test_suite(): return unittest.makeSuite(BuildPyTestCase) @@ -299,7 +299,7 @@ Library - Issue #7311: fix html.parser to accept non-ASCII attribute values. - Issue #11605: email.parser.BytesFeedParser was incorrectly converting - multipart subpararts with an 8bit CTE into unicode instead of preserving the + multipart subparts with an 8-bit CTE into unicode instead of preserving the bytes. - Issue #10963: Ensure that subprocess.communicate() never raises EPIPE. @@ -496,7 +496,7 @@ Tests - Issue #11577: improve test coverage of binhex.py. Patch by Arkady Koplyarov. -- Issue #11578: added test for the timeit module. Patch Michael Henry. +- Issue #11578: added test for the timeit module. Patch by Michael Henry. - Issue #11503: improve test coverage of posixpath.py. Patch by Evan Dandrea. @@ -796,10 +796,10 @@ Library comparisons that could lead to infinite recursion. - Issue #10686: the email package now :rfc:`2047`\ -encodes headers with - non-ASCII bytes (parsed by a Bytes Parser) when doing conversion to 7bit-clean + non-ASCII bytes (parsed by a BytesParser) when doing conversion to 7bit-clean presentation, instead of replacing them with ?s. -- email.header.Header was incorrectly encoding folding white space when +- email.header.Header was incorrectly encoding folding whitespace when rfc2047-encoding header values with embedded newlines, leaving them without folding whitespace. It now uses the continuation_ws, as it does for continuation lines that it creates itself. |