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

2009-01-03 20:55:06 +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

Georg Brandl

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

.. warning::

This should be changed to support bz2 files

875

876

877

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

878

879

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

880

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

881

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

882

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

883

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

884

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

885

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

.. warning::

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

890

891

892

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

893

894

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

895

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

896

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

897

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

898

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

899

900

901

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

902

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

903

904

.. module:: distutils.dep_util

905

:synopsis: Utility functions for simple dependency checking

906

907

908

This module provides functions for performing simple, timestamp-based

909

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

910

timestamp dependency analysis.

911

912

913

.. function:: newer(source, target)

914

915

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

916

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

917

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

918

*source* does not exist.

919

920

921

.. function:: newer_pairwise(sources, targets)

922

923

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

924

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

925

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

926

927

.. % % equivalent to a listcomp...

928

929

930

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

931

932

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

933

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

934

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

935

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

936

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

937

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

938

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

939

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

940

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

the commands).

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

945

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

946

947

.. module:: distutils.dir_util

948

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

949

950

951

This module provides functions for operating on directories and trees of

directories.

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

956

957

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

958

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

959

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

960

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

961

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

962

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

963

directories actually created.

964

965

966

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

967

968

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

969

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

970

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

971

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

972

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

977

978

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

979

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

980

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

981

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

982

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

983

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

984

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

985

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

986

*dst*.

987

988

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

989

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

990

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

991

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

992

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

993

as for :func:`copy_file`.

994

995

996

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

997

998

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

999

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

1000

true).

1001

1002

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

1003

1004

1005

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

1006

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

1007

1008

.. module:: distutils.file_util

1009

:synopsis: Utility functions for operating on single files

1010

1011

1012

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

1013

1014

1015

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

1016

1017

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

1018

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

1019

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

1020

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

1021

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

1022

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

1023

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

1024

is older than *src*.

1025

1026

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

1027

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

1028

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

1029

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

1030

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

1031

contents.

1032

1033

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

1034

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

1035

copied, if *dry_run* true).

1036

1037

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

1038

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

1039

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

1040

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

1041

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

1042

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

1043

1044

1045

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

1046

1047

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

1048

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

1049

new full name of the file.

.. warning::

Georg Brandl

2009-04-05 10:32:26 +0000

[diff] [blame]

1053

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

1054

other systems?

Georg Brandl

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

[diff] [blame]

1055

1056

1057

.. function:: write_file(filename, contents)

1058

1059

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

1060

without line terminators) to it.

1061

1062

1063

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

1064

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

1065

1066

.. module:: distutils.util

1067

:synopsis: Miscellaneous other utility functions

1068

1069

1070

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

1071

other utility module.

1072

1073

1074

.. function:: get_platform()

1075

1076

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

1077

distinguish platform-specific build directories and platform-specific built

1078

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

1079

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

1080

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

1081

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

1082

important.

1083

1084

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

1093

Georg Brandl

89b1296

2009-04-05 10:29:57 +0000

[diff] [blame]

1094

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

Ronald Oussoren

2008-12-28 19:40:56 +0000

[diff] [blame]

1095

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

Georg Brandl

2009-01-03 20:55:06 +0000

[diff] [blame]

1096

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

Ronald Oussoren

2008-12-28 19:40:56 +0000

[diff] [blame]

1097

Georg Brandl

89b1296

2009-04-05 10:29:57 +0000

[diff] [blame]

1098

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

Ronald Oussoren

2008-12-28 19:40:56 +0000

[diff] [blame]

1099

the univeral binary status instead of the architecture of the current

Georg Brandl

2009-01-03 20:55:06 +0000

[diff] [blame]

1100

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

1101

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

1102

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

Ronald Oussoren

2008-12-28 19:40:56 +0000

[diff] [blame]

1103

Georg Brandl

89b1296

2009-04-05 10:29:57 +0000

[diff] [blame]

1104

Examples of returned values on Mac OS X:

Ronald Oussoren

2008-12-28 19:40:56 +0000

[diff] [blame]

1105

1106

* ``macosx-10.3-ppc``

1107

1108

* ``macosx-10.3-fat``

1109

1110

* ``macosx-10.5-universal``

1111

Georg Brandl

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

[diff] [blame]

1112

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

1113

1114

1115

.. function:: convert_path(pathname)

1116

1117

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

1118

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

1119

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

1120

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

1121

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

1122

*pathname* either starts or ends with a slash.

1123

1124

1125

.. function:: change_root(new_root, pathname)

1126

1127

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

1128

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

1129

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

1130

1131

1132

.. function:: check_environ()

1133

1134

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

1135

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

1136

includes:

1137

1138

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

1139

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

1140

OS (see :func:`get_platform`)

1141

1142

1143

.. function:: subst_vars(s, local_vars)

1144

1145

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

1146

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

1147

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

1148

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

1149

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

1150

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

1151

1152

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

1153

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

1154

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

1155

1156

1157

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

1158

1159

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

1160

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

1161

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

1162

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

1163

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

1164

prefixed with *prefix*.

1165

1166

1167

.. function:: split_quoted(s)

1168

1169

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

1170

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

1171

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

1172

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

1173

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

1174

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

1175

list of words.

1176

1177

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

1178

1179

1180

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

1181

1182

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

1183

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

1184

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

1185

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

1186

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

1187

1188

1189

.. function:: strtobool(val)

1190

1191

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

1192

1193

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

1194

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

1195

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

1196

1197

1198

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

1199

1200

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

1201

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

1202

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

1203

*optimize* must be one of the following:

1204

1205

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

1206

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

1207

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

1208

1209

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

1210

Georg Brandl

5e52db0

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

[diff] [blame]

1211

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

Georg Brandl

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

[diff] [blame]

1212

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

1213

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

1214

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

1215

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

1216

*base_dir*, as you wish.

1217

1218

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

1219

filesystem.

1220

1221

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

1222

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

1223

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

1224

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

1225

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

1226

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

1227

1228

1229

.. function:: rfc822_escape(header)

1230

1231

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

1232

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

1233

modification of the string.

1234

1235

.. % this _can_ be replaced

1236

1237

.. % \subsection{Distutils objects}

1238

1239

1240

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

1241

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

1242

1243

.. module:: distutils.dist

1244

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

1245

built/installed/distributed

1246

1247

1248

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

1249

module distribution being built/installed/distributed.

1250

1251

1252

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

1253

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

1254

1255

.. module:: distutils.extension

1256

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

1261

extension modules in setup scripts.

1262

1263

.. % \subsection{Ungrouped modules}

1264

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

1265

1266

1267

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

1268

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

1269

1270

.. module:: distutils.debug

1271

:synopsis: Provides the debug flag for distutils

1272

1273

1274

This module provides the DEBUG flag.

1275

1276

1277

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

1278

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

1279

1280

.. module:: distutils.errors

1281

:synopsis: Provides standard distutils exceptions

1282

1283

1284

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

1285

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

1286

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

1287

1288

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

1289

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

1290

1291

1292

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

1293

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

1294

1295

.. module:: distutils.fancy_getopt

1296

:synopsis: Additional getopt functionality

1297

1298

1299

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

1300

provides the following additional features:

1301

1302

* short and long options are tied together

1303

1304

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

1305

complete usage summary

1306

1307

* options set attributes of a passed-in object

1308

1309

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

1310

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

1311

command line sets *verbose* to false.

1312

1313

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

1314

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

1315

1316

1317

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

1318

1319

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

1320

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

1321

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

1322

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

1323

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

1324

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

1325

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

1326

1327

1328

.. function:: wrap_text(text, width)

1329

1330

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

.. warning::

Should be replaced with :mod:`textwrap` (which is available in Python 2.3 and

later).

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

1339

1340

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

1341

help_string)``

1342

1343

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

1344

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

1345

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

1346

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

1347

1348

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

1349

1350

1351

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

1352

1353

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

1354

1355

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

1356

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

1357

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

1358

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

1359

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

1360

which is left untouched.

1361

1362

.. % and args returned are?

1363

1364

1365

.. method:: FancyGetopt.get_option_order()

1366

1367

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

1368

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

yet.

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

1373

1374

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

1375

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

1376

1377

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

1378

1379

1380

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

1381

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

1382

1383

.. module:: distutils.filelist

1384

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

files.

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

1389

filesystem and building lists of files.

1390

1391

1392

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

1393

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

1394

1395

.. module:: distutils.log

1396

:synopsis: A simple logging mechanism, 282-style

.. warning::

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

1402

1403

.. % \subsubsection{\module{} --- }

1404

.. % \declaremodule{standard}{distutils.magic}

1405

.. % \modulesynopsis{ }

1406

1407

1408

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

1409

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

1410

1411

.. module:: distutils.spawn

1412

:synopsis: Provides the spawn() function

1413

1414

1415

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

1416

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

1417

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

name.

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

1422

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

1423

1424

.. module:: distutils.sysconfig

1425

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

1426

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

1427

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

1428

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

1429

1430

1431

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

1432

configuration information. The specific configuration variables available

1433

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

1434

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

1435

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

1436

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

1437

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

1438

for earlier versions of Python.

1439

1440

Some additional functions are provided which perform some useful manipulations

1441

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

.. data:: PREFIX

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

1447

1448

1449

.. data:: EXEC_PREFIX

1450

1451

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

1452

1453

1454

.. function:: get_config_var(name)

1455

1456

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

1457

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

1458

1459

1460

.. function:: get_config_vars(...)

1461

1462

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

1463

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

1464

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

1465

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

1466

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

1467

1468

1469

.. function:: get_config_h_filename()

1470

1471

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

1472

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

1473

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

1474

file is a platform-specific text file.

1475

1476

1477

.. function:: get_makefile_filename()

1478

1479

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

1480

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

1481

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

1482

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

1483

1484

1485

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

1486

1487

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

1488

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

1489

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

1490

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

1491

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

1492

*plat_specific* is true.

1493

1494

1495

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

1496

1497

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

1498

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

1499

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

1500

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

1501

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

1502

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

1503

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

1504

third-party extensions.

1505

1506

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

package.

.. function:: customize_compiler(compiler)

1511

1512

Do any platform-specific customization of a

1513

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

1514

1515

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

1516

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

1517

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

1518

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

1519

extension used by the linker for shared objects.

1520

1521

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

1522

Python's own build procedures.

1523

1524

1525

.. function:: set_python_build()

1526

1527

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

1528

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

1529

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

Python.

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

1534

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

1535

1536

.. module:: distutils.text_file

1537

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

1538

1539

1540

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

1541

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

1542

lines, and joining lines with backslashes.

1543

1544

1545

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

1546

1547

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

1548

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

1549

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

1550

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

1551

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

1552

independently controllable.

1553

1554

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

1555

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

1556

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

1557

line-at-a-time lookahead.

1558

1559

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

1560

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

1561

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

1562

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

1563

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

1564

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

1565

:func:`open` built-in function.

1566

1567

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

1568

1569

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

1570

| option name | description | default |

1571

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

1572

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

1573

| | line, as well as any | |

1574

| | whitespace leading up to the | |

1575

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

1576

| | escaped by a backslash | |

1577

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

1578

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

1579

| | each line before returning it | |

1580

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

1581

| *rstrip_ws* | strip trailing whitespace | true |

1582

| | (including line terminator!) | |

1583

| | from each line before | |

1584

| | returning it. | |

1585

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

1586

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

1587

| | \*after\* stripping comments | |

1588

| | and whitespace. (If both | |

1589

| | lstrip_ws and rstrip_ws are | |

1590

| | false, then some lines may | |

1591

| | consist of solely whitespace: | |

1592

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

1593

| | even if *skip_blanks* is | |

1594

| | true.) | |

1595

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

1596

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

1597

| | non-newline character on a | |

1598

| | line after stripping comments | |

1599

| | and whitespace, join the | |

1600

| | following line to it to form | |

1601

| | one logical line; if N | |

1602

| | consecutive lines end with a | |

1603

| | backslash, then N+1 physical | |

1604

| | lines will be joined to form | |

1605

| | one logical line. | |

1606

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

1607

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

1608

| | lines that are joined to their | |

1609

| | predecessor; only matters if | |

1610

| | ``(join_lines and not | |

1611

| | lstrip_ws)`` | |

1612

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

1613

1614

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

1615

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

1616

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

1617

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

1618

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

1619

1620

1621

.. method:: TextFile.open(filename)

1622

1623

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

arguments.

.. method:: TextFile.close()

1628

1629

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

1630

filename and the current line number).

1631

1632

1633

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

1634

1635

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

1636

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

1637

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

1638

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

1639

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

physical line.

.. method:: TextFile.readline()

1644

1645

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

1646

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

1647

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

1648

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

1649

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

1650

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

1651

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

1652

1653

1654

.. method:: TextFile.readlines()

1655

1656

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

1657

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

1658

1659

1660

.. method:: TextFile.unreadline(line)

1661

1662

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

1663

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

1664

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

1665

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

1666

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

1667

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

1668

1669

1670

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

1671

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

1672

1673

.. module:: distutils.version

1674

:synopsis: implements classes that represent module version numbers.

.. % todo

.. % \section{Distutils Commands}

Georg Brandl

2009-01-03 20:55:06 +0000

[diff] [blame]

1679

.. %

Georg Brandl

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

[diff] [blame]

1680

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

1681

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

1682

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

1683

1684

1685

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

1686

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

1687

1688

.. module:: distutils.cmd

1689

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

1690

by the modules in the distutils.command subpackage.

1691

1692

1693

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

1694

1695

1696

.. class:: Command(dist)

1697

1698

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

1699

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

1700

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

1701

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

1702

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

1703

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

1704

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

1705

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

1706

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

1707

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

1708

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

1709

1710

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

instance.

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

1715

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

1716

1717

.. module:: distutils.command

1718

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

1719

1720

1721

.. % \subsubsection{Individual Distutils commands}

.. % todo

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

1726

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

1727

1728

.. module:: distutils.command.bdist

1729

:synopsis: Build a binary installer for a package

.. % todo

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

1736

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

1737

1738

.. module:: distutils.command.bdist_packager

1739

:synopsis: Abstract base class for packagers

.. % todo

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

1746

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

1747

1748

.. module:: distutils.command.bdist_dumb

1749

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

.. % todo

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

1756

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

1757

1758

.. module:: distutils.command.bdist_msi

1759

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

1760

Georg Brandl

95fafec

2009-03-31 22:03:40 +0000

[diff] [blame]

1761

.. class:: bdist_msi(Command)

Georg Brandl

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

[diff] [blame]

1762

Georg Brandl

95fafec

2009-03-31 22:03:40 +0000

[diff] [blame]

1763

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

1764

1765

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

1766

1767

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

1768

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

1769

Win64 platforms, allows administrators to perform non-interactive

1770

installations, and allows installation through group policies.

Georg Brandl