Blame - Doc/distutils/apiref.rst - platform/external/python/cpython3

2009-01-03 21:18:54 +0000

[diff] [blame]

758

.. %

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

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

.. % function.

:mod:`distutils.unixccompiler` --- Unix C Compiler

766

==================================================

767

768

.. module:: distutils.unixccompiler

769

:synopsis: UNIX C Compiler

770

771

772

This module provides the :class:`UnixCCompiler` class, a subclass of

773

:class:`CCompiler` that handles the typical Unix-style command-line C compiler:

774

775

* macros defined with :option:`-Dname[=value]`

776

777

* macros undefined with :option:`-Uname`

778

779

* include search directories specified with :option:`-Idir`

780

781

* libraries specified with :option:`-llib`

782

783

* library search directories specified with :option:`-Ldir`

784

785

* compile handled by :program:`cc` (or similar) executable with :option:`-c`

786

option: compiles :file:`.c` to :file:`.o`

787

788

* link static library handled by :program:`ar` command (possibly with

789

:program:`ranlib`)

790

791

* link shared library handled by :program:`cc` :option:`-shared`

792

793

794

:mod:`distutils.msvccompiler` --- Microsoft Compiler

795

====================================================

796

797

.. module:: distutils.msvccompiler

798

:synopsis: Microsoft Compiler

799

800

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.

807

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`.

815

816

817

:mod:`distutils.bcppcompiler` --- Borland Compiler

818

==================================================

819

820

.. module:: distutils.bcppcompiler

821

822

823

This module provides :class:`BorlandCCompiler`, an subclass of the abstract

824

:class:`CCompiler` class for the Borland C++ compiler.

825

826

827

:mod:`distutils.cygwincompiler` --- Cygwin Compiler

828

===================================================

829

830

.. module:: distutils.cygwinccompiler

831

832

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).

837

838

839

:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler

840

===================================================

841

842

.. module:: distutils.emxccompiler

843

:synopsis: OS/2 EMX Compiler support

844

845

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.

848

849

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

850

:mod:`distutils.archive_util` --- Archiving utilities

851

======================================================

852

853

.. module:: distutils.archive_util

854

:synopsis: Utility functions for creating archive files (tarballs, zip files, ...)

855

856

857

This module provides a few functions for creating archive files, such as

858

tarballs or zipfiles.

859

860

861

.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])

862

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.

871

Georg Brandl

2009-04-27 16:23:47 +0000

[diff] [blame]

872

.. XXX This should be changed to support bz2 files.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

873

874

875

.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])

876

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.

884

Georg Brandl

2009-04-27 16:23:47 +0000

[diff] [blame]

885

.. XXX This should be replaced with calls to the :mod:`tarfile` module.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

886

887

888

.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])

889

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.

895

896

897

:mod:`distutils.dep_util` --- Dependency checking

898

=================================================

899

900

.. module:: distutils.dep_util

901

:synopsis: Utility functions for simple dependency checking

902

903

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.

907

908

909

.. function:: newer(source, target)

910

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.

915

916

917

.. function:: newer_pairwise(sources, targets)

918

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`

922

923

.. % % equivalent to a listcomp...

924

925

926

.. function:: newer_group(sources, target[, missing='error'])

927

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

the commands).

:mod:`distutils.dir_util` --- Directory tree operations

941

=======================================================

942

943

.. module:: distutils.dir_util

944

:synopsis: Utility functions for operating on directories and directory trees

945

946

947

This module provides functions for operating on directories and trees of

directories.

Georg Brandl

2008-05-26 17:55:52 +0000

[diff] [blame]

951

.. function:: mkpath(name[, mode=0o777, verbose=0, dry_run=0])

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

952

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.

960

961

Georg Brandl

f4a4123

2008-05-26 17:55:52 +0000

[diff] [blame]

962

.. function:: create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

963

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

:func:`mkpath`.

.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0])

973

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*.

983

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`.

990

991

992

.. function:: remove_tree(directory[, verbose=0, dry_run=0])

993

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).

997

998

**\*\*** Some of this could be replaced with the shutil module? **\*\***

999

1000

1001

:mod:`distutils.file_util` --- Single file operations

1002

=====================================================

1003

1004

.. module:: distutils.file_util

1005

:synopsis: Utility functions for operating on single files

1006

1007

1008

This module contains some utility functions for operating on individual files.

1009

1010

1011

.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])

1012

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*.

1021

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.

1028

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).

1032

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)).

1039

1040

1041

.. function:: move_file(src, dst[, verbose, dry_run])

1042

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.

.. warning::

Benjamin Peterson

2009-04-05 19:13:16 +0000

[diff] [blame]

1049

Handles cross-device moves on Unix using :func:`copy_file`. What about

1050

other systems?

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1051

1052

1053

.. function:: write_file(filename, contents)

1054

1055

Create a file called *filename* and write *contents* (a sequence of strings

1056

without line terminators) to it.

1057

1058

1059

:mod:`distutils.util` --- Miscellaneous other utility functions

1060

===============================================================

1061

1062

.. module:: distutils.util

1063

:synopsis: Miscellaneous other utility functions

1064

1065

1066

This module contains other assorted bits and pieces that don't fit into any

1067

other utility module.

1068

1069

1070

.. function:: get_platform()

1071

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.

1079

1080

Examples of returned values:

* ``linux-i586``

* ``linux-alpha``

* ``solaris-2.6-sun4u``

* ``irix-5.3``

* ``irix64-6.2``

For non-POSIX platforms, currently just returns ``sys.platform``.

1089

Benjamin Peterson

2009-04-05 19:13:16 +0000

[diff] [blame]

1090

For Mac OS X systems the OS version reflects the minimal version on which

Benjamin Peterson

2008-12-30 17:56:45 +0000

[diff] [blame]

1091

binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``

Georg Brandl

2009-01-03 21:18:54 +0000

[diff] [blame]

1092

during the build of Python), not the OS version of the current system.

Benjamin Peterson

2008-12-30 17:56:45 +0000

[diff] [blame]

1093

Benjamin Peterson

2009-04-05 19:13:16 +0000

[diff] [blame]

1094

For universal binary builds on Mac OS X the architecture value reflects

Benjamin Peterson

2008-12-30 17:56:45 +0000

[diff] [blame]

1095

the univeral binary status instead of the architecture of the current

Georg Brandl

2009-01-03 21:18:54 +0000

[diff] [blame]

1096

processor. For 32-bit universal binaries the architecture is ``fat``,

1097

for 64-bit universal binaries the architecture is ``fat64``, and

Ronald Oussoren

bea37ae

2009-09-15 19:16:02 +0000

[diff] [blame]

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

Benjamin Peterson

2008-12-30 17:56:45 +0000

[diff] [blame]

1102

Benjamin Peterson

2009-04-05 19:13:16 +0000

[diff] [blame]

1103

Examples of returned values on Mac OS X:

Benjamin Peterson

2008-12-30 17:56:45 +0000

[diff] [blame]

1104

1105

* ``macosx-10.3-ppc``

1106

1107

* ``macosx-10.3-fat``

1108

1109

* ``macosx-10.5-universal``

1110

Ronald Oussoren

bea37ae

2009-09-15 19:16:02 +0000

[diff] [blame]

1111

* ``macosx-10.6-intel``

1112

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1113

.. % XXX isn't this also provided by some other non-distutils module?

1114

1115

1116

.. function:: convert_path(pathname)

1117

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.

1124

1125

1126

.. function:: change_root(new_root, pathname)

1127

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.

1131

1132

1133

.. function:: check_environ()

1134

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:

1138

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`)

1142

1143

1144

.. function:: subst_vars(s, local_vars)

1145

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``.

1152

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.

1156

1157

1158

.. function:: grok_environment_error(exc[, prefix='error: '])

1159

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*.

1166

1167

1168

.. function:: split_quoted(s)

1169

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.

1177

1178

.. % Should probably be moved into the standard library.

1179

1180

1181

.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])

1182

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.

1188

1189

1190

.. function:: strtobool(val)

1191

1192

Convert a string representation of truth to true (1) or false (0).

1193

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.

1197

1198

1199

.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])

1200

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:

1205

1206

* ``0`` - don't optimize (generate :file:`.pyc`)

1207

* ``1`` - normal optimization (like ``python -O``)

1208

* ``2`` - extra optimization (like ``python -OO``)

1209

1210

If *force* is true, all files are recompiled regardless of timestamps.

1211

Georg Brandl

9afde1c

2007-11-01 20:32:30 +0000

[diff] [blame]

1212

The source filename encoded in each :term:`bytecode` file defaults to the filenames

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

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.

1218

1219

If *dry_run* is true, doesn't actually do anything that would affect the

1220

filesystem.

1221

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``.

1228

1229

1230

.. function:: rfc822_escape(header)

1231

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.

1235

1236

.. % this _can_ be replaced

1237

1238

.. % \subsection{Distutils objects}

1239

1240

1241

:mod:`distutils.dist` --- The Distribution class

1242

================================================

1243

1244

.. module:: distutils.dist

1245

:synopsis: Provides the Distribution class, which represents the module distribution being

1246

built/installed/distributed

1247

1248

1249

This module provides the :class:`Distribution` class, which represents the

1250

module distribution being built/installed/distributed.

1251

1252

1253

:mod:`distutils.extension` --- The Extension class

1254

==================================================

1255

1256

.. module:: distutils.extension

1257

:synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup

scripts

This module provides the :class:`Extension` class, used to describe C/C++

1262

extension modules in setup scripts.

1263

1264

.. % \subsection{Ungrouped modules}

1265

.. % The following haven't been moved into a more appropriate section yet.

1266

1267

1268

:mod:`distutils.debug` --- Distutils debug mode

1269

===============================================

1270

1271

.. module:: distutils.debug

1272

:synopsis: Provides the debug flag for distutils

1273

1274

1275

This module provides the DEBUG flag.

1276

1277

1278

:mod:`distutils.errors` --- Distutils exceptions

1279

================================================

1280

1281

.. module:: distutils.errors

1282

:synopsis: Provides standard distutils exceptions

1283

1284

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).

1288

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``.

1291

1292

1293

:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module

1294

===========================================================================

1295

1296

.. module:: distutils.fancy_getopt

1297

:synopsis: Additional getopt functionality

1298

1299

1300

This module provides a wrapper around the standard :mod:`getopt` module that

1301

provides the following additional features:

1302

1303

* short and long options are tied together

1304

1305

* options have help strings, so :func:`fancy_getopt` could potentially create a

1306

complete usage summary

1307

1308

* options set attributes of a passed-in object

1309

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.

1313

1314

**\*\*** Should be replaced with :mod:`optik` (which is also now known as

1315

:mod:`optparse` in Python 2.3 and later). **\*\***

1316

1317

1318

.. function:: fancy_getopt(options, negative_opt, object, args)

1319

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*.

1327

1328

1329

.. function:: wrap_text(text, width)

1330

1331

Wraps *text* to less than *width* wide.

1332

Georg Brandl

2009-04-27 16:23:47 +0000

[diff] [blame]

1333

.. XXX Should be replaced with :mod:`textwrap` (which is available in Python

1334

2.3 and later).

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1335

1336

1337

.. class:: FancyGetopt([option_table=None])

1338

1339

The option_table is a list of 3-tuples: ``(long_option, short_option,

1340

help_string)``

1341

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.

1346

1347

The :class:`FancyGetopt` class provides the following methods:

1348

1349

1350

.. method:: FancyGetopt.getopt([args=None, object=None])

1351

1352

Parse command-line options in args. Store as attributes on *object*.

1353

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.

1360

1361

.. % and args returned are?

1362

1363

1364

.. method:: FancyGetopt.get_option_order()

1365

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

yet.

.. method:: FancyGetopt.generate_help([header=None])

1372

1373

Generate help text (a list of strings, one per suggested line of output) from

1374

the option table for this :class:`FancyGetopt` object.

1375

1376

If supplied, prints the supplied *header* at the top of the help.

1377

1378

1379

:mod:`distutils.filelist` --- The FileList class

1380

================================================

1381

1382

.. module:: distutils.filelist

Georg Brandl

2009-04-27 16:23:47 +0000

[diff] [blame]

1383

:synopsis: The FileList class, used for poking about the file system and

1384

building lists of files.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1385

1386

1387

This module provides the :class:`FileList` class, used for poking about the

1388

filesystem and building lists of files.

1389

1390

1391

:mod:`distutils.log` --- Simple PEP 282-style logging

1392

=====================================================

1393

1394

.. module:: distutils.log

1395

:synopsis: A simple logging mechanism, 282-style

1396

1397

Georg Brandl

2009-04-27 16:23:47 +0000

[diff] [blame]

1398

.. XXX Should be replaced with standard :mod:`logging` module.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1399

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1400

1401

1402

:mod:`distutils.spawn` --- Spawn a sub-process

1403

==============================================

1404

1405

.. module:: distutils.spawn

1406

:synopsis: Provides the spawn() function

1407

1408

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

name.

:mod:`distutils.sysconfig` --- System configuration information

1416

===============================================================

1417

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>

1423

1424

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.

1433

1434

Some additional functions are provided which perform some useful manipulations

1435

for other parts of the :mod:`distutils` package.

.. data:: PREFIX

The result of ``os.path.normpath(sys.prefix)``.

1441

1442

1443

.. data:: EXEC_PREFIX

1444

1445

The result of ``os.path.normpath(sys.exec_prefix)``.

1446

1447

1448

.. function:: get_config_var(name)

1449

1450

Return the value of a single variable. This is equivalent to

1451

``get_config_vars().get(name)``.

1452

1453

1454

.. function:: get_config_vars(...)

1455

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.

1461

1462

1463

.. function:: get_config_h_filename()

1464

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.

1469

1470

1471

.. function:: get_makefile_filename()

1472

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.

1477

1478

1479

.. function:: get_python_inc([plat_specific[, prefix]])

1480

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.

1487

1488

1489

.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])

1490

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.

1499

1500

The following function is only intended for use within the :mod:`distutils`

package.

.. function:: customize_compiler(compiler)

1505

1506

Do any platform-specific customization of a

1507

:class:`distutils.ccompiler.CCompiler` instance.

1508

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.

1514

1515

This function is even more special-purpose, and should only be used from

1516

Python's own build procedures.

1517

1518

1519

.. function:: set_python_build()

1520

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

Python.

:mod:`distutils.text_file` --- The TextFile class

1528

=================================================

1529

1530

.. module:: distutils.text_file

1531

:synopsis: provides the TextFile class, a simple interface to text files

1532

1533

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.

1537

1538

1539

.. class:: TextFile([filename=None, file=None, **options])

1540

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.

1547

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.

1552

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.

1560

1561

The options are all boolean, and affect the values returned by :meth:`readline`

1562

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

+------------------+--------------------------------+---------+

1607

1608

Note that since *rstrip_ws* can strip the trailing newline, the semantics of

Georg Brandl

22b3431

2009-07-26 14:54:51 +0000

[diff] [blame]

1609

:meth:`readline` must differ from those of the built-in file object's

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

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.

1613

1614

1615

.. method:: TextFile.open(filename)

1616

Georg Brandl

22b3431

2009-07-26 14:54:51 +0000

[diff] [blame]

1617

Open a new file *filename*. This overrides any *file* or *filename*

1618

constructor arguments.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1619

1620

1621

.. method:: TextFile.close()

1622

1623

Close the current file and forget everything we know about it (including the

1624

filename and the current line number).

1625

1626

1627

.. method:: TextFile.warn(msg[,line=None])

1628

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

physical line.

.. method:: TextFile.readline()

1638

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.

1646

1647

1648

.. method:: TextFile.readlines()

1649

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.

1652

1653

1654

.. method:: TextFile.unreadline(line)

1655

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.

1662

1663

1664

:mod:`distutils.version` --- Version number classes

1665

===================================================

1666

1667

.. module:: distutils.version

1668

:synopsis: implements classes that represent module version numbers.

.. % todo

.. % \section{Distutils Commands}

Georg Brandl

2009-01-03 21:18:54 +0000

[diff] [blame]

1673

.. %

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

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.

1677

1678

1679

:mod:`distutils.cmd` --- Abstract base class for Distutils commands

1680

===================================================================

1681

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.

1685

1686

1687

This module supplies the abstract base class :class:`Command`.

1688

1689

1690

.. class:: Command(dist)

1691

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.

1703

1704

The class constructor takes a single argument *dist*, a :class:`Distribution`

instance.

:mod:`distutils.command` --- Individual Distutils commands

1709

==========================================================

1710

1711

.. module:: distutils.command

1712

:synopsis: This subpackage contains one module for each standard Distutils command.

1713

1714

1715

.. % \subsubsection{Individual Distutils commands}

.. % todo

:mod:`distutils.command.bdist` --- Build a binary installer

1720

===========================================================

1721

1722

.. module:: distutils.command.bdist

1723

:synopsis: Build a binary installer for a package

.. % todo

:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers

1730

=============================================================================

1731

1732

.. module:: distutils.command.bdist_packager

1733

:synopsis: Abstract base class for packagers

.. % todo

:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer

1740

================================================================

1741

1742

.. module:: distutils.command.bdist_dumb

1743

:synopsis: Build a "dumb" installer - a simple archive of files

.. % todo

:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package

1750

=================================================================================

1751

1752

.. module:: distutils.command.bdist_msi

1753

:synopsis: Build a binary distribution as a Windows MSI file

1754

Benjamin Peterson

2009-04-05 19:13:16 +0000

[diff] [blame]

1755

.. class:: bdist_msi(Command)

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1756

Benjamin Peterson

2009-04-05 19:13:16 +0000

[diff] [blame]

1757

Builds a `Windows Installer`_ (.msi) binary package.

1758

1759

.. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx

1760

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.

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1765

1766

1767

:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM

1768

===========================================================================================

1769

1770

.. module:: distutils.command.bdist_rpm

1771

:synopsis: Build a binary distribution as a Redhat RPM and SRPM

.. % todo

:mod:`distutils.command.bdist_wininst` --- Build a Windows installer

1778

====================================================================

1779

1780

.. module:: distutils.command.bdist_wininst

1781

:synopsis: Build a Windows installer

.. % todo

:mod:`distutils.command.sdist` --- Build a source distribution

1788

==============================================================

1789

1790

.. module:: distutils.command.sdist

1791

:synopsis: Build a source distribution

.. % todo

:mod:`distutils.command.build` --- Build all files of a package

1798

===============================================================

1799

1800

.. module:: distutils.command.build

1801

:synopsis: Build all files of a package

.. % todo

:mod:`distutils.command.build_clib` --- Build any C libraries in a package

1808

==========================================================================

1809

1810

.. module:: distutils.command.build_clib

1811

:synopsis: Build any C libraries in a package

.. % todo

:mod:`distutils.command.build_ext` --- Build any extensions in a package

1818

========================================================================

1819

1820

.. module:: distutils.command.build_ext

1821

:synopsis: Build any extensions in a package

.. % todo

:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package

1828

===========================================================================

1829

1830

.. module:: distutils.command.build_py

1831

:synopsis: Build the .py/.pyc files of a package

1832

1833

Martin v. Löwis

73a22f0

2008-03-22 00:35:10 +0000

[diff] [blame]

1834

.. class:: build_py(Command)

1835

1836

.. class:: build_py_2to3(build_py)

1837

1838

Alternative implementation of build_py which also runs the

1839

2to3 conversion library on each .py file that is going to be

1840

installed. To use this in a setup.py file for a distribution

1841

that is designed to run with both Python 2.x and 3.x, add::

1842

1843

try:

1844

from distutils.command.build_py import build_py_2to3 as build_py

1845

except ImportError:

1846

from distutils.command.build_py import build_py

1847

1848

to your setup.py, and later::

1849

1850

cmdclass = {'build_py':build_py}

1851

1852

to the invocation of setup().

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1853

1854

1855

:mod:`distutils.command.build_scripts` --- Build the scripts of a package

1856

=========================================================================

1857

1858

.. module:: distutils.command.build_scripts

1859

:synopsis: Build the scripts of a package

.. % todo

:mod:`distutils.command.clean` --- Clean a package build area

1866

=============================================================

1867

1868

.. module:: distutils.command.clean

1869

:synopsis: Clean a package build area

.. % todo

:mod:`distutils.command.config` --- Perform package configuration

1876

=================================================================

1877

1878

.. module:: distutils.command.config

1879

:synopsis: Perform package configuration

.. % todo

:mod:`distutils.command.install` --- Install a package

1886

======================================================

1887

1888

.. module:: distutils.command.install

1889

:synopsis: Install a package

.. % todo

:mod:`distutils.command.install_data` --- Install data files from a package

1896

===========================================================================

1897

1898

.. module:: distutils.command.install_data

1899

:synopsis: Install data files from a package

.. % todo

:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package

1906

======================================================================================

1907

1908

.. module:: distutils.command.install_headers

1909

:synopsis: Install C/C++ header files from a package

.. % todo

:mod:`distutils.command.install_lib` --- Install library files from a package

1916

=============================================================================

1917

1918

.. module:: distutils.command.install_lib

1919

:synopsis: Install library files from a package

.. % todo

:mod:`distutils.command.install_scripts` --- Install script files from a package

1926

================================================================================

1927

1928

.. module:: distutils.command.install_scripts

1929

:synopsis: Install script files from a package

.. % todo

:mod:`distutils.command.register` --- Register a module with the Python Package Index

1936

=====================================================================================

1937

1938

.. module:: distutils.command.register

1939

:synopsis: Register a module with the Python Package Index

1940

1941

1942

The ``register`` command registers the package with the Python Package Index.

1943

This is described in more detail in :pep:`301`.

.. % todo

Tarek Ziadé

2009-04-11 15:00:43 +0000

[diff] [blame]

1947

:mod:`distutils.command.check` --- Check the meta-data of a package

1948

===================================================================

1949

1950

.. module:: distutils.command.check

1951

:synopsis: Check the metadata of a package

1952

1953

1954

The ``check`` command performs some tests on the meta-data of a package.

1955

It makes sure for example that all required meta-data are provided through

1956

the arguments passed to the :func:`setup` function.

.. % todo

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1960

1961

Creating a new Distutils command

1962

================================

1963

1964

This section outlines the steps to create a new Distutils command.

1965

1966

A new command lives in a module in the :mod:`distutils.command` package. There

1967

is a sample template in that directory called :file:`command_template`. Copy

1968

this file to a new module with the same name as the new command you're

1969

implementing. This module should implement a class with the same name as the

1970

module (and the command). So, for instance, to create the command

1971

``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy

1972

:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit

1973

it so that it's implementing the class :class:`peel_banana`, a subclass of

1974

:class:`distutils.cmd.Command`.

1975

1976

Subclasses of :class:`Command` must define the following methods.

1977

1978

Georg Brandl

495f7b5

2009-10-27 15:28:25 +0000

[diff] [blame^]

1979

.. method:: Command.initialize_options()

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1980

Georg Brandl

495f7b5

2009-10-27 15:28:25 +0000

[diff] [blame^]

1981

Set default values for all the options that this command supports. Note that

Georg Brandl

2007-08-15 14:28:22 +0000

[diff] [blame]

1982

these defaults may be overridden by other commands, by the setup script, by

1983

config files, or by the command-line. Thus, this is not the place to code

1984

dependencies between options; generally, :meth:`initialize_options`

1985

implementations are just a bunch of ``self.foo = None`` assignments.

1986

1987

1988

.. method:: Command.finalize_options()

1989

1990

Set final values for all the options that this command supports. This is

1991

always called as late as possible, ie. after any option assignments from the

1992

command-line or from other commands have been done. Thus, this is the place

1993

to to code option dependencies: if *foo* depends on *bar*, then it is safe to

1994

set *foo* from *bar* as long as *foo* still has the same value it was

1995

assigned in :meth:`initialize_options`.

1996

1997

1998

.. method:: Command.run()

1999

2000

A command's raison d'etre: carry out the action it exists to perform, controlled

2001

by the options initialized in :meth:`initialize_options`, customized by other

2002

commands, the setup script, the command-line, and config files, and finalized in

2003

:meth:`finalize_options`. All terminal output and filesystem interaction should

2004

be done by :meth:`run`.

2005

2006

*sub_commands* formalizes the notion of a "family" of commands, eg. ``install``

2007

as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The

2008

parent of a family of commands defines *sub_commands* as a class attribute; it's

2009

a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string

Georg Brandl

2e0b755

2007-11-27 12:43:08 +0000

[diff] [blame]

2010

and *predicate* a function, a string or None. *predicate* is a method of

Georg Brandl