mirror of
https://github.com/python/cpython.git
synced 2025-10-31 13:41:24 +00:00
f1d5cdef57
Replace old names when they refer to actual versions of macOS.
Keep historical names in references to older versions.
Co-authored-by: Patrick Reader <_@pxeger.com>
(cherry picked from commit 36122e1814)
Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>
2070 lines
95 KiB
ReStructuredText
2070 lines
95 KiB
ReStructuredText
.. _api-reference:
|
|
|
|
*************
|
|
API Reference
|
|
*************
|
|
|
|
.. seealso::
|
|
|
|
`New and changed setup.py arguments in setuptools`_
|
|
The ``setuptools`` project adds new capabilities to the ``setup`` function
|
|
and other APIs, makes the API consistent across different Python versions,
|
|
and is hence recommended over using ``distutils`` directly.
|
|
|
|
.. _New and changed setup.py arguments in setuptools: https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords
|
|
|
|
.. include:: ./_setuptools_disclaimer.rst
|
|
|
|
:mod:`distutils.core` --- Core Distutils functionality
|
|
======================================================
|
|
|
|
.. module:: distutils.core
|
|
:synopsis: The core Distutils functionality
|
|
|
|
|
|
The :mod:`distutils.core` module is the only module that needs to be installed
|
|
to use the Distutils. It provides the :func:`setup` (which is called from the
|
|
setup script). Indirectly provides the :class:`distutils.dist.Distribution` and
|
|
:class:`distutils.cmd.Command` class.
|
|
|
|
|
|
.. function:: setup(arguments)
|
|
|
|
The basic do-everything function that does most everything you could ever ask
|
|
for from a Distutils method.
|
|
|
|
The setup function takes a large number of arguments. These are laid out in the
|
|
following table.
|
|
|
|
.. tabularcolumns:: |l|L|L|
|
|
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| argument name | value | type |
|
|
+====================+================================+=============================================================+
|
|
| *name* | The name of the package | a string |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *version* | The version number of the | a string |
|
|
| | package; see | |
|
|
| | :mod:`distutils.version` | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *description* | A single line describing the | a string |
|
|
| | package | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *long_description* | Longer description of the | a string |
|
|
| | package | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *author* | The name of the package author | a string |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *author_email* | The email address of the | a string |
|
|
| | package author | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *maintainer* | The name of the current | a string |
|
|
| | maintainer, if different from | |
|
|
| | the author. Note that if | |
|
|
| | the maintainer is provided, | |
|
|
| | distutils will use it as the | |
|
|
| | author in :file:`PKG-INFO` | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *maintainer_email* | The email address of the | a string |
|
|
| | current maintainer, if | |
|
|
| | different from the author | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *url* | A URL for the package | a string |
|
|
| | (homepage) | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *download_url* | A URL to download the package | a string |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *packages* | A list of Python packages that | a list of strings |
|
|
| | distutils will manipulate | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *py_modules* | A list of Python modules that | a list of strings |
|
|
| | distutils will manipulate | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *scripts* | A list of standalone script | a list of strings |
|
|
| | files to be built and | |
|
|
| | installed | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *ext_modules* | A list of Python extensions to | a list of instances of |
|
|
| | be built | :class:`distutils.core.Extension` |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI |
|
|
| | package | <https://pypi.org/classifiers>`_. |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *distclass* | the :class:`Distribution` | a subclass of |
|
|
| | class to use | :class:`distutils.core.Distribution` |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *script_name* | The name of the setup.py | a string |
|
|
| | script - defaults to | |
|
|
| | ``sys.argv[0]`` | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *script_args* | Arguments to supply to the | a list of strings |
|
|
| | setup script | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *options* | default options for the setup | a dictionary |
|
|
| | script | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *license* | The license for the package | a string |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *keywords* | Descriptive meta-data, see | a list of strings or a comma-separated string |
|
|
| | :pep:`314` | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *platforms* | | a list of strings or a comma-separated string |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *cmdclass* | A mapping of command names to | a dictionary |
|
|
| | :class:`Command` subclasses | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *data_files* | A list of data files to | a list |
|
|
| | install | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
| *package_dir* | A mapping of package to | a dictionary |
|
|
| | directory names | |
|
|
+--------------------+--------------------------------+-------------------------------------------------------------+
|
|
|
|
|
|
|
|
.. function:: run_setup(script_name[, script_args=None, stop_after='run'])
|
|
|
|
Run a setup script in a somewhat controlled environment, and return the
|
|
:class:`distutils.dist.Distribution` instance that drives things. This is
|
|
useful if you need to find out the distribution meta-data (passed as keyword
|
|
args from *script* to :func:`setup`), or the contents of the config files or
|
|
command-line.
|
|
|
|
*script_name* is a file that will be read and run with :func:`exec`. ``sys.argv[0]``
|
|
will be replaced with *script* for the duration of the call. *script_args* is a
|
|
list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args*
|
|
for the duration of the call.
|
|
|
|
*stop_after* tells :func:`setup` when to stop processing; possible values:
|
|
|
|
.. tabularcolumns:: |l|L|
|
|
|
|
+---------------+---------------------------------------------+
|
|
| value | description |
|
|
+===============+=============================================+
|
|
| *init* | Stop after the :class:`Distribution` |
|
|
| | instance has been created and populated |
|
|
| | with the keyword arguments to :func:`setup` |
|
|
+---------------+---------------------------------------------+
|
|
| *config* | Stop after config files have been parsed |
|
|
| | (and their data stored in the |
|
|
| | :class:`Distribution` instance) |
|
|
+---------------+---------------------------------------------+
|
|
| *commandline* | Stop after the command-line |
|
|
| | (``sys.argv[1:]`` or *script_args*) have |
|
|
| | been parsed (and the data stored in the |
|
|
| | :class:`Distribution` instance.) |
|
|
+---------------+---------------------------------------------+
|
|
| *run* | Stop after all commands have been run (the |
|
|
| | same as if :func:`setup` had been called |
|
|
| | in the usual way). This is the default |
|
|
| | value. |
|
|
+---------------+---------------------------------------------+
|
|
|
|
In addition, the :mod:`distutils.core` module exposed a number of classes that
|
|
live elsewhere.
|
|
|
|
* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
|
|
|
|
* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
|
|
|
|
* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
|
|
|
|
A short description of each of these follows, but see the relevant module for
|
|
the full reference.
|
|
|
|
|
|
.. class:: Extension
|
|
|
|
The Extension class describes a single C or C++ extension module in a setup
|
|
script. It accepts the following keyword arguments in its constructor:
|
|
|
|
.. tabularcolumns:: |l|L|l|
|
|
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| argument name | value | type |
|
|
+========================+================================+===========================+
|
|
| *name* | the full name of the | a string |
|
|
| | extension, including any | |
|
|
| | packages --- ie. *not* a | |
|
|
| | filename or pathname, but | |
|
|
| | Python dotted name | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *sources* | list of source filenames, | a list of strings |
|
|
| | relative to the distribution | |
|
|
| | root (where the setup script | |
|
|
| | lives), in Unix form | |
|
|
| | (slash-separated) for | |
|
|
| | portability. | |
|
|
| | Source files may be C, C++, | |
|
|
| | SWIG (.i), platform-specific | |
|
|
| | resource files, or whatever | |
|
|
| | else is recognized by the | |
|
|
| | :command:`build_ext` command | |
|
|
| | as source for a Python | |
|
|
| | extension. | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *include_dirs* | list of directories to search | a list of strings |
|
|
| | for C/C++ header files (in | |
|
|
| | Unix form for portability) | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *define_macros* | list of macros to define; each | a list of tuples |
|
|
| | macro is defined using a | |
|
|
| | 2-tuple ``(name, value)``, | |
|
|
| | where *value* is | |
|
|
| | either the string to define it | |
|
|
| | to or ``None`` to define it | |
|
|
| | without a particular value | |
|
|
| | (equivalent of ``#define FOO`` | |
|
|
| | in source or :option:`!-DFOO` | |
|
|
| | on Unix C compiler command | |
|
|
| | line) | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *undef_macros* | list of macros to undefine | a list of strings |
|
|
| | explicitly | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *library_dirs* | list of directories to search | a list of strings |
|
|
| | for C/C++ libraries at link | |
|
|
| | time | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *libraries* | list of library names (not | a list of strings |
|
|
| | filenames or paths) to link | |
|
|
| | against | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *runtime_library_dirs* | list of directories to search | a list of strings |
|
|
| | for C/C++ libraries at run | |
|
|
| | time (for shared extensions, | |
|
|
| | this is when the extension is | |
|
|
| | loaded) | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *extra_objects* | list of extra files to link | a list of strings |
|
|
| | with (eg. object files not | |
|
|
| | implied by 'sources', static | |
|
|
| | library that must be | |
|
|
| | explicitly specified, binary | |
|
|
| | resource files, etc.) | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *extra_compile_args* | any extra platform- and | a list of strings |
|
|
| | compiler-specific information | |
|
|
| | to use when compiling the | |
|
|
| | source files in 'sources'. For | |
|
|
| | platforms and compilers where | |
|
|
| | a command line makes sense, | |
|
|
| | this is typically a list of | |
|
|
| | command-line arguments, but | |
|
|
| | for other platforms it could | |
|
|
| | be anything. | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *extra_link_args* | any extra platform- and | a list of strings |
|
|
| | compiler-specific information | |
|
|
| | to use when linking object | |
|
|
| | files together to create the | |
|
|
| | extension (or to create a new | |
|
|
| | static Python interpreter). | |
|
|
| | Similar interpretation as for | |
|
|
| | 'extra_compile_args'. | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *export_symbols* | list of symbols to be exported | a list of strings |
|
|
| | from a shared extension. Not | |
|
|
| | used on all platforms, and not | |
|
|
| | generally necessary for Python | |
|
|
| | extensions, which typically | |
|
|
| | export exactly one symbol: | |
|
|
| | ``init`` + extension_name. | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *depends* | list of files that the | a list of strings |
|
|
| | extension depends on | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *language* | extension language (i.e. | a string |
|
|
| | ``'c'``, ``'c++'``, | |
|
|
| | ``'objc'``). Will be detected | |
|
|
| | from the source extensions if | |
|
|
| | not provided. | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
| *optional* | specifies that a build failure | a boolean |
|
|
| | in the extension should not | |
|
|
| | abort the build process, but | |
|
|
| | simply skip the extension. | |
|
|
+------------------------+--------------------------------+---------------------------+
|
|
|
|
.. versionchanged:: 3.8
|
|
|
|
On Unix, C extensions are no longer linked to libpython except on
|
|
Android and Cygwin.
|
|
|
|
|
|
.. class:: Distribution
|
|
|
|
A :class:`Distribution` describes how to build, install and package up a Python
|
|
software package.
|
|
|
|
See the :func:`setup` function for a list of keyword arguments accepted by the
|
|
Distribution constructor. :func:`setup` creates a Distribution instance.
|
|
|
|
.. versionchanged:: 3.7
|
|
:class:`~distutils.core.Distribution` now warns if ``classifiers``,
|
|
``keywords`` and ``platforms`` fields are not specified as a list or
|
|
a string.
|
|
|
|
.. class:: Command
|
|
|
|
A :class:`Command` class (or rather, an instance of one of its subclasses)
|
|
implement a single distutils command.
|
|
|
|
|
|
:mod:`distutils.ccompiler` --- CCompiler base class
|
|
===================================================
|
|
|
|
.. module:: distutils.ccompiler
|
|
:synopsis: Abstract CCompiler class
|
|
|
|
|
|
This module provides the abstract base class for the :class:`CCompiler`
|
|
classes. A :class:`CCompiler` instance can be used for all the compile and
|
|
link steps needed to build a single project. Methods are provided to set
|
|
options for the compiler --- macro definitions, include directories, link path,
|
|
libraries and the like.
|
|
|
|
This module provides the following functions.
|
|
|
|
|
|
.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries)
|
|
|
|
Generate linker options for searching library directories and linking with
|
|
specific libraries. *libraries* and *library_dirs* are, respectively, lists of
|
|
library names (not filenames!) and search directories. Returns a list of
|
|
command-line options suitable for use with some compiler (depending on the two
|
|
format strings passed in).
|
|
|
|
|
|
.. function:: gen_preprocess_options(macros, include_dirs)
|
|
|
|
Generate C pre-processor options (:option:`!-D`, :option:`!-U`, :option:`!-I`) as
|
|
used by at least two types of compilers: the typical Unix compiler and Visual
|
|
C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)``
|
|
means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define
|
|
(:option:`!-D`) macro *name* to *value*. *include_dirs* is just a list of
|
|
directory names to be added to the header file search path (:option:`!-I`).
|
|
Returns a list of command-line options suitable for either Unix compilers or
|
|
Visual C++.
|
|
|
|
|
|
.. function:: get_default_compiler(osname, platform)
|
|
|
|
Determine the default compiler to use for the given platform.
|
|
|
|
*osname* should be one of the standard Python OS names (i.e. the ones returned
|
|
by ``os.name``) and *platform* the common value returned by ``sys.platform`` for
|
|
the platform in question.
|
|
|
|
The default values are ``os.name`` and ``sys.platform`` in case the parameters
|
|
are not given.
|
|
|
|
|
|
.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0)
|
|
|
|
Factory function to generate an instance of some CCompiler subclass for the
|
|
supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg.
|
|
``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for
|
|
that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the
|
|
default compilers are "traditional Unix interface" (:class:`UnixCCompiler`
|
|
class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly
|
|
possible to ask for a Unix compiler object under Windows, and a Microsoft
|
|
compiler object under Unix---if you supply a value for *compiler*, *plat* is
|
|
ignored.
|
|
|
|
.. % Is the posix/nt only thing still true? macOS seems to work, and
|
|
.. % returns a UnixCCompiler instance. How to document this... hmm.
|
|
|
|
|
|
.. function:: show_compilers()
|
|
|
|
Print list of available compilers (used by the :option:`!--help-compiler` options
|
|
to :command:`build`, :command:`build_ext`, :command:`build_clib`).
|
|
|
|
|
|
.. class:: CCompiler([verbose=0, dry_run=0, force=0])
|
|
|
|
The abstract base class :class:`CCompiler` defines the interface that must be
|
|
implemented by real compiler classes. The class also has some utility methods
|
|
used by several compiler classes.
|
|
|
|
The basic idea behind a compiler abstraction class is that each instance can be
|
|
used for all the compile/link steps in building a single project. Thus,
|
|
attributes common to all of those compile and link steps --- include
|
|
directories, macros to define, libraries to link against, etc. --- are
|
|
attributes of the compiler instance. To allow for variability in how individual
|
|
files are treated, most of those attributes may be varied on a per-compilation
|
|
or per-link basis.
|
|
|
|
The constructor for each subclass creates an instance of the Compiler object.
|
|
Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the
|
|
steps) and *force* (rebuild everything, regardless of dependencies). All of
|
|
these flags default to ``0`` (off). Note that you probably don't want to
|
|
instantiate :class:`CCompiler` or one of its subclasses directly - use the
|
|
:func:`distutils.CCompiler.new_compiler` factory function instead.
|
|
|
|
The following methods allow you to manually alter compiler options for the
|
|
instance of the Compiler class.
|
|
|
|
|
|
.. method:: CCompiler.add_include_dir(dir)
|
|
|
|
Add *dir* to the list of directories that will be searched for header files.
|
|
The compiler is instructed to search directories in the order in which they are
|
|
supplied by successive calls to :meth:`add_include_dir`.
|
|
|
|
|
|
.. method:: CCompiler.set_include_dirs(dirs)
|
|
|
|
Set the list of directories that will be searched to *dirs* (a list of strings).
|
|
Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to
|
|
:meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`.
|
|
This does not affect any list of standard include directories that the compiler
|
|
may search by default.
|
|
|
|
|
|
.. method:: CCompiler.add_library(libname)
|
|
|
|
Add *libname* to the list of libraries that will be included in all links driven
|
|
by this compiler object. Note that *libname* should \*not\* be the name of a
|
|
file containing a library, but the name of the library itself: the actual
|
|
filename will be inferred by the linker, the compiler, or the compiler class
|
|
(depending on the platform).
|
|
|
|
The linker will be instructed to link against libraries in the order they were
|
|
supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly
|
|
valid to duplicate library names; the linker will be instructed to link against
|
|
libraries as many times as they are mentioned.
|
|
|
|
|
|
.. method:: CCompiler.set_libraries(libnames)
|
|
|
|
Set the list of libraries to be included in all links driven by this compiler
|
|
object to *libnames* (a list of strings). This does not affect any standard
|
|
system libraries that the linker may include by default.
|
|
|
|
|
|
.. method:: CCompiler.add_library_dir(dir)
|
|
|
|
Add *dir* to the list of directories that will be searched for libraries
|
|
specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be
|
|
instructed to search for libraries in the order they are supplied to
|
|
:meth:`add_library_dir` and/or :meth:`set_library_dirs`.
|
|
|
|
|
|
.. method:: CCompiler.set_library_dirs(dirs)
|
|
|
|
Set the list of library search directories to *dirs* (a list of strings). This
|
|
does not affect any standard library search path that the linker may search by
|
|
default.
|
|
|
|
|
|
.. method:: CCompiler.add_runtime_library_dir(dir)
|
|
|
|
Add *dir* to the list of directories that will be searched for shared libraries
|
|
at runtime.
|
|
|
|
|
|
.. method:: CCompiler.set_runtime_library_dirs(dirs)
|
|
|
|
Set the list of directories to search for shared libraries at runtime to *dirs*
|
|
(a list of strings). This does not affect any standard search path that the
|
|
runtime linker may search by default.
|
|
|
|
|
|
.. method:: CCompiler.define_macro(name[, value=None])
|
|
|
|
Define a preprocessor macro for all compilations driven by this compiler object.
|
|
The optional parameter *value* should be a string; if it is not supplied, then
|
|
the macro will be defined without an explicit value and the exact outcome
|
|
depends on the compiler used.
|
|
|
|
.. XXX true? does ANSI say anything about this?
|
|
|
|
|
|
.. method:: CCompiler.undefine_macro(name)
|
|
|
|
Undefine a preprocessor macro for all compilations driven by this compiler
|
|
object. If the same macro is defined by :meth:`define_macro` and
|
|
undefined by :meth:`undefine_macro` the last call takes precedence
|
|
(including multiple redefinitions or undefinitions). If the macro is
|
|
redefined/undefined on a per-compilation basis (ie. in the call to
|
|
:meth:`compile`), then that takes precedence.
|
|
|
|
|
|
.. method:: CCompiler.add_link_object(object)
|
|
|
|
Add *object* to the list of object files (or analogues, such as explicitly named
|
|
library files or the output of "resource compilers") to be included in every
|
|
link driven by this compiler object.
|
|
|
|
|
|
.. method:: CCompiler.set_link_objects(objects)
|
|
|
|
Set the list of object files (or analogues) to be included in every link to
|
|
*objects*. This does not affect any standard object files that the linker may
|
|
include by default (such as system libraries).
|
|
|
|
The following methods implement methods for autodetection of compiler options,
|
|
providing some functionality similar to GNU :program:`autoconf`.
|
|
|
|
|
|
.. method:: CCompiler.detect_language(sources)
|
|
|
|
Detect the language of a given file, or list of files. Uses the instance
|
|
attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a
|
|
list) to do the job.
|
|
|
|
|
|
.. method:: CCompiler.find_library_file(dirs, lib[, debug=0])
|
|
|
|
Search the specified list of directories for a static or shared library file
|
|
*lib* and return the full path to that file. If *debug* is true, look for a
|
|
debugging version (if that makes sense on the current platform). Return
|
|
``None`` if *lib* wasn't found in any of the specified directories.
|
|
|
|
|
|
.. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None])
|
|
|
|
Return a boolean indicating whether *funcname* is supported on the current
|
|
platform. The optional arguments can be used to augment the compilation
|
|
environment by providing additional include files and paths and libraries and
|
|
paths.
|
|
|
|
|
|
.. method:: CCompiler.library_dir_option(dir)
|
|
|
|
Return the compiler option to add *dir* to the list of directories searched for
|
|
libraries.
|
|
|
|
|
|
.. method:: CCompiler.library_option(lib)
|
|
|
|
Return the compiler option to add *lib* to the list of libraries linked into the
|
|
shared library or executable.
|
|
|
|
|
|
.. method:: CCompiler.runtime_library_dir_option(dir)
|
|
|
|
Return the compiler option to add *dir* to the list of directories searched for
|
|
runtime libraries.
|
|
|
|
|
|
.. method:: CCompiler.set_executables(**args)
|
|
|
|
Define the executables (and options for them) that will be run to perform the
|
|
various stages of compilation. The exact set of executables that may be
|
|
specified here depends on the compiler class (via the 'executables' class
|
|
attribute), but most will have:
|
|
|
|
+--------------+------------------------------------------+
|
|
| attribute | description |
|
|
+==============+==========================================+
|
|
| *compiler* | the C/C++ compiler |
|
|
+--------------+------------------------------------------+
|
|
| *linker_so* | linker used to create shared objects and |
|
|
| | libraries |
|
|
+--------------+------------------------------------------+
|
|
| *linker_exe* | linker used to create binary executables |
|
|
+--------------+------------------------------------------+
|
|
| *archiver* | static library creator |
|
|
+--------------+------------------------------------------+
|
|
|
|
On platforms with a command-line (Unix, DOS/Windows), each of these is a string
|
|
that will be split into executable name and (optional) list of arguments.
|
|
(Splitting the string is done similarly to how Unix shells operate: words are
|
|
delimited by spaces, but quotes and backslashes can override this. See
|
|
:func:`distutils.util.split_quoted`.)
|
|
|
|
The following methods invoke stages in the build process.
|
|
|
|
|
|
.. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None])
|
|
|
|
Compile one or more source files. Generates object files (e.g. transforms a
|
|
:file:`.c` file to a :file:`.o` file.)
|
|
|
|
*sources* must be a list of filenames, most likely C/C++ files, but in reality
|
|
anything that can be handled by a particular compiler and compiler class (eg.
|
|
:class:`MSVCCompiler` can handle resource files in *sources*). Return a list of
|
|
object filenames, one per source filename in *sources*. Depending on the
|
|
implementation, not all source files will necessarily be compiled, but all
|
|
corresponding object filenames will be returned.
|
|
|
|
If *output_dir* is given, object files will be put under it, while retaining
|
|
their original path component. That is, :file:`foo/bar.c` normally compiles to
|
|
:file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then
|
|
it would compile to :file:`build/foo/bar.o`.
|
|
|
|
*macros*, if given, must be a list of macro definitions. A macro definition is
|
|
either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines
|
|
a macro; if the value is ``None``, the macro is defined without an explicit
|
|
value. The 1-tuple case undefines a macro. Later
|
|
definitions/redefinitions/undefinitions take precedence.
|
|
|
|
*include_dirs*, if given, must be a list of strings, the directories to add to
|
|
the default include file search path for this compilation only.
|
|
|
|
*debug* is a boolean; if true, the compiler will be instructed to output debug
|
|
symbols in (or alongside) the object file(s).
|
|
|
|
*extra_preargs* and *extra_postargs* are implementation-dependent. On platforms
|
|
that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most
|
|
likely lists of strings: extra command-line arguments to prepend/append to the
|
|
compiler command line. On other platforms, consult the implementation class
|
|
documentation. In any event, they are intended as an escape hatch for those
|
|
occasions when the abstract compiler framework doesn't cut the mustard.
|
|
|
|
*depends*, if given, is a list of filenames that all targets depend on. If a
|
|
source file is older than any file in depends, then the source file will be
|
|
recompiled. This supports dependency tracking, but only at a coarse
|
|
granularity.
|
|
|
|
Raises :exc:`CompileError` on failure.
|
|
|
|
|
|
.. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None])
|
|
|
|
Link a bunch of stuff together to create a static library file. The "bunch of
|
|
stuff" consists of the list of object files supplied as *objects*, the extra
|
|
object files supplied to :meth:`add_link_object` and/or
|
|
:meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or
|
|
:meth:`set_libraries`, and the libraries supplied as *libraries* (if any).
|
|
|
|
*output_libname* should be a library name, not a filename; the filename will be
|
|
inferred from the library name. *output_dir* is the directory where the library
|
|
file will be put.
|
|
|
|
.. XXX defaults to what?
|
|
|
|
*debug* is a boolean; if true, debugging information will be included in the
|
|
library (note that on most platforms, it is the compile step where this matters:
|
|
the *debug* flag is included here just for consistency).
|
|
|
|
*target_lang* is the target language for which the given objects are being
|
|
compiled. This allows specific linkage time treatment of certain languages.
|
|
|
|
Raises :exc:`LibError` on failure.
|
|
|
|
|
|
.. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
|
|
|
|
Link a bunch of stuff together to create an executable or shared library file.
|
|
|
|
The "bunch of stuff" consists of the list of object files supplied as *objects*.
|
|
*output_filename* should be a filename. If *output_dir* is supplied,
|
|
*output_filename* is relative to it (i.e. *output_filename* can provide
|
|
directory components if needed).
|
|
|
|
*libraries* is a list of libraries to link against. These are library names,
|
|
not filenames, since they're translated into filenames in a platform-specific
|
|
way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on
|
|
DOS/Windows). However, they can include a directory component, which means the
|
|
linker will look in that specific directory rather than searching all the normal
|
|
locations.
|
|
|
|
*library_dirs*, if supplied, should be a list of directories to search for
|
|
libraries that were specified as bare library names (ie. no directory
|
|
component). These are on top of the system default and those supplied to
|
|
:meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs*
|
|
is a list of directories that will be embedded into the shared library and used
|
|
to search for other shared libraries that \*it\* depends on at run-time. (This
|
|
may only be relevant on Unix.)
|
|
|
|
*export_symbols* is a list of symbols that the shared library will export.
|
|
(This appears to be relevant only on Windows.)
|
|
|
|
*debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the
|
|
slight distinction that it actually matters on most platforms (as opposed to
|
|
:meth:`create_static_lib`, which includes a *debug* flag mostly for form's
|
|
sake).
|
|
|
|
*extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of
|
|
course that they supply command-line arguments for the particular linker being
|
|
used).
|
|
|
|
*target_lang* is the target language for which the given objects are being
|
|
compiled. This allows specific linkage time treatment of certain languages.
|
|
|
|
Raises :exc:`LinkError` on failure.
|
|
|
|
|
|
.. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None])
|
|
|
|
Link an executable. *output_progname* is the name of the file executable, while
|
|
*objects* are a list of object filenames to link in. Other arguments are as for
|
|
the :meth:`link` method.
|
|
|
|
|
|
.. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
|
|
|
|
Link a shared library. *output_libname* is the name of the output library,
|
|
while *objects* is a list of object filenames to link in. Other arguments are
|
|
as for the :meth:`link` method.
|
|
|
|
|
|
.. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None])
|
|
|
|
Link a shared object. *output_filename* is the name of the shared object that
|
|
will be created, while *objects* is a list of object filenames to link in.
|
|
Other arguments are as for the :meth:`link` method.
|
|
|
|
|
|
.. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None])
|
|
|
|
Preprocess a single C/C++ source file, named in *source*. Output will be written
|
|
to file named *output_file*, or *stdout* if *output_file* not supplied.
|
|
*macros* is a list of macro definitions as for :meth:`compile`, which will
|
|
augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`.
|
|
*include_dirs* is a list of directory names that will be added to the default
|
|
list, in the same way as :meth:`add_include_dir`.
|
|
|
|
Raises :exc:`PreprocessError` on failure.
|
|
|
|
The following utility methods are defined by the :class:`CCompiler` class, for
|
|
use by the various concrete subclasses.
|
|
|
|
|
|
.. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir=''])
|
|
|
|
Returns the filename of the executable for the given *basename*. Typically for
|
|
non-Windows platforms this is the same as the basename, while Windows will get
|
|
a :file:`.exe` added.
|
|
|
|
|
|
.. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir=''])
|
|
|
|
Returns the filename for the given library name on the current platform. On Unix
|
|
a library with *lib_type* of ``'static'`` will typically be of the form
|
|
:file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form
|
|
:file:`liblibname.so`.
|
|
|
|
|
|
.. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir=''])
|
|
|
|
Returns the name of the object files for the given source files.
|
|
*source_filenames* should be a list of filenames.
|
|
|
|
|
|
.. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir=''])
|
|
|
|
Returns the name of a shared object file for the given file name *basename*.
|
|
|
|
|
|
.. method:: CCompiler.execute(func, args[, msg=None, level=1])
|
|
|
|
Invokes :func:`distutils.util.execute`. This method invokes a Python function
|
|
*func* with the given arguments *args*, after logging and taking into account
|
|
the *dry_run* flag.
|
|
|
|
|
|
.. method:: CCompiler.spawn(cmd)
|
|
|
|
Invokes :func:`distutils.util.spawn`. This invokes an external process to run
|
|
the given command.
|
|
|
|
|
|
.. method:: CCompiler.mkpath(name[, mode=511])
|
|
|
|
Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any
|
|
missing ancestor directories.
|
|
|
|
|
|
.. method:: CCompiler.move_file(src, dst)
|
|
|
|
Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*.
|
|
|
|
|
|
.. method:: CCompiler.announce(msg[, level=1])
|
|
|
|
Write a message using :func:`distutils.log.debug`.
|
|
|
|
|
|
.. method:: CCompiler.warn(msg)
|
|
|
|
Write a warning message *msg* to standard error.
|
|
|
|
|
|
.. method:: CCompiler.debug_print(msg)
|
|
|
|
If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to
|
|
standard output, otherwise do nothing.
|
|
|
|
.. % \subsection{Compiler-specific modules}
|
|
.. %
|
|
.. % The following modules implement concrete subclasses of the abstract
|
|
.. % \class{CCompiler} class. They should not be instantiated directly, but should
|
|
.. % be created using \function{distutils.ccompiler.new_compiler()} factory
|
|
.. % function.
|
|
|
|
|
|
:mod:`distutils.unixccompiler` --- Unix C Compiler
|
|
==================================================
|
|
|
|
.. module:: distutils.unixccompiler
|
|
:synopsis: UNIX C Compiler
|
|
|
|
|
|
This module provides the :class:`UnixCCompiler` class, a subclass of
|
|
:class:`CCompiler` that handles the typical Unix-style command-line C compiler:
|
|
|
|
* macros defined with :option:`!-Dname[=value]`
|
|
|
|
* macros undefined with :option:`!-Uname`
|
|
|
|
* include search directories specified with :option:`!-Idir`
|
|
|
|
* libraries specified with :option:`!-llib`
|
|
|
|
* library search directories specified with :option:`!-Ldir`
|
|
|
|
* compile handled by :program:`cc` (or similar) executable with :option:`!-c`
|
|
option: compiles :file:`.c` to :file:`.o`
|
|
|
|
* link static library handled by :program:`ar` command (possibly with
|
|
:program:`ranlib`)
|
|
|
|
* link shared library handled by :program:`cc` :option:`!-shared`
|
|
|
|
|
|
:mod:`distutils.msvccompiler` --- Microsoft Compiler
|
|
====================================================
|
|
|
|
.. module:: distutils.msvccompiler
|
|
:synopsis: Microsoft Compiler
|
|
|
|
.. XXX: This is *waaaaay* out of date!
|
|
|
|
This module provides :class:`MSVCCompiler`, an implementation of the abstract
|
|
:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension
|
|
modules need to be compiled with the same compiler that was used to compile
|
|
Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python
|
|
2.4 and 2.5, the compiler is Visual Studio .NET 2003.
|
|
|
|
:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on
|
|
its own. To override this choice, the environment variables *DISTUTILS_USE_SDK*
|
|
and *MSSdk* must be both set. *MSSdk* indicates that the current environment has
|
|
been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables
|
|
had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates
|
|
that the distutils user has made an explicit choice to override the compiler
|
|
selection by :class:`MSVCCompiler`.
|
|
|
|
|
|
:mod:`distutils.bcppcompiler` --- Borland Compiler
|
|
==================================================
|
|
|
|
.. module:: distutils.bcppcompiler
|
|
|
|
|
|
This module provides :class:`BorlandCCompiler`, a subclass of the abstract
|
|
:class:`CCompiler` class for the Borland C++ compiler.
|
|
|
|
|
|
:mod:`distutils.cygwincompiler` --- Cygwin Compiler
|
|
===================================================
|
|
|
|
.. module:: distutils.cygwinccompiler
|
|
|
|
|
|
This module provides the :class:`CygwinCCompiler` class, a subclass of
|
|
:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to
|
|
Windows. It also contains the Mingw32CCompiler class which handles the mingw32
|
|
port of GCC (same as cygwin in no-cygwin mode).
|
|
|
|
|
|
:mod:`distutils.archive_util` --- Archiving utilities
|
|
======================================================
|
|
|
|
.. module:: distutils.archive_util
|
|
:synopsis: Utility functions for creating archive files (tarballs, zip files, ...)
|
|
|
|
|
|
This module provides a few functions for creating archive files, such as
|
|
tarballs or zipfiles.
|
|
|
|
|
|
.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0])
|
|
|
|
Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of
|
|
the file to create, minus any format-specific extension; *format* is the
|
|
archive format: one of ``zip``, ``tar``, ``gztar``, ``bztar``, ``xztar``, or
|
|
``ztar``. *root_dir* is a directory that will be the root directory of the
|
|
archive; ie. we typically ``chdir`` into *root_dir* before creating the
|
|
archive. *base_dir* is the directory where we start archiving from; ie.
|
|
*base_dir* will be the common prefix of all files and directories in the
|
|
archive. *root_dir* and *base_dir* both default to the current directory.
|
|
Returns the name of the archive file.
|
|
|
|
.. versionchanged:: 3.5
|
|
Added support for the ``xztar`` format.
|
|
|
|
|
|
.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
|
|
|
|
'Create an (optional compressed) archive as a tar file from all files in and
|
|
under *base_dir*. *compress* must be ``'gzip'`` (the default),
|
|
``'bzip2'``, ``'xz'``, ``'compress'``, or ``None``. For the ``'compress'``
|
|
method the compression utility named by :program:`compress` must be on the
|
|
default program search path, so this is probably Unix-specific. The output
|
|
tar file will be named :file:`base_dir.tar`, possibly plus the appropriate
|
|
compression extension (``.gz``, ``.bz2``, ``.xz`` or ``.Z``). Return the
|
|
output filename.
|
|
|
|
.. versionchanged:: 3.5
|
|
Added support for the ``xz`` compression.
|
|
|
|
|
|
.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
|
|
|
|
Create a zip file from all files in and under *base_dir*. The output zip file
|
|
will be named *base_name* + :file:`.zip`. Uses either the :mod:`zipfile` Python
|
|
module (if available) or the InfoZIP :file:`zip` utility (if installed and
|
|
found on the default search path). If neither tool is available, raises
|
|
:exc:`DistutilsExecError`. Returns the name of the output zip file.
|
|
|
|
|
|
:mod:`distutils.dep_util` --- Dependency checking
|
|
=================================================
|
|
|
|
.. module:: distutils.dep_util
|
|
:synopsis: Utility functions for simple dependency checking
|
|
|
|
|
|
This module provides functions for performing simple, timestamp-based
|
|
dependency of files and groups of files; also, functions based entirely on such
|
|
timestamp dependency analysis.
|
|
|
|
|
|
.. function:: newer(source, target)
|
|
|
|
Return true if *source* exists and is more recently modified than *target*, or
|
|
if *source* exists and *target* doesn't. Return false if both exist and *target*
|
|
is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if
|
|
*source* does not exist.
|
|
|
|
|
|
.. function:: newer_pairwise(sources, targets)
|
|
|
|
Walk two filename lists in parallel, testing if each source is newer than its
|
|
corresponding target. Return a pair of lists (*sources*, *targets*) where
|
|
source is newer than target, according to the semantics of :func:`newer`.
|
|
|
|
.. % % equivalent to a listcomp...
|
|
|
|
|
|
.. function:: newer_group(sources, target[, missing='error'])
|
|
|
|
Return true if *target* is out-of-date with respect to any file listed in
|
|
*sources*. In other words, if *target* exists and is newer than every file in
|
|
*sources*, return false; otherwise return true. *missing* controls what we do
|
|
when a source file is missing; the default (``'error'``) is to blow up with an
|
|
:exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently
|
|
drop any missing source files; if it is ``'newer'``, any missing source files
|
|
make us assume that *target* is out-of-date (this is handy in "dry-run" mode:
|
|
it'll make you pretend to carry out commands that wouldn't work because inputs
|
|
are missing, but that doesn't matter because you're not actually going to run
|
|
the commands).
|
|
|
|
|
|
:mod:`distutils.dir_util` --- Directory tree operations
|
|
=======================================================
|
|
|
|
.. module:: distutils.dir_util
|
|
:synopsis: Utility functions for operating on directories and directory trees
|
|
|
|
|
|
This module provides functions for operating on directories and trees of
|
|
directories.
|
|
|
|
|
|
.. function:: mkpath(name[, mode=0o777, verbose=0, dry_run=0])
|
|
|
|
Create a directory and any missing ancestor directories. If the directory
|
|
already exists (or if *name* is the empty string, which means the current
|
|
directory, which of course exists), then do nothing. Raise
|
|
:exc:`DistutilsFileError` if unable to create some directory along the way (eg.
|
|
some sub-path exists, but is a file rather than a directory). If *verbose* is
|
|
true, print a one-line summary of each mkdir to stdout. Return the list of
|
|
directories actually created.
|
|
|
|
|
|
.. function:: create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0])
|
|
|
|
Create all the empty directories under *base_dir* needed to put *files* there.
|
|
*base_dir* is just the name of a directory which doesn't necessarily exist
|
|
yet; *files* is a list of filenames to be interpreted relative to *base_dir*.
|
|
*base_dir* + the directory portion of every file in *files* will be created if
|
|
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])
|
|
|
|
Copy an entire directory tree *src* to a new location *dst*. Both *src* and
|
|
*dst* must be directory names. If *src* is not a directory, raise
|
|
:exc:`DistutilsFileError`. If *dst* does not exist, it is created with
|
|
:func:`mkpath`. The end result of the copy is that every file in *src* is
|
|
copied to *dst*, and directories under *src* are recursively copied to *dst*.
|
|
Return the list of files that were copied or might have been copied, using their
|
|
output name. The return value is unaffected by *update* or *dry_run*: it is
|
|
simply the list of all files under *src*, with the names changed to be under
|
|
*dst*.
|
|
|
|
*preserve_mode* and *preserve_times* are the same as for
|
|
:func:`distutils.file_util.copy_file`; note that they only apply to
|
|
regular files, not to
|
|
directories. If *preserve_symlinks* is true, symlinks will be copied as
|
|
symlinks (on platforms that support them!); otherwise (the default), the
|
|
destination of the symlink will be copied. *update* and *verbose* are the same
|
|
as for :func:`copy_file`.
|
|
|
|
Files in *src* that begin with :file:`.nfs` are skipped (more information on
|
|
these files is available in answer D2 of the `NFS FAQ page
|
|
<http://nfs.sourceforge.net/#section_d>`_).
|
|
|
|
.. versionchanged:: 3.3.1
|
|
NFS files are ignored.
|
|
|
|
.. function:: remove_tree(directory[, verbose=0, dry_run=0])
|
|
|
|
Recursively remove *directory* and all files and directories underneath it. Any
|
|
errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
|
|
true).
|
|
|
|
|
|
:mod:`distutils.file_util` --- Single file operations
|
|
=====================================================
|
|
|
|
.. module:: distutils.file_util
|
|
:synopsis: Utility functions for operating on single files
|
|
|
|
|
|
This module contains some utility functions for operating on individual files.
|
|
|
|
|
|
.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0])
|
|
|
|
Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there
|
|
with the same name; otherwise, it must be a filename. (If the file exists, it
|
|
will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the
|
|
file's mode (type and permission bits, or whatever is analogous on the
|
|
current platform) is copied. If *preserve_times* is true (the default), the
|
|
last-modified and last-access times are copied as well. If *update* is true,
|
|
*src* will only be copied if *dst* does not exist, or if *dst* does exist but
|
|
is older than *src*.
|
|
|
|
*link* allows you to make hard links (using :func:`os.link`) or symbolic links
|
|
(using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or
|
|
``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link*
|
|
on systems that don't support it: :func:`copy_file` doesn't check if hard or
|
|
symbolic linking is available. It uses :func:`_copy_file_contents` to copy file
|
|
contents.
|
|
|
|
Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the
|
|
output file, and *copied* is true if the file was copied (or would have been
|
|
copied, if *dry_run* true).
|
|
|
|
.. % XXX if the destination file already exists, we clobber it if
|
|
.. % copying, but blow up if linking. Hmmm. And I don't know what
|
|
.. % macostools.copyfile() does. Should definitely be consistent, and
|
|
.. % should probably blow up if destination exists and we would be
|
|
.. % changing it (ie. it's not already a hard/soft link to src OR
|
|
.. % (not update) and (src newer than dst)).
|
|
|
|
|
|
.. function:: move_file(src, dst[, verbose, dry_run])
|
|
|
|
Move file *src* to *dst*. If *dst* is a directory, the file will be moved into
|
|
it with the same name; otherwise, *src* is just renamed to *dst*. Returns the
|
|
new full name of the file.
|
|
|
|
.. warning::
|
|
|
|
Handles cross-device moves on Unix using :func:`copy_file`. What about
|
|
other systems?
|
|
|
|
|
|
.. function:: write_file(filename, contents)
|
|
|
|
Create a file called *filename* and write *contents* (a sequence of strings
|
|
without line terminators) to it.
|
|
|
|
|
|
:mod:`distutils.util` --- Miscellaneous other utility functions
|
|
===============================================================
|
|
|
|
.. module:: distutils.util
|
|
:synopsis: Miscellaneous other utility functions
|
|
|
|
|
|
This module contains other assorted bits and pieces that don't fit into any
|
|
other utility module.
|
|
|
|
|
|
.. function:: get_platform()
|
|
|
|
Return a string that identifies the current platform. This is used mainly to
|
|
distinguish platform-specific build directories and platform-specific built
|
|
distributions. Typically includes the OS name and version and the
|
|
architecture (as supplied by 'os.uname()'), although the exact information
|
|
included depends on the OS; e.g., on Linux, the kernel version isn't
|
|
particularly important.
|
|
|
|
Examples of returned values:
|
|
|
|
* ``linux-i586``
|
|
* ``linux-alpha``
|
|
* ``solaris-2.6-sun4u``
|
|
|
|
For non-POSIX platforms, currently just returns ``sys.platform``.
|
|
|
|
For macOS systems the OS version reflects the minimal version on which
|
|
binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET``
|
|
during the build of Python), not the OS version of the current system.
|
|
|
|
For universal binary builds on macOS the architecture value reflects
|
|
the universal binary status instead of the architecture of the current
|
|
processor. For 32-bit universal binaries the architecture is ``fat``,
|
|
for 64-bit universal binaries the architecture is ``fat64``, and
|
|
for 4-way universal binaries the architecture is ``universal``. Starting
|
|
from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for
|
|
a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for
|
|
a universal build with the i386 and x86_64 architectures
|
|
|
|
Examples of returned values on macOS:
|
|
|
|
* ``macosx-10.3-ppc``
|
|
|
|
* ``macosx-10.3-fat``
|
|
|
|
* ``macosx-10.5-universal``
|
|
|
|
* ``macosx-10.6-intel``
|
|
|
|
For AIX, Python 3.9 and later return a string starting with "aix", followed
|
|
by additional fields (separated by ``'-'``) that represent the combined
|
|
values of AIX Version, Release and Technology Level (first field), Build Date
|
|
(second field), and bit-size (third field). Python 3.8 and earlier returned
|
|
only a single additional field with the AIX Version and Release.
|
|
|
|
Examples of returned values on AIX:
|
|
|
|
* ``aix-5307-0747-32`` # 32-bit build on AIX ``oslevel -s``: 5300-07-00-0000
|
|
|
|
* ``aix-7105-1731-64`` # 64-bit build on AIX ``oslevel -s``: 7100-05-01-1731
|
|
|
|
* ``aix-7.2`` # Legacy form reported in Python 3.8 and earlier
|
|
|
|
.. versionchanged:: 3.9
|
|
The AIX platform string format now also includes the technology level,
|
|
build date, and ABI bit-size.
|
|
|
|
|
|
.. function:: convert_path(pathname)
|
|
|
|
Return 'pathname' as a name that will work on the native filesystem, i.e. split
|
|
it on '/' and put it back together again using the current directory separator.
|
|
Needed because filenames in the setup script are always supplied in Unix style,
|
|
and have to be converted to the local convention before we can actually use them
|
|
in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if
|
|
*pathname* either starts or ends with a slash.
|
|
|
|
|
|
.. function:: change_root(new_root, pathname)
|
|
|
|
Return *pathname* with *new_root* prepended. If *pathname* is relative, this is
|
|
equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making
|
|
*pathname* relative and then joining the two, which is tricky on DOS/Windows.
|
|
|
|
|
|
.. function:: check_environ()
|
|
|
|
Ensure that 'os.environ' has all the environment variables we guarantee that
|
|
users can use in config files, command-line options, etc. Currently this
|
|
includes:
|
|
|
|
* :envvar:`HOME` - user's home directory (Unix only)
|
|
* :envvar:`PLAT` - description of the current platform, including hardware and
|
|
OS (see :func:`get_platform`)
|
|
|
|
|
|
.. function:: subst_vars(s, local_vars)
|
|
|
|
Perform shell/Perl-style variable substitution on *s*. Every occurrence of
|
|
``$`` followed by a name is considered a variable, and variable is substituted
|
|
by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's
|
|
not in *local_vars*. *os.environ* is first checked/augmented to guarantee that
|
|
it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError`
|
|
for any variables not found in either *local_vars* or ``os.environ``.
|
|
|
|
Note that this is not a fully-fledged string interpolation function. A valid
|
|
``$variable`` can consist only of upper and lower case letters, numbers and an
|
|
underscore. No { } or ( ) style quoting is available.
|
|
|
|
|
|
.. function:: split_quoted(s)
|
|
|
|
Split a string up according to Unix shell-like rules for quotes and backslashes.
|
|
In short: words are delimited by spaces, as long as those spaces are not escaped
|
|
by a backslash, or inside a quoted string. Single and double quotes are
|
|
equivalent, and the quote characters can be backslash-escaped. The backslash is
|
|
stripped from any two-character escape sequence, leaving only the escaped
|
|
character. The quote characters are stripped from any quoted string. Returns a
|
|
list of words.
|
|
|
|
.. % Should probably be moved into the standard library.
|
|
|
|
|
|
.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0])
|
|
|
|
Perform some action that affects the outside world (for instance, writing to the
|
|
filesystem). Such actions are special because they are disabled by the
|
|
*dry_run* flag. This method takes care of all that bureaucracy for you; all
|
|
you have to do is supply the function to call and an argument tuple for it (to
|
|
embody the "external action" being performed), and an optional message to print.
|
|
|
|
|
|
.. function:: strtobool(val)
|
|
|
|
Convert a string representation of truth to true (1) or false (0).
|
|
|
|
True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values
|
|
are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises
|
|
:exc:`ValueError` if *val* is anything else.
|
|
|
|
|
|
.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None])
|
|
|
|
Byte-compile a collection of Python source files to :file:`.pyc` files in a
|
|
:file:`__pycache__` subdirectory (see :pep:`3147` and :pep:`488`).
|
|
*py_files* is a list of files to compile; any files that don't end in
|
|
:file:`.py` are silently skipped. *optimize* must be one of the following:
|
|
|
|
* ``0`` - don't optimize
|
|
* ``1`` - normal optimization (like ``python -O``)
|
|
* ``2`` - extra optimization (like ``python -OO``)
|
|
|
|
If *force* is true, all files are recompiled regardless of timestamps.
|
|
|
|
The source filename encoded in each :term:`bytecode` file defaults to the filenames
|
|
listed in *py_files*; you can modify these with *prefix* and *basedir*.
|
|
*prefix* is a string that will be stripped off of each source filename, and
|
|
*base_dir* is a directory name that will be prepended (after *prefix* is
|
|
stripped). You can supply either or both (or neither) of *prefix* and
|
|
*base_dir*, as you wish.
|
|
|
|
If *dry_run* is true, doesn't actually do anything that would affect the
|
|
filesystem.
|
|
|
|
Byte-compilation is either done directly in this interpreter process with the
|
|
standard :mod:`py_compile` module, or indirectly by writing a temporary script
|
|
and executing it. Normally, you should let :func:`byte_compile` figure out to
|
|
use direct compilation or not (see the source for details). The *direct* flag
|
|
is used by the script generated in indirect mode; unless you know what you're
|
|
doing, leave it set to ``None``.
|
|
|
|
.. versionchanged:: 3.2.3
|
|
Create ``.pyc`` files with an :func:`import magic tag
|
|
<imp.get_tag>` in their name, in a :file:`__pycache__` subdirectory
|
|
instead of files without tag in the current directory.
|
|
|
|
.. versionchanged:: 3.5
|
|
Create ``.pyc`` files according to :pep:`488`.
|
|
|
|
|
|
.. function:: rfc822_escape(header)
|
|
|
|
Return a version of *header* escaped for inclusion in an :rfc:`822` header, by
|
|
ensuring there are 8 spaces space after each newline. Note that it does no other
|
|
modification of the string.
|
|
|
|
.. % this _can_ be replaced
|
|
|
|
.. % \subsection{Distutils objects}
|
|
|
|
|
|
:mod:`distutils.dist` --- The Distribution class
|
|
================================================
|
|
|
|
.. module:: distutils.dist
|
|
:synopsis: Provides the Distribution class, which represents the module distribution being
|
|
built/installed/distributed
|
|
|
|
|
|
This module provides the :class:`~distutils.core.Distribution` class, which
|
|
represents the module distribution being built/installed/distributed.
|
|
|
|
|
|
:mod:`distutils.extension` --- The Extension class
|
|
==================================================
|
|
|
|
.. module:: distutils.extension
|
|
: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++
|
|
extension modules in setup scripts.
|
|
|
|
.. % \subsection{Ungrouped modules}
|
|
.. % The following haven't been moved into a more appropriate section yet.
|
|
|
|
|
|
:mod:`distutils.debug` --- Distutils debug mode
|
|
===============================================
|
|
|
|
.. module:: distutils.debug
|
|
:synopsis: Provides the debug flag for distutils
|
|
|
|
|
|
This module provides the DEBUG flag.
|
|
|
|
|
|
:mod:`distutils.errors` --- Distutils exceptions
|
|
================================================
|
|
|
|
.. module:: distutils.errors
|
|
:synopsis: Provides standard distutils exceptions
|
|
|
|
|
|
Provides exceptions used by the Distutils modules. Note that Distutils modules
|
|
may raise standard exceptions; in particular, SystemExit is usually raised for
|
|
errors that are obviously the end-user's fault (eg. bad command-line arguments).
|
|
|
|
This module is safe to use in ``from ... import *`` mode; it only exports
|
|
symbols whose names start with ``Distutils`` and end with ``Error``.
|
|
|
|
|
|
:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module
|
|
===========================================================================
|
|
|
|
.. module:: distutils.fancy_getopt
|
|
:synopsis: Additional getopt functionality
|
|
|
|
|
|
This module provides a wrapper around the standard :mod:`getopt` module that
|
|
provides the following additional features:
|
|
|
|
* short and long options are tied together
|
|
|
|
* options have help strings, so :func:`fancy_getopt` could potentially create a
|
|
complete usage summary
|
|
|
|
* options set attributes of a passed-in object
|
|
|
|
* boolean options can have "negative aliases" --- eg. if :option:`!--quiet` is
|
|
the "negative alias" of :option:`!--verbose`, then :option:`!--quiet` on the
|
|
command line sets *verbose* to false.
|
|
|
|
.. function:: fancy_getopt(options, negative_opt, object, args)
|
|
|
|
Wrapper function. *options* is a list of ``(long_option, short_option,
|
|
help_string)`` 3-tuples as described in the constructor for
|
|
:class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names
|
|
to option names, both the key and value should be in the *options* list.
|
|
*object* is an object which will be used to store values (see the :meth:`getopt`
|
|
method of the :class:`FancyGetopt` class). *args* is the argument list. Will use
|
|
``sys.argv[1:]`` if you pass ``None`` as *args*.
|
|
|
|
|
|
.. function:: wrap_text(text, width)
|
|
|
|
Wraps *text* to less than *width* wide.
|
|
|
|
|
|
.. class:: FancyGetopt([option_table=None])
|
|
|
|
The option_table is a list of 3-tuples: ``(long_option, short_option,
|
|
help_string)``
|
|
|
|
If an option takes an argument, its *long_option* should have ``'='`` appended;
|
|
*short_option* should just be a single character, no ``':'`` in any case.
|
|
*short_option* should be ``None`` if a *long_option* doesn't have a
|
|
corresponding *short_option*. All option tuples must have long options.
|
|
|
|
The :class:`FancyGetopt` class provides the following methods:
|
|
|
|
|
|
.. method:: FancyGetopt.getopt([args=None, object=None])
|
|
|
|
Parse command-line options in args. Store as attributes on *object*.
|
|
|
|
If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is
|
|
``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores
|
|
option values there, and returns a tuple ``(args, object)``. If *object* is
|
|
supplied, it is modified in place and :func:`getopt` just returns *args*; in
|
|
both cases, the returned *args* is a modified copy of the passed-in *args* list,
|
|
which is left untouched.
|
|
|
|
.. % and args returned are?
|
|
|
|
|
|
.. method:: FancyGetopt.get_option_order()
|
|
|
|
Returns the list of ``(option, value)`` tuples processed by the previous run of
|
|
:meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called
|
|
yet.
|
|
|
|
|
|
.. method:: FancyGetopt.generate_help([header=None])
|
|
|
|
Generate help text (a list of strings, one per suggested line of output) from
|
|
the option table for this :class:`FancyGetopt` object.
|
|
|
|
If supplied, prints the supplied *header* at the top of the help.
|
|
|
|
|
|
:mod:`distutils.filelist` --- The FileList class
|
|
================================================
|
|
|
|
.. module:: distutils.filelist
|
|
:synopsis: The FileList class, used for poking about the file system and
|
|
building lists of files.
|
|
|
|
|
|
This module provides the :class:`FileList` class, used for poking about the
|
|
filesystem and building lists of files.
|
|
|
|
|
|
:mod:`distutils.log` --- Simple :pep:`282`-style logging
|
|
========================================================
|
|
|
|
.. module:: distutils.log
|
|
:synopsis: A simple logging mechanism, :pep:`282`-style
|
|
|
|
|
|
:mod:`distutils.spawn` --- Spawn a sub-process
|
|
==============================================
|
|
|
|
.. module:: distutils.spawn
|
|
:synopsis: Provides the spawn() function
|
|
|
|
|
|
This module provides the :func:`spawn` function, a front-end to various
|
|
platform-specific functions for launching another program in a sub-process.
|
|
Also provides :func:`find_executable` to search the path for a given executable
|
|
name.
|
|
|
|
|
|
:mod:`distutils.sysconfig` --- System configuration information
|
|
===============================================================
|
|
|
|
.. module:: distutils.sysconfig
|
|
:synopsis: Low-level access to configuration information of the Python interpreter.
|
|
.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
|
|
.. moduleauthor:: Greg Ward <gward@python.net>
|
|
.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
|
|
|
|
|
|
The :mod:`distutils.sysconfig` module provides access to Python's low-level
|
|
configuration information. The specific configuration variables available
|
|
depend heavily on the platform and configuration. The specific variables depend
|
|
on the build process for the specific version of Python being run; the variables
|
|
are those found in the :file:`Makefile` and configuration header that are
|
|
installed with Python on Unix systems. The configuration header is called
|
|
:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h`
|
|
for earlier versions of Python.
|
|
|
|
Some additional functions are provided which perform some useful manipulations
|
|
for other parts of the :mod:`distutils` package.
|
|
|
|
|
|
.. data:: PREFIX
|
|
|
|
The result of ``os.path.normpath(sys.prefix)``.
|
|
|
|
|
|
.. data:: EXEC_PREFIX
|
|
|
|
The result of ``os.path.normpath(sys.exec_prefix)``.
|
|
|
|
|
|
.. function:: get_config_var(name)
|
|
|
|
Return the value of a single variable. This is equivalent to
|
|
``get_config_vars().get(name)``.
|
|
|
|
|
|
.. function:: get_config_vars(...)
|
|
|
|
Return a set of variable definitions. If there are no arguments, this returns a
|
|
dictionary mapping names of configuration variables to values. If arguments are
|
|
provided, they should be strings, and the return value will be a sequence giving
|
|
the associated values. If a given name does not have a corresponding value,
|
|
``None`` will be included for that variable.
|
|
|
|
|
|
.. function:: get_config_h_filename()
|
|
|
|
Return the full path name of the configuration header. For Unix, this will be
|
|
the header generated by the :program:`configure` script; for other platforms the
|
|
header will have been supplied directly by the Python source distribution. The
|
|
file is a platform-specific text file.
|
|
|
|
|
|
.. function:: get_makefile_filename()
|
|
|
|
Return the full path name of the :file:`Makefile` used to build Python. For
|
|
Unix, this will be a file generated by the :program:`configure` script; the
|
|
meaning for other platforms will vary. The file is a platform-specific text
|
|
file, if it exists. This function is only useful on POSIX platforms.
|
|
|
|
|
|
.. function:: get_python_inc([plat_specific[, prefix]])
|
|
|
|
Return the directory for either the general or platform-dependent C include
|
|
files. If *plat_specific* is true, the platform-dependent include directory is
|
|
returned; if false or omitted, the platform-independent directory is returned.
|
|
If *prefix* is given, it is used as either the prefix instead of
|
|
:const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
|
|
*plat_specific* is true.
|
|
|
|
|
|
.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]])
|
|
|
|
Return the directory for either the general or platform-dependent library
|
|
installation. If *plat_specific* is true, the platform-dependent include
|
|
directory is returned; if false or omitted, the platform-independent directory
|
|
is returned. If *prefix* is given, it is used as either the prefix instead of
|
|
:const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if
|
|
*plat_specific* is true. If *standard_lib* is true, the directory for the
|
|
standard library is returned rather than the directory for the installation of
|
|
third-party extensions.
|
|
|
|
The following function is only intended for use within the :mod:`distutils`
|
|
package.
|
|
|
|
|
|
.. function:: customize_compiler(compiler)
|
|
|
|
Do any platform-specific customization of a
|
|
:class:`distutils.ccompiler.CCompiler` instance.
|
|
|
|
This function is only needed on Unix at this time, but should be called
|
|
consistently to support forward-compatibility. It inserts the information that
|
|
varies across Unix flavors and is stored in Python's :file:`Makefile`. This
|
|
information includes the selected compiler, compiler and linker options, and the
|
|
extension used by the linker for shared objects.
|
|
|
|
This function is even more special-purpose, and should only be used from
|
|
Python's own build procedures.
|
|
|
|
|
|
.. function:: set_python_build()
|
|
|
|
Inform the :mod:`distutils.sysconfig` module that it is being used as part of
|
|
the build process for Python. This changes a lot of relative locations for
|
|
files, allowing them to be located in the build area rather than in an installed
|
|
Python.
|
|
|
|
|
|
:mod:`distutils.text_file` --- The TextFile class
|
|
=================================================
|
|
|
|
.. module:: distutils.text_file
|
|
:synopsis: Provides the TextFile class, a simple interface to text files
|
|
|
|
|
|
This module provides the :class:`TextFile` class, which gives an interface to
|
|
text files that (optionally) takes care of stripping comments, ignoring blank
|
|
lines, and joining lines with backslashes.
|
|
|
|
|
|
.. class:: TextFile([filename=None, file=None, **options])
|
|
|
|
This class provides a file-like object that takes care of all the things you
|
|
commonly want to do when processing a text file that has some line-by-line
|
|
syntax: strip comments (as long as ``#`` is your comment character), skip blank
|
|
lines, join adjacent lines by escaping the newline (ie. backslash at end of
|
|
line), strip leading and/or trailing whitespace. All of these are optional and
|
|
independently controllable.
|
|
|
|
The class provides a :meth:`warn` method so you can generate warning messages
|
|
that report physical line number, even if the logical line in question spans
|
|
multiple physical lines. Also provides :meth:`unreadline` for implementing
|
|
line-at-a-time lookahead.
|
|
|
|
:class:`TextFile` instances are create with either *filename*, *file*, or both.
|
|
:exc:`RuntimeError` is raised if both are ``None``. *filename* should be a
|
|
string, and *file* a file object (or something that provides :meth:`readline`
|
|
and :meth:`close` methods). It is recommended that you supply at least
|
|
*filename*, so that :class:`TextFile` can include it in warning messages. If
|
|
*file* is not supplied, :class:`TextFile` creates its own using the
|
|
:func:`open` built-in function.
|
|
|
|
The options are all boolean, and affect the values returned by :meth:`readline`
|
|
|
|
.. tabularcolumns:: |l|L|l|
|
|
|
|
+------------------+--------------------------------+---------+
|
|
| option name | description | default |
|
|
+==================+================================+=========+
|
|
| *strip_comments* | strip from ``'#'`` to | true |
|
|
| | end-of-line, as well as any | |
|
|
| | whitespace leading up to the | |
|
|
| | ``'#'``\ ---unless it is | |
|
|
| | escaped by a backslash | |
|
|
+------------------+--------------------------------+---------+
|
|
| *lstrip_ws* | strip leading whitespace from | false |
|
|
| | each line before returning it | |
|
|
+------------------+--------------------------------+---------+
|
|
| *rstrip_ws* | strip trailing whitespace | true |
|
|
| | (including line terminator!) | |
|
|
| | from each line before | |
|
|
| | returning it. | |
|
|
+------------------+--------------------------------+---------+
|
|
| *skip_blanks* | skip lines that are empty | true |
|
|
| | \*after\* stripping comments | |
|
|
| | and whitespace. (If both | |
|
|
| | lstrip_ws and rstrip_ws are | |
|
|
| | false, then some lines may | |
|
|
| | consist of solely whitespace: | |
|
|
| | these will \*not\* be skipped, | |
|
|
| | even if *skip_blanks* is | |
|
|
| | true.) | |
|
|
+------------------+--------------------------------+---------+
|
|
| *join_lines* | if a backslash is the last | false |
|
|
| | non-newline character on a | |
|
|
| | line after stripping comments | |
|
|
| | and whitespace, join the | |
|
|
| | following line to it to form | |
|
|
| | one logical line; if N | |
|
|
| | consecutive lines end with a | |
|
|
| | backslash, then N+1 physical | |
|
|
| | lines will be joined to form | |
|
|
| | one logical line. | |
|
|
+------------------+--------------------------------+---------+
|
|
| *collapse_join* | strip leading whitespace from | false |
|
|
| | lines that are joined to their | |
|
|
| | predecessor; only matters if | |
|
|
| | ``(join_lines and not | |
|
|
| | lstrip_ws)`` | |
|
|
+------------------+--------------------------------+---------+
|
|
|
|
Note that since *rstrip_ws* can strip the trailing newline, the semantics of
|
|
:meth:`readline` must differ from those of the built-in file object's
|
|
:meth:`readline` method! In particular, :meth:`readline` returns ``None`` for
|
|
end-of-file: an empty string might just be a blank line (or an all-whitespace
|
|
line), if *rstrip_ws* is true but *skip_blanks* is not.
|
|
|
|
|
|
.. method:: TextFile.open(filename)
|
|
|
|
Open a new file *filename*. This overrides any *file* or *filename*
|
|
constructor arguments.
|
|
|
|
|
|
.. method:: TextFile.close()
|
|
|
|
Close the current file and forget everything we know about it (including the
|
|
filename and the current line number).
|
|
|
|
|
|
.. method:: TextFile.warn(msg[,line=None])
|
|
|
|
Print (to stderr) a warning message tied to the current logical line in the
|
|
current file. If the current logical line in the file spans multiple physical
|
|
lines, the warning refers to the whole range, such as ``"lines 3-5"``. If
|
|
*line* is supplied, it overrides the current line number; it may be a list or
|
|
tuple to indicate a range of physical lines, or an integer for a single
|
|
physical line.
|
|
|
|
|
|
.. method:: TextFile.readline()
|
|
|
|
Read and return a single logical line from the current file (or from an internal
|
|
buffer if lines have previously been "unread" with :meth:`unreadline`). If the
|
|
*join_lines* option is true, this may involve reading multiple physical lines
|
|
concatenated into a single string. Updates the current line number, so calling
|
|
:meth:`warn` after :meth:`readline` emits a warning about the physical line(s)
|
|
just read. Returns ``None`` on end-of-file, since the empty string can occur
|
|
if *rstrip_ws* is true but *strip_blanks* is not.
|
|
|
|
|
|
.. method:: TextFile.readlines()
|
|
|
|
Read and return the list of all logical lines remaining in the current file.
|
|
This updates the current line number to the last line of the file.
|
|
|
|
|
|
.. method:: TextFile.unreadline(line)
|
|
|
|
Push *line* (a string) onto an internal buffer that will be checked by future
|
|
:meth:`readline` calls. Handy for implementing a parser with line-at-a-time
|
|
lookahead. Note that lines that are "unread" with :meth:`unreadline` are not
|
|
subsequently re-cleansed (whitespace stripped, or whatever) when read with
|
|
:meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call
|
|
to :meth:`readline`, the lines will be returned most in most recent first order.
|
|
|
|
|
|
:mod:`distutils.version` --- Version number classes
|
|
===================================================
|
|
|
|
.. module:: distutils.version
|
|
:synopsis: Implements classes that represent module version numbers.
|
|
|
|
|
|
.. % todo
|
|
.. % \section{Distutils Commands}
|
|
.. %
|
|
.. % This part of Distutils implements the various Distutils commands, such
|
|
.. % as \code{build}, \code{install} \&c. Each command is implemented as a
|
|
.. % separate module, with the command name as the name of the module.
|
|
|
|
|
|
:mod:`distutils.cmd` --- Abstract base class for Distutils commands
|
|
===================================================================
|
|
|
|
.. module:: distutils.cmd
|
|
:synopsis: Provides the abstract base class :class:`~distutils.cmd.Command`. This class
|
|
is subclassed by the modules in the distutils.command subpackage.
|
|
|
|
|
|
This module supplies the abstract base class :class:`Command`.
|
|
|
|
|
|
.. class:: Command(dist)
|
|
|
|
Abstract base class for defining command classes, the "worker bees" of the
|
|
Distutils. A useful analogy for command classes is to think of them as
|
|
subroutines with local variables called *options*. The options are declared
|
|
in :meth:`initialize_options` and defined (given their final values) in
|
|
:meth:`finalize_options`, both of which must be defined by every command
|
|
class. The distinction between the two is necessary because option values
|
|
might come from the outside world (command line, config file, ...), and any
|
|
options dependent on other options must be computed after these outside
|
|
influences have been processed --- hence :meth:`finalize_options`. The body
|
|
of the subroutine, where it does all its work based on the values of its
|
|
options, is the :meth:`run` method, which must also be implemented by every
|
|
command class.
|
|
|
|
The class constructor takes a single argument *dist*, a
|
|
:class:`~distutils.core.Distribution` instance.
|
|
|
|
|
|
Creating a new Distutils command
|
|
================================
|
|
|
|
This section outlines the steps to create a new Distutils command.
|
|
|
|
A new command lives in a module in the :mod:`distutils.command` package. There
|
|
is a sample template in that directory called :file:`command_template`. Copy
|
|
this file to a new module with the same name as the new command you're
|
|
implementing. This module should implement a class with the same name as the
|
|
module (and the command). So, for instance, to create the command
|
|
``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
|
|
:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
|
|
it so that it's implementing the class :class:`peel_banana`, a subclass of
|
|
:class:`distutils.cmd.Command`.
|
|
|
|
Subclasses of :class:`Command` must define the following methods.
|
|
|
|
.. method:: Command.initialize_options()
|
|
|
|
Set default values for all the options that this command supports. Note that
|
|
these defaults may be overridden by other commands, by the setup script, by
|
|
config files, or by the command-line. Thus, this is not the place to code
|
|
dependencies between options; generally, :meth:`initialize_options`
|
|
implementations are just a bunch of ``self.foo = None`` assignments.
|
|
|
|
|
|
.. method:: Command.finalize_options()
|
|
|
|
Set final values for all the options that this command supports. This is
|
|
always called as late as possible, ie. after any option assignments from the
|
|
command-line or from other commands have been done. Thus, this is the place
|
|
to code option dependencies: if *foo* depends on *bar*, then it is safe to
|
|
set *foo* from *bar* as long as *foo* still has the same value it was
|
|
assigned in :meth:`initialize_options`.
|
|
|
|
|
|
.. method:: Command.run()
|
|
|
|
A command's raison d'etre: carry out the action it exists to perform, controlled
|
|
by the options initialized in :meth:`initialize_options`, customized by other
|
|
commands, the setup script, the command-line, and config files, and finalized in
|
|
:meth:`finalize_options`. All terminal output and filesystem interaction should
|
|
be done by :meth:`run`.
|
|
|
|
|
|
.. attribute:: Command.sub_commands
|
|
|
|
*sub_commands* formalizes the notion of a "family" of commands,
|
|
e.g. ``install`` as the parent with sub-commands ``install_lib``,
|
|
``install_headers``, etc. The parent of a family of commands defines
|
|
*sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,
|
|
predicate)``, with *command_name* a string and *predicate* a function, a
|
|
string or ``None``. *predicate* is a method of the parent command that
|
|
determines whether the corresponding command is applicable in the current
|
|
situation. (E.g. ``install_headers`` is only applicable if we have any C
|
|
header files to install.) If *predicate* is ``None``, that command is always
|
|
applicable.
|
|
|
|
*sub_commands* is usually defined at the *end* of a class, because
|
|
predicates can be methods of the class, so they must already have been
|
|
defined. The canonical example is the :command:`install` command.
|
|
|
|
|
|
:mod:`distutils.command` --- Individual Distutils commands
|
|
==========================================================
|
|
|
|
.. module:: distutils.command
|
|
:synopsis: Contains one module for each standard Distutils command.
|
|
|
|
|
|
.. % \subsubsection{Individual Distutils commands}
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.bdist` --- Build a binary installer
|
|
===========================================================
|
|
|
|
.. module:: distutils.command.bdist
|
|
:synopsis: Build a binary installer for a package
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
|
|
=============================================================================
|
|
|
|
.. module:: distutils.command.bdist_packager
|
|
:synopsis: Abstract base class for packagers
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
|
|
================================================================
|
|
|
|
.. module:: distutils.command.bdist_dumb
|
|
:synopsis: Build a "dumb" installer - a simple archive of files
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
|
|
=================================================================================
|
|
|
|
.. module:: distutils.command.bdist_msi
|
|
:synopsis: Build a binary distribution as a Windows MSI file
|
|
|
|
.. class:: bdist_msi
|
|
|
|
.. deprecated:: 3.9
|
|
Use bdist_wheel (wheel packages) instead.
|
|
|
|
Builds a `Windows Installer`_ (.msi) binary package.
|
|
|
|
.. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
|
|
|
|
In most cases, the ``bdist_msi`` installer is a better choice than the
|
|
``bdist_wininst`` installer, because it provides better support for
|
|
Win64 platforms, allows administrators to perform non-interactive
|
|
installations, and allows installation through group policies.
|
|
|
|
|
|
:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
|
|
===========================================================================================
|
|
|
|
.. module:: distutils.command.bdist_rpm
|
|
:synopsis: Build a binary distribution as a Redhat RPM and SRPM
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
|
|
====================================================================
|
|
|
|
.. module:: distutils.command.bdist_wininst
|
|
:synopsis: Build a Windows installer
|
|
|
|
.. deprecated:: 3.8
|
|
Use bdist_wheel (wheel packages) instead.
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.sdist` --- Build a source distribution
|
|
==============================================================
|
|
|
|
.. module:: distutils.command.sdist
|
|
:synopsis: Build a source distribution
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.build` --- Build all files of a package
|
|
===============================================================
|
|
|
|
.. module:: distutils.command.build
|
|
:synopsis: Build all files of a package
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.build_clib` --- Build any C libraries in a package
|
|
==========================================================================
|
|
|
|
.. module:: distutils.command.build_clib
|
|
:synopsis: Build any C libraries in a package
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.build_ext` --- Build any extensions in a package
|
|
========================================================================
|
|
|
|
.. module:: distutils.command.build_ext
|
|
:synopsis: Build any extensions in a package
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
|
|
===========================================================================
|
|
|
|
.. module:: distutils.command.build_py
|
|
:synopsis: Build the .py/.pyc files of a package
|
|
|
|
|
|
.. class:: build_py
|
|
|
|
.. class:: build_py_2to3
|
|
|
|
Alternative implementation of build_py which also runs the
|
|
2to3 conversion library on each .py file that is going to be
|
|
installed. To use this in a setup.py file for a distribution
|
|
that is designed to run with both Python 2.x and 3.x, add::
|
|
|
|
try:
|
|
from distutils.command.build_py import build_py_2to3 as build_py
|
|
except ImportError:
|
|
from distutils.command.build_py import build_py
|
|
|
|
to your setup.py, and later::
|
|
|
|
cmdclass = {'build_py': build_py}
|
|
|
|
to the invocation of setup().
|
|
|
|
|
|
:mod:`distutils.command.build_scripts` --- Build the scripts of a package
|
|
=========================================================================
|
|
|
|
.. module:: distutils.command.build_scripts
|
|
:synopsis: Build the scripts of a package
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.clean` --- Clean a package build area
|
|
=============================================================
|
|
|
|
.. module:: distutils.command.clean
|
|
:synopsis: Clean a package build area
|
|
|
|
This command removes the temporary files created by :command:`build`
|
|
and its subcommands, like intermediary compiled object files. With
|
|
the ``--all`` option, the complete build directory will be removed.
|
|
|
|
Extension modules built :ref:`in place <distutils-build-ext-inplace>`
|
|
will not be cleaned, as they are not in the build directory.
|
|
|
|
|
|
:mod:`distutils.command.config` --- Perform package configuration
|
|
=================================================================
|
|
|
|
.. module:: distutils.command.config
|
|
:synopsis: Perform package configuration
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.install` --- Install a package
|
|
======================================================
|
|
|
|
.. module:: distutils.command.install
|
|
:synopsis: Install a package
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.install_data` --- Install data files from a package
|
|
===========================================================================
|
|
|
|
.. module:: distutils.command.install_data
|
|
:synopsis: Install data files from a package
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
|
|
======================================================================================
|
|
|
|
.. module:: distutils.command.install_headers
|
|
:synopsis: Install C/C++ header files from a package
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.install_lib` --- Install library files from a package
|
|
=============================================================================
|
|
|
|
.. module:: distutils.command.install_lib
|
|
:synopsis: Install library files from a package
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.install_scripts` --- Install script files from a package
|
|
================================================================================
|
|
|
|
.. module:: distutils.command.install_scripts
|
|
:synopsis: Install script files from a package
|
|
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.register` --- Register a module with the Python Package Index
|
|
=====================================================================================
|
|
|
|
.. module:: distutils.command.register
|
|
:synopsis: Register a module with the Python Package Index
|
|
|
|
|
|
The ``register`` command registers the package with the Python Package Index.
|
|
This is described in more detail in :pep:`301`.
|
|
|
|
.. % todo
|
|
|
|
|
|
:mod:`distutils.command.check` --- Check the meta-data of a package
|
|
===================================================================
|
|
|
|
.. module:: distutils.command.check
|
|
:synopsis: Check the meta-data of a package
|
|
|
|
|
|
The ``check`` command performs some tests on the meta-data of a package.
|
|
For example, it verifies that all required meta-data are provided as
|
|
the arguments passed to the :func:`setup` function.
|
|
|
|
.. % todo
|