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

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

[diff] [blame]

763

.. %

Georg Brandl

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

[diff] [blame]

764

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

765

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

766

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

.. % function.

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

771

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

772

773

.. module:: distutils.unixccompiler

774

:synopsis: UNIX C Compiler

775

776

777

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

778

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

779

780

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

781

782

* macros undefined with :option:`-Uname`

783

784

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

785

786

* libraries specified with :option:`-llib`

787

788

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

789

790

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

791

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

792

793

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

794

:program:`ranlib`)

795

796

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

797

798

799

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

800

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

801

802

.. module:: distutils.msvccompiler

803

:synopsis: Microsoft Compiler

804

805

806

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

807

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

808

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

809

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

810

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

811

binaries are created using the Platform SDK.

812

813

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

814

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

815

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

816

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

817

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

818

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

819

selection by :class:`MSVCCompiler`.

820

821

822

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

823

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

824

825

.. module:: distutils.bcppcompiler

826

827

828

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

829

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

830

831

832

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

833

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

834

835

.. module:: distutils.cygwinccompiler

836

837

838

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

839

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

840

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

841

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

842

843

844

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

845

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

846

847

.. module:: distutils.emxccompiler

848

:synopsis: OS/2 EMX Compiler support

849

850

851

This module provides the EMXCCompiler class, a subclass of

852

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

853

854

Georg Brandl

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

[diff] [blame]

855

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

856

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

857

858

.. module:: distutils.archive_util

859

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

860

861

862

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

863

tarballs or zipfiles.

864

865

866

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

867

868

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

869

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

870

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

871

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

872

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

873

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

874

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

875

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

876

Georg Brandl

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

[diff] [blame]

877

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

Georg Brandl

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

[diff] [blame]

878

879

880

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

881

882

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

883

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

884

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

885

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

886

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

887

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

888

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

889

Georg Brandl

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

[diff] [blame]

890

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

Georg Brandl

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

[diff] [blame]

891

892

893

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

894

895

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

Éric Araujo

4433a5f

2010-12-15 20:26:30 +0000

[diff] [blame]

896

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

Georg Brandl

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

[diff] [blame]

897

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

898

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

899

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

900

901

902

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

903

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

904

905

.. module:: distutils.dep_util

906

:synopsis: Utility functions for simple dependency checking

907

908

909

This module provides functions for performing simple, timestamp-based

910

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

911

timestamp dependency analysis.

912

913

914

.. function:: newer(source, target)

915

916

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

917

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

918

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

919

*source* does not exist.

920

921

922

.. function:: newer_pairwise(sources, targets)

923

924

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

925

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

926

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

927

928

.. % % equivalent to a listcomp...

929

930

931

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

932

933

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

934

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

935

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

936

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

937

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

938

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

939

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

940

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

941

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

the commands).

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

946

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

947

948

.. module:: distutils.dir_util

949

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

950

951

952

This module provides functions for operating on directories and trees of

directories.

Georg Brandl

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

[diff] [blame]

956

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

Georg Brandl

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

[diff] [blame]

957

958

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

959

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

960

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

961

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

962

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

963

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

964

directories actually created.

965

966

Georg Brandl

f4a4123

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

[diff] [blame]

967

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

Georg Brandl

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

[diff] [blame]

968

969

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

970

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

971

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

972

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

973

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

978

979

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

980

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

981

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

982

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

983

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

984

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

985

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

986

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

987

*dst*.

988

989

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

990

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

991

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

992

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

993

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

994

as for :func:`copy_file`.

995

996

997

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

998

999

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

1000

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

1001

true).

1002

Georg Brandl

d5f2d6e

2010-07-31 09:15:10 +0000

[diff] [blame]

1003

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

Georg Brandl

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

[diff] [blame]

1004

1005

1006

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

1007

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

1008

1009

.. module:: distutils.file_util

1010

:synopsis: Utility functions for operating on single files

1011

1012

1013

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

1014

1015

1016

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

1017

1018

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

1019

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

1020

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

1021

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

1022

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

1023

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

1024

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

1025

is older than *src*.

1026

1027

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

1028

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

1029

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

1030

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

1031

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

1032

contents.

1033

1034

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

1035

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

1036

copied, if *dry_run* true).

1037

1038

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

1039

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

1040

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

1041

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

1042

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

1043

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

1044

1045

1046

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

1047

1048

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

1049

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

1050

new full name of the file.

.. warning::

Benjamin Peterson

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

[diff] [blame]

1054

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

1055

other systems?

Georg Brandl

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

[diff] [blame]

1056

1057

1058

.. function:: write_file(filename, contents)

1059

1060

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

1061

without line terminators) to it.

1062

1063

1064

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

1065

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

1066

1067

.. module:: distutils.util

1068

:synopsis: Miscellaneous other utility functions

1069

1070

1071

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

1072

other utility module.

1073

1074

1075

.. function:: get_platform()

1076

1077

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

1078

distinguish platform-specific build directories and platform-specific built

1079

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

1080

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

1081

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

1082

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

1083

important.

1084

1085

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

1094

Benjamin Peterson

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

[diff] [blame]

1095

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]

1096

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

Georg Brandl

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

[diff] [blame]

1097

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

Benjamin Peterson

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

[diff] [blame]

1098

Benjamin Peterson

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

[diff] [blame]

1099

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

Benjamin Peterson

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

[diff] [blame]

1100

the univeral binary status instead of the architecture of the current

Georg Brandl

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

[diff] [blame]

1101

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

1102

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

Ronald Oussoren

bea37ae

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

[diff] [blame]

1103

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

1104

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

1105

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

1106

a univeral build with the i386 and x86_64 architectures

Benjamin Peterson

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

[diff] [blame]

1107

Benjamin Peterson

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

[diff] [blame]

1108

Examples of returned values on Mac OS X:

Benjamin Peterson

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

[diff] [blame]

1109

1110

* ``macosx-10.3-ppc``

1111

1112

* ``macosx-10.3-fat``

1113

1114

* ``macosx-10.5-universal``

1115

Ronald Oussoren

bea37ae

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

[diff] [blame]

1116

* ``macosx-10.6-intel``

1117

Georg Brandl

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

[diff] [blame]

1118

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

1119

1120

1121

.. function:: convert_path(pathname)

1122

1123

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

1124

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

1125

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

1126

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

1127

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

1128

*pathname* either starts or ends with a slash.

1129

1130

1131

.. function:: change_root(new_root, pathname)

1132

1133

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

1134

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

1135

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

1136

1137

1138

.. function:: check_environ()

1139

1140

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

1141

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

1142

includes:

1143

1144

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

1145

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

1146

OS (see :func:`get_platform`)

1147

1148

1149

.. function:: subst_vars(s, local_vars)

1150

1151

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

1152

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

1153

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

1154

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

1155

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

1156

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

1157

1158

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

1159

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

1160

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

1161

1162

1163

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

1164

Antoine Pitrou

771dea7

2011-10-12 18:35:18 +0200

[diff] [blame]

1165

Generate a useful error message from an :exc:`OSError` exception object.

1166

Handles Python 1.5.1 and later styles, and does what it can to deal with

1167

exception objects that don't have a filename (which happens when the error

1168

is due to a two-file operation, such as :func:`rename` or :func:`link`).

1169

Returns the error message as a string prefixed with *prefix*.

Georg Brandl

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

[diff] [blame]

1170

1171

1172

.. function:: split_quoted(s)

1173

1174

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

1175

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

1176

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

1177

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

1178

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

1179

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

1180

list of words.

1181

1182

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

1183

1184

1185

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

1186

1187

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

1188

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

1189

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

1190

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

1191

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

1192

1193

1194

.. function:: strtobool(val)

1195

1196

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

1197

1198

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

1199

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

1200

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

1201

1202

1203

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

1204

1205

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

Éric Araujo

47a4521

2011-10-08 00:34:13 +0200

[diff] [blame]

1206

:file:`.pyo` files in a :file:`__pycache__` subdirectory (see :pep:`3147`).

1207

*py_files* is a list of files to compile; any files that don't end in

1208

:file:`.py` are silently skipped. *optimize* must be one of the following:

Georg Brandl

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

[diff] [blame]

1209

1210

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

1211

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

1212

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

1213

1214

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

1215

Georg Brandl

9afde1c

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

[diff] [blame]

1216

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

Georg Brandl

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

[diff] [blame]

1217

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

1218

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

1219

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

1220

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

1221

*base_dir*, as you wish.

1222

1223

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

1224

filesystem.

1225

1226

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

1227

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

1228

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

1229

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

1230

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

1231

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

1232

Éric Araujo

47a4521

2011-10-08 00:34:13 +0200

[diff] [blame]

1233

.. versionchanged:: 3.2.3

1234

Create ``.pyc`` or ``.pyo`` files with an :func:`import magic tag

1235

<imp.get_tag>` in their name, in a :file:`__pycache__` subdirectory

1236

instead of files without tag in the current directory.

1237

Georg Brandl

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

[diff] [blame]

1238

1239

.. function:: rfc822_escape(header)

1240

1241

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

1242

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

1243

modification of the string.

1244

1245

.. % this _can_ be replaced

1246

1247

.. % \subsection{Distutils objects}

1248

1249

1250

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

1251

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

1252

1253

.. module:: distutils.dist

1254

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

1255

built/installed/distributed

1256

1257

1258

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

1259

module distribution being built/installed/distributed.

1260

1261

1262

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

1263

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

1264

1265

.. module:: distutils.extension

1266

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

1271

extension modules in setup scripts.

1272

1273

.. % \subsection{Ungrouped modules}

1274

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

1275

1276

1277

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

1278

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

1279

1280

.. module:: distutils.debug

1281

:synopsis: Provides the debug flag for distutils

1282

1283

1284

This module provides the DEBUG flag.

1285

1286

1287

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

1288

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

1289

1290

.. module:: distutils.errors

1291

:synopsis: Provides standard distutils exceptions

1292

1293

1294

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

1295

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

1296

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

1297

1298

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

1299

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

1300

1301

1302

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

1303

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

1304

1305

.. module:: distutils.fancy_getopt

1306

:synopsis: Additional getopt functionality

1307

1308

1309

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

1310

provides the following additional features:

1311

1312

* short and long options are tied together

1313

1314

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

1315

complete usage summary

1316

1317

* options set attributes of a passed-in object

1318

1319

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

1320

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

1321

command line sets *verbose* to false.

1322

Georg Brandl

d5f2d6e

2010-07-31 09:15:10 +0000

[diff] [blame]

1323

.. XXX Should be replaced with optparse

Georg Brandl

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

[diff] [blame]

1324

1325

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

1326

1327

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

1328

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

1329

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

1330

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

1331

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

1332

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

1333

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

1334

1335

1336

.. function:: wrap_text(text, width)

1337

1338

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

1339

Georg Brandl

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

[diff] [blame]

1340

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

1341

2.3 and later).

Georg Brandl

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

[diff] [blame]

1342

1343

1344

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

1345

1346

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

1347

help_string)``

1348

1349

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

1350

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

1351

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

1352

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

1353

1354

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

1355

1356

1357

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

1358

1359

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

1360

1361

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

1362

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

1363

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

1364

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

1365

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

1366

which is left untouched.

1367

1368

.. % and args returned are?

1369

1370

1371

.. method:: FancyGetopt.get_option_order()

1372

1373

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

1374

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

yet.

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

1379

1380

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

1381

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

1382

1383

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

1384

1385

1386

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

1387

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

1388

1389

.. module:: distutils.filelist

Georg Brandl

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

[diff] [blame]

1390

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

1391

building lists of files.

Georg Brandl

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

[diff] [blame]

1392

1393

1394

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

1395

filesystem and building lists of files.

1396

1397

1398

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

1399

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

1400

1401

.. module:: distutils.log

1402

:synopsis: A simple logging mechanism, 282-style

1403

1404

Georg Brandl

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

[diff] [blame]

1405

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

Georg Brandl

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

[diff] [blame]

1406

Georg Brandl

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

[diff] [blame]

1407

1408

1409

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

1410

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

1411

1412

.. module:: distutils.spawn

1413

:synopsis: Provides the spawn() function

1414

1415

1416

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

1417

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

1418

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

name.

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

1423

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

1424

1425

.. module:: distutils.sysconfig

1426

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

1427

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

1428

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

1429

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

1430

1431

1432

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

1433

configuration information. The specific configuration variables available

1434

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

1435

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

1436

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

1437

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

1438

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

1439

for earlier versions of Python.

1440

1441

Some additional functions are provided which perform some useful manipulations

1442

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

.. data:: PREFIX

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

1448

1449

1450

.. data:: EXEC_PREFIX

1451

1452

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

1453

1454

1455

.. function:: get_config_var(name)

1456

1457

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

1458

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

1459

1460

1461

.. function:: get_config_vars(...)

1462

1463

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

1464

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

1465

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

1466

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

1467

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

1468

1469

1470

.. function:: get_config_h_filename()

1471

1472

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

1473

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

1474

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

1475

file is a platform-specific text file.

1476

1477

1478

.. function:: get_makefile_filename()

1479

1480

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

1481

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

1482

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

1483

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

1484

1485

1486

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

1487

1488

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

1489

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

1490

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

1491

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

1492

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

1493

*plat_specific* is true.

1494

1495

1496

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

1497

1498

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

1499

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

1500

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

1501

is returned. 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. If *standard_lib* is true, the directory for the

1504

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

1505

third-party extensions.

1506

1507

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

package.

.. function:: customize_compiler(compiler)

1512

1513

Do any platform-specific customization of a

1514

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

1515

1516

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

1517

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

1518

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

1519

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

1520

extension used by the linker for shared objects.

1521

1522

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

1523

Python's own build procedures.

1524

1525

1526

.. function:: set_python_build()

1527

1528

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

1529

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

1530

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

Python.

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

1535

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

1536

1537

.. module:: distutils.text_file

1538

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

1539

1540

1541

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

1542

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

1543

lines, and joining lines with backslashes.

1544

1545

1546

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

1547

1548

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

1549

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

1550

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

1551

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

1552

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

1553

independently controllable.

1554

1555

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

1556

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

1557

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

1558

line-at-a-time lookahead.

1559

1560

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

1561

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

1562

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

1563

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

1564

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

1565

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

1566

:func:`open` built-in function.

1567

1568

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

1569

1570

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

1571

| option name | description | default |

1572

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

1573

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

1574

| | line, as well as any | |

1575

| | whitespace leading up to the | |

1576

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

1577

| | escaped by a backslash | |

1578

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

1579

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

1580

| | each line before returning it | |

1581

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

1582

| *rstrip_ws* | strip trailing whitespace | true |

1583

| | (including line terminator!) | |

1584

| | from each line before | |

1585

| | returning it. | |

1586

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

1587

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

1588

| | \*after\* stripping comments | |

1589

| | and whitespace. (If both | |

1590

| | lstrip_ws and rstrip_ws are | |

1591

| | false, then some lines may | |

1592

| | consist of solely whitespace: | |

1593

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

1594

| | even if *skip_blanks* is | |

1595

| | true.) | |

1596

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

1597

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

1598

| | non-newline character on a | |

1599

| | line after stripping comments | |

1600

| | and whitespace, join the | |

1601

| | following line to it to form | |

1602

| | one logical line; if N | |

1603

| | consecutive lines end with a | |

1604

| | backslash, then N+1 physical | |

1605

| | lines will be joined to form | |

1606

| | one logical line. | |

1607

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

1608

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

1609

| | lines that are joined to their | |

1610

| | predecessor; only matters if | |

1611

| | ``(join_lines and not | |

1612

| | lstrip_ws)`` | |

1613

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

1614

1615

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]

1616

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

Georg Brandl

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

[diff] [blame]

1617

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

1618

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

1619

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

1620

1621

1622

.. method:: TextFile.open(filename)

1623

Georg Brandl

22b3431

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

[diff] [blame]

1624

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

1625

constructor arguments.

Georg Brandl

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

[diff] [blame]

1626

1627

1628

.. method:: TextFile.close()

1629

1630

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

1631

filename and the current line number).

1632

1633

1634

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

1635

1636

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

1637

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

1638

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

1639

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

1640

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

physical line.

.. method:: TextFile.readline()

1645

1646

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

1647

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

1648

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

1649

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

1650

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

1651

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

1652

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

1653

1654

1655

.. method:: TextFile.readlines()

1656

1657

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

1658

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

1659

1660

1661

.. method:: TextFile.unreadline(line)

1662

1663

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

1664

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

1665

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

1666

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

1667

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

1668

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

1669

1670

1671

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

1672

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

1673

1674

.. module:: distutils.version

1675

:synopsis: implements classes that represent module version numbers.

.. % todo

.. % \section{Distutils Commands}

Georg Brandl

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

[diff] [blame]

1680

.. %

Georg Brandl

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

[diff] [blame]

1681

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

1682

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

1683

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

1684

1685

1686

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

1687

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

1688

1689

.. module:: distutils.cmd

Georg Brandl

2010-10-06 08:26:09 +0000

[diff] [blame]

1690

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

1691

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

Georg Brandl

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

[diff] [blame]

1692

1693

1694

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

1695

1696

1697

.. class:: Command(dist)

1698

1699

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

1700

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

Georg Brandl

2010-10-06 08:26:09 +0000

[diff] [blame]

1701

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

1702

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

1703

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

1704

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

1705

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

1706

options dependent on other options must be computed after these outside

1707

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

1708

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

1709

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

1710

command class.

Georg Brandl

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

[diff] [blame]

1711

Georg Brandl

2010-10-06 08:26:09 +0000

[diff] [blame]

1712

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-10-06 08:26:09 +0000

[diff] [blame]

1716

Creating a new Distutils command

1717

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

1718

1719

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

1720

1721

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

1722

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

1723

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

1724

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

1725

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

1726

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

1727

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

1728

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

1729

:class:`distutils.cmd.Command`.

1730

1731

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

1732

1733

.. method:: Command.initialize_options()

1734

1735

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

1736

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

1737

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

1738

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

1739

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

1740

1741

1742

.. method:: Command.finalize_options()

1743

1744

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

1745

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

1746

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

Ezio Melotti

e130a52

2011-10-19 10:58:56 +0300

[diff] [blame]

1747

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

Georg Brandl

2010-10-06 08:26:09 +0000

[diff] [blame]

1748

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

1749

assigned in :meth:`initialize_options`.

1750

1751

1752

.. method:: Command.run()

1753

1754

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

1755

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

1756

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

1757

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

1758

be done by :meth:`run`.

1759

1760

1761

.. attribute:: Command.sub_commands

1762

1763

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

1764

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

1765

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

1766

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

1767

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

1768

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

1769

determines whether the corresponding command is applicable in the current

Éric Araujo

000893f

2011-05-29 00:14:45 +0200

[diff] [blame]

1770

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

Georg Brandl

2010-10-06 08:26:09 +0000

[diff] [blame]

1771

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

1772

applicable.

1773

1774

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

1775

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

1776

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

1777

1778

Georg Brandl

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

[diff] [blame]

1779

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

1780

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

1781

1782

.. module:: distutils.command

1783

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

1784

1785

1786

.. % \subsubsection{Individual Distutils commands}

.. % todo

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

1791

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

1792

1793

.. module:: distutils.command.bdist

1794

:synopsis: Build a binary installer for a package

.. % todo

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

1801

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

1802

1803

.. module:: distutils.command.bdist_packager

1804

:synopsis: Abstract base class for packagers

.. % todo

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

1811

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

1812

1813

.. module:: distutils.command.bdist_dumb

1814

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

.. % todo

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

1821

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

1822

1823

.. module:: distutils.command.bdist_msi

1824

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

1825

Éric Araujo

5864b9f

2011-05-31 21:50:38 +0200

[diff] [blame]

1826

.. class:: bdist_msi

Georg Brandl

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

[diff] [blame]

1827

Benjamin Peterson

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

[diff] [blame]

1828

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

1829

1830

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

1831

1832

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

1833

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

1834

Win64 platforms, allows administrators to perform non-interactive

1835

installations, and allows installation through group policies.

Georg Brandl

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

[diff] [blame]

1836

1837

1838

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

1839

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

1840

1841

.. module:: distutils.command.bdist_rpm

1842

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

.. % todo

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

1849

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

1850

1851

.. module:: distutils.command.bdist_wininst

1852

:synopsis: Build a Windows installer

.. % todo

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

1859

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

1860

1861

.. module:: distutils.command.sdist

1862

:synopsis: Build a source distribution

.. % todo

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

1869

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

1870

1871

.. module:: distutils.command.build

1872

:synopsis: Build all files of a package

.. % todo

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

1879

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

1880

1881

.. module:: distutils.command.build_clib

1882

:synopsis: Build any C libraries in a package

.. % todo

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

1889

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

1890

1891

.. module:: distutils.command.build_ext

1892

:synopsis: Build any extensions in a package

.. % todo

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

1899

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

1900

1901

.. module:: distutils.command.build_py

1902

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

1903

1904

Éric Araujo

5864b9f

2011-05-31 21:50:38 +0200

[diff] [blame]

1905

.. class:: build_py

Martin v. Löwis

73a22f0

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

[diff] [blame]

1906

Éric Araujo

5864b9f

2011-05-31 21:50:38 +0200

[diff] [blame]

1907

.. class:: build_py_2to3

Martin v. Löwis

73a22f0

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

[diff] [blame]

1908

1909

Alternative implementation of build_py which also runs the

1910

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

1911

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

1912

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

1913

1914

try:

1915

from distutils.command.build_py import build_py_2to3 as build_py

1916

except ImportError:

1917

from distutils.command.build_py import build_py

1918

1919

to your setup.py, and later::

1920

Georg Brandl

682d7e0

2010-10-06 10:26:05 +0000

[diff] [blame]

1921

cmdclass = {'build_py': build_py}

Martin v. Löwis

73a22f0

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

[diff] [blame]

1922

1923

to the invocation of setup().

Georg Brandl