diff options
Diffstat (limited to 'Doc/distutils')
| -rw-r--r-- | Doc/distutils/apiref.rst | 172 | ||||
| -rw-r--r-- | Doc/distutils/builtdist.rst | 10 | ||||
| -rw-r--r-- | Doc/distutils/commandref.rst | 4 | ||||
| -rw-r--r-- | Doc/distutils/examples.rst | 6 | ||||
| -rw-r--r-- | Doc/distutils/extending.rst | 4 | ||||
| -rw-r--r-- | Doc/distutils/sourcedist.rst | 6 | ||||
| -rw-r--r-- | Doc/distutils/uploading.rst | 7 |
7 files changed, 109 insertions, 100 deletions
diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst index 81de1ad..a7dc68e 100644 --- a/Doc/distutils/apiref.rst +++ b/Doc/distutils/apiref.rst @@ -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:`~distutils.extension.Extension` from :mod:`distutils.extension` +* :class:`Extension` from :mod:`distutils.extension` -* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd` +* :class:`Command` from :mod:`distutils.cmd` -* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist` +* :class:`Distribution` from :mod:`distutils.dist` A short description of each of these follows, but see the relevant module for the full reference. @@ -1311,8 +1311,7 @@ provides the following additional features: the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. -.. XXX Should be replaced with :mod:`optparse`. - +.. XXX Should be replaced with optparse .. function:: fancy_getopt(options, negative_opt, object, args) @@ -1679,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`. @@ -1690,84 +1689,20 @@ 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. 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 ========================================================== @@ -2006,3 +1941,76 @@ The ``register`` command registers the package with the Python Package Index. 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. diff --git a/Doc/distutils/builtdist.rst b/Doc/distutils/builtdist.rst index 2697ba0..d1ab7db 100644 --- a/Doc/distutils/builtdist.rst +++ b/Doc/distutils/builtdist.rst @@ -139,13 +139,13 @@ The following sections give details on the individual :command:`bdist_\*` commands. -.. _creating-dumb: +.. .. _creating-dumb: -Creating dumb built distributions -================================= +.. Creating dumb built distributions +.. ================================= .. XXX Need to document absolute vs. prefix-relative packages here, but first - I have to implement it! + I have to implement it! .. _creating-rpms: @@ -425,7 +425,7 @@ built-in functions in the installation script. Which folders are available depends on the exact Windows version, and probably also the configuration. For details refer to Microsoft's documentation of the - :cfunc:`SHGetSpecialFolderPath` function. + :c:func:`SHGetSpecialFolderPath` function. .. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) diff --git a/Doc/distutils/commandref.rst b/Doc/distutils/commandref.rst index fbe40de..6a2ac96 100644 --- a/Doc/distutils/commandref.rst +++ b/Doc/distutils/commandref.rst @@ -53,7 +53,7 @@ This command installs all (Python) scripts in the distribution. Creating a source distribution: the :command:`sdist` command ============================================================ -**\*\*** fragment moved down from above: needs context! **\*\*** +.. XXX fragment moved down from above: needs context! The manifest template commands are: @@ -90,7 +90,7 @@ character, and ``[range]`` matches any of the characters in *range* (e.g., character" is platform-specific: on Unix it is anything except slash; on Windows anything except backslash or colon. -**\*\*** Windows support not there yet **\*\*** +.. XXX Windows support not there yet .. % \section{Creating a built distribution: the .. % \protect\command{bdist} command family} diff --git a/Doc/distutils/examples.rst b/Doc/distutils/examples.rst index 6c27738..e31ff72 100644 --- a/Doc/distutils/examples.rst +++ b/Doc/distutils/examples.rst @@ -258,9 +258,8 @@ Running the ``check`` command will display some warnings:: If you use the reStructuredText syntax in the ``long_description`` field and -`docutils <http://docutils.sourceforge.net/>`_ is installed you can check if -the syntax is fine with the ``check`` command, using the ``restructuredtext`` -option. +`docutils`_ is installed you can check if the syntax is fine with the +``check`` command, using the ``restructuredtext`` option. For example, if the :file:`setup.py` script is changed like this:: @@ -291,3 +290,4 @@ by using the :mod:`docutils` parser:: .. % \section{Putting it all together} +.. _docutils: http://docutils.sourceforge.net diff --git a/Doc/distutils/extending.rst b/Doc/distutils/extending.rst index 5a70d03..972ff02 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:`distutils.cmd.Command` class. New commands may directly inherit from +Most distutils command implementations are subclasses of the :class:`Command` +class from :mod:`distutils.cmd`. 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/distutils/sourcedist.rst b/Doc/distutils/sourcedist.rst index 2dea83d..15d0baf 100644 --- a/Doc/distutils/sourcedist.rst +++ b/Doc/distutils/sourcedist.rst @@ -68,10 +68,10 @@ source distribution: :option:`packages` options * all C source files mentioned in the :option:`ext_modules` or - :option:`libraries` options + :option:`libraries` options ( - .. XXX Getting C library sources is currently broken -- no - :meth:`get_source_files` method in :file:`build_clib.py`! + .. XXX getting C library sources currently broken---no + :meth:`get_source_files` method in :file:`build_clib.py`! * scripts identified by the :option:`scripts` option See :ref:`distutils-installing-scripts`. diff --git a/Doc/distutils/uploading.rst b/Doc/distutils/uploading.rst index fd0c508..1b3cb58 100644 --- a/Doc/distutils/uploading.rst +++ b/Doc/distutils/uploading.rst @@ -67,9 +67,10 @@ In that case, :file:`README.txt` is a regular reStructuredText text file located in the root of the package besides :file:`setup.py`. To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the :mod:`docutils` package -and check the ``long_description`` from the command line:: +:program:`rst2html` program that is provided by the :mod:`docutils` package and +check the ``long_description`` from the command line:: $ python setup.py --long-description | rst2html.py > output.html -:mod:`docutils` will display a warning if there's something wrong with your syntax. +:mod:`docutils` will display a warning if there's something wrong with your +syntax. |