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

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

[diff] [blame]

760

.. %

Georg Brandl

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

[diff] [blame]

761

.. % The following modules implement concrete subclasses of the abstract

762

.. % \class{CCompiler} class. They should not be instantiated directly, but should

763

.. % be created using \function{distutils.ccompiler.new_compiler()} factory

.. % function.

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

768

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

769

770

.. module:: distutils.unixccompiler

771

:synopsis: UNIX C Compiler

772

773

774

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

775

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

776

777

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

778

779

* macros undefined with :option:`-Uname`

780

781

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

782

783

* libraries specified with :option:`-llib`

784

785

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

786

787

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

788

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

789

790

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

791

:program:`ranlib`)

792

793

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

794

795

796

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

797

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

798

799

.. module:: distutils.msvccompiler

800

:synopsis: Microsoft Compiler

801

802

803

This module provides :class:`MSVCCompiler`, an implementation of the abstract

804

:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension

805

modules need to be compiled with the same compiler that was used to compile

806

Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python

807

2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium

808

binaries are created using the Platform SDK.

809

810

:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on

811

its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*

812

and *MSSdk* must be both set. *MSSdk* indicates that the current environment has

813

been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables

814

had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates

815

that the distutils user has made an explicit choice to override the compiler

816

selection by :class:`MSVCCompiler`.

817

818

819

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

820

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

821

822

.. module:: distutils.bcppcompiler

823

824

825

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

826

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

827

828

829

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

830

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

831

832

.. module:: distutils.cygwinccompiler

833

834

835

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

836

:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to

837

Windows. It also contains the Mingw32CCompiler class which handles the mingw32

838

port of GCC (same as cygwin in no-cygwin mode).

839

840

841

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

842

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

843

844

.. module:: distutils.emxccompiler

845

:synopsis: OS/2 EMX Compiler support

846

847

848

This module provides the EMXCCompiler class, a subclass of

849

:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.

850

851

Georg Brandl

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

[diff] [blame]

852

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

853

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

854

855

.. module:: distutils.archive_util

856

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

857

858

859

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

860

tarballs or zipfiles.

861

862

863

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

864

865

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

866

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

867

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

868

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

869

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

870

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

871

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

872

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

873

Georg Brandl

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

[diff] [blame]

874

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

Georg Brandl

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

[diff] [blame]

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.

886

Georg Brandl

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

[diff] [blame]

887

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

Georg Brandl

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

[diff] [blame]

888

889

890

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

891

892

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

893

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

894

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

895

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

896

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

897

898

899

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

900

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

901

902

.. module:: distutils.dep_util

903

:synopsis: Utility functions for simple dependency checking

904

905

906

This module provides functions for performing simple, timestamp-based

907

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

908

timestamp dependency analysis.

909

910

911

.. function:: newer(source, target)

912

913

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

914

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

915

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

916

*source* does not exist.

917

918

919

.. function:: newer_pairwise(sources, targets)

920

921

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

922

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

923

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

924

925

.. % % equivalent to a listcomp...

926

927

928

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

929

930

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

931

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

932

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

933

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

934

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

935

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

936

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

937

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

938

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

the commands).

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

943

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

944

945

.. module:: distutils.dir_util

946

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

947

948

949

This module provides functions for operating on directories and trees of

directories.

Georg Brandl

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

[diff] [blame]

953

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

Georg Brandl

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

[diff] [blame]

954

955

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

956

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

957

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

958

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

959

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

960

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

961

directories actually created.

962

963

Georg Brandl

f4a4123

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

[diff] [blame]

964

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

Georg Brandl

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

[diff] [blame]

965

966

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

967

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

968

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

969

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

970

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

975

976

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

977

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

978

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

979

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

980

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

981

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

982

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

983

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

984

*dst*.

985

986

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

987

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

988

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

989

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

990

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

991

as for :func:`copy_file`.

992

993

994

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

995

996

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

997

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

998

true).

999

Georg Brandl

b913784

2010-07-07 19:04:36 +0000

[diff] [blame]

1000

.. XXX Some of this could be replaced with the shutil module?

Georg Brandl

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

[diff] [blame]

1001

1002

1003

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

1004

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

1005

1006

.. module:: distutils.file_util

1007

:synopsis: Utility functions for operating on single files

1008

1009

1010

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

1011

1012

1013

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

1014

1015

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

1016

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

1017

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

1018

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

1019

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

1020

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

1021

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

1022

is older than *src*.

1023

1024

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

1025

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

1026

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

1027

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

1028

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

1029

contents.

1030

1031

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

1032

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

1033

copied, if *dry_run* true).

1034

1035

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

1036

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

1037

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

1038

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

1039

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

1040

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

1041

1042

1043

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

1044

1045

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

1046

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

1047

new full name of the file.

.. warning::

Benjamin Peterson

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

[diff] [blame]

1051

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

1052

other systems?

Georg Brandl

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

[diff] [blame]

1053

1054

1055

.. function:: write_file(filename, contents)

1056

1057

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

1058

without line terminators) to it.

1059

1060

1061

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

1062

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

1063

1064

.. module:: distutils.util

1065

:synopsis: Miscellaneous other utility functions

1066

1067

1068

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

1069

other utility module.

1070

1071

1072

.. function:: get_platform()

1073

1074

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

1075

distinguish platform-specific build directories and platform-specific built

1076

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

1077

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

1078

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

1079

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

1080

important.

1081

1082

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

1091

Benjamin Peterson

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

[diff] [blame]

1092

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

Benjamin Peterson

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

[diff] [blame]

1093

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

Georg Brandl

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

[diff] [blame]

1094

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

Benjamin Peterson

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

[diff] [blame]

1095

Benjamin Peterson

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

[diff] [blame]

1096

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

Benjamin Peterson

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

[diff] [blame]

1097

the univeral binary status instead of the architecture of the current

Georg Brandl

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

[diff] [blame]

1098

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

1099

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

Ronald Oussoren

bea37ae

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

[diff] [blame]

1100

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

1101

from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for

1102

a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for

1103

a univeral build with the i386 and x86_64 architectures

Benjamin Peterson

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

[diff] [blame]

1104

Benjamin Peterson

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

[diff] [blame]

1105

Examples of returned values on Mac OS X:

Benjamin Peterson

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

[diff] [blame]

1106

1107

* ``macosx-10.3-ppc``

1108

1109

* ``macosx-10.3-fat``

1110

1111

* ``macosx-10.5-universal``

1112

Ronald Oussoren

bea37ae

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

[diff] [blame]

1113

* ``macosx-10.6-intel``

1114

Georg Brandl

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

[diff] [blame]

1115

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

1116

1117

1118

.. function:: convert_path(pathname)

1119

1120

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

1121

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

1122

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

1123

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

1124

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

1125

*pathname* either starts or ends with a slash.

1126

1127

1128

.. function:: change_root(new_root, pathname)

1129

1130

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

1131

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

1132

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

1133

1134

1135

.. function:: check_environ()

1136

1137

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

1138

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

1139

includes:

1140

1141

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

1142

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

1143

OS (see :func:`get_platform`)

1144

1145

1146

.. function:: subst_vars(s, local_vars)

1147

1148

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

1149

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

1150

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

1151

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

1152

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

1153

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

1154

1155

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

1156

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

1157

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

1158

1159

1160

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

1161

1162

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

1163

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

1164

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

1165

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

1166

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

1167

prefixed with *prefix*.

1168

1169

1170

.. function:: split_quoted(s)

1171

1172

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

1173

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

1174

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

1175

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

1176

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

1177

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

1178

list of words.

1179

1180

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

1181

1182

1183

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

1184

1185

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

1186

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

1187

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

1188

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

1189

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

1190

1191

1192

.. function:: strtobool(val)

1193

1194

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

1195

1196

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

1197

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

1198

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

1199

1200

1201

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

1202

1203

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

1204

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

1205

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

1206

*optimize* must be one of the following:

1207

1208

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

1209

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

1210

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

1211

1212

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

1213

Georg Brandl

9afde1c

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

[diff] [blame]

1214

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

Georg Brandl

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

[diff] [blame]

1215

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

1216

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

1217

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

1218

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

1219

*base_dir*, as you wish.

1220

1221

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

1222

filesystem.

1223

1224

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

1225

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

1226

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

1227

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

1228

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

1229

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

1230

1231

1232

.. function:: rfc822_escape(header)

1233

1234

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

1235

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

1236

modification of the string.

1237

1238

.. % this _can_ be replaced

1239

1240

.. % \subsection{Distutils objects}

1241

1242

1243

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

1244

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

1245

1246

.. module:: distutils.dist

1247

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

1248

built/installed/distributed

1249

1250

1251

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

1252

module distribution being built/installed/distributed.

1253

1254

1255

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

1256

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

1257

1258

.. module:: distutils.extension

1259

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

1264

extension modules in setup scripts.

1265

1266

.. % \subsection{Ungrouped modules}

1267

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

1268

1269

1270

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

1271

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

1272

1273

.. module:: distutils.debug

1274

:synopsis: Provides the debug flag for distutils

1275

1276

1277

This module provides the DEBUG flag.

1278

1279

1280

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

1281

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

1282

1283

.. module:: distutils.errors

1284

:synopsis: Provides standard distutils exceptions

1285

1286

1287

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

1288

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

1289

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

1290

1291

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

1292

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

1293

1294

1295

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

1296

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

1297

1298

.. module:: distutils.fancy_getopt

1299

:synopsis: Additional getopt functionality

1300

1301

1302

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

1303

provides the following additional features:

1304

1305

* short and long options are tied together

1306

1307

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

1308

complete usage summary

1309

1310

* options set attributes of a passed-in object

1311

1312

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

1313

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

1314

command line sets *verbose* to false.

1315

Georg Brandl

b913784

2010-07-07 19:04:36 +0000

[diff] [blame]

1316

.. XXX Should be replaced with :mod:`optparse`.

Georg Brandl

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

[diff] [blame]

1317

1318

1319

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

1320

1321

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

1322

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

1323

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

1324

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

1325

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

1326

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

1327

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

1328

1329

1330

.. function:: wrap_text(text, width)

1331

1332

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

1333

Georg Brandl

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

[diff] [blame]

1334

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

1335

2.3 and later).

Georg Brandl

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

[diff] [blame]

1336

1337

1338

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

Georg Brandl

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

[diff] [blame]

1384

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

1385

building lists of files.

Georg Brandl

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

[diff] [blame]

1386

1387

1388

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

1397

1398

Georg Brandl

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

[diff] [blame]

1399

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

Georg Brandl

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

[diff] [blame]

1400

Georg Brandl

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

[diff] [blame]

1401

1402

1403

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

1404

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

1405

1406

.. module:: distutils.spawn

1407

:synopsis: Provides the spawn() function

1408

1409

1410

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

1411

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

1412

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

name.

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

1417

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

1418

1419

.. module:: distutils.sysconfig

1420

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

1421

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

1422

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

1423

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

1424

1425

1426

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

1427

configuration information. The specific configuration variables available

1428

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

1429

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

1430

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

1431

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

1432

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

1433

for earlier versions of Python.

1434

1435

Some additional functions are provided which perform some useful manipulations

1436

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

.. data:: PREFIX

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

1442

1443

1444

.. data:: EXEC_PREFIX

1445

1446

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

1447

1448

1449

.. function:: get_config_var(name)

1450

1451

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

1452

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

1453

1454

1455

.. function:: get_config_vars(...)

1456

1457

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

1458

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

1459

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

1460

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

1461

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

1462

1463

1464

.. function:: get_config_h_filename()

1465

1466

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

1467

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

1468

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

1469

file is a platform-specific text file.

1470

1471

1472

.. function:: get_makefile_filename()

1473

1474

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

1475

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

1476

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

1477

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

1478

1479

1480

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

1481

1482

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

1483

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

1484

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

1485

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

1486

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

1487

*plat_specific* is true.

1488

1489

1490

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

1491

1492

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

1493

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

1494

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

1495

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

1496

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

1497

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

1498

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

1499

third-party extensions.

1500

1501

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

package.

.. function:: customize_compiler(compiler)

1506

1507

Do any platform-specific customization of a

1508

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

1509

1510

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

1511

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

1512

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

1513

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

1514

extension used by the linker for shared objects.

1515

1516

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

1517

Python's own build procedures.

1518

1519

1520

.. function:: set_python_build()

1521

1522

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

1523

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

1524

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

Python.

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

1529

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

1530

1531

.. module:: distutils.text_file

1532

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

1533

1534

1535

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

1536

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

1537

lines, and joining lines with backslashes.

1538

1539

1540

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

1541

1542

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

1543

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

1544

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

1545

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

1546

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

1547

independently controllable.

1548

1549

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

1550

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

1551

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

1552

line-at-a-time lookahead.

1553

1554

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

1555

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

1556

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

1557

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

1558

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

1559

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

1560

:func:`open` built-in function.

1561

1562

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

1563

1564

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

1565

| option name | description | default |

1566

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

1567

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

1568

| | line, as well as any | |

1569

| | whitespace leading up to the | |

1570

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

1571

| | escaped by a backslash | |

1572

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

1573

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

1574

| | each line before returning it | |

1575

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

1576

| *rstrip_ws* | strip trailing whitespace | true |

1577

| | (including line terminator!) | |

1578

| | from each line before | |

1579

| | returning it. | |

1580

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

1581

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

1582

| | \*after\* stripping comments | |

1583

| | and whitespace. (If both | |

1584

| | lstrip_ws and rstrip_ws are | |

1585

| | false, then some lines may | |

1586

| | consist of solely whitespace: | |

1587

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

1588

| | even if *skip_blanks* is | |

1589

| | true.) | |

1590

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

1591

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

1592

| | non-newline character on a | |

1593

| | line after stripping comments | |

1594

| | and whitespace, join the | |

1595

| | following line to it to form | |

1596

| | one logical line; if N | |

1597

| | consecutive lines end with a | |

1598

| | backslash, then N+1 physical | |

1599

| | lines will be joined to form | |

1600

| | one logical line. | |

1601

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

1602

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

1603

| | lines that are joined to their | |

1604

| | predecessor; only matters if | |

1605

| | ``(join_lines and not | |

1606

| | lstrip_ws)`` | |

1607

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

1608

1609

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

Georg Brandl

22b3431

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

[diff] [blame]

1610

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

Georg Brandl

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

[diff] [blame]

1611

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

1612

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

1613

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

1614

1615

1616

.. method:: TextFile.open(filename)

1617

Georg Brandl

22b3431

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

[diff] [blame]

1618

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

1619

constructor arguments.

Georg Brandl

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

[diff] [blame]

1620

1621

1622

.. method:: TextFile.close()

1623

1624

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

1625

filename and the current line number).

1626

1627

1628

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

1629

1630

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

1631

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

1632

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

1633

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

1634

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

physical line.

.. method:: TextFile.readline()

1639

1640

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

1641

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

1642

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

1643

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

1644

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

1645

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

1646

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

1647

1648

1649

.. method:: TextFile.readlines()

1650

1651

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

1652

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

1653

1654

1655

.. method:: TextFile.unreadline(line)

1656

1657

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

1658

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

1659

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

1660

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

1661

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

1662

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

1663

1664

1665

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

1666

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

1667

1668

.. module:: distutils.version

1669

:synopsis: implements classes that represent module version numbers.

.. % todo

.. % \section{Distutils Commands}

Georg Brandl

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

[diff] [blame]

1674

.. %

Georg Brandl

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

[diff] [blame]

1675

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

1676

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

1677

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

1678

1679

1680

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

1681

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

1682

1683

.. module:: distutils.cmd

Georg Brandl

2010-07-11 10:22:44 +0000

[diff] [blame]

1684

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

1685

is subclassed by the modules in the distutils.command subpackage.

Georg Brandl

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

[diff] [blame]

1686

1687

1688

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

1689

1690

1691

.. class:: Command(dist)

1692

1693

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

1694

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

Georg Brandl

2010-07-11 10:22:44 +0000

[diff] [blame]

1695

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

1696

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

1697

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

1698

class. The distinction between the two is necessary because option values

1699

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

1700

options dependent on other options must be computed after these outside

1701

influences have been processed --- hence :meth:`finalize_options`. The body

1702

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

1703

options, is the :meth:`run` method, which must also be implemented by every

1704

command class.

Georg Brandl

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

[diff] [blame]

1705

Georg Brandl

2010-07-11 10:22:44 +0000

[diff] [blame]

1706

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

Georg Brandl

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

[diff] [blame]

instance.

Georg Brandl

2010-07-11 10:22:44 +0000

[diff] [blame]

1710

Creating a new Distutils command

1711

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

1712

1713

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

1714

1715

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

1716

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

1717

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

1718

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

1719

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

1720

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

1721

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

1722

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

1723

:class:`distutils.cmd.Command`.

1724

1725

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

1726

1727

.. method:: Command.initialize_options()

1728

1729

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

1730

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

1731

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

1732

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

1733

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

1734

1735

1736

.. method:: Command.finalize_options()

1737

1738

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

1739

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

1740

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

1741

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

1742

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

1743

assigned in :meth:`initialize_options`.

1744

1745

1746

.. method:: Command.run()

1747

Georg Brandl

49b31d0

2010-07-14 08:53:18 +0000

[diff] [blame]

1748

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

1749

controlled by the options initialized in :meth:`initialize_options`,

1750

customized by other commands, the setup script, the command-line, and config

1751

files, and finalized in :meth:`finalize_options`. All terminal output and

1752

filesystem interaction should be done by :meth:`run`.

Georg Brandl

2010-07-11 10:22:44 +0000

[diff] [blame]

1753

1754

1755

.. attribute:: Command.sub_commands

1756

1757

*sub_commands* formalizes the notion of a "family" of commands,

1758

e.g. ``install`` as the parent with sub-commands ``install_lib``,

1759

``install_headers``, etc. The parent of a family of commands defines

1760

*sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,

1761

predicate)``, with *command_name* a string and *predicate* a function, a

1762

string or ``None``. *predicate* is a method of the parent command that

1763

determines whether the corresponding command is applicable in the current

1764

situation. (E.g. we ``install_headers`` is only applicable if we have any C

1765

header files to install.) If *predicate* is ``None``, that command is always

1766

applicable.

1767

1768

*sub_commands* is usually defined at the *end* of a class, because

1769

predicates can be methods of the class, so they must already have been

1770

defined. The canonical example is the :command:`install` command.

1771

1772

Georg Brandl

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

[diff] [blame]

1773

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

1774

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

1775

1776

.. module:: distutils.command

1777

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

1778

1779

1780

.. % \subsubsection{Individual Distutils commands}

.. % todo

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

1785

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

1786

1787

.. module:: distutils.command.bdist

1788

:synopsis: Build a binary installer for a package

.. % todo

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

1795

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

1796

1797

.. module:: distutils.command.bdist_packager

1798

:synopsis: Abstract base class for packagers

.. % todo

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

1805

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

1806

1807

.. module:: distutils.command.bdist_dumb

1808

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

.. % todo

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

1815

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

1816

1817

.. module:: distutils.command.bdist_msi

1818

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

1819

Benjamin Peterson

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

[diff] [blame]

1820

.. class:: bdist_msi(Command)

Georg Brandl

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

[diff] [blame]

1821

Benjamin Peterson

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

[diff] [blame]

1822

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

1823

1824

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

1825

1826

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

1827

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

1828

Win64 platforms, allows administrators to perform non-interactive

1829

installations, and allows installation through group policies.

Georg Brandl

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

[diff] [blame]

1830

1831

1832

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

1833

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

1834

1835

.. module:: distutils.command.bdist_rpm

1836

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

.. % todo

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

1843

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

1844

1845

.. module:: distutils.command.bdist_wininst

1846

:synopsis: Build a Windows installer

.. % todo

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

1853

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

1854

1855

.. module:: distutils.command.sdist

1856

:synopsis: Build a source distribution

.. % todo

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

1863

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

1864

1865

.. module:: distutils.command.build

1866

:synopsis: Build all files of a package

.. % todo

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

1873

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

1874

1875

.. module:: distutils.command.build_clib

1876

:synopsis: Build any C libraries in a package

.. % todo

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

1883

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

1884

1885

.. module:: distutils.command.build_ext

1886

:synopsis: Build any extensions in a package

.. % todo

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

1893

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

1894

1895

.. module:: distutils.command.build_py

1896

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

1897

1898

Martin v. Löwis

73a22f0

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

[diff] [blame]

1899

.. class:: build_py(Command)

1900

1901

.. class:: build_py_2to3(build_py)

1902

1903

Alternative implementation of build_py which also runs the

1904

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

1905

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

1906

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

1907

1908

try:

1909

from distutils.command.build_py import build_py_2to3 as build_py

1910

except ImportError:

1911

from distutils.command.build_py import build_py

1912

1913

to your setup.py, and later::

1914

1915

cmdclass = {'build_py':build_py}

1916

1917

to the invocation of setup().

Georg Brandl