cpython: c5d6a384132d (original) (raw)

--- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -21,7 +21,7 @@ setup script). Indirectly provides the .. 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 In addition, the :mod:distutils.core module exposed a number of classes that live elsewhere.

-* :class:Extension from :mod:distutils.extension - -* :class:Command from :mod:distutils.cmd - -* :class:Distribution from :mod:distutils.dist +* :class:~distutils.extension.Extension from :mod:distutils.extension + +* :class:~distutils.cmd.Command from :mod:distutils.cmd + +* :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 backslashe =================================================================== .. module:: distutils.cmd

:synopsis: This module provides the abstract base class Command. This class is subclassed

         by the modules in the distutils.command  subpackage.[](#l1.34)

:synopsis: This module provides the abstract base class Command. This class

         is subclassed by the modules in the distutils.command subpackage.[](#l1.36)

This module supplies the abstract base class :class:Command. @@ -1689,20 +1689,84 @@ This module supplies the abstract base c 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 ========================================================== @@ -1954,63 +2018,3 @@ For example, it verifies that all requir 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.

--- a/Doc/distutils/extending.rst +++ b/Doc/distutils/extending.rst @@ -15,8 +15,8 @@ want to modify existing commands; many s 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.

--- 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.[](#l3.7)
```

```
 every invocation).[](#l3.8)
```

.. index:: single: generator expression

--- a/Doc/library/functions.rst +++ b/Doc/library/functions.rst @@ -580,7 +580,7 @@ are always available. They are listed h 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])

--- a/Lib/distutils/tests/test_build_py.py +++ b/Lib/distutils/tests/test_build_py.py @@ -57,12 +57,15 @@ class BuildPyTestCase(support.TempdirMan self.assertEqual(len(cmd.get_outputs()), 3) pkgdest = os.path.join(destination, "pkg") files = os.listdir(pkgdest)

   self.assertTrue("__init__.py" in files)[](#l5.7)

   if not sys.dont_write_bytecode:[](#l5.8)

       self.assertTrue("__init__.pyc" in files)[](#l5.9)

   self.assertTrue("README.txt" in files)[](#l5.10)

   self.assertIn("__init__.py", files)[](#l5.11)

   self.assertIn("README.txt", files)[](#l5.12)

   # XXX even with -O, distutils writes pyc, not pyo; bug?[](#l5.13)

   if sys.dont_write_bytecode:[](#l5.14)

       self.assertNotIn("__init__.pyc", files)[](#l5.15)

```
   else:[](#l5.16)
```

       self.assertIn("__init__.pyc", files)[](#l5.17)

def test_empty_package_dir (self):

def test_empty_package_dir(self): # See SF 1668596/1720897. cwd = os.getcwd()

@@ -110,7 +113,7 @@ class BuildPyTestCase(support.TempdirMan finally: sys.dont_write_bytecode = old_dont_write_bytecode

   self.assertTrue('byte-compiling is disabled' in self.logs[0][1])[](#l5.28)

   self.assertIn('byte-compiling is disabled', self.logs[0][1])[](#l5.29)

def test_suite(): return unittest.makeSuite(BuildPyTestCase)

--- a/Lib/packaging/tests/test_command_build_py.py +++ b/Lib/packaging/tests/test_command_build_py.py @@ -61,9 +61,12 @@ class BuildPyTestCase(support.TempdirMan pkgdest = os.path.join(destination, "pkg") files = os.listdir(pkgdest) self.assertIn("init.py", files)

   if not sys.dont_write_bytecode:[](#l6.7)

   self.assertIn("README.txt", files)[](#l6.8)

   # XXX even with -O, distutils writes pyc, not pyo; bug?[](#l6.9)

   if sys.dont_write_bytecode:[](#l6.10)

       self.assertNotIn("__init__.pyc", files)[](#l6.11)

   else:[](#l6.12)
       self.assertIn("__init__.pyc", files)[](#l6.13)

   self.assertIn("README.txt", files)[](#l6.14)

def test_empty_package_dir(self): # See SF 1668596/1720897. @@ -93,7 +96,7 @@ class BuildPyTestCase(support.TempdirMan try: dist.run_commands()

       except PackagingFileError as e:[](#l6.22)

       except PackagingFileError:[](#l6.23)
           self.fail("failed package_data test when package_dir is ''")[](#l6.24)
   finally:[](#l6.25)
       # Restore state.[](#l6.26)