Custom distutils commands

This can easily be done with distutils by subclassing distutils.core.Command inside of setup.py.

For example:

from distutils.core import setup, Command
import os, sys

class CleanCommand(Command):
    description = "custom clean command that forcefully removes dist/build directories"
    user_options = []
    def initialize_options(self):
        self.cwd = None
    def finalize_options(self):
        self.cwd = os.getcwd()
    def run(self):
        assert os.getcwd() == self.cwd, 'Must be in package root: %s' % self.cwd
        os.system('rm -rf ./build ./dist')  

To enable the command you must reference it in setup():

setup(
     # stuff omitted for conciseness.
     cmdclass={
        'clean': CleanCommand
}

Note that you can override built-in commands this way too, such as what I did with ‘clean’. (I didn’t like how the built-in version left behind the ‘dist’ and ‘build’ directories.)

% python setup.py --help-commands | grep clean
  clean            custom clean command that forcefully removes dist/build dirs.

There are a number of conventions that are used:

• You specify any command-line arguments with user_options.
• You declare any variables you would use with the initialize_options() method, which is called after initialization to setup your custom namespace for the subclass.
• The finalize_options() method is called right before run().
• The guts of the command itself will occur in run() so be sure to do any other prep work before that.

The best example to use is just to look at the source code for one of the default commands found at PYTHON_DIR/distutils/command such as install.py or build.py.

Sure, you can extend distutils with new commands. In your distutil configuration file, add:

 [global]
 command-packages=foo.bar

this can be in distutils.cfg in the distutils package itself, ..pydistutils.cfg in your home directory (no leading dot on Windows), or setup.cfg in the current directory.

Then you need a foo.bar package in your Python’s site-packages directory.

Then in that package you add the classes implementing your new desired commands, such as stage, subclassing distutils.cmd — the docs are weak, but there are plenty of examples since all the existing distutils commands are also built that way.