| blob | a70c8071f112d82e41b4f42f124bd12593adff3c |
1 .. _api-reference:
3 *************
4 API Reference
5 *************
8 :mod:`distutils.core` --- Core Distutils functionality
9 ======================================================
11 .. module:: distutils.core
12 :synopsis: The core Distutils functionality
15 The :mod:`distutils.core` module is the only module that needs to be installed
16 to use the Distutils. It provides the :func:`setup` (which is called from the
17 setup script). Indirectly provides the :class:`distutils.dist.Distribution` and
18 :class:`distutils.cmd.Command` class.
21 .. function:: setup(arguments)
23 The basic do-everything function that does most everything you could ever ask
24 for from a Distutils method. See XXXXX
26 The setup function takes a large number of arguments. These are laid out in the
27 following table.
29 +--------------------+--------------------------------+-------------------------------------------------------------+
30 | argument name | value | type |
31 +====================+================================+=============================================================+
32 | *name* | The name of the package | a string |
33 +--------------------+--------------------------------+-------------------------------------------------------------+
34 | *version* | The version number of the | See :mod:`distutils.version` |
35 | | package | |
36 +--------------------+--------------------------------+-------------------------------------------------------------+
37 | *description* | A single line describing the | a string |
38 | | package | |
39 +--------------------+--------------------------------+-------------------------------------------------------------+
40 | *long_description* | Longer description of the | a string |
41 | | package | |
42 +--------------------+--------------------------------+-------------------------------------------------------------+
43 | *author* | The name of the package author | a string |
44 +--------------------+--------------------------------+-------------------------------------------------------------+
45 | *author_email* | The email address of the | a string |
46 | | package author | |
47 +--------------------+--------------------------------+-------------------------------------------------------------+
48 | *maintainer* | The name of the current | a string |
49 | | maintainer, if different from | |
50 | | the author | |
51 +--------------------+--------------------------------+-------------------------------------------------------------+
52 | *maintainer_email* | The email address of the | |
53 | | current maintainer, if | |
54 | | different from the author | |
55 +--------------------+--------------------------------+-------------------------------------------------------------+
56 | *url* | A URL for the package | a URL |
57 | | (homepage) | |
58 +--------------------+--------------------------------+-------------------------------------------------------------+
59 | *download_url* | A URL to download the package | a URL |
60 +--------------------+--------------------------------+-------------------------------------------------------------+
61 | *packages* | A list of Python packages that | a list of strings |
62 | | distutils will manipulate | |
63 +--------------------+--------------------------------+-------------------------------------------------------------+
64 | *py_modules* | A list of Python modules that | a list of strings |
65 | | distutils will manipulate | |
66 +--------------------+--------------------------------+-------------------------------------------------------------+
67 | *scripts* | A list of standalone script | a list of strings |
68 | | files to be built and | |
69 | | installed | |
70 +--------------------+--------------------------------+-------------------------------------------------------------+
71 | *ext_modules* | A list of Python extensions to | A list of instances of |
72 | | be built | :class:`distutils.core.Extension` |
73 +--------------------+--------------------------------+-------------------------------------------------------------+
74 | *classifiers* | A list of categories for the | The list of available |
75 | | package | categorizations is at |
76 | | | http://pypi.python.org/pypi?:action=list_classifiers. |
77 +--------------------+--------------------------------+-------------------------------------------------------------+
78 | *distclass* | the :class:`Distribution` | A subclass of |
79 | | class to use | :class:`distutils.core.Distribution` |
80 +--------------------+--------------------------------+-------------------------------------------------------------+
81 | *script_name* | The name of the setup.py | a string |
82 | | script - defaults to | |
83 | | ``sys.argv[0]`` | |
84 +--------------------+--------------------------------+-------------------------------------------------------------+
85 | *script_args* | Arguments to supply to the | a list of strings |
86 | | setup script | |
87 +--------------------+--------------------------------+-------------------------------------------------------------+
88 | *options* | default options for the setup | a string |
89 | | script | |
90 +--------------------+--------------------------------+-------------------------------------------------------------+
91 | *license* | The license for the package | a string |
92 +--------------------+--------------------------------+-------------------------------------------------------------+
93 | *keywords* | Descriptive meta-data, see | |
94 | | :pep:`314` | |
95 +--------------------+--------------------------------+-------------------------------------------------------------+
96 | *platforms* | | |
97 +--------------------+--------------------------------+-------------------------------------------------------------+
98 | *cmdclass* | A mapping of command names to | a dictionary |
99 | | :class:`Command` subclasses | |
100 +--------------------+--------------------------------+-------------------------------------------------------------+
101 | *data_files* | A list of data files to | a list |
102 | | install | |
103 +--------------------+--------------------------------+-------------------------------------------------------------+
104 | *package_dir* | A mapping of package to | a dictionary |
105 | | directory names | |
106 +--------------------+--------------------------------+-------------------------------------------------------------+
110 .. function:: run_setup(script_name[, script_args=None, stop_after='run'])
112 Run a setup script in a somewhat controlled environment, and return the
113 :class:`distutils.dist.Distribution` instance that drives things. This is
114 useful if you need to find out the distribution meta-data (passed as keyword
115 args from *script* to :func:`setup`), or the contents of the config files or
116 command-line.
118 *script_name* is a file that will be run with :func:`execfile` ``sys.argv[0]``
119 will be replaced with *script* for the duration of the call. *script_args* is a
120 list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args*
121 for the duration of the call.
123 *stop_after* tells :func:`setup` when to stop processing; possible values:
125 +---------------+---------------------------------------------+
126 | value | description |
127 +===============+=============================================+
128 | *init* | Stop after the :class:`Distribution` |
129 | | instance has been created and populated |
130 | | with the keyword arguments to :func:`setup` |
131 +---------------+---------------------------------------------+
132 | *config* | Stop after config files have been parsed |
133 | | (and their data stored in the |
134 | | :class:`Distribution` instance) |
135 +---------------+---------------------------------------------+
136 | *commandline* | Stop after the command-line |
137 | | (``sys.argv[1:]`` or *script_args*) have |
138 | | been parsed (and the data stored in the |
139 | | :class:`Distribution` instance.) |
140 +---------------+---------------------------------------------+
141 | *run* | Stop after all commands have been run (the |
142 | | same as if :func:`setup` had been called |
143 | | in the usual way). This is the default |
144 | | value. |
145 +---------------+---------------------------------------------+
147 In addition, the :mod:`distutils.core` module exposed a number of classes that
148 live elsewhere.
150 * :class:`Extension` from :mod:`distutils.extension`
152 * :class:`Command` from :mod:`distutils.cmd`
154 * :class:`Distribution` from :mod:`distutils.dist`
156 A short description of each of these follows, but see the relevant module for
157 the full reference.
160 .. class:: Extension
162 The Extension class describes a single C or C++extension module in a setup
163 script. It accepts the following keyword arguments in its constructor
165 +------------------------+--------------------------------+---------------------------+
166 | argument name | value | type |
167 +========================+================================+===========================+
168 | *name* | the full name of the | string |
169 | | extension, including any | |
170 | | packages --- ie. *not* a | |
171 | | filename or pathname, but | |
172 | | Python dotted name | |
173 +------------------------+--------------------------------+---------------------------+
174 | *sources* | list of source filenames, | string |
175 | | relative to the distribution | |
176 | | root (where the setup script | |
177 | | lives), in Unix form (slash- | |
178 | | separated) for portability. | |
179 | | Source files may be C, C++, | |
180 | | SWIG (.i), platform-specific | |
181 | | resource files, or whatever | |
182 | | else is recognized by the | |
183 | | :command:`build_ext` command | |
184 | | as source for a Python | |
185 | | extension. | |
186 +------------------------+--------------------------------+---------------------------+
187 | *include_dirs* | list of directories to search | string |
188 | | for C/C++ header files (in | |
189 | | Unix form for portability) | |
190 +------------------------+--------------------------------+---------------------------+
191 | *define_macros* | list of macros to define; each | (string, string) tuple or |
192 | | macro is defined using a | (name, ``None``) |
193 | | 2-tuple ``(name, value)``, | |
194 | | where *value* is | |
195 | | either the string to define it | |
196 | | to or ``None`` to define it | |
197 | | without a particular value | |
198 | | (equivalent of ``#define FOO`` | |
199 | | in source or :option:`-DFOO` | |
200 | | on Unix C compiler command | |
201 | | line) | |
202 +------------------------+--------------------------------+---------------------------+
203 | *undef_macros* | list of macros to undefine | string |
204 | | explicitly | |
205 +------------------------+--------------------------------+---------------------------+
206 | *library_dirs* | list of directories to search | string |
207 | | for C/C++ libraries at link | |
208 | | time | |
209 +------------------------+--------------------------------+---------------------------+
210 | *libraries* | list of library names (not | string |
211 | | filenames or paths) to link | |
212 | | against | |
213 +------------------------+--------------------------------+---------------------------+
214 | *runtime_library_dirs* | list of directories to search | string |
215 | | for C/C++ libraries at run | |
216 | | time (for shared extensions, | |
217 | | this is when the extension is | |
218 | | loaded) | |
219 +------------------------+--------------------------------+---------------------------+
220 | *extra_objects* | list of extra files to link | string |
221 | | with (eg. object files not | |
222 | | implied by 'sources', static | |
223 | | library that must be | |
224 | | explicitly specified, binary | |
225 | | resource files, etc.) | |
226 +------------------------+--------------------------------+---------------------------+
227 | *extra_compile_args* | any extra platform- and | string |
228 | | compiler-specific information | |
229 | | to use when compiling the | |
230 | | source files in 'sources'. For | |
231 | | platforms and compilers where | |
232 | | a command line makes sense, | |
233 | | this is typically a list of | |
234 | | command-line arguments, but | |
235 | | for other platforms it could | |
236 | | be anything. | |
237 +------------------------+--------------------------------+---------------------------+
238 | *extra_link_args* | any extra platform- and | string |
239 | | compiler-specific information | |
240 | | to use when linking object | |
241 | | files together to create the | |
242 | | extension (or to create a new | |
243 | | static Python interpreter). | |
244 | | Similar interpretation as for | |
245 | | 'extra_compile_args'. | |
246 +------------------------+--------------------------------+---------------------------+
247 | *export_symbols* | list of symbols to be exported | string |
248 | | from a shared extension. Not | |
249 | | used on all platforms, and not | |
250 | | generally necessary for Python | |
251 | | extensions, which typically | |
252 | | export exactly one symbol: | |
253 | | ``init`` + extension_name. | |
254 +------------------------+--------------------------------+---------------------------+
255 | *depends* | list of files that the | string |
256 | | extension depends on | |
257 +------------------------+--------------------------------+---------------------------+
258 | *language* | extension language (i.e. | string |
259 | | ``'c'``, ``'c++'``, | |
260 | | ``'objc'``). Will be detected | |
261 | | from the source extensions if | |
262 | | not provided. | |
263 +------------------------+--------------------------------+---------------------------+
266 .. class:: Distribution
268 A :class:`Distribution` describes how to build, install and package up a Python
269 software package.
271 See the :func:`setup` function for a list of keyword arguments accepted by the
272 Distribution constructor. :func:`setup` creates a Distribution instance.
275 .. class:: Command
277 A :class:`Command` class (or rather, an instance of one of its subclasses)
278 implement a single distutils command.
281 :mod:`distutils.ccompiler` --- CCompiler base class
282 ===================================================
284 .. module:: distutils.ccompiler
285 :synopsis: Abstract CCompiler class
288 This module provides the abstract base class for the :class:`CCompiler`
289 classes. A :class:`CCompiler` instance can be used for all the compile and
290 link steps needed to build a single project. Methods are provided to set
291 options for the compiler --- macro definitions, include directories, link path,
292 libraries and the like.
294 This module provides the following functions.
297 .. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
299 Generate linker options for searching library directories and linking with
300 specific libraries. *libraries* and *library_dirs* are, respectively, lists of
301 library names (not filenames!) and search directories. Returns a list of
302 command-line options suitable for use with some compiler (depending on the two
303 format strings passed in).
306 .. function:: gen_preprocess_options(macros, include_dirs)
308 Generate C pre-processor options (:option:`-D`, :option:`-U`, :option:`-I`) as
309 used by at least two types of compilers: the typical Unix compiler and Visual
310 C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
311 means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means define
312 (:option:`-D`) macro *name* to *value*. *include_dirs* is just a list of
313 directory names to be added to the header file search path (:option:`-I`).
314 Returns a list of command-line options suitable for either Unix compilers or
315 Visual C++.
318 .. function:: get_default_compiler(osname, platform)
320 Determine the default compiler to use for the given platform.
322 *osname* should be one of the standard Python OS names (i.e. the ones returned
323 by ``os.name``) and *platform* the common value returned by ``sys.platform`` for
324 the platform in question.
326 The default values are ``os.name`` and ``sys.platform`` in case the parameters
327 are not given.
330 .. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
332 Factory function to generate an instance of some CCompiler subclass for the
333 supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
334 ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for
335 that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
336 default compilers are "traditional Unix interface" (:class:`UnixCCompiler`
337 class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly
338 possible to ask for a Unix compiler object under Windows, and a Microsoft
339 compiler object under Unix---if you supply a value for *compiler*, *plat* is
340 ignored.
342 .. % Is the posix/nt only thing still true? Mac OS X seems to work, and
343 .. % returns a UnixCCompiler instance. How to document this... hmm.
346 .. function:: show_compilers()
348 Print list of available compilers (used by the :option:`--help-compiler` options
349 to :command:`build`, :command:`build_ext`, :command:`build_clib`).
352 .. class:: CCompiler([verbose=0, dry_run=0, force=0])
354 The abstract base class :class:`CCompiler` defines the interface that must be
355 implemented by real compiler classes. The class also has some utility methods
356 used by several compiler classes.
358 The basic idea behind a compiler abstraction class is that each instance can be
359 used for all the compile/link steps in building a single project. Thus,
360 attributes common to all of those compile and link steps --- include
361 directories, macros to define, libraries to link against, etc. --- are
362 attributes of the compiler instance. To allow for variability in how individual
363 files are treated, most of those attributes may be varied on a per-compilation
364 or per-link basis.
366 The constructor for each subclass creates an instance of the Compiler object.
367 Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the
368 steps) and *force* (rebuild everything, regardless of dependencies). All of
369 these flags default to ``0`` (off). Note that you probably don't want to
370 instantiate :class:`CCompiler` or one of its subclasses directly - use the
371 :func:`distutils.CCompiler.new_compiler` factory function instead.
373 The following methods allow you to manually alter compiler options for the
374 instance of the Compiler class.
377 .. method:: CCompiler.add_include_dir(dir)
379 Add *dir* to the list of directories that will be searched for header files.
380 The compiler is instructed to search directories in the order in which they are
381 supplied by successive calls to :meth:`add_include_dir`.
384 .. method:: CCompiler.set_include_dirs(dirs)
386 Set the list of directories that will be searched to *dirs* (a list of strings).
387 Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to
388 :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.
389 This does not affect any list of standard include directories that the compiler
390 may search by default.
393 .. method:: CCompiler.add_library(libname)
395 Add *libname* to the list of libraries that will be included in all links driven
396 by this compiler object. Note that *libname* should \*not\* be the name of a
397 file containing a library, but the name of the library itself: the actual
398 filename will be inferred by the linker, the compiler, or the compiler class
399 (depending on the platform).
401 The linker will be instructed to link against libraries in the order they were
402 supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly
403 valid to duplicate library names; the linker will be instructed to link against
404 libraries as many times as they are mentioned.
407 .. method:: CCompiler.set_libraries(libnames)
409 Set the list of libraries to be included in all links driven by this compiler
410 object to *libnames* (a list of strings). This does not affect any standard
411 system libraries that the linker may include by default.
414 .. method:: CCompiler.add_library_dir(dir)
416 Add *dir* to the list of directories that will be searched for libraries
417 specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be
418 instructed to search for libraries in the order they are supplied to
419 :meth:`add_library_dir` and/or :meth:`set_library_dirs`.
422 .. method:: CCompiler.set_library_dirs(dirs)
424 Set the list of library search directories to *dirs* (a list of strings). This
425 does not affect any standard library search path that the linker may search by
426 default.
429 .. method:: CCompiler.add_runtime_library_dir(dir)
431 Add *dir* to the list of directories that will be searched for shared libraries
432 at runtime.
435 .. method:: CCompiler.set_runtime_library_dirs(dirs)
437 Set the list of directories to search for shared libraries at runtime to *dirs*
438 (a list of strings). This does not affect any standard search path that the
439 runtime linker may search by default.
442 .. method:: CCompiler.define_macro(name[, value=None])
444 Define a preprocessor macro for all compilations driven by this compiler object.
445 The optional parameter *value* should be a string; if it is not supplied, then
446 the macro will be defined without an explicit value and the exact outcome
447 depends on the compiler used (XXX true? does ANSI say anything about this?)
450 .. method:: CCompiler.undefine_macro(name)
452 Undefine a preprocessor macro for all compilations driven by this compiler
453 object. If the same macro is defined by :meth:`define_macro` and
454 undefined by :meth:`undefine_macro` the last call takes precedence
455 (including multiple redefinitions or undefinitions). If the macro is
456 redefined/undefined on a per-compilation basis (ie. in the call to
457 :meth:`compile`), then that takes precedence.
460 .. method:: CCompiler.add_link_object(object)
462 Add *object* to the list of object files (or analogues, such as explicitly named
463 library files or the output of "resource compilers") to be included in every
464 link driven by this compiler object.
467 .. method:: CCompiler.set_link_objects(objects)
469 Set the list of object files (or analogues) to be included in every link to
470 *objects*. This does not affect any standard object files that the linker may
471 include by default (such as system libraries).
473 The following methods implement methods for autodetection of compiler options,
474 providing some functionality similar to GNU :program:`autoconf`.
477 .. method:: CCompiler.detect_language(sources)
479 Detect the language of a given file, or list of files. Uses the instance
480 attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a
481 list) to do the job.
484 .. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
486 Search the specified list of directories for a static or shared library file
487 *lib* and return the full path to that file. If *debug* is true, look for a
488 debugging version (if that makes sense on the current platform). Return
489 ``None`` if *lib* wasn't found in any of the specified directories.
492 .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
494 Return a boolean indicating whether *funcname* is supported on the current
495 platform. The optional arguments can be used to augment the compilation
496 environment by providing additional include files and paths and libraries and
497 paths.
500 .. method:: CCompiler.library_dir_option(dir)
502 Return the compiler option to add *dir* to the list of directories searched for
503 libraries.
506 .. method:: CCompiler.library_option(lib)
508 Return the compiler option to add *dir* to the list of libraries linked into the
509 shared library or executable.
512 .. method:: CCompiler.runtime_library_dir_option(dir)
514 Return the compiler option to add *dir* to the list of directories searched for
515 runtime libraries.
518 .. method:: CCompiler.set_executables(**args)
520 Define the executables (and options for them) that will be run to perform the
521 various stages of compilation. The exact set of executables that may be
522 specified here depends on the compiler class (via the 'executables' class
523 attribute), but most will have:
525 +--------------+------------------------------------------+
526 | attribute | description |
527 +==============+==========================================+
528 | *compiler* | the C/C++ compiler |
529 +--------------+------------------------------------------+
530 | *linker_so* | linker used to create shared objects and |
531 | | libraries |
532 +--------------+------------------------------------------+
533 | *linker_exe* | linker used to create binary executables |
534 +--------------+------------------------------------------+
535 | *archiver* | static library creator |
536 +--------------+------------------------------------------+
538 On platforms with a command-line (Unix, DOS/Windows), each of these is a string
539 that will be split into executable name and (optional) list of arguments.
540 (Splitting the string is done similarly to how Unix shells operate: words are
541 delimited by spaces, but quotes and backslashes can override this. See
542 :func:`distutils.util.split_quoted`.)
544 The following methods invoke stages in the build process.
547 .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
549 Compile one or more source files. Generates object files (e.g. transforms a
550 :file:`.c` file to a :file:`.o` file.)
552 *sources* must be a list of filenames, most likely C/C++ files, but in reality
553 anything that can be handled by a particular compiler and compiler class (eg.
554 :class:`MSVCCompiler` can handle resource files in *sources*). Return a list of
555 object filenames, one per source filename in *sources*. Depending on the
556 implementation, not all source files will necessarily be compiled, but all
557 corresponding object filenames will be returned.
559 If *output_dir* is given, object files will be put under it, while retaining
560 their original path component. That is, :file:`foo/bar.c` normally compiles to
561 :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
562 it would compile to :file:`build/foo/bar.o`.
564 *macros*, if given, must be a list of macro definitions. A macro definition is
565 either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
566 a macro; if the value is ``None``, the macro is defined without an explicit
567 value. The 1-tuple case undefines a macro. Later
568 definitions/redefinitions/undefinitions take precedence.
570 *include_dirs*, if given, must be a list of strings, the directories to add to
571 the default include file search path for this compilation only.
573 *debug* is a boolean; if true, the compiler will be instructed to output debug
574 symbols in (or alongside) the object file(s).
576 *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
577 that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
578 likely lists of strings: extra command-line arguments to prepend/append to the
579 compiler command line. On other platforms, consult the implementation class
580 documentation. In any event, they are intended as an escape hatch for those
581 occasions when the abstract compiler framework doesn't cut the mustard.
583 *depends*, if given, is a list of filenames that all targets depend on. If a
584 source file is older than any file in depends, then the source file will be
585 recompiled. This supports dependency tracking, but only at a coarse
586 granularity.
588 Raises :exc:`CompileError` on failure.
591 .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
593 Link a bunch of stuff together to create a static library file. The "bunch of
594 stuff" consists of the list of object files supplied as *objects*, the extra
595 object files supplied to :meth:`add_link_object` and/or
596 :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
597 :meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
599 *output_libname* should be a library name, not a filename; the filename will be
600 inferred from the library name. *output_dir* is the directory where the library
601 file will be put. XXX defaults to what?
603 *debug* is a boolean; if true, debugging information will be included in the
604 library (note that on most platforms, it is the compile step where this matters:
605 the *debug* flag is included here just for consistency).
607 *target_lang* is the target language for which the given objects are being
608 compiled. This allows specific linkage time treatment of certain languages.
610 Raises :exc:`LibError` on failure.
613 .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
615 Link a bunch of stuff together to create an executable or shared library file.
617 The "bunch of stuff" consists of the list of object files supplied as *objects*.
618 *output_filename* should be a filename. If *output_dir* is supplied,
619 *output_filename* is relative to it (i.e. *output_filename* can provide
620 directory components if needed).
622 *libraries* is a list of libraries to link against. These are library names,
623 not filenames, since they're translated into filenames in a platform-specific
624 way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
625 DOS/Windows). However, they can include a directory component, which means the
626 linker will look in that specific directory rather than searching all the normal
627 locations.
629 *library_dirs*, if supplied, should be a list of directories to search for
630 libraries that were specified as bare library names (ie. no directory
631 component). These are on top of the system default and those supplied to
632 :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs*
633 is a list of directories that will be embedded into the shared library and used
634 to search for other shared libraries that \*it\* depends on at run-time. (This
635 may only be relevant on Unix.)
637 *export_symbols* is a list of symbols that the shared library will export.
638 (This appears to be relevant only on Windows.)
640 *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the
641 slight distinction that it actually matters on most platforms (as opposed to
642 :meth:`create_static_lib`, which includes a *debug* flag mostly for form's
643 sake).
645 *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of
646 course that they supply command-line arguments for the particular linker being
647 used).
649 *target_lang* is the target language for which the given objects are being
650 compiled. This allows specific linkage time treatment of certain languages.
652 Raises :exc:`LinkError` on failure.
655 .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])
657 Link an executable. *output_progname* is the name of the file executable, while
658 *objects* are a list of object filenames to link in. Other arguments are as for
659 the :meth:`link` method.
662 .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
664 Link a shared library. *output_libname* is the name of the output library,
665 while *objects* is a list of object filenames to link in. Other arguments are
666 as for the :meth:`link` method.
669 .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
671 Link a shared object. *output_filename* is the name of the shared object that
672 will be created, while *objects* is a list of object filenames to link in.
673 Other arguments are as for the :meth:`link` method.
676 .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
678 Preprocess a single C/C++ source file, named in *source*. Output will be written
679 to file named *output_file*, or *stdout* if *output_file* not supplied.
680 *macros* is a list of macro definitions as for :meth:`compile`, which will
681 augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
682 *include_dirs* is a list of directory names that will be added to the default
683 list, in the same way as :meth:`add_include_dir`.
685 Raises :exc:`PreprocessError` on failure.
687 The following utility methods are defined by the :class:`CCompiler` class, for
688 use by the various concrete subclasses.
691 .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
693 Returns the filename of the executable for the given *basename*. Typically for
694 non-Windows platforms this is the same as the basename, while Windows will get
695 a :file:`.exe` added.
698 .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
700 Returns the filename for the given library name on the current platform. On Unix
701 a library with *lib_type* of ``'static'`` will typically be of the form
702 :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form
703 :file:`liblibname.so`.
706 .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
708 Returns the name of the object files for the given source files.
709 *source_filenames* should be a list of filenames.
712 .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
714 Returns the name of a shared object file for the given file name *basename*.
717 .. method:: CCompiler.execute(func, args[, msg=None, level=1])
719 Invokes :func:`distutils.util.execute` This method invokes a Python function
720 *func* with the given arguments *args*, after logging and taking into account
721 the *dry_run* flag. XXX see also.
724 .. method:: CCompiler.spawn(cmd)
726 Invokes :func:`distutils.util.spawn`. This invokes an external process to run
727 the given command. XXX see also.
730 .. method:: CCompiler.mkpath(name[, mode=511])
732 Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any
733 missing ancestor directories. XXX see also.
736 .. method:: CCompiler.move_file(src, dst)
738 Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. XXX see
739 also.
742 .. method:: CCompiler.announce(msg[, level=1])
744 Write a message using :func:`distutils.log.debug`. XXX see also.
747 .. method:: CCompiler.warn(msg)
749 Write a warning message *msg* to standard error.
752 .. method:: CCompiler.debug_print(msg)
754 If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to
755 standard output, otherwise do nothing.
757 .. % \subsection{Compiler-specific modules}
758 .. %
759 .. % The following modules implement concrete subclasses of the abstract
760 .. % \class{CCompiler} class. They should not be instantiated directly, but should
761 .. % be created using \function{distutils.ccompiler.new_compiler()} factory
762 .. % function.
765 :mod:`distutils.unixccompiler` --- Unix C Compiler
766 ==================================================
768 .. module:: distutils.unixccompiler
769 :synopsis: UNIX C Compiler
772 This module provides the :class:`UnixCCompiler` class, a subclass of
773 :class:`CCompiler` that handles the typical Unix-style command-line C compiler:
775 * macros defined with :option:`-Dname[=value]`
777 * macros undefined with :option:`-Uname`
779 * include search directories specified with :option:`-Idir`
781 * libraries specified with :option:`-llib`
783 * library search directories specified with :option:`-Ldir`
785 * compile handled by :program:`cc` (or similar) executable with :option:`-c`
786 option: compiles :file:`.c` to :file:`.o`
788 * link static library handled by :program:`ar` command (possibly with
789 :program:`ranlib`)
791 * link shared library handled by :program:`cc` :option:`-shared`
794 :mod:`distutils.msvccompiler` --- Microsoft Compiler
795 ====================================================
797 .. module:: distutils.msvccompiler
798 :synopsis: Microsoft Compiler
801 This module provides :class:`MSVCCompiler`, an implementation of the abstract
802 :class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
803 modules need to be compiled with the same compiler that was used to compile
804 Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
805 2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium
806 binaries are created using the Platform SDK.
808 :class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
809 its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
810 and *MSSdk* must be both set. *MSSdk* indicates that the current environment has
811 been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables
812 had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates
813 that the distutils user has made an explicit choice to override the compiler
814 selection by :class:`MSVCCompiler`.
817 :mod:`distutils.bcppcompiler` --- Borland Compiler
818 ==================================================
820 .. module:: distutils.bcppcompiler
823 This module provides :class:`BorlandCCompiler`, an subclass of the abstract
824 :class:`CCompiler` class for the Borland C++ compiler.
827 :mod:`distutils.cygwincompiler` --- Cygwin Compiler
828 ===================================================
830 .. module:: distutils.cygwinccompiler
833 This module provides the :class:`CygwinCCompiler` class, a subclass of
834 :class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to
835 Windows. It also contains the Mingw32CCompiler class which handles the mingw32
836 port of GCC (same as cygwin in no-cygwin mode).
839 :mod:`distutils.emxccompiler` --- OS/2 EMX Compiler
840 ===================================================
842 .. module:: distutils.emxccompiler
843 :synopsis: OS/2 EMX Compiler support
846 This module provides the EMXCCompiler class, a subclass of
847 :class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.
850 :mod:`distutils.archive_util` --- Archiving utilities
851 ======================================================
853 .. module:: distutils.archive_util
854 :synopsis: Utility functions for creating archive files (tarballs, zip files, ...)
857 This module provides a few functions for creating archive files, such as
858 tarballs or zipfiles.
861 .. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])
863 Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of
864 the file to create, minus any format-specific extension; *format* is the
865 archive format: one of ``zip``, ``tar``, ``ztar``, or ``gztar``. *root_dir* is
866 a directory that will be the root directory of the archive; ie. we typically
867 ``chdir`` into *root_dir* before creating the archive. *base_dir* is the
868 directory where we start archiving from; ie. *base_dir* will be the common
869 prefix of all files and directories in the archive. *root_dir* and *base_dir*
870 both default to the current directory. Returns the name of the archive file.
872 .. XXX This should be changed to support bz2 files.
875 .. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
877 'Create an (optional compressed) archive as a tar file from all files in and
878 under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``,
879 ``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named
880 by *compress* must be on the default program search path, so this is probably
881 Unix-specific. The output tar file will be named :file:`base_dir.tar`,
882 possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`
883 or :file:`.Z`). Return the output filename.
885 .. XXX This should be replaced with calls to the :mod:`tarfile` module.
888 .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
890 Create a zip file from all files in and under *base_dir*. The output zip file
891 will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python
892 module (if available) or the InfoZIP :file:`zip` utility (if installed and
893 found on the default search path). If neither tool is available, raises
894 :exc:`DistutilsExecError`. Returns the name of the output zip file.
897 :mod:`distutils.dep_util` --- Dependency checking
898 =================================================
900 .. module:: distutils.dep_util
901 :synopsis: Utility functions for simple dependency checking
904 This module provides functions for performing simple, timestamp-based
905 dependency of files and groups of files; also, functions based entirely on such
906 timestamp dependency analysis.
909 .. function:: newer(source, target)
911 Return true if *source* exists and is more recently modified than *target*, or
912 if *source* exists and *target* doesn't. Return false if both exist and *target*
913 is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if
914 *source* does not exist.
917 .. function:: newer_pairwise(sources, targets)
919 Walk two filename lists in parallel, testing if each source is newer than its
920 corresponding target. Return a pair of lists (*sources*, *targets*) where
921 source is newer than target, according to the semantics of :func:`newer`
923 .. % % equivalent to a listcomp...
926 .. function:: newer_group(sources, target[, missing='error'])
928 Return true if *target* is out-of-date with respect to any file listed in
929 *sources* In other words, if *target* exists and is newer than every file in
930 *sources*, return false; otherwise return true. *missing* controls what we do
931 when a source file is missing; the default (``'error'``) is to blow up with an
932 :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently
933 drop any missing source files; if it is ``'newer'``, any missing source files
934 make us assume that *target* is out-of-date (this is handy in "dry-run" mode:
935 it'll make you pretend to carry out commands that wouldn't work because inputs
936 are missing, but that doesn't matter because you're not actually going to run
937 the commands).
940 :mod:`distutils.dir_util` --- Directory tree operations
941 =======================================================
943 .. module:: distutils.dir_util
944 :synopsis: Utility functions for operating on directories and directory trees
947 This module provides functions for operating on directories and trees of
948 directories.
951 .. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0])
953 Create a directory and any missing ancestor directories. If the directory
954 already exists (or if *name* is the empty string, which means the current
955 directory, which of course exists), then do nothing. Raise
956 :exc:`DistutilsFileError` if unable to create some directory along the way (eg.
957 some sub-path exists, but is a file rather than a directory). If *verbose* is
958 true, print a one-line summary of each mkdir to stdout. Return the list of
959 directories actually created.
962 .. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0])
964 Create all the empty directories under *base_dir* needed to put *files* there.
965 *base_dir* is just the a name of a directory which doesn't necessarily exist
966 yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
967 *base_dir* + the directory portion of every file in *files* will be created if
968 it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for
969 :func:`mkpath`.
972 .. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])
974 Copy an entire directory tree *src* to a new location *dst*. Both *src* and
975 *dst* must be directory names. If *src* is not a directory, raise
976 :exc:`DistutilsFileError`. If *dst* does not exist, it is created with
977 :func:`mkpath`. The end result of the copy is that every file in *src* is
978 copied to *dst*, and directories under *src* are recursively copied to *dst*.
979 Return the list of files that were copied or might have been copied, using their
980 output name. The return value is unaffected by *update* or *dry_run*: it is
981 simply the list of all files under *src*, with the names changed to be under
982 *dst*.
984 *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in
985 :mod:`distutils.file_util`; note that they only apply to regular files, not to
986 directories. If *preserve_symlinks* is true, symlinks will be copied as
987 symlinks (on platforms that support them!); otherwise (the default), the
988 destination of the symlink will be copied. *update* and *verbose* are the same
989 as for :func:`copy_file`.
992 .. function:: remove_tree(directory[, verbose=0, dry_run=0])
994 Recursively remove *directory* and all files and directories underneath it. Any
995 errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
996 true).
998 **\*\*** Some of this could be replaced with the shutil module? **\*\***
1001 :mod:`distutils.file_util` --- Single file operations
1002 =====================================================
1004 .. module:: distutils.file_util
1005 :synopsis: Utility functions for operating on single files
1008 This module contains some utility functions for operating on individual files.
1011 .. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])
1013 Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
1014 with the same name; otherwise, it must be a filename. (If the file exists, it
1015 will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
1016 file's mode (type and permission bits, or whatever is analogous on the
1017 current platform) is copied. If *preserve_times* is true (the default), the
1018 last-modified and last-access times are copied as well. If *update* is true,
1019 *src* will only be copied if *dst* does not exist, or if *dst* does exist but
1020 is older than *src*.
1022 *link* allows you to make hard links (using :func:`os.link`) or symbolic links
1023 (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
1024 ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
1025 on systems that don't support it: :func:`copy_file` doesn't check if hard or
1026 symbolic linking is available. It uses :func:`_copy_file_contents` to copy file
1027 contents.
1029 Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the
1030 output file, and *copied* is true if the file was copied (or would have been
1031 copied, if *dry_run* true).
1033 .. % XXX if the destination file already exists, we clobber it if
1034 .. % copying, but blow up if linking. Hmmm. And I don't know what
1035 .. % macostools.copyfile() does. Should definitely be consistent, and
1036 .. % should probably blow up if destination exists and we would be
1037 .. % changing it (ie. it's not already a hard/soft link to src OR
1038 .. % (not update) and (src newer than dst)).
1041 .. function:: move_file(src, dst[, verbose, dry_run])
1043 Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
1044 it with the same name; otherwise, *src* is just renamed to *dst*. Returns the
1045 new full name of the file.
1047 .. warning::
1049 Handles cross-device moves on Unix using :func:`copy_file`. What about
1050 other systems?
1053 .. function:: write_file(filename, contents)
1055 Create a file called *filename* and write *contents* (a sequence of strings
1056 without line terminators) to it.
1059 :mod:`distutils.util` --- Miscellaneous other utility functions
1060 ===============================================================
1062 .. module:: distutils.util
1063 :synopsis: Miscellaneous other utility functions
1066 This module contains other assorted bits and pieces that don't fit into any
1067 other utility module.
1070 .. function:: get_platform()
1072 Return a string that identifies the current platform. This is used mainly to
1073 distinguish platform-specific build directories and platform-specific built
1074 distributions. Typically includes the OS name and version and the architecture
1075 (as supplied by 'os.uname()'), although the exact information included depends
1076 on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only
1077 runs on SGI hardware), but for Linux the kernel version isn't particularly
1078 important.
1080 Examples of returned values:
1082 * ``linux-i586``
1083 * ``linux-alpha``
1084 * ``solaris-2.6-sun4u``
1085 * ``irix-5.3``
1086 * ``irix64-6.2``
1088 For non-POSIX platforms, currently just returns ``sys.platform``.
1090 For Mac OS X systems the OS version reflects the minimal version on which
1091 binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
1092 during the build of Python), not the OS version of the current system.
1094 For universal binary builds on Mac OS X the architecture value reflects
1095 the univeral binary status instead of the architecture of the current
1096 processor. For 32-bit universal binaries the architecture is ``fat``,
1097 for 64-bit universal binaries the architecture is ``fat64``, and
1098 for 4-way universal binaries the architecture is ``universal``. Starting
1099 from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for
1100 a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for
1101 a univeral build with the i386 and x86_64 architectures
1103 Examples of returned values on Mac OS X:
1105 * ``macosx-10.3-ppc``
1107 * ``macosx-10.3-fat``
1109 * ``macosx-10.5-universal``
1111 * ``macosx-10.6-intel``
1113 .. % XXX isn't this also provided by some other non-distutils module?
1116 .. function:: convert_path(pathname)
1118 Return 'pathname' as a name that will work on the native filesystem, i.e. split
1119 it on '/' and put it back together again using the current directory separator.
1120 Needed because filenames in the setup script are always supplied in Unix style,
1121 and have to be converted to the local convention before we can actually use them
1122 in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if
1123 *pathname* either starts or ends with a slash.
1126 .. function:: change_root(new_root, pathname)
1128 Return *pathname* with *new_root* prepended. If *pathname* is relative, this is
1129 equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making
1130 *pathname* relative and then joining the two, which is tricky on DOS/Windows.
1133 .. function:: check_environ()
1135 Ensure that 'os.environ' has all the environment variables we guarantee that
1136 users can use in config files, command-line options, etc. Currently this
1137 includes:
1139 * :envvar:`HOME` - user's home directory (Unix only)
1140 * :envvar:`PLAT` - description of the current platform, including hardware and
1141 OS (see :func:`get_platform`)
1144 .. function:: subst_vars(s, local_vars)
1146 Perform shell/Perl-style variable substitution on *s*. Every occurrence of
1147 ``$`` followed by a name is considered a variable, and variable is substituted
1148 by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
1149 not in *local_vars*. *os.environ* is first checked/augmented to guarantee that
1150 it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError`
1151 for any variables not found in either *local_vars* or ``os.environ``.
1153 Note that this is not a fully-fledged string interpolation function. A valid
1154 ``$variable`` can consist only of upper and lower case letters, numbers and an
1155 underscore. No { } or ( ) style quoting is available.
1158 .. function:: grok_environment_error(exc[, prefix='error: '])
1160 Generate a useful error message from an :exc:`EnvironmentError` (:exc:`IOError`
1161 or :exc:`OSError`) exception object. Handles Python 1.5.1 and later styles,
1162 and does what it can to deal with exception objects that don't have a filename
1163 (which happens when the error is due to a two-file operation, such as
1164 :func:`rename` or :func:`link`). Returns the error message as a string
1165 prefixed with *prefix*.
1168 .. function:: split_quoted(s)
1170 Split a string up according to Unix shell-like rules for quotes and backslashes.
1171 In short: words are delimited by spaces, as long as those spaces are not escaped
1172 by a backslash, or inside a quoted string. Single and double quotes are
1173 equivalent, and the quote characters can be backslash-escaped. The backslash is
1174 stripped from any two-character escape sequence, leaving only the escaped
1175 character. The quote characters are stripped from any quoted string. Returns a
1176 list of words.
1178 .. % Should probably be moved into the standard library.
1181 .. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
1183 Perform some action that affects the outside world (for instance, writing to the
1184 filesystem). Such actions are special because they are disabled by the
1185 *dry_run* flag. This method takes care of all that bureaucracy for you; all
1186 you have to do is supply the function to call and an argument tuple for it (to
1187 embody the "external action" being performed), and an optional message to print.
1190 .. function:: strtobool(val)
1192 Convert a string representation of truth to true (1) or false (0).
1194 True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values
1195 are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises
1196 :exc:`ValueError` if *val* is anything else.
1199 .. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
1201 Byte-compile a collection of Python source files to either :file:`.pyc` or
1202 :file:`.pyo` files in the same directory. *py_files* is a list of files to
1203 compile; any files that don't end in :file:`.py` are silently skipped.
1204 *optimize* must be one of the following:
1206 * ``0`` - don't optimize (generate :file:`.pyc`)
1207 * ``1`` - normal optimization (like ``python -O``)
1208 * ``2`` - extra optimization (like ``python -OO``)
1210 If *force* is true, all files are recompiled regardless of timestamps.
1212 The source filename encoded in each :term:`bytecode` file defaults to the filenames
1213 listed in *py_files*; you can modify these with *prefix* and *basedir*.
1214 *prefix* is a string that will be stripped off of each source filename, and
1215 *base_dir* is a directory name that will be prepended (after *prefix* is
1216 stripped). You can supply either or both (or neither) of *prefix* and
1217 *base_dir*, as you wish.
1219 If *dry_run* is true, doesn't actually do anything that would affect the
1220 filesystem.
1222 Byte-compilation is either done directly in this interpreter process with the
1223 standard :mod:`py_compile` module, or indirectly by writing a temporary script
1224 and executing it. Normally, you should let :func:`byte_compile` figure out to
1225 use direct compilation or not (see the source for details). The *direct* flag
1226 is used by the script generated in indirect mode; unless you know what you're
1227 doing, leave it set to ``None``.
1230 .. function:: rfc822_escape(header)
1232 Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
1233 ensuring there are 8 spaces space after each newline. Note that it does no other
1234 modification of the string.
1236 .. % this _can_ be replaced
1238 .. % \subsection{Distutils objects}
1241 :mod:`distutils.dist` --- The Distribution class
1242 ================================================
1244 .. module:: distutils.dist
1245 :synopsis: Provides the Distribution class, which represents the module distribution being
1246 built/installed/distributed
1249 This module provides the :class:`Distribution` class, which represents the
1250 module distribution being built/installed/distributed.
1253 :mod:`distutils.extension` --- The Extension class
1254 ==================================================
1256 .. module:: distutils.extension
1257 :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup
1258 scripts
1261 This module provides the :class:`Extension` class, used to describe C/C++
1262 extension modules in setup scripts.
1264 .. % \subsection{Ungrouped modules}
1265 .. % The following haven't been moved into a more appropriate section yet.
1268 :mod:`distutils.debug` --- Distutils debug mode
1269 ===============================================
1271 .. module:: distutils.debug
1272 :synopsis: Provides the debug flag for distutils
1275 This module provides the DEBUG flag.
1278 :mod:`distutils.errors` --- Distutils exceptions
1279 ================================================
1281 .. module:: distutils.errors
1282 :synopsis: Provides standard distutils exceptions
1285 Provides exceptions used by the Distutils modules. Note that Distutils modules
1286 may raise standard exceptions; in particular, SystemExit is usually raised for
1287 errors that are obviously the end-user's fault (eg. bad command-line arguments).
1289 This module is safe to use in ``from ... import *`` mode; it only exports
1290 symbols whose names start with ``Distutils`` and end with ``Error``.
1293 :mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module
1294 ===========================================================================
1296 .. module:: distutils.fancy_getopt
1297 :synopsis: Additional getopt functionality
1300 This module provides a wrapper around the standard :mod:`getopt` module that
1301 provides the following additional features:
1303 * short and long options are tied together
1305 * options have help strings, so :func:`fancy_getopt` could potentially create a
1306 complete usage summary
1308 * options set attributes of a passed-in object
1310 * boolean options can have "negative aliases" --- eg. if :option:`--quiet` is
1311 the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
1312 command line sets *verbose* to false.
1314 **\*\*** Should be replaced with :mod:`optik` (which is also now known as
1315 :mod:`optparse` in Python 2.3 and later). **\*\***
1318 .. function:: fancy_getopt(options, negative_opt, object, args)
1320 Wrapper function. *options* is a list of ``(long_option, short_option,
1321 help_string)`` 3-tuples as described in the constructor for
1322 :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
1323 to option names, both the key and value should be in the *options* list.
1324 *object* is an object which will be used to store values (see the :meth:`getopt`
1325 method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
1326 ``sys.argv[1:]`` if you pass ``None`` as *args*.
1329 .. function:: wrap_text(text, width)
1331 Wraps *text* to less than *width* wide.
1333 .. XXX Should be replaced with :mod:`textwrap` (which is available in Python
1334 2.3 and later).
1337 .. class:: FancyGetopt([option_table=None])
1339 The option_table is a list of 3-tuples: ``(long_option, short_option,
1340 help_string)``
1342 If an option takes an argument, its *long_option* should have ``'='`` appended;
1343 *short_option* should just be a single character, no ``':'`` in any case.
1344 *short_option* should be ``None`` if a *long_option* doesn't have a
1345 corresponding *short_option*. All option tuples must have long options.
1347 The :class:`FancyGetopt` class provides the following methods:
1350 .. method:: FancyGetopt.getopt([args=None, object=None])
1352 Parse command-line options in args. Store as attributes on *object*.
1354 If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is
1355 ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
1356 option values there, and returns a tuple ``(args, object)``. If *object* is
1357 supplied, it is modified in place and :func:`getopt` just returns *args*; in
1358 both cases, the returned *args* is a modified copy of the passed-in *args* list,
1359 which is left untouched.
1361 .. % and args returned are?
1364 .. method:: FancyGetopt.get_option_order()
1366 Returns the list of ``(option, value)`` tuples processed by the previous run of
1367 :meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
1368 yet.
1371 .. method:: FancyGetopt.generate_help([header=None])
1373 Generate help text (a list of strings, one per suggested line of output) from
1374 the option table for this :class:`FancyGetopt` object.
1376 If supplied, prints the supplied *header* at the top of the help.
1379 :mod:`distutils.filelist` --- The FileList class
1380 ================================================
1382 .. module:: distutils.filelist
1383 :synopsis: The FileList class, used for poking about the file system and
1384 building lists of files.
1387 This module provides the :class:`FileList` class, used for poking about the
1388 filesystem and building lists of files.
1391 :mod:`distutils.log` --- Simple PEP 282-style logging
1392 =====================================================
1394 .. module:: distutils.log
1395 :synopsis: A simple logging mechanism, 282-style
1398 .. XXX Should be replaced with standard :mod:`logging` module.
1402 :mod:`distutils.spawn` --- Spawn a sub-process
1403 ==============================================
1405 .. module:: distutils.spawn
1406 :synopsis: Provides the spawn() function
1409 This module provides the :func:`spawn` function, a front-end to various
1410 platform-specific functions for launching another program in a sub-process.
1411 Also provides :func:`find_executable` to search the path for a given executable
1412 name.
1415 :mod:`distutils.sysconfig` --- System configuration information
1416 ===============================================================
1418 .. module:: distutils.sysconfig
1419 :synopsis: Low-level access to configuration information of the Python interpreter.
1420 .. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1421 .. moduleauthor:: Greg Ward <gward@python.net>
1422 .. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
1425 The :mod:`distutils.sysconfig` module provides access to Python's low-level
1426 configuration information. The specific configuration variables available
1427 depend heavily on the platform and configuration. The specific variables depend
1428 on the build process for the specific version of Python being run; the variables
1429 are those found in the :file:`Makefile` and configuration header that are
1430 installed with Python on Unix systems. The configuration header is called
1431 :file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`
1432 for earlier versions of Python.
1434 Some additional functions are provided which perform some useful manipulations
1435 for other parts of the :mod:`distutils` package.
1438 .. data:: PREFIX
1440 The result of ``os.path.normpath(sys.prefix)``.
1443 .. data:: EXEC_PREFIX
1445 The result of ``os.path.normpath(sys.exec_prefix)``.
1448 .. function:: get_config_var(name)
1450 Return the value of a single variable. This is equivalent to
1451 ``get_config_vars().get(name)``.
1454 .. function:: get_config_vars(...)
1456 Return a set of variable definitions. If there are no arguments, this returns a
1457 dictionary mapping names of configuration variables to values. If arguments are
1458 provided, they should be strings, and the return value will be a sequence giving
1459 the associated values. If a given name does not have a corresponding value,
1460 ``None`` will be included for that variable.
1463 .. function:: get_config_h_filename()
1465 Return the full path name of the configuration header. For Unix, this will be
1466 the header generated by the :program:`configure` script; for other platforms the
1467 header will have been supplied directly by the Python source distribution. The
1468 file is a platform-specific text file.
1471 .. function:: get_makefile_filename()
1473 Return the full path name of the :file:`Makefile` used to build Python. For
1474 Unix, this will be a file generated by the :program:`configure` script; the
1475 meaning for other platforms will vary. The file is a platform-specific text
1476 file, if it exists. This function is only useful on POSIX platforms.
1479 .. function:: get_python_inc([plat_specific[, prefix]])
1481 Return the directory for either the general or platform-dependent C include
1482 files. If *plat_specific* is true, the platform-dependent include directory is
1483 returned; if false or omitted, the platform-independent directory is returned.
1484 If *prefix* is given, it is used as either the prefix instead of
1485 :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1486 *plat_specific* is true.
1489 .. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])
1491 Return the directory for either the general or platform-dependent library
1492 installation. If *plat_specific* is true, the platform-dependent include
1493 directory is returned; if false or omitted, the platform-independent directory
1494 is returned. If *prefix* is given, it is used as either the prefix instead of
1495 :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
1496 *plat_specific* is true. If *standard_lib* is true, the directory for the
1497 standard library is returned rather than the directory for the installation of
1498 third-party extensions.
1500 The following function is only intended for use within the :mod:`distutils`
1501 package.
1504 .. function:: customize_compiler(compiler)
1506 Do any platform-specific customization of a
1507 :class:`distutils.ccompiler.CCompiler` instance.
1509 This function is only needed on Unix at this time, but should be called
1510 consistently to support forward-compatibility. It inserts the information that
1511 varies across Unix flavors and is stored in Python's :file:`Makefile`. This
1512 information includes the selected compiler, compiler and linker options, and the
1513 extension used by the linker for shared objects.
1515 This function is even more special-purpose, and should only be used from
1516 Python's own build procedures.
1519 .. function:: set_python_build()
1521 Inform the :mod:`distutils.sysconfig` module that it is being used as part of
1522 the build process for Python. This changes a lot of relative locations for
1523 files, allowing them to be located in the build area rather than in an installed
1524 Python.
1527 :mod:`distutils.text_file` --- The TextFile class
1528 =================================================
1530 .. module:: distutils.text_file
1531 :synopsis: provides the TextFile class, a simple interface to text files
1534 This module provides the :class:`TextFile` class, which gives an interface to
1535 text files that (optionally) takes care of stripping comments, ignoring blank
1536 lines, and joining lines with backslashes.
1539 .. class:: TextFile([filename=None, file=None, **options])
1541 This class provides a file-like object that takes care of all the things you
1542 commonly want to do when processing a text file that has some line-by-line
1543 syntax: strip comments (as long as ``#`` is your comment character), skip blank
1544 lines, join adjacent lines by escaping the newline (ie. backslash at end of
1545 line), strip leading and/or trailing whitespace. All of these are optional and
1546 independently controllable.
1548 The class provides a :meth:`warn` method so you can generate warning messages
1549 that report physical line number, even if the logical line in question spans
1550 multiple physical lines. Also provides :meth:`unreadline` for implementing
1551 line-at-a-time lookahead.
1553 :class:`TextFile` instances are create with either *filename*, *file*, or both.
1554 :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a
1555 string, and *file* a file object (or something that provides :meth:`readline`
1556 and :meth:`close` methods). It is recommended that you supply at least
1557 *filename*, so that :class:`TextFile` can include it in warning messages. If
1558 *file* is not supplied, :class:`TextFile` creates its own using the
1559 :func:`open` built-in function.
1561 The options are all boolean, and affect the values returned by :meth:`readline`
1563 +------------------+--------------------------------+---------+
1564 | option name | description | default |
1565 +==================+================================+=========+
1566 | *strip_comments* | strip from ``'#'`` to end-of- | true |
1567 | | line, as well as any | |
1568 | | whitespace leading up to the | |
1569 | | ``'#'``\ ---unless it is | |
1570 | | escaped by a backslash | |
1571 +------------------+--------------------------------+---------+
1572 | *lstrip_ws* | strip leading whitespace from | false |
1573 | | each line before returning it | |
1574 +------------------+--------------------------------+---------+
1575 | *rstrip_ws* | strip trailing whitespace | true |
1576 | | (including line terminator!) | |
1577 | | from each line before | |
1578 | | returning it. | |
1579 +------------------+--------------------------------+---------+
1580 | *skip_blanks* | skip lines that are empty | true |
1581 | | \*after\* stripping comments | |
1582 | | and whitespace. (If both | |
1583 | | lstrip_ws and rstrip_ws are | |
1584 | | false, then some lines may | |
1585 | | consist of solely whitespace: | |
1586 | | these will \*not\* be skipped, | |
1587 | | even if *skip_blanks* is | |
1588 | | true.) | |
1589 +------------------+--------------------------------+---------+
1590 | *join_lines* | if a backslash is the last | false |
1591 | | non-newline character on a | |
1592 | | line after stripping comments | |
1593 | | and whitespace, join the | |
1594 | | following line to it to form | |
1595 | | one logical line; if N | |
1596 | | consecutive lines end with a | |
1597 | | backslash, then N+1 physical | |
1598 | | lines will be joined to form | |
1599 | | one logical line. | |
1600 +------------------+--------------------------------+---------+
1601 | *collapse_join* | strip leading whitespace from | false |
1602 | | lines that are joined to their | |
1603 | | predecessor; only matters if | |
1604 | | ``(join_lines and not | |
1605 | | lstrip_ws)`` | |
1606 +------------------+--------------------------------+---------+
1608 Note that since *rstrip_ws* can strip the trailing newline, the semantics of
1609 :meth:`readline` must differ from those of the built-in file object's
1610 :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for
1611 end-of-file: an empty string might just be a blank line (or an all-whitespace
1612 line), if *rstrip_ws* is true but *skip_blanks* is not.
1615 .. method:: TextFile.open(filename)
1617 Open a new file *filename*. This overrides any *file* or *filename*
1618 constructor arguments.
1621 .. method:: TextFile.close()
1623 Close the current file and forget everything we know about it (including the
1624 filename and the current line number).
1627 .. method:: TextFile.warn(msg[,line=None])
1629 Print (to stderr) a warning message tied to the current logical line in the
1630 current file. If the current logical line in the file spans multiple physical
1631 lines, the warning refers to the whole range, such as ``"lines 3-5"``. If
1632 *line* is supplied, it overrides the current line number; it may be a list or
1633 tuple to indicate a range of physical lines, or an integer for a single
1634 physical line.
1637 .. method:: TextFile.readline()
1639 Read and return a single logical line from the current file (or from an internal
1640 buffer if lines have previously been "unread" with :meth:`unreadline`). If the
1641 *join_lines* option is true, this may involve reading multiple physical lines
1642 concatenated into a single string. Updates the current line number, so calling
1643 :meth:`warn` after :meth:`readline` emits a warning about the physical line(s)
1644 just read. Returns ``None`` on end-of-file, since the empty string can occur
1645 if *rstrip_ws* is true but *strip_blanks* is not.
1648 .. method:: TextFile.readlines()
1650 Read and return the list of all logical lines remaining in the current file.
1651 This updates the current line number to the last line of the file.
1654 .. method:: TextFile.unreadline(line)
1656 Push *line* (a string) onto an internal buffer that will be checked by future
1657 :meth:`readline` calls. Handy for implementing a parser with line-at-a-time
1658 lookahead. Note that lines that are "unread" with :meth:`unreadline` are not
1659 subsequently re-cleansed (whitespace stripped, or whatever) when read with
1660 :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call
1661 to :meth:`readline`, the lines will be returned most in most recent first order.
1664 :mod:`distutils.version` --- Version number classes
1665 ===================================================
1667 .. module:: distutils.version
1668 :synopsis: implements classes that represent module version numbers.
1671 .. % todo
1672 .. % \section{Distutils Commands}
1673 .. %
1674 .. % This part of Distutils implements the various Distutils commands, such
1675 .. % as \code{build}, \code{install} \&c. Each command is implemented as a
1676 .. % separate module, with the command name as the name of the module.
1679 :mod:`distutils.cmd` --- Abstract base class for Distutils commands
1680 ===================================================================
1682 .. module:: distutils.cmd
1683 :synopsis: This module provides the abstract base class Command. This class is subclassed
1684 by the modules in the distutils.command subpackage.
1687 This module supplies the abstract base class :class:`Command`.
1690 .. class:: Command(dist)
1692 Abstract base class for defining command classes, the "worker bees" of the
1693 Distutils. A useful analogy for command classes is to think of them as
1694 subroutines with local variables called *options*. The options are declared in
1695 :meth:`initialize_options` and defined (given their final values) in
1696 :meth:`finalize_options`, both of which must be defined by every command class.
1697 The distinction between the two is necessary because option values might come
1698 from the outside world (command line, config file, ...), and any options
1699 dependent on other options must be computed after these outside influences have
1700 been processed --- hence :meth:`finalize_options`. The body of the subroutine,
1701 where it does all its work based on the values of its options, is the
1702 :meth:`run` method, which must also be implemented by every command class.
1704 The class constructor takes a single argument *dist*, a :class:`Distribution`
1705 instance.
1708 :mod:`distutils.command` --- Individual Distutils commands
1709 ==========================================================
1711 .. module:: distutils.command
1712 :synopsis: This subpackage contains one module for each standard Distutils command.
1715 .. % \subsubsection{Individual Distutils commands}
1716 .. % todo
1719 :mod:`distutils.command.bdist` --- Build a binary installer
1720 ===========================================================
1722 .. module:: distutils.command.bdist
1723 :synopsis: Build a binary installer for a package
1726 .. % todo
1729 :mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
1730 =============================================================================
1732 .. module:: distutils.command.bdist_packager
1733 :synopsis: Abstract base class for packagers
1736 .. % todo
1739 :mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
1740 ================================================================
1742 .. module:: distutils.command.bdist_dumb
1743 :synopsis: Build a "dumb" installer - a simple archive of files
1746 .. % todo
1749 :mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
1750 =================================================================================
1752 .. module:: distutils.command.bdist_msi
1753 :synopsis: Build a binary distribution as a Windows MSI file
1755 .. class:: bdist_msi(Command)
1757 Builds a `Windows Installer`_ (.msi) binary package.
1759 .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
1761 In most cases, the ``bdist_msi`` installer is a better choice than the
1762 ``bdist_wininst`` installer, because it provides better support for
1763 Win64 platforms, allows administrators to perform non-interactive
1764 installations, and allows installation through group policies.
1767 :mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
1768 ===========================================================================================
1770 .. module:: distutils.command.bdist_rpm
1771 :synopsis: Build a binary distribution as a Redhat RPM and SRPM
1774 .. % todo
1777 :mod:`distutils.command.bdist_wininst` --- Build a Windows installer
1778 ====================================================================
1780 .. module:: distutils.command.bdist_wininst
1781 :synopsis: Build a Windows installer
1784 .. % todo
1787 :mod:`distutils.command.sdist` --- Build a source distribution
1788 ==============================================================
1790 .. module:: distutils.command.sdist
1791 :synopsis: Build a source distribution
1794 .. % todo
1797 :mod:`distutils.command.build` --- Build all files of a package
1798 ===============================================================
1800 .. module:: distutils.command.build
1801 :synopsis: Build all files of a package
1804 .. % todo
1807 :mod:`distutils.command.build_clib` --- Build any C libraries in a package
1808 ==========================================================================
1810 .. module:: distutils.command.build_clib
1811 :synopsis: Build any C libraries in a package
1814 .. % todo
1817 :mod:`distutils.command.build_ext` --- Build any extensions in a package
1818 ========================================================================
1820 .. module:: distutils.command.build_ext
1821 :synopsis: Build any extensions in a package
1824 .. % todo
1827 :mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
1828 ===========================================================================
1830 .. module:: distutils.command.build_py
1831 :synopsis: Build the .py/.pyc files of a package
1834 .. % todo
1837 :mod:`distutils.command.build_scripts` --- Build the scripts of a package
1838 =========================================================================
1840 .. module:: distutils.command.build_scripts
1841 :synopsis: Build the scripts of a package
1844 .. % todo
1847 :mod:`distutils.command.clean` --- Clean a package build area
1848 =============================================================
1850 .. module:: distutils.command.clean
1851 :synopsis: Clean a package build area
1854 .. % todo
1857 :mod:`distutils.command.config` --- Perform package configuration
1858 =================================================================
1860 .. module:: distutils.command.config
1861 :synopsis: Perform package configuration
1864 .. % todo
1867 :mod:`distutils.command.install` --- Install a package
1868 ======================================================
1870 .. module:: distutils.command.install
1871 :synopsis: Install a package
1874 .. % todo
1877 :mod:`distutils.command.install_data` --- Install data files from a package
1878 ===========================================================================
1880 .. module:: distutils.command.install_data
1881 :synopsis: Install data files from a package
1884 .. % todo
1887 :mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
1888 ======================================================================================
1890 .. module:: distutils.command.install_headers
1891 :synopsis: Install C/C++ header files from a package
1894 .. % todo
1897 :mod:`distutils.command.install_lib` --- Install library files from a package
1898 =============================================================================
1900 .. module:: distutils.command.install_lib
1901 :synopsis: Install library files from a package
1904 .. % todo
1907 :mod:`distutils.command.install_scripts` --- Install script files from a package
1908 ================================================================================
1910 .. module:: distutils.command.install_scripts
1911 :synopsis: Install script files from a package
1914 .. % todo
1917 :mod:`distutils.command.register` --- Register a module with the Python Package Index
1918 =====================================================================================
1920 .. module:: distutils.command.register
1921 :synopsis: Register a module with the Python Package Index
1924 The ``register`` command registers the package with the Python Package Index.
1925 This is described in more detail in :pep:`301`.
1927 .. % todo
1929 :mod:`distutils.command.check` --- Check the meta-data of a package
1930 ===================================================================
1932 .. module:: distutils.command.check
1933 :synopsis: Check the metadata of a package
1936 The ``check`` command performs some tests on the meta-data of a package.
1937 For example, it verifies that all required meta-data are provided as
1938 the arguments passed to the :func:`setup` function.
1940 .. % todo
1943 Creating a new Distutils command
1944 ================================
1946 This section outlines the steps to create a new Distutils command.
1948 A new command lives in a module in the :mod:`distutils.command` package. There
1949 is a sample template in that directory called :file:`command_template`. Copy
1950 this file to a new module with the same name as the new command you're
1951 implementing. This module should implement a class with the same name as the
1952 module (and the command). So, for instance, to create the command
1953 ``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
1954 :file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
1955 it so that it's implementing the class :class:`peel_banana`, a subclass of
1956 :class:`distutils.cmd.Command`.
1958 Subclasses of :class:`Command` must define the following methods.
1961 .. method:: Command.initialize_options()
1963 Set default values for all the options that this command supports. Note that
1964 these defaults may be overridden by other commands, by the setup script, by
1965 config files, or by the command-line. Thus, this is not the place to code
1966 dependencies between options; generally, :meth:`initialize_options`
1967 implementations are just a bunch of ``self.foo = None`` assignments.
1970 .. method:: Command.finalize_options()
1972 Set final values for all the options that this command supports. This is
1973 always called as late as possible, ie. after any option assignments from the
1974 command-line or from other commands have been done. Thus, this is the place
1975 to to code option dependencies: if *foo* depends on *bar*, then it is safe to
1976 set *foo* from *bar* as long as *foo* still has the same value it was
1977 assigned in :meth:`initialize_options`.
1980 .. method:: Command.run()
1982 A command's raison d'etre: carry out the action it exists to perform, controlled
1983 by the options initialized in :meth:`initialize_options`, customized by other
1984 commands, the setup script, the command-line, and config files, and finalized in
1985 :meth:`finalize_options`. All terminal output and filesystem interaction should
1986 be done by :meth:`run`.
1988 *sub_commands* formalizes the notion of a "family" of commands, eg. ``install``
1989 as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The
1990 parent of a family of commands defines *sub_commands* as a class attribute; it's
1991 a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string
1992 and *predicate* an unbound method, a string or None. *predicate* is a method of
1993 the parent command that determines whether the corresponding command is
1994 applicable in the current situation. (Eg. we ``install_headers`` is only
1995 applicable if we have any C header files to install.) If *predicate* is None,
1996 that command is always applicable.
1998 *sub_commands* is usually defined at the \*end\* of a class, because predicates
1999 can be unbound methods, so they must already have been defined. The canonical
2000 example is the :command:`install` command.