|
|
|
Distributing Python Modules |
|
|
|
The distutils.core module is the only module that needs to be
installed to use the Distutils. It provides the setup() (which
is called from the setup script). Indirectly provides the
distutils.dist.Distribution and distutils.cmd.Command class.
-
The basic do-everything function that does most everything you could ever
ask for from a Distutils method. See XXXXX
The setup function takes a large number of arguments. These
are laid out in the following table.
argument name |
value |
type |
name |
The name of the package |
a string |
version |
The version number of the package |
See distutils.version |
description |
A single line describing the package |
a string |
long_description |
Longer description of the package |
a string |
author |
The name of the package author |
a string |
author_email |
The email address of the package author |
a string |
maintainer |
The name of the current maintainer, if different from the author |
a string |
maintainer_email |
The email address of the current maintainer, if different from the author |
|
url |
A URL for the package (homepage) |
a URL |
download_url |
A URL to download the package |
a URL |
packages |
A list of Python packages that distutils will manipulate |
a list of strings |
py_modules |
A list of Python modules that distutils will manipulate |
a list of strings |
scripts |
A list of standalone script files to be built and installed |
a list of strings |
ext_modules |
A list of Python extensions to be built |
A list of
instances of distutils.core.Extension |
classifiers |
A list of categories for the package |
The list of available categorizations is at http://cheeseshop.python.org/pypi?:action=list_classifiers. |
distclass |
the Distribution class to use |
A subclass of distutils.core.Distribution |
script_name |
The name of the setup.py script - defaults to sys.argv[0] |
a string |
script_args |
Arguments to supply to the setup script |
a list of strings |
options |
default options for the setup script |
a string |
license |
The license for the package |
|
keywords |
Descriptive meta-data. See PEP 314 |
|
platforms |
|
|
cmdclass |
A mapping of command names to Command subclasses |
a dictionary |
run_setup( |
script_name[, script_args=None , stop_after='run' ]) |
-
Run a setup script in a somewhat controlled environment, and return
the distutils.dist.Distribution instance that drives things.
This is useful if you need to find out the distribution meta-data
(passed as keyword args from script to setup()), or
the contents of the config files or command-line.
script_name is a file that will be run with execfile()
sys.argv[0] will be replaced with script for the duration of the
call. script_args is a list of strings; if supplied,
sys.argv[1:] will be replaced by script_args for the duration
of the call.
stop_after tells setup() when to stop processing; possible
values:
value |
description |
init |
Stop after the Distribution instance has been created
and populated with the keyword arguments to setup() |
config |
Stop after config files have been parsed (and their data
stored in the Distribution instance) |
commandline |
Stop after the command-line (sys.argv[1:] or
script_args) have been parsed (and the data stored in the
Distribution instance.) |
run |
Stop after all commands have been run (the same as
if setup() had been called in the usual way). This is the default
value. |
In addition, the distutils.core module exposed a number of
classes that live elsewhere.
A short description of each of these follows, but see the relevant
module for the full reference.
- class Extension
-
The Extension class describes a single C or C++extension module in a
setup script. It accepts the following keyword arguments in its
constructor
argument name |
value |
type |
name |
the full name of the extension, including any packages
-- ie. not a filename or pathname, but Python dotted name |
string |
sources |
list of source filenames, relative to the distribution
root (where the setup script lives), in Unix form (slash-separated) for
portability. Source files may be C, C++, SWIG (.i), platform-specific
resource files, or whatever else is recognized by the build_ext
command as source for a Python extension. |
string |
include_dirs |
list of directories to search for C/C++ header
files (in Unix form for portability) |
string |
define_macros |
list of macros to define; each macro is defined
using a 2-tuple, where 'value' is either the string to define it to or
None to define it without a particular value (equivalent of
#define FOO in source or -DFOO on Unix C
compiler command line) |
(string,string)
tuple or (name,None ) |
undef_macros |
list of macros to undefine explicitly |
string |
library_dirs |
list of directories to search for C/C++ libraries
at link time |
string |
libraries |
list of library names (not filenames or paths) to
link against |
string |
runtime_library_dirs |
list of directories to search for C/C++
libraries at run time (for shared extensions, this is when the extension
is loaded) |
string |
extra_objects |
list of extra files to link with (eg. object
files not implied by 'sources', static library that must be explicitly
specified, binary resource files, etc.) |
string |
extra_compile_args |
any extra platform- and compiler-specific
information to use when compiling the source files in 'sources'. For
platforms and compilers where a command line makes sense, this is
typically a list of command-line arguments, but for other platforms it
could be anything. |
string |
extra_link_args |
any extra platform- and compiler-specific
information to use when linking object files together to create the
extension (or to create a new static Python interpreter). Similar
interpretation as for 'extra_compile_args'. |
string |
export_symbols |
list of symbols to be exported from a shared
extension. Not used on all platforms, and not generally necessary for
Python extensions, which typically export exactly one symbol: init +
extension_name. |
string |
depends |
list of files that the extension depends on |
string |
language |
extension language (i.e. 'c' , 'c++' ,
'objc' ). Will be detected from the source extensions if not provided.
|
string |
- class Distribution
-
A Distribution describes how to build, install and package up a
Python software package.
See the setup() function for a list of keyword arguments accepted
by the Distribution constructor. setup() creates a Distribution
instance.
- class Command
-
A Command class (or rather, an instance of one of its subclasses)
implement a single distutils command.
Release 2.5.2, documentation updated on 21st February, 2008.
See About this document... for information on suggesting changes.
|