Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 1 | :mod:`packaging.command` --- Standard Packaging commands |
| 2 | ======================================================== |
| 3 | |
| 4 | .. module:: packaging.command |
| 5 | :synopsis: Standard packaging commands. |
| 6 | |
| 7 | |
| 8 | This subpackage contains one module for each standard Packaging command, such as |
| 9 | :command:`build` or :command:`upload`. Each command is implemented as a |
| 10 | separate module, with the command name as the name of the module and of the |
| 11 | class defined therein. |
| 12 | |
| 13 | |
| 14 | |
| 15 | :mod:`packaging.command.cmd` --- Abstract base class for Packaging commands |
| 16 | =========================================================================== |
| 17 | |
| 18 | .. module:: packaging.command.cmd |
| 19 | :synopsis: Abstract base class for commands. |
| 20 | |
| 21 | |
| 22 | This module supplies the abstract base class :class:`Command`. This class is |
| 23 | subclassed by the modules in the packaging.command subpackage. |
| 24 | |
| 25 | |
| 26 | .. class:: Command(dist) |
| 27 | |
| 28 | Abstract base class for defining command classes, the "worker bees" of the |
| 29 | Packaging. A useful analogy for command classes is to think of them as |
| 30 | subroutines with local variables called *options*. The options are declared |
| 31 | in :meth:`initialize_options` and defined (given their final values) in |
| 32 | :meth:`finalize_options`, both of which must be defined by every command |
| 33 | class. The distinction between the two is necessary because option values |
| 34 | might come from the outside world (command line, config file, ...), and any |
| 35 | options dependent on other options must be computed after these outside |
| 36 | influences have been processed --- hence :meth:`finalize_options`. The body |
| 37 | of the subroutine, where it does all its work based on the values of its |
| 38 | options, is the :meth:`run` method, which must also be implemented by every |
| 39 | command class. |
| 40 | |
| 41 | The class constructor takes a single argument *dist*, a |
| 42 | :class:`~packaging.dist.Distribution` instance. |
| 43 | |
| 44 | |
| 45 | Creating a new Packaging command |
| 46 | -------------------------------- |
| 47 | |
| 48 | This section outlines the steps to create a new Packaging command. |
| 49 | |
| 50 | .. XXX the following paragraph is focused on the stdlib; expand it to document |
| 51 | how to write and register a command in third-party projects |
| 52 | |
| 53 | A new command lives in a module in the :mod:`packaging.command` package. There |
| 54 | is a sample template in that directory called :file:`command_template`. Copy |
| 55 | this file to a new module with the same name as the new command you're |
| 56 | implementing. This module should implement a class with the same name as the |
| 57 | module (and the command). So, for instance, to create the command |
| 58 | ``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy |
| 59 | :file:`command_template` to :file:`packaging/command/peel_banana.py`, then edit |
| 60 | it so that it's implementing the class :class:`peel_banana`, a subclass of |
| 61 | :class:`Command`. It must define the following methods: |
| 62 | |
| 63 | .. method:: Command.initialize_options() |
| 64 | |
| 65 | Set default values for all the options that this command supports. Note that |
| 66 | these defaults may be overridden by other commands, by the setup script, by |
| 67 | config files, or by the command line. Thus, this is not the place to code |
| 68 | dependencies between options; generally, :meth:`initialize_options` |
| 69 | implementations are just a bunch of ``self.foo = None`` assignments. |
| 70 | |
| 71 | |
| 72 | .. method:: Command.finalize_options() |
| 73 | |
| 74 | Set final values for all the options that this command supports. This is |
| 75 | always called as late as possible, i.e. after any option assignments from the |
| 76 | command line or from other commands have been done. Thus, this is the place |
Ezio Melotti | f106449 | 2011-10-19 11:06:26 +0300 | [diff] [blame^] | 77 | to code option dependencies: if *foo* depends on *bar*, then it is safe to |
Éric Araujo | 3a9f58f | 2011-06-01 20:42:49 +0200 | [diff] [blame] | 78 | set *foo* from *bar* as long as *foo* still has the same value it was |
| 79 | assigned in :meth:`initialize_options`. |
| 80 | |
| 81 | |
| 82 | .. method:: Command.run() |
| 83 | |
| 84 | A command's raison d'etre: carry out the action it exists to perform, |
| 85 | controlled by the options initialized in :meth:`initialize_options`, |
| 86 | customized by other commands, the setup script, the command line, and config |
| 87 | files, and finalized in :meth:`finalize_options`. All terminal output and |
| 88 | filesystem interaction should be done by :meth:`run`. |
| 89 | |
| 90 | |
| 91 | Command classes may define this attribute: |
| 92 | |
| 93 | |
| 94 | .. attribute:: Command.sub_commands |
| 95 | |
| 96 | *sub_commands* formalizes the notion of a "family" of commands, |
| 97 | e.g. ``install_dist`` as the parent with sub-commands ``install_lib``, |
| 98 | ``install_headers``, etc. The parent of a family of commands defines |
| 99 | *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, |
| 100 | predicate)``, with *command_name* a string and *predicate* a function, a |
| 101 | string or ``None``. *predicate* is a method of the parent command that |
| 102 | determines whether the corresponding command is applicable in the current |
| 103 | situation. (E.g. ``install_headers`` is only applicable if we have any C |
| 104 | header files to install.) If *predicate* is ``None``, that command is always |
| 105 | applicable. |
| 106 | |
| 107 | *sub_commands* is usually defined at the *end* of a class, because |
| 108 | predicates can be methods of the class, so they must already have been |
| 109 | defined. The canonical example is the :command:`install_dist` command. |
| 110 | |
| 111 | .. XXX document how to add a custom command to another one's subcommands |