10.46 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 distutils.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 distutils/command/peel_banana.py, then edit it so that it's implementing the class peel_banana, a subclass of distutils.cmd.Command.

Subclasses of Command must define the following methods.

initialize_options()( S): et 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.

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 initialize_options().

run( ): 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().

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 an unbound method, 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 unbound methods, so they must already have been defined. The canonical example is the install command.

See About this document... for information on suggesting changes.