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

2009-01-03 21:55:17 +0000

[diff] [blame]

758

.. %

Georg Brandl

2007-08-15 14:28:01 +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

850

:mod:`distutils.mwerkscompiler` --- Metrowerks CodeWarrior support

851

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

852

853

.. module:: distutils.mwerkscompiler

854

:synopsis: Metrowerks CodeWarrior support

855

856

857

Contains :class:`MWerksCompiler`, an implementation of the abstract

858

:class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X

859

Macintosh. Needs work to support CW on Windows or Mac OS X.

860

861

.. % \subsection{Utility modules}

Georg Brandl

2009-01-03 21:55:17 +0000

[diff] [blame]

862

.. %

Georg Brandl

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

[diff] [blame]

863

.. % The following modules all provide general utility functions. They haven't

864

.. % all been documented yet.

865

866

867

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

868

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

869

870

.. module:: distutils.archive_util

871

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

872

873

874

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

875

tarballs or zipfiles.

876

877

878

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

879

880

Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of

881

the file to create, minus any format-specific extension; *format* is the

882

archive format: one of ``zip``, ``tar``, ``ztar``, or ``gztar``. *root_dir* is

883

a directory that will be the root directory of the archive; ie. we typically

884

``chdir`` into *root_dir* before creating the archive. *base_dir* is the

885

directory where we start archiving from; ie. *base_dir* will be the common

886

prefix of all files and directories in the archive. *root_dir* and *base_dir*

887

both default to the current directory. Returns the name of the archive file.

888

Georg Brandl

2009-04-28 18:23:28 +0000

[diff] [blame^]

889

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

Georg Brandl

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

[diff] [blame]

890

891

892

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

893

894

'Create an (optional compressed) archive as a tar file from all files in and

895

under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``,

896

``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named

897

by *compress* must be on the default program search path, so this is probably

898

Unix-specific. The output tar file will be named :file:`base_dir.tar`,

899

possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2`

900

or :file:`.Z`). Return the output filename.

901

Georg Brandl

2009-04-28 18:23:28 +0000

[diff] [blame^]

902

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

Georg Brandl

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

[diff] [blame]

903

904

905

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

906

907

Create a zip file from all files in and under *base_dir*. The output zip file

908

will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python

909

module (if available) or the InfoZIP :file:`zip` utility (if installed and

910

found on the default search path). If neither tool is available, raises

911

:exc:`DistutilsExecError`. Returns the name of the output zip file.

912

913

914

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

915

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

916

917

.. module:: distutils.dep_util

918

:synopsis: Utility functions for simple dependency checking

919

920

921

This module provides functions for performing simple, timestamp-based

922

dependency of files and groups of files; also, functions based entirely on such

923

timestamp dependency analysis.

924

925

926

.. function:: newer(source, target)

927

928

Return true if *source* exists and is more recently modified than *target*, or

929

if *source* exists and *target* doesn't. Return false if both exist and *target*

930

is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if

931

*source* does not exist.

932

933

934

.. function:: newer_pairwise(sources, targets)

935

936

Walk two filename lists in parallel, testing if each source is newer than its

937

corresponding target. Return a pair of lists (*sources*, *targets*) where

938

source is newer than target, according to the semantics of :func:`newer`

939

940

.. % % equivalent to a listcomp...

941

942

943

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

944

945

Return true if *target* is out-of-date with respect to any file listed in

946

*sources* In other words, if *target* exists and is newer than every file in

947

*sources*, return false; otherwise return true. *missing* controls what we do

948

when a source file is missing; the default (``'error'``) is to blow up with an

949

:exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently

950

drop any missing source files; if it is ``'newer'``, any missing source files

951

make us assume that *target* is out-of-date (this is handy in "dry-run" mode:

952

it'll make you pretend to carry out commands that wouldn't work because inputs

953

are missing, but that doesn't matter because you're not actually going to run

the commands).

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

958

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

959

960

.. module:: distutils.dir_util

961

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

962

963

964

This module provides functions for operating on directories and trees of

directories.

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

969

970

Create a directory and any missing ancestor directories. If the directory

971

already exists (or if *name* is the empty string, which means the current

972

directory, which of course exists), then do nothing. Raise

973

:exc:`DistutilsFileError` if unable to create some directory along the way (eg.

974

some sub-path exists, but is a file rather than a directory). If *verbose* is

975

true, print a one-line summary of each mkdir to stdout. Return the list of

976

directories actually created.

977

978

979

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

980

981

Create all the empty directories under *base_dir* needed to put *files* there.

982

*base_dir* is just the a name of a directory which doesn't necessarily exist

983

yet; *files* is a list of filenames to be interpreted relative to *base_dir*.

984

*base_dir* + the directory portion of every file in *files* will be created if

985

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

990

991

Copy an entire directory tree *src* to a new location *dst*. Both *src* and

992

*dst* must be directory names. If *src* is not a directory, raise

993

:exc:`DistutilsFileError`. If *dst* does not exist, it is created with

994

:func:`mkpath`. The end result of the copy is that every file in *src* is

995

copied to *dst*, and directories under *src* are recursively copied to *dst*.

996

Return the list of files that were copied or might have been copied, using their

997

output name. The return value is unaffected by *update* or *dry_run*: it is

998

simply the list of all files under *src*, with the names changed to be under

999

*dst*.

1000

1001

*preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in

1002

:mod:`distutils.file_util`; note that they only apply to regular files, not to

1003

directories. If *preserve_symlinks* is true, symlinks will be copied as

1004

symlinks (on platforms that support them!); otherwise (the default), the

1005

destination of the symlink will be copied. *update* and *verbose* are the same

1006

as for :func:`copy_file`.

1007

1008

1009

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

1010

1011

Recursively remove *directory* and all files and directories underneath it. Any

1012

errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is

1013

true).

1014

1015

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

1016

1017

1018

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

1019

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

1020

1021

.. module:: distutils.file_util

1022

:synopsis: Utility functions for operating on single files

1023

1024

1025

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

1026

1027

1028

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

1029

1030

Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there

1031

with the same name; otherwise, it must be a filename. (If the file exists, it

1032

will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the

1033

file's mode (type and permission bits, or whatever is analogous on the

1034

current platform) is copied. If *preserve_times* is true (the default), the

1035

last-modified and last-access times are copied as well. If *update* is true,

1036

*src* will only be copied if *dst* does not exist, or if *dst* does exist but

1037

is older than *src*.

1038

1039

*link* allows you to make hard links (using :func:`os.link`) or symbolic links

1040

(using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or

1041

``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*

1042

on systems that don't support it: :func:`copy_file` doesn't check if hard or

1043

symbolic linking is available. It uses :func:`_copy_file_contents` to copy file

1044

contents.

1045

1046

Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the

1047

output file, and *copied* is true if the file was copied (or would have been

1048

copied, if *dry_run* true).

1049

1050

.. % XXX if the destination file already exists, we clobber it if

1051

.. % copying, but blow up if linking. Hmmm. And I don't know what

1052

.. % macostools.copyfile() does. Should definitely be consistent, and

1053

.. % should probably blow up if destination exists and we would be

1054

.. % changing it (ie. it's not already a hard/soft link to src OR

1055

.. % (not update) and (src newer than dst)).

1056

1057

1058

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

1059

1060

Move file *src* to *dst*. If *dst* is a directory, the file will be moved into

1061

it with the same name; otherwise, *src* is just renamed to *dst*. Returns the

1062

new full name of the file.

.. warning::

Georg Brandl

2009-04-05 21:26:31 +0000

[diff] [blame]

1066

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

1067

other systems?

Georg Brandl

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

[diff] [blame]

1068

1069

1070

.. function:: write_file(filename, contents)

1071

1072

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

1073

without line terminators) to it.

1074

1075

1076

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

1077

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

1078

1079

.. module:: distutils.util

1080

:synopsis: Miscellaneous other utility functions

1081

1082

1083

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

1084

other utility module.

1085

1086

1087

.. function:: get_platform()

1088

1089

Return a string that identifies the current platform. This is used mainly to

1090

distinguish platform-specific build directories and platform-specific built

1091

distributions. Typically includes the OS name and version and the architecture

1092

(as supplied by 'os.uname()'), although the exact information included depends

1093

on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only

1094

runs on SGI hardware), but for Linux the kernel version isn't particularly

1095

important.

1096

1097

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

1106

Georg Brandl

e9b9121

2009-04-05 21:26:31 +0000

[diff] [blame]

1107

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

Georg Brandl

2009-01-01 15:46:10 +0000

[diff] [blame]

1108

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

Georg Brandl

2009-01-03 21:55:17 +0000

[diff] [blame]

1109

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

Georg Brandl

2009-01-01 15:46:10 +0000

[diff] [blame]

1110

Georg Brandl

e9b9121

2009-04-05 21:26:31 +0000

[diff] [blame]

1111

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

Georg Brandl

2009-01-01 15:46:10 +0000

[diff] [blame]

1112

the univeral binary status instead of the architecture of the current

Georg Brandl

2009-01-03 21:55:17 +0000

[diff] [blame]

1113

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

1114

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

1115

for 4-way universal binaries the architecture is ``universal``.

Georg Brandl

2009-01-01 15:46:10 +0000

[diff] [blame]

1116

Georg Brandl

e9b9121

2009-04-05 21:26:31 +0000

[diff] [blame]

1117

Examples of returned values on Mac OS X:

Georg Brandl

2009-01-01 15:46:10 +0000

[diff] [blame]

1118

1119

* ``macosx-10.3-ppc``

1120

1121

* ``macosx-10.3-fat``

1122

1123

* ``macosx-10.5-universal``

1124

Georg Brandl

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

[diff] [blame]

1125

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

1126

1127

1128

.. function:: convert_path(pathname)

1129

1130

Return 'pathname' as a name that will work on the native filesystem, i.e. split

1131

it on '/' and put it back together again using the current directory separator.

1132

Needed because filenames in the setup script are always supplied in Unix style,

1133

and have to be converted to the local convention before we can actually use them

1134

in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if

1135

*pathname* either starts or ends with a slash.

1136

1137

1138

.. function:: change_root(new_root, pathname)

1139

1140

Return *pathname* with *new_root* prepended. If *pathname* is relative, this is

1141

equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making

1142

*pathname* relative and then joining the two, which is tricky on DOS/Windows.

1143

1144

1145

.. function:: check_environ()

1146

1147

Ensure that 'os.environ' has all the environment variables we guarantee that

1148

users can use in config files, command-line options, etc. Currently this

1149

includes:

1150

1151

* :envvar:`HOME` - user's home directory (Unix only)

1152

* :envvar:`PLAT` - description of the current platform, including hardware and

1153

OS (see :func:`get_platform`)

1154

1155

1156

.. function:: subst_vars(s, local_vars)

1157

1158

Perform shell/Perl-style variable substitution on *s*. Every occurrence of

1159

``$`` followed by a name is considered a variable, and variable is substituted

1160

by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's

1161

not in *local_vars*. *os.environ* is first checked/augmented to guarantee that

1162

it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError`

1163

for any variables not found in either *local_vars* or ``os.environ``.

1164

1165

Note that this is not a fully-fledged string interpolation function. A valid

1166

``$variable`` can consist only of upper and lower case letters, numbers and an

1167

underscore. No { } or ( ) style quoting is available.

1168

1169

1170

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

1171

1172

Generate a useful error message from an :exc:`EnvironmentError` (:exc:`IOError`

1173

or :exc:`OSError`) exception object. Handles Python 1.5.1 and later styles,

1174

and does what it can to deal with exception objects that don't have a filename

1175

(which happens when the error is due to a two-file operation, such as

1176

:func:`rename` or :func:`link`). Returns the error message as a string

1177

prefixed with *prefix*.

1178

1179

1180

.. function:: split_quoted(s)

1181

1182

Split a string up according to Unix shell-like rules for quotes and backslashes.

1183

In short: words are delimited by spaces, as long as those spaces are not escaped

1184

by a backslash, or inside a quoted string. Single and double quotes are

1185

equivalent, and the quote characters can be backslash-escaped. The backslash is

1186

stripped from any two-character escape sequence, leaving only the escaped

1187

character. The quote characters are stripped from any quoted string. Returns a

1188

list of words.

1189

1190

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

1191

1192

1193

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

1194

1195

Perform some action that affects the outside world (for instance, writing to the

1196

filesystem). Such actions are special because they are disabled by the

1197

*dry_run* flag. This method takes care of all that bureaucracy for you; all

1198

you have to do is supply the function to call and an argument tuple for it (to

1199

embody the "external action" being performed), and an optional message to print.

1200

1201

1202

.. function:: strtobool(val)

1203

1204

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

1205

1206

True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values

1207

are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises

1208

:exc:`ValueError` if *val* is anything else.

1209

1210

1211

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

1212

1213

Byte-compile a collection of Python source files to either :file:`.pyc` or

1214

:file:`.pyo` files in the same directory. *py_files* is a list of files to

1215

compile; any files that don't end in :file:`.py` are silently skipped.

1216

*optimize* must be one of the following:

1217

1218

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

1219

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

1220

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

1221

1222

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

1223

Georg Brandl

5e52db0

2007-10-21 10:45:46 +0000

[diff] [blame]

1224

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

Georg Brandl

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

[diff] [blame]

1225

listed in *py_files*; you can modify these with *prefix* and *basedir*.

1226

*prefix* is a string that will be stripped off of each source filename, and

1227

*base_dir* is a directory name that will be prepended (after *prefix* is

1228

stripped). You can supply either or both (or neither) of *prefix* and

1229

*base_dir*, as you wish.

1230

1231

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

1232

filesystem.

1233

1234

Byte-compilation is either done directly in this interpreter process with the

1235

standard :mod:`py_compile` module, or indirectly by writing a temporary script

1236

and executing it. Normally, you should let :func:`byte_compile` figure out to

1237

use direct compilation or not (see the source for details). The *direct* flag

1238

is used by the script generated in indirect mode; unless you know what you're

1239

doing, leave it set to ``None``.

1240

1241

1242

.. function:: rfc822_escape(header)

1243

1244

Return a version of *header* escaped for inclusion in an :rfc:`822` header, by

1245

ensuring there are 8 spaces space after each newline. Note that it does no other

1246

modification of the string.

1247

1248

.. % this _can_ be replaced

1249

1250

.. % \subsection{Distutils objects}

1251

1252

1253

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

1254

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

1255

1256

.. module:: distutils.dist

1257

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

1258

built/installed/distributed

1259

1260

1261

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

1262

module distribution being built/installed/distributed.

1263

1264

1265

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

1266

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

1267

1268

.. module:: distutils.extension

1269

: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++

1274

extension modules in setup scripts.

1275

1276

.. % \subsection{Ungrouped modules}

1277

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

1278

1279

1280

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

1281

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

1282

1283

.. module:: distutils.debug

1284

:synopsis: Provides the debug flag for distutils

1285

1286

1287

This module provides the DEBUG flag.

1288

1289

1290

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

1291

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

1292

1293

.. module:: distutils.errors

1294

:synopsis: Provides standard distutils exceptions

1295

1296

1297

Provides exceptions used by the Distutils modules. Note that Distutils modules

1298

may raise standard exceptions; in particular, SystemExit is usually raised for

1299

errors that are obviously the end-user's fault (eg. bad command-line arguments).

1300

1301

This module is safe to use in ``from ... import *`` mode; it only exports

1302

symbols whose names start with ``Distutils`` and end with ``Error``.

1303

1304

1305

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

1306

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

1307

1308

.. module:: distutils.fancy_getopt

1309

:synopsis: Additional getopt functionality

1310

1311

1312

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

1313

provides the following additional features:

1314

1315

* short and long options are tied together

1316

1317

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

1318

complete usage summary

1319

1320

* options set attributes of a passed-in object

1321

1322

* boolean options can have "negative aliases" --- eg. if :option:`--quiet` is

1323

the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the

1324

command line sets *verbose* to false.

1325

1326

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

1327

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

1328

1329

1330

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

1331

1332

Wrapper function. *options* is a list of ``(long_option, short_option,

1333

help_string)`` 3-tuples as described in the constructor for

1334

:class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names

1335

to option names, both the key and value should be in the *options* list.

1336

*object* is an object which will be used to store values (see the :meth:`getopt`

1337

method of the :class:`FancyGetopt` class). *args* is the argument list. Will use

1338

``sys.argv[1:]`` if you pass ``None`` as *args*.

1339

1340

1341

.. function:: wrap_text(text, width)

1342

1343

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

1344

Georg Brandl

2009-04-28 18:23:28 +0000

[diff] [blame^]

1345

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

1346

2.3 and later).

Georg Brandl

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

[diff] [blame]

1347

1348

1349

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

1350

1351

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

1352

help_string)``

1353

1354

If an option takes an argument, its *long_option* should have ``'='`` appended;

1355

*short_option* should just be a single character, no ``':'`` in any case.

1356

*short_option* should be ``None`` if a *long_option* doesn't have a

1357

corresponding *short_option*. All option tuples must have long options.

1358

1359

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

1360

1361

1362

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

1363

1364

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

1365

1366

If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is

1367

``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores

1368

option values there, and returns a tuple ``(args, object)``. If *object* is

1369

supplied, it is modified in place and :func:`getopt` just returns *args*; in

1370

both cases, the returned *args* is a modified copy of the passed-in *args* list,

1371

which is left untouched.

1372

1373

.. % and args returned are?

1374

1375

1376

.. method:: FancyGetopt.get_option_order()

1377

1378

Returns the list of ``(option, value)`` tuples processed by the previous run of

1379

:meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called

yet.

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

1384

1385

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

1386

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

1387

1388

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

1389

1390

1391

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

1392

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

1393

1394

.. module:: distutils.filelist

Georg Brandl

2009-04-28 18:23:28 +0000

[diff] [blame^]

1395

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

1396

building lists of files.

Georg Brandl

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

[diff] [blame]

1397

1398

1399

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

1400

filesystem and building lists of files.

1401

1402

1403

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

1404

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

1405

1406

.. module:: distutils.log

1407

:synopsis: A simple logging mechanism, 282-style

1408

1409

Georg Brandl

2009-04-28 18:23:28 +0000

[diff] [blame^]

1410

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

Georg Brandl

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

[diff] [blame]

1411

Georg Brandl

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

[diff] [blame]

1412

1413

1414

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

1415

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

1416

1417

.. module:: distutils.spawn

1418

:synopsis: Provides the spawn() function

1419

1420

1421

This module provides the :func:`spawn` function, a front-end to various

1422

platform-specific functions for launching another program in a sub-process.

1423

Also provides :func:`find_executable` to search the path for a given executable

name.

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

1428

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

1429

1430

.. module:: distutils.sysconfig

1431

:synopsis: Low-level access to configuration information of the Python interpreter.

1432

.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

1433

.. moduleauthor:: Greg Ward <gward@python.net>

1434

.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>

1435

1436

1437

The :mod:`distutils.sysconfig` module provides access to Python's low-level

1438

configuration information. The specific configuration variables available

1439

depend heavily on the platform and configuration. The specific variables depend

1440

on the build process for the specific version of Python being run; the variables

1441

are those found in the :file:`Makefile` and configuration header that are

1442

installed with Python on Unix systems. The configuration header is called

1443

:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`

1444

for earlier versions of Python.

1445

1446

Some additional functions are provided which perform some useful manipulations

1447

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

.. data:: PREFIX

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

1453

1454

1455

.. data:: EXEC_PREFIX

1456

1457

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

1458

1459

1460

.. function:: get_config_var(name)

1461

1462

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

1463

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

1464

1465

1466

.. function:: get_config_vars(...)

1467

1468

Return a set of variable definitions. If there are no arguments, this returns a

1469

dictionary mapping names of configuration variables to values. If arguments are

1470

provided, they should be strings, and the return value will be a sequence giving

1471

the associated values. If a given name does not have a corresponding value,

1472

``None`` will be included for that variable.

1473

1474

1475

.. function:: get_config_h_filename()

1476

1477

Return the full path name of the configuration header. For Unix, this will be

1478

the header generated by the :program:`configure` script; for other platforms the

1479

header will have been supplied directly by the Python source distribution. The

1480

file is a platform-specific text file.

1481

1482

1483

.. function:: get_makefile_filename()

1484

1485

Return the full path name of the :file:`Makefile` used to build Python. For

1486

Unix, this will be a file generated by the :program:`configure` script; the

1487

meaning for other platforms will vary. The file is a platform-specific text

1488

file, if it exists. This function is only useful on POSIX platforms.

1489

1490

1491

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

1492

1493

Return the directory for either the general or platform-dependent C include

1494

files. If *plat_specific* is true, the platform-dependent include directory is

1495

returned; if false or omitted, the platform-independent directory is returned.

1496

If *prefix* is given, it is used as either the prefix instead of

1497

:const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if

1498

*plat_specific* is true.

1499

1500

1501

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

1502

1503

Return the directory for either the general or platform-dependent library

1504

installation. If *plat_specific* is true, the platform-dependent include

1505

directory is returned; if false or omitted, the platform-independent directory

1506

is returned. If *prefix* is given, it is used as either the prefix instead of

1507

:const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if

1508

*plat_specific* is true. If *standard_lib* is true, the directory for the

1509

standard library is returned rather than the directory for the installation of

1510

third-party extensions.

1511

1512

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

package.

.. function:: customize_compiler(compiler)

1517

1518

Do any platform-specific customization of a

1519

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

1520

1521

This function is only needed on Unix at this time, but should be called

1522

consistently to support forward-compatibility. It inserts the information that

1523

varies across Unix flavors and is stored in Python's :file:`Makefile`. This

1524

information includes the selected compiler, compiler and linker options, and the

1525

extension used by the linker for shared objects.

1526

1527

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

1528

Python's own build procedures.

1529

1530

1531

.. function:: set_python_build()

1532

1533

Inform the :mod:`distutils.sysconfig` module that it is being used as part of

1534

the build process for Python. This changes a lot of relative locations for

1535

files, allowing them to be located in the build area rather than in an installed

Python.

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

1540

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

1541

1542

.. module:: distutils.text_file

1543

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

1544

1545

1546

This module provides the :class:`TextFile` class, which gives an interface to

1547

text files that (optionally) takes care of stripping comments, ignoring blank

1548

lines, and joining lines with backslashes.

1549

1550

1551

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

1552

1553

This class provides a file-like object that takes care of all the things you

1554

commonly want to do when processing a text file that has some line-by-line

1555

syntax: strip comments (as long as ``#`` is your comment character), skip blank

1556

lines, join adjacent lines by escaping the newline (ie. backslash at end of

1557

line), strip leading and/or trailing whitespace. All of these are optional and

1558

independently controllable.

1559

1560

The class provides a :meth:`warn` method so you can generate warning messages

1561

that report physical line number, even if the logical line in question spans

1562

multiple physical lines. Also provides :meth:`unreadline` for implementing

1563

line-at-a-time lookahead.

1564

1565

:class:`TextFile` instances are create with either *filename*, *file*, or both.

1566

:exc:`RuntimeError` is raised if both are ``None``. *filename* should be a

1567

string, and *file* a file object (or something that provides :meth:`readline`

1568

and :meth:`close` methods). It is recommended that you supply at least

1569

*filename*, so that :class:`TextFile` can include it in warning messages. If

1570

*file* is not supplied, :class:`TextFile` creates its own using the

1571

:func:`open` built-in function.

1572

1573

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

1574

1575

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

1576

| option name | description | default |

1577

+==================+================================+=========+

1578

| *strip_comments* | strip from ``'#'`` to end-of- | true |

1579

| | line, as well as any | |

1580

| | whitespace leading up to the | |

1581

| | ``'#'``\ ---unless it is | |

1582

| | escaped by a backslash | |

1583

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

1584

| *lstrip_ws* | strip leading whitespace from | false |

1585

| | each line before returning it | |

1586

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

1587

| *rstrip_ws* | strip trailing whitespace | true |

1588

| | (including line terminator!) | |

1589

| | from each line before | |

1590

| | returning it. | |

1591

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

1592

| *skip_blanks* | skip lines that are empty | true |

1593

| | \*after\* stripping comments | |

1594

| | and whitespace. (If both | |

1595

| | lstrip_ws and rstrip_ws are | |

1596

| | false, then some lines may | |

1597

| | consist of solely whitespace: | |

1598

| | these will \*not\* be skipped, | |

1599

| | even if *skip_blanks* is | |

1600

| | true.) | |

1601

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

1602

| *join_lines* | if a backslash is the last | false |

1603

| | non-newline character on a | |

1604

| | line after stripping comments | |

1605

| | and whitespace, join the | |

1606

| | following line to it to form | |

1607

| | one logical line; if N | |

1608

| | consecutive lines end with a | |

1609

| | backslash, then N+1 physical | |

1610

| | lines will be joined to form | |

1611

| | one logical line. | |

1612

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

1613

| *collapse_join* | strip leading whitespace from | false |

1614

| | lines that are joined to their | |

1615

| | predecessor; only matters if | |

1616

| | ``(join_lines and not | |

1617

| | lstrip_ws)`` | |

1618

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

1619

1620

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

1621

:meth:`readline` must differ from those of the builtin file object's

1622

:meth:`readline` method! In particular, :meth:`readline` returns ``None`` for

1623

end-of-file: an empty string might just be a blank line (or an all-whitespace

1624

line), if *rstrip_ws* is true but *skip_blanks* is not.

1625

1626

1627

.. method:: TextFile.open(filename)

1628

1629

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

arguments.

.. method:: TextFile.close()

1634

1635

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

1636

filename and the current line number).

1637

1638

1639

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

1640

1641

Print (to stderr) a warning message tied to the current logical line in the

1642

current file. If the current logical line in the file spans multiple physical

1643

lines, the warning refers to the whole range, such as ``"lines 3-5"``. If

1644

*line* is supplied, it overrides the current line number; it may be a list or

1645

tuple to indicate a range of physical lines, or an integer for a single

physical line.

.. method:: TextFile.readline()

1650

1651

Read and return a single logical line from the current file (or from an internal

1652

buffer if lines have previously been "unread" with :meth:`unreadline`). If the

1653

*join_lines* option is true, this may involve reading multiple physical lines

1654

concatenated into a single string. Updates the current line number, so calling

1655

:meth:`warn` after :meth:`readline` emits a warning about the physical line(s)

1656

just read. Returns ``None`` on end-of-file, since the empty string can occur

1657

if *rstrip_ws* is true but *strip_blanks* is not.

1658

1659

1660

.. method:: TextFile.readlines()

1661

1662

Read and return the list of all logical lines remaining in the current file.

1663

This updates the current line number to the last line of the file.

1664

1665

1666

.. method:: TextFile.unreadline(line)

1667

1668

Push *line* (a string) onto an internal buffer that will be checked by future

1669

:meth:`readline` calls. Handy for implementing a parser with line-at-a-time

1670

lookahead. Note that lines that are "unread" with :meth:`unreadline` are not

1671

subsequently re-cleansed (whitespace stripped, or whatever) when read with

1672

:meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call

1673

to :meth:`readline`, the lines will be returned most in most recent first order.

1674

1675

1676

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

1677

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

1678

1679

.. module:: distutils.version

1680

:synopsis: implements classes that represent module version numbers.

.. % todo

.. % \section{Distutils Commands}

Georg Brandl

2009-01-03 21:55:17 +0000

[diff] [blame]

1685

.. %

Georg Brandl

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

[diff] [blame]

1686

.. % This part of Distutils implements the various Distutils commands, such

1687

.. % as \code{build}, \code{install} \&c. Each command is implemented as a

1688

.. % separate module, with the command name as the name of the module.

1689

1690

1691

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

1692

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

1693

1694

.. module:: distutils.cmd

1695

:synopsis: This module provides the abstract base class Command. This class is subclassed

1696

by the modules in the distutils.command subpackage.

1697

1698

1699

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

1700

1701

1702

.. class:: Command(dist)

1703

1704

Abstract base class for defining command classes, the "worker bees" of the

1705

Distutils. A useful analogy for command classes is to think of them as

1706

subroutines with local variables called *options*. The options are declared in

1707

:meth:`initialize_options` and defined (given their final values) in

1708

:meth:`finalize_options`, both of which must be defined by every command class.

1709

The distinction between the two is necessary because option values might come

1710

from the outside world (command line, config file, ...), and any options

1711

dependent on other options must be computed after these outside influences have

1712

been processed --- hence :meth:`finalize_options`. The body of the subroutine,

1713

where it does all its work based on the values of its options, is the

1714

:meth:`run` method, which must also be implemented by every command class.

1715

1716

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

instance.

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

1721

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

1722

1723

.. module:: distutils.command

1724

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

1725

1726

1727

.. % \subsubsection{Individual Distutils commands}

.. % todo

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

1732

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

1733

1734

.. module:: distutils.command.bdist

1735

:synopsis: Build a binary installer for a package

.. % todo

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

1742

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

1743

1744

.. module:: distutils.command.bdist_packager

1745

:synopsis: Abstract base class for packagers

.. % todo

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

1752

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

1753

1754

.. module:: distutils.command.bdist_dumb

1755

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

.. % todo

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

1762

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

1763

1764

.. module:: distutils.command.bdist_msi

1765

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

1766

Georg Brandl

9b08e05

2009-04-05 21:21:05 +0000

[diff] [blame]

1767

.. class:: bdist_msi(Command)

Georg Brandl

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

[diff] [blame]

1768

Georg Brandl

9b08e05

2009-04-05 21:21:05 +0000

[diff] [blame]

1769

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

1770

1771

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

1772

1773

In most cases, the ``bdist_msi`` installer is a better choice than the

1774

``bdist_wininst`` installer, because it provides better support for

1775

Win64 platforms, allows administrators to perform non-interactive

1776

installations, and allows installation through group policies.

Georg Brandl