Author: tarek.ziade Date: Sat Jul 31 11:10:51 2010 New Revision: 83322 Log: reverted distutils doc to its 3.1 state Modified: python/branches/py3k/Doc/distutils/apiref.rst python/branches/py3k/Doc/distutils/builtdist.rst python/branches/py3k/Doc/distutils/commandref.rst python/branches/py3k/Doc/distutils/examples.rst python/branches/py3k/Doc/distutils/extending.rst python/branches/py3k/Doc/distutils/setupscript.rst python/branches/py3k/Doc/distutils/sourcedist.rst python/branches/py3k/Doc/distutils/uploading.rst Modified: python/branches/py3k/Doc/distutils/apiref.rst ============================================================================== --- python/branches/py3k/Doc/distutils/apiref.rst (original) +++ python/branches/py3k/Doc/distutils/apiref.rst Sat Jul 31 11:10:51 2010 @@ -21,9 +21,7 @@ .. 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. See XXXXX The setup function takes a large number of arguments. These are laid out in the following table. @@ -149,11 +147,11 @@ 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. @@ -997,7 +995,7 @@ errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is true). -.. XXX Some of this could be replaced with the shutil module? +**\*\*** Some of this could be replaced with the shutil module? **\*\*** :mod:`distutils.file_util` --- Single file operations @@ -1313,7 +1311,8 @@ the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. -.. XXX Should be replaced with :mod:`optparse`. +**\*\*** Should be replaced with :mod:`optik` (which is also now known as +:mod:`optparse` in Python 2.3 and later). **\*\*** .. function:: fancy_getopt(options, negative_opt, object, args) @@ -1681,8 +1680,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`. @@ -1692,84 +1691,20 @@ 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 ========================================================== @@ -2008,3 +1943,76 @@ 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. Modified: python/branches/py3k/Doc/distutils/builtdist.rst ============================================================================== --- python/branches/py3k/Doc/distutils/builtdist.rst (original) +++ python/branches/py3k/Doc/distutils/builtdist.rst Sat Jul 31 11:10:51 2010 @@ -146,8 +146,8 @@ Creating dumb built distributions ================================= -.. XXX Need to document absolute vs. prefix-relative packages here, but first - I have to implement it! +**\*\*** Need to document absolute vs. prefix-relative packages here, but first +I have to implement it! **\*\*** .. _creating-rpms: @@ -241,8 +241,7 @@ configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If you distribute or package many Python module distributions, you might want to put options that apply to all of them in your personal Distutils configuration -file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable -this file, you can pass the --no-user-cfg option to setup.py. +file (:file:`~/.pydistutils.cfg`). There are three steps to building a binary RPM package, all of which are handled automatically by the Distutils: Modified: python/branches/py3k/Doc/distutils/commandref.rst ============================================================================== --- python/branches/py3k/Doc/distutils/commandref.rst (original) +++ python/branches/py3k/Doc/distutils/commandref.rst Sat Jul 31 11:10:51 2010 @@ -48,6 +48,50 @@ .. % \label{clean-cmd} +.. _sdist-cmd: + +Creating a source distribution: the :command:`sdist` command +============================================================ + +**\*\*** fragment moved down from above: needs context! **\*\*** + +The manifest template commands are: + ++-------------------------------------------+-----------------------------------------------+ +| Command | Description | ++===========================================+===============================================+ +| :command:`include pat1 pat2 ...` | include all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`prune dir` | exclude all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ +| :command:`graft dir` | include all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ + +The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of +regular filename characters, ``?`` matches any single regular filename +character, and ``[range]`` matches any of the characters in *range* (e.g., +``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename +character" is platform-specific: on Unix it is anything except slash; on Windows +anything except backslash or colon. + +**\*\*** Windows support not there yet **\*\*** + .. % \section{Creating a built distribution: the .. % \protect\command{bdist} command family} .. % \label{bdist-cmds} Modified: python/branches/py3k/Doc/distutils/examples.rst ============================================================================== --- python/branches/py3k/Doc/distutils/examples.rst (original) +++ python/branches/py3k/Doc/distutils/examples.rst Sat Jul 31 11:10:51 2010 @@ -233,6 +233,58 @@ ext_modules=[Extension('foopkg.foo', ['foo.c'])], ) +Checking a package +================== + +The ``check`` command allows you to verify if your package meta-data +meet the minimum requirements to build a distribution. + +To run it, just call it using your :file:`setup.py` script. If something is +missing, ``check`` will display a warning. + +Let's take an example with a simple script:: + + from distutils.core import setup + + setup(name='foobar') + +Running the ``check`` command will display some warnings:: + + $ python setup.py check + running check + warning: check: missing required meta-data: version, url + warning: check: missing meta-data: either (author and author_email) or + (maintainer and maintainer_email) must be supplied + + +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. + +For example, if the :file:`setup.py` script is changed like this:: + + from distutils.core import setup + + desc = """\ + My description + ============= + + This is the description of the ``foobar`` package. + """ + + setup(name='foobar', version='1', author='tarek', + author_email='tarek@ziade.org', + url='http://example.com', long_description=desc) + +Where the long description is broken, ``check`` will be able to detect it +by using the `docutils` parser:: + + $ pythontrunk setup.py check --restructuredtext + running check + warning: check: Title underline too short. (line 2) + warning: check: Could not finish the parsing. + .. % \section{Multiple extension modules} .. % \label{multiple-ext} Modified: python/branches/py3k/Doc/distutils/extending.rst ============================================================================== --- python/branches/py3k/Doc/distutils/extending.rst (original) +++ python/branches/py3k/Doc/distutils/extending.rst Sat Jul 31 11:10:51 2010 @@ -15,8 +15,8 @@ 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`. Modified: python/branches/py3k/Doc/distutils/setupscript.rst ============================================================================== --- python/branches/py3k/Doc/distutils/setupscript.rst (original) +++ python/branches/py3k/Doc/distutils/setupscript.rst Sat Jul 31 11:10:51 2010 @@ -207,7 +207,7 @@ SWIG on the interface file and compile the resulting C/C++ file into your extension. -.. XXX SWIG support is rough around the edges and largely untested! +**\*\*** SWIG support is rough around the edges and largely untested! **\*\*** This warning notwithstanding, options to SWIG can be currently passed like this:: @@ -326,7 +326,7 @@ (Again, this sort of non-portable construct should be avoided if you intend to distribute your code.) -.. XXX Should mention clib libraries here or somewhere else! +**\*\*** Should mention clib libraries here or somewhere else! **\*\*** Other options Modified: python/branches/py3k/Doc/distutils/sourcedist.rst ============================================================================== --- python/branches/py3k/Doc/distutils/sourcedist.rst (original) +++ python/branches/py3k/Doc/distutils/sourcedist.rst Sat Jul 31 11:10:51 2010 @@ -26,16 +26,16 @@ +===========+=========================+=========+ | ``zip`` | zip file (:file:`.zip`) | (1),(3) | +-----------+-------------------------+---------+ -| ``gztar`` | gzip'ed tar file | \(2) | +| ``gztar`` | gzip'ed tar file | (2),(4) | | | (:file:`.tar.gz`) | | +-----------+-------------------------+---------+ -| ``bztar`` | bzip2'ed tar file | | +| ``bztar`` | bzip2'ed tar file | \(4) | | | (:file:`.tar.bz2`) | | +-----------+-------------------------+---------+ | ``ztar`` | compressed tar file | \(4) | | | (:file:`.tar.Z`) | | +-----------+-------------------------+---------+ -| ``tar`` | tar file (:file:`.tar`) | | +| ``tar`` | tar file (:file:`.tar`) | \(4) | +-----------+-------------------------+---------+ Notes: @@ -51,16 +51,8 @@ of the standard Python library since Python 1.6) (4) - requires the :program:`compress` program. Notice that this format is now - pending for deprecation and will be removed in the future versions of Python. - -When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or -``tar``) under Unix, you can specify the ``owner`` and ``group`` names -that will be set for each member of the archive. - -For example, if you want all files of the archive to be owned by root:: - - python setup.py sdist --owner=root --group=root + requires external utilities: :program:`tar` and possibly one of :program:`gzip`, + :program:`bzip2`, or :program:`compress` .. _manifest: @@ -76,10 +68,10 @@ :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`! + **\*\*** 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`. @@ -111,60 +103,9 @@ :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. -See :ref:`manifest_template` section for a syntax reference. - -.. _manifest-options: - -Manifest-related options -======================== - -The normal course of operations for the :command:`sdist` command is as follows: - -* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` - and create the manifest - -* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest - with just the default file set - -* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more - recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading - :file:`MANIFEST.in` - -* use the list of files now in :file:`MANIFEST` (either just generated or read - in) to create the source distribution archive(s) - -There are a couple of options that modify this behaviour. First, use the -:option:`--no-defaults` and :option:`--no-prune` to disable the standard -"include" and "exclude" sets. - -Second, you might just want to (re)generate the manifest, but not create a -source distribution:: - - python setup.py sdist --manifest-only - -:option:`-o` is a sortcut for :option:`--manifest-only`. - -.. _manifest_template: - -The MANIFEST.in template -======================== - -A :file:`MANIFEST.in` file can be added in a project to define the list of -files to include in the distribution built by the :command:`sdist` command. - -When :command:`sdist` is run, it will look for the :file:`MANIFEST.in` file -and interpret it to generate the :file:`MANIFEST` file that contains the -list of files that will be included in the package. - -This mechanism can be used when the default list of files is not enough. -(See :ref:`manifest`). - -Principle ---------- - The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an -example, let's look at the Distutils' own manifest template:: +example, again we turn to the Distutils' own manifest template:: include *.txt recursive-include examples *.txt *.py @@ -176,7 +117,9 @@ :file:`examples/sample?/build`. All of this is done *after* the standard include set, so you can exclude files from the standard set with explicit instructions in the manifest template. (Or, you can use the -:option:`--no-defaults` option to disable the standard set entirely.) +:option:`--no-defaults` option to disable the standard set entirely.) There are +several other commands available in the manifest template mini-language; see +section :ref:`sdist-cmd`. The order of commands in the manifest template matters: initially, we have the list of default files as described above, and each command in the template adds @@ -230,41 +173,36 @@ them to the standard representation on your platform. That way, the manifest template is portable across operating systems. -Commands --------- -The manifest template commands are: +.. _manifest-options: + +Manifest-related options +======================== + +The normal course of operations for the :command:`sdist` command is as follows: + +* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` + and create the manifest + +* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest + with just the default file set + +* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more + recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading + :file:`MANIFEST.in` + +* use the list of files now in :file:`MANIFEST` (either just generated or read + in) to create the source distribution archive(s) + +There are a couple of options that modify this behaviour. First, use the +:option:`--no-defaults` and :option:`--no-prune` to disable the standard +"include" and "exclude" sets. + +Second, you might just want to (re)generate the manifest, but not create a source +distribution:: + + python setup.py sdist --manifest-only + +:option:`-o` is a shortcut for :option:`--manifest-only`. -+-------------------------------------------+-----------------------------------------------+ -| Command | Description | -+===========================================+===============================================+ -| :command:`include pat1 pat2 ...` | include all files matching any of the listed | -| | patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | -| | patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | -| ...` | the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | -| ...` | the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | -| | matching --- & any of the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | -| | matching --- & any of the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`prune dir` | exclude all files under *dir* | -+-------------------------------------------+-----------------------------------------------+ -| :command:`graft dir` | include all files under *dir* | -+-------------------------------------------+-----------------------------------------------+ - -The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of -regular filename characters, ``?`` matches any single regular filename -character, and ``[range]`` matches any of the characters in *range* (e.g., -``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename -character" is platform-specific: on Unix it is anything except slash; on Windows -anything except backslash or colon. Modified: python/branches/py3k/Doc/distutils/uploading.rst ============================================================================== --- python/branches/py3k/Doc/distutils/uploading.rst (original) +++ python/branches/py3k/Doc/distutils/uploading.rst Sat Jul 31 11:10:51 2010 @@ -60,13 +60,13 @@ setup(name='Distutils', long_description=open('README.txt')) -In that case, :file:`README.txt` is a regular reStructuredText text file located -in the root of the package besides :file:`setup.py`. +In that case, `README.txt` is a regular reStructuredText text file located +in the root of the package besides `setup.py`. To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the :mod:`docutils` package +:program:`rst2html` program that is provided by the `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. +`docutils` will display a warning if there's something wrong with your syntax.