Custom distutils commands
Question:
I have a library called “example” that I’m installing into my global site-packages directory. However, I’d like to be able to install two versions, one for production and one for testing (I have a web application and other things that are versioned this way).
Is there a way to specify, say “python setup.py stage” that will not only install a different egg into site-packages, but also rename the module from “example” to “example_stage” or something similar?
If distutils cannot do this, is there any other tool that can?
Answers:
If you’d like to use multiple version then virtualenv with virtualenvwrapper can help.
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.
See Alex’s answer if you want a way to do this with distutils, but I find Paver to be better for this kind of thing. It makes it a lot easier to make custom commands or override existing ones. Plus the transition isn’t terribly difficult if you’re used to distutils or setuptools.
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.
I have a library called “example” that I’m installing into my global site-packages directory. However, I’d like to be able to install two versions, one for production and one for testing (I have a web application and other things that are versioned this way).
Is there a way to specify, say “python setup.py stage” that will not only install a different egg into site-packages, but also rename the module from “example” to “example_stage” or something similar?
If distutils cannot do this, is there any other tool that can?
If you’d like to use multiple version then virtualenv with virtualenvwrapper can help.
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.
See Alex’s answer if you want a way to do this with distutils, but I find Paver to be better for this kind of thing. It makes it a lot easier to make custom commands or override existing ones. Plus the transition isn’t terribly difficult if you’re used to distutils or setuptools.
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.