This subpackage contains one module for each standard Packaging command, such as build or upload. Each command is implemented as a separate module, with the command name as the name of the module and of the class defined therein.
This module supplies the abstract base class Command. This class is subclassed by the modules in the packaging.command subpackage.
Abstract base class for defining command classes, the “worker bees” of the Packaging. A useful analogy for command classes is to think of them as subroutines with local variables called options. The options are declared in initialize_options() and defined (given their final values) in 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 finalize_options(). The body of the subroutine, where it does all its work based on the values of its options, is the run() method, which must also be implemented by every command class.
The class constructor takes a single argument dist, a Distribution instance.
This section outlines the steps to create a new Packaging command.
A new command lives in a module in the packaging.command package. There is a sample template in that directory called 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 command_template to packaging/command/peel_banana.py, then edit it so that it’s implementing the class peel_banana, a subclass of Command. It must define the following methods:
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, initialize_options() implementations are just a bunch of self.foo = None assignments.
Set final values for all the options that this command supports. This is always called as late as possible, i.e. after any option assignments from the command line or from other commands have been done. Thus, this is the place 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 initialize_options().
A command’s raison d’etre: carry out the action it exists to perform, controlled by the options initialized in initialize_options(), customized by other commands, the setup script, the command line, and config files, and finalized in finalize_options(). All terminal output and filesystem interaction should be done by run().
Command classes may define this attribute:
sub_commands formalizes the notion of a “family” of commands, e.g. install_dist 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 install_dist command.
