<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"dist.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"dist.html" title='Distributing Python Modules'
/>
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"prev" href=
"module-distutils.command.register.html" />
<link rel=
"parent" href=
"api-reference.html" />
<link rel=
"next" href=
"modindex.html" />
<meta name='aesop' content='information'
/>
<title>10.46 Creating a new Distutils command
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"10.45 distutils.command.register "
href=
"module-distutils.command.register.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"10. API Reference"
href=
"api-reference.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"Module Index"
href=
"modindex.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Distributing Python Modules
</td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-distutils.command.register.html">10.45 distutils.command.register
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"api-reference.html">10. API Reference
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"modindex.html">Module Index
</A>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION00104600000000000000000">
10.46 Creating a new Distutils command
</A>
This section outlines the steps to create a new Distutils command.
A new command lives in a module in the
<tt class=
"module">distutils.command
</tt>package. There is a sample template in that directory called
<span class=
"file">command_template
</span>. 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
<code>peel_banana
</code> (so that users
can run
"<tt class="samp
">setup.py peel_banana</tt>"), you'd copy
<span class=
"file">command_template
</span> to
<span class=
"file">distutils/command/peel_banana.py
</span>, then edit it so that it's
implementing the class
<tt class=
"class">peel_banana
</tt>, a subclass of
<tt class=
"class">distutils.cmd.Command
</tt>.
Subclasses of
<tt class=
"class">Command
</tt> must define the following methods.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
148' xml:id='l2h-
148'
class=
"method">initialize_options()
</tt></b>(
</nobr></td>
<td><var>S
</var>)
</td></tr></table></dt>
<dd>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,
<tt class=
"method">initialize_options()
</tt> implementations
are just a bunch of
"<tt class="samp
">self.foo = None</tt>" assignments.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
149' xml:id='l2h-
149'
class=
"method">finalize_options
</tt></b>(
</nobr></td>
<td><var></var>)
</td></tr></table></dt>
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
<var>foo
</var> depends on
<var>bar
</var>, then it is safe to set
<var>foo
</var> from
<var>bar
</var> as long as
<var>foo
</var> still has the same value it was assigned in
<tt class=
"method">initialize_options()
</tt>.
<dl><dt><table cellpadding=
"0" cellspacing=
"0"><tr valign=
"baseline">
<td><nobr><b><tt id='l2h-
150' xml:id='l2h-
150'
class=
"method">run
</tt></b>(
</nobr></td>
<td><var></var>)
</td></tr></table></dt>
A command's raison d'etre: carry out the action it exists to
perform, controlled by the options initialized in
<tt class=
"method">initialize_options()
</tt>, customized by other commands, the setup
script, the command-line, and config files, and finalized in
<tt class=
"method">finalize_options()
</tt>. All terminal output and filesystem
interaction should be done by
<tt class=
"method">run()
</tt>.
<var>sub_commands
</var> formalizes the notion of a ``family'' of commands,
eg.
<code>install
</code> as the parent with sub-commands
<code>install_lib
</code>,
<code>install_headers
</code>, etc. The parent of a family of commands
defines
<var>sub_commands
</var> as a class attribute; it's a list of
2-tuples
"<tt class="samp
">(command_name, predicate)</tt>", with
<var>command_name
</var> a string
and
<var>predicate
</var> an unbound method, a string or None.
<var>predicate
</var> is a method of the parent command that
determines whether the corresponding command is applicable in the
current situation. (Eg. we
<code>install_headers
</code> is only applicable if
we have any C header files to install.) If
<var>predicate
</var> is None,
that command is always applicable.
<var>sub_commands
</var> 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
<code class=
"du-command">install
</code> command.
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"10.45 distutils.command.register "
href=
"module-distutils.command.register.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"parent" title=
"10. API Reference"
href=
"api-reference.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td><td class='online-navigation'
><a rel=
"next" title=
"Module Index"
href=
"modindex.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td><td align=
"center" width=
"100%">Distributing Python Modules
</td>
<td class='online-navigation'
><img src='../icons/blank.png'
border='
0' height='
32' alt='' width='
32'
/></td><td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td><td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td><div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-distutils.command.register.html">10.45 distutils.command.register
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"api-reference.html">10. API Reference
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"modindex.html">Module Index
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.
projects / OpenSPARC-T2-SAM / blob