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

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

[diff] [blame]

758

.. %

Georg Brandl

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

[diff] [blame]

759

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

760

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

761

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

.. % function.

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

766

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

767

768

.. module:: distutils.unixccompiler

769

:synopsis: UNIX C Compiler

770

771

772

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

773

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

774

775

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

776

777

* macros undefined with :option:`-Uname`

778

779

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

780

781

* libraries specified with :option:`-llib`

782

783

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

784

785

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

786

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

787

788

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

789

:program:`ranlib`)

790

791

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

792

793

794

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

795

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

796

797

.. module:: distutils.msvccompiler

798

:synopsis: Microsoft Compiler

799

800

801

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

802

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

803

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

804

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

805

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

806

binaries are created using the Platform SDK.

807

808

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

809

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

810

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

811

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

812

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

813

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

814

selection by :class:`MSVCCompiler`.

815

816

817

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

818

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

819

820

.. module:: distutils.bcppcompiler

821

822

823

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

824

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

825

826

827

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

828

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

829

830

.. module:: distutils.cygwinccompiler

831

832

833

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

834

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

835

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

836

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

837

838

839

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

840

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

841

842

.. module:: distutils.emxccompiler

843

:synopsis: OS/2 EMX Compiler support

844

845

846

This module provides the EMXCCompiler class, a subclass of

847

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

848

849

850

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

851

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

852

853

.. module:: distutils.mwerkscompiler

854

:synopsis: Metrowerks CodeWarrior support

855

856

857

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

858

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

859

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

860

861

.. % \subsection{Utility modules}

Georg Brandl

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

[diff] [blame]

862

.. %

Georg Brandl

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

[diff] [blame]

863

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

864

.. % all been documented yet.

865

866

867

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

868

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

869

870

.. module:: distutils.archive_util

871

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

872

873

874

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

875

tarballs or zipfiles.

876

877

878

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

879

880

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

881

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

882

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

883

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

884

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

885

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

886

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

887

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

888

Georg Brandl

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

[diff] [blame]

889

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

Georg Brandl

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

[diff] [blame]

890

891

892

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

893

894

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

895

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

896

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

897

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

898

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

899

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

900

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

901

Georg Brandl

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

[diff] [blame]

902

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

Georg Brandl

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

[diff] [blame]

903

904

905

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

906

907

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

908

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

909

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

910

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

911

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

912

913

914

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

915

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

916

917

.. module:: distutils.dep_util

918

:synopsis: Utility functions for simple dependency checking

919

920

921

This module provides functions for performing simple, timestamp-based

922

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

923

timestamp dependency analysis.

924

925

926

.. function:: newer(source, target)

927

928

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

929

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

930

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

931

*source* does not exist.

932

933

934

.. function:: newer_pairwise(sources, targets)

935

936

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

937

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

938

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

939

940

.. % % equivalent to a listcomp...

941

942

943

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

944

945

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

946

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

947

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

948

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

949

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

950

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

951

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

952

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

953

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

the commands).

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

958

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

959

960

.. module:: distutils.dir_util

961

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

962

963

964

This module provides functions for operating on directories and trees of

directories.

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

969

970

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

971

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

972

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

973

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

974

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

975

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

976

directories actually created.

977

978

979

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

980

981

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

982

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

983

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

984

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

985

it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for

:func:`mkpath`.

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

990

991

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

992

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

993

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

994

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

995

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

996

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

997

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

998

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

999

*dst*.

1000

1001

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

1002

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

1003

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

1004

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

1005

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

1006

as for :func:`copy_file`.

1007

1008

1009

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

1010

1011

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

1012

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

1013

true).

1014

1015

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

1016

1017

1018

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

1019

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

1020

1021

.. module:: distutils.file_util

1022

:synopsis: Utility functions for operating on single files

1023

1024

1025

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

1026

1027

1028

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

1029

1030

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

1031

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

1032

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

1033

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

1034

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

1035

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

1036

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

1037

is older than *src*.

1038

1039

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

1040

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

1041

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

1042

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

1043

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

1044

contents.

1045

1046

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

1047

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

1048

copied, if *dry_run* true).

1049

1050

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

1051

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

1052

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

1053

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

1054

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

1055

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

1056

1057

1058

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

1059

1060

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

1061

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

1062

new full name of the file.

.. warning::

Georg Brandl

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

[diff] [blame]

1066

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

1067

other systems?

Georg Brandl

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

[diff] [blame]

1068

1069

1070

.. function:: write_file(filename, contents)

1071

1072

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

1073

without line terminators) to it.

1074

1075

1076

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

1077

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

1078

1079

.. module:: distutils.util

1080

:synopsis: Miscellaneous other utility functions

1081

1082

1083

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

1084

other utility module.

1085

1086

1087

.. function:: get_platform()

1088

1089

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

1090

distinguish platform-specific build directories and platform-specific built

1091

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

1092

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

1093

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

1094

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

1095

important.

1096

1097

Examples of returned values:

* ``linux-i586``

* ``linux-alpha``

* ``solaris-2.6-sun4u``

* ``irix-5.3``

* ``irix64-6.2``

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

1106

Georg Brandl

e9b9121

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

[diff] [blame]

1107

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

Georg Brandl

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

[diff] [blame]

1108

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

Georg Brandl

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

[diff] [blame]

1109

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

Georg Brandl

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

[diff] [blame]

1110

Georg Brandl

e9b9121

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

[diff] [blame]

1111

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

Georg Brandl

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

[diff] [blame]

1112

the univeral binary status instead of the architecture of the current

Georg Brandl

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

[diff] [blame]

1113

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

1114

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

Ronald Oussoren

cba2fd3

2009-09-15 19:14:37 +0000

[diff] [blame]

1115

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

1116

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

1117

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

1118

a univeral build with the i386 and x86_64 architectures

Georg Brandl

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

[diff] [blame]

1119

Georg Brandl

e9b9121

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

[diff] [blame]

1120

Examples of returned values on Mac OS X:

Georg Brandl

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

[diff] [blame]

1121

1122

* ``macosx-10.3-ppc``

1123

1124

* ``macosx-10.3-fat``

1125

1126

* ``macosx-10.5-universal``

1127

Ronald Oussoren

cba2fd3

2009-09-15 19:14:37 +0000

[diff] [blame]

1128

* ``macosx-10.6-intel``

1129

Georg Brandl

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

[diff] [blame]

1130

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

1131

1132

1133

.. function:: convert_path(pathname)

1134

1135

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

1136

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

1137

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

1138

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

1139

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

1140

*pathname* either starts or ends with a slash.

1141

1142

1143

.. function:: change_root(new_root, pathname)

1144

1145

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

1146

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

1147

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

1148

1149

1150

.. function:: check_environ()

1151

1152

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

1153

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

1154

includes:

1155

1156

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

1157

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

1158

OS (see :func:`get_platform`)

1159

1160

1161

.. function:: subst_vars(s, local_vars)

1162

1163

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

1164

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

1165

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

1166

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

1167

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

1168

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

1169

1170

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

1171

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

1172

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

1173

1174

1175

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

1176

1177

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

1178

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

1179

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

1180

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

1181

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

1182

prefixed with *prefix*.

1183

1184

1185

.. function:: split_quoted(s)

1186

1187

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

1188

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

1189

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

1190

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

1191

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

1192

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

1193

list of words.

1194

1195

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

1196

1197

1198

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

1199

1200

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

1201

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

1202

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

1203

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

1204

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

1205

1206

1207

.. function:: strtobool(val)

1208

1209

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

1210

1211

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

1212

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

1213

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

1214

1215

1216

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

1217

1218

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

1219

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

1220

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

1221

*optimize* must be one of the following:

1222

1223

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

1224

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

1225

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

1226

1227

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

1228

Georg Brandl

5e52db0

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

[diff] [blame]

1229

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

Georg Brandl

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

[diff] [blame]

1230

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

1231

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

1232

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

1233

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

1234

*base_dir*, as you wish.

1235

1236

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

1237

filesystem.

1238

1239

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

1240

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

1241

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

1242

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

1243

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

1244

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

1245

1246

1247

.. function:: rfc822_escape(header)

1248

1249

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

1250

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

1251

modification of the string.

1252

1253

.. % this _can_ be replaced

1254

1255

.. % \subsection{Distutils objects}

1256

1257

1258

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

1259

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

1260

1261

.. module:: distutils.dist

1262

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

1263

built/installed/distributed

1264

1265

1266

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

1267

module distribution being built/installed/distributed.

1268

1269

1270

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

1271

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

1272

1273

.. module:: distutils.extension

1274

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

1279

extension modules in setup scripts.

1280

1281

.. % \subsection{Ungrouped modules}

1282

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

1283

1284

1285

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

1286

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

1287

1288

.. module:: distutils.debug

1289

:synopsis: Provides the debug flag for distutils

1290

1291

1292

This module provides the DEBUG flag.

1293

1294

1295

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

1296

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

1297

1298

.. module:: distutils.errors

1299

:synopsis: Provides standard distutils exceptions

1300

1301

1302

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

1303

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

1304

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

1305

1306

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

1307

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

1308

1309

1310

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

1311

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

1312

1313

.. module:: distutils.fancy_getopt

1314

:synopsis: Additional getopt functionality

1315

1316

1317

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

1318

provides the following additional features:

1319

1320

* short and long options are tied together

1321

1322

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

1323

complete usage summary

1324

1325

* options set attributes of a passed-in object

1326

1327

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

1328

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

1329

command line sets *verbose* to false.

1330

1331

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

1332

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

1333

1334

1335

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

1336

1337

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

1338

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

1339

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

1340

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

1341

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

1342

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

1343

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

1344

1345

1346

.. function:: wrap_text(text, width)

1347

1348

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

1349

Georg Brandl

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

[diff] [blame]

1350

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

1351

2.3 and later).

Georg Brandl

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

[diff] [blame]

1352

1353

1354

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

1355

1356

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

1357

help_string)``

1358

1359

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

1360

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

1361

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

1362

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

1363

1364

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

1365

1366

1367

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

1368

1369

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

1370

1371

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

1372

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

1373

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

1374

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

1375

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

1376

which is left untouched.

1377

1378

.. % and args returned are?

1379

1380

1381

.. method:: FancyGetopt.get_option_order()

1382

1383

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

1384

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

yet.

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

1389

1390

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

1391

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

1392

1393

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

1394

1395

1396

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

1397

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

1398

1399

.. module:: distutils.filelist

Georg Brandl

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

[diff] [blame]

1400

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

1401

building lists of files.

Georg Brandl

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

[diff] [blame]

1402

1403

1404

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

1405

filesystem and building lists of files.

1406

1407

1408

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

1409

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

1410

1411

.. module:: distutils.log

1412

:synopsis: A simple logging mechanism, 282-style

1413

1414

Georg Brandl

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

[diff] [blame]

1415

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

Georg Brandl

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

[diff] [blame]

1416

Georg Brandl

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

[diff] [blame]

1417

1418

1419

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

1420

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

1421

1422

.. module:: distutils.spawn

1423

:synopsis: Provides the spawn() function

1424

1425

1426

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

1427

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

1428

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

name.

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

1433

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

1434

1435

.. module:: distutils.sysconfig

1436

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

1437

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

1438

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

1439

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

1440

1441

1442

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

1443

configuration information. The specific configuration variables available

1444

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

1445

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

1446

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

1447

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

1448

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

1449

for earlier versions of Python.

1450

1451

Some additional functions are provided which perform some useful manipulations

1452

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

.. data:: PREFIX

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

1458

1459

1460

.. data:: EXEC_PREFIX

1461

1462

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

1463

1464

1465

.. function:: get_config_var(name)

1466

1467

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

1468

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

1469

1470

1471

.. function:: get_config_vars(...)

1472

1473

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

1474

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

1475

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

1476

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

1477

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

1478

1479

1480

.. function:: get_config_h_filename()

1481

1482

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

1483

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

1484

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

1485

file is a platform-specific text file.

1486

1487

1488

.. function:: get_makefile_filename()

1489

1490

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

1491

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

1492

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

1493

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

1494

1495

1496

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

1497

1498

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

1499

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

1500

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

1501

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

1502

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

1503

*plat_specific* is true.

1504

1505

1506

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

1507

1508

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

1509

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

1510

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

1511

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

1512

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

1513

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

1514

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

1515

third-party extensions.

1516

1517

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

package.

.. function:: customize_compiler(compiler)

1522

1523

Do any platform-specific customization of a

1524

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

1525

1526

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

1527

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

1528

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

1529

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

1530

extension used by the linker for shared objects.

1531

1532

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

1533

Python's own build procedures.

1534

1535

1536

.. function:: set_python_build()

1537

1538

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

1539

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

1540

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

Python.

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

1545

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

1546

1547

.. module:: distutils.text_file

1548

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

1549

1550

1551

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

1552

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

1553

lines, and joining lines with backslashes.

1554

1555

1556

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

1557

1558

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

1559

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

1560

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

1561

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

1562

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

1563

independently controllable.

1564

1565

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

1566

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

1567

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

1568

line-at-a-time lookahead.

1569

1570

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

1571

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

1572

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

1573

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

1574

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

1575

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

1576

:func:`open` built-in function.

1577

1578

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

1579

1580

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

1581

| option name | description | default |

1582

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

1583

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

1584

| | line, as well as any | |

1585

| | whitespace leading up to the | |

1586

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

1587

| | escaped by a backslash | |

1588

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

1589

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

1590

| | each line before returning it | |

1591

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

1592

| *rstrip_ws* | strip trailing whitespace | true |

1593

| | (including line terminator!) | |

1594

| | from each line before | |

1595

| | returning it. | |

1596

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

1597

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

1598

| | \*after\* stripping comments | |

1599

| | and whitespace. (If both | |

1600

| | lstrip_ws and rstrip_ws are | |

1601

| | false, then some lines may | |

1602

| | consist of solely whitespace: | |

1603

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

1604

| | even if *skip_blanks* is | |

1605

| | true.) | |

1606

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

1607

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

1608

| | non-newline character on a | |

1609

| | line after stripping comments | |

1610

| | and whitespace, join the | |

1611

| | following line to it to form | |

1612

| | one logical line; if N | |

1613

| | consecutive lines end with a | |

1614

| | backslash, then N+1 physical | |

1615

| | lines will be joined to form | |

1616

| | one logical line. | |

1617

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

1618

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

1619

| | lines that are joined to their | |

1620

| | predecessor; only matters if | |

1621

| | ``(join_lines and not | |

1622

| | lstrip_ws)`` | |

1623

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

1624

1625

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

Georg Brandl

4ae4f87

2009-10-27 14:37:48 +0000

[diff] [blame]

1626

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

Georg Brandl

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

[diff] [blame]

1627

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

1628

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

1629

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

1630

1631

1632

.. method:: TextFile.open(filename)

1633

Georg Brandl

4ae4f87

2009-10-27 14:37:48 +0000

[diff] [blame]

1634

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

1635

constructor arguments.

Georg Brandl

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

[diff] [blame]

1636

1637

1638

.. method:: TextFile.close()

1639

1640

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

1641

filename and the current line number).

1642

1643

1644

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

1645

1646

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

1647

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

1648

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

1649

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

1650

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

physical line.

.. method:: TextFile.readline()

1655

1656

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

1657

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

1658

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

1659

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

1660

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

1661

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

1662

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

1663

1664

1665

.. method:: TextFile.readlines()

1666

1667

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

1668

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

1669

1670

1671

.. method:: TextFile.unreadline(line)

1672

1673

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

1674

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

1675

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

1676

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

1677

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

1678

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

1679

1680

1681

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

1682

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

1683

1684

.. module:: distutils.version

1685

:synopsis: implements classes that represent module version numbers.

.. % todo

.. % \section{Distutils Commands}

Georg Brandl

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

[diff] [blame]

1690

.. %

Georg Brandl

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

[diff] [blame]

1691

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

1692

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

1693

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

1694

1695

1696

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

1697

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

1698

1699

.. module:: distutils.cmd

1700

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

1701

by the modules in the distutils.command subpackage.

1702

1703

1704

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

1705

1706

1707

.. class:: Command(dist)

1708

1709

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

1710

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

1711

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

1712

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

1713

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

1714

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

1715

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

1716

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

1717

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

1718

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

1719

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

1720

1721

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

instance.

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

1726

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

1727

1728

.. module:: distutils.command

1729

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

1730

1731

1732

.. % \subsubsection{Individual Distutils commands}

.. % todo

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

1737

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

1738

1739

.. module:: distutils.command.bdist

1740

:synopsis: Build a binary installer for a package

.. % todo

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

1747

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

1748

1749

.. module:: distutils.command.bdist_packager

1750

:synopsis: Abstract base class for packagers

.. % todo

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

1757

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

1758

1759

.. module:: distutils.command.bdist_dumb

1760

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

.. % todo

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

1767

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

1768

1769

.. module:: distutils.command.bdist_msi

1770

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

1771

Georg Brandl

9b08e05

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

[diff] [blame]

1772

.. class:: bdist_msi(Command)

Georg Brandl

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

[diff] [blame]

1773

Georg Brandl

9b08e05

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

[diff] [blame]

1774

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

1775

1776

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

1777

1778

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

1779

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

1780

Win64 platforms, allows administrators to perform non-interactive

1781

installations, and allows installation through group policies.

Georg Brandl

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

[diff] [blame]

1782

1783

1784

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

1785

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

1786

1787

.. module:: distutils.command.bdist_rpm

1788

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

.. % todo

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

1795

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

1796

1797

.. module:: distutils.command.bdist_wininst

1798

:synopsis: Build a Windows installer

.. % todo

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

1805

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

1806

1807

.. module:: distutils.command.sdist

1808

:synopsis: Build a source distribution

.. % todo

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

1815

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

1816

1817

.. module:: distutils.command.build

1818

:synopsis: Build all files of a package

.. % todo

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

1825

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

1826

1827

.. module:: distutils.command.build_clib

1828

:synopsis: Build any C libraries in a package

.. % todo

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

1835

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

1836

1837

.. module:: distutils.command.build_ext

1838

:synopsis: Build any extensions in a package

.. % todo

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

1845

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

1846

1847

.. module:: distutils.command.build_py

1848

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

.. % todo

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

1855

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

1856

1857

.. module:: distutils.command.build_scripts

1858

:synopsis: Build the scripts of a package

.. % todo

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

1865

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

1866

1867

.. module:: distutils.command.clean

1868

:synopsis: Clean a package build area

.. % todo

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

1875

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

1876

1877

.. module:: distutils.command.config

1878

:synopsis: Perform package configuration

.. % todo

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

1885

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

1886

1887

.. module:: distutils.command.install

1888

:synopsis: Install a package

.. % todo

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

1895

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

1896

1897

.. module:: distutils.command.install_data

1898

:synopsis: Install data files from a package

.. % todo

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

1905

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

1906

1907

.. module:: distutils.command.install_headers

1908

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

.. % todo

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

1915

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

1916

1917

.. module:: distutils.command.install_lib

1918

:synopsis: Install library files from a package

.. % todo

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

1925

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

1926

1927

.. module:: distutils.command.install_scripts

1928

:synopsis: Install script files from a package

.. % todo

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

1935

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

1936

1937

.. module:: distutils.command.register

1938

:synopsis: Register a module with the Python Package Index

1939

1940

1941

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

1942

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

.. % todo

Creating a new Distutils command

1948

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

1949

1950

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

1951

1952

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

1953

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

1954

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

1955

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

1956

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

1957

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

1958

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

1959

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

1960

:class:`distutils.cmd.Command`.

1961

1962

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

1963

1964

Georg Brandl

a7fef6a

2009-10-27 15:10:48 +0000

[diff] [blame^]

1965

.. method:: Command.initialize_options()

Georg Brandl

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

[diff] [blame]

1966

Georg Brandl

a7fef6a

2009-10-27 15:10:48 +0000

[diff] [blame^]

1967

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

Georg Brandl