| .. function:: setup(arguments) |
| |
| The basic do-everything function that does most everything you could ever ask |
| for from a Distutils method. See XXXXX |
| |
| The setup function takes a large number of arguments. These are laid out in the |
| following table. |
| |
n | +--------------------+--------------------------------+------------------------------------------------------------------+ |
n | +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | argument name | value | type | |
| | argument name | value | type | |
| +====================+================================+==================================================================+ |
| +====================+================================+=============================================================+ |
| | *name* | The name of the package | a string | |
| | *name* | The name of the package | a string | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *version* | The version number of the | See :mod:`distutils.version` | |
| | *version* | The version number of the | See :mod:`distutils.version` | |
| | | package | | |
| | | package | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *description* | A single line describing the | a string | |
| | *description* | A single line describing the | a string | |
| | | package | | |
| | | package | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *long_description* | Longer description of the | a string | |
| | *long_description* | Longer description of the | a string | |
| | | package | | |
| | | package | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *author* | The name of the package author | a string | |
| | *author* | The name of the package author | a string | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *author_email* | The email address of the | a string | |
| | *author_email* | The email address of the | a string | |
| | | package author | | |
| | | package author | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *maintainer* | The name of the current | a string | |
| | *maintainer* | The name of the current | a string | |
| | | maintainer, if different from | | |
| | | maintainer, if different from | | |
| | | the author | | |
| | | the author | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *maintainer_email* | The email address of the | | |
| | *maintainer_email* | The email address of the | | |
| | | current maintainer, if | | |
| | | current maintainer, if | | |
| | | different from the author | | |
| | | different from the author | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *url* | A URL for the package | a URL | |
| | *url* | A URL for the package | a URL | |
| | | (homepage) | | |
| | | (homepage) | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *download_url* | A URL to download the package | a URL | |
| | *download_url* | A URL to download the package | a URL | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *packages* | A list of Python packages that | a list of strings | |
| | *packages* | A list of Python packages that | a list of strings | |
| | | distutils will manipulate | | |
| | | distutils will manipulate | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *py_modules* | A list of Python modules that | a list of strings | |
| | *py_modules* | A list of Python modules that | a list of strings | |
| | | distutils will manipulate | | |
| | | distutils will manipulate | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *scripts* | A list of standalone script | a list of strings | |
| | *scripts* | A list of standalone script | a list of strings | |
| | | files to be built and | | |
| | | files to be built and | | |
| | | installed | | |
| | | installed | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *ext_modules* | A list of Python extensions to | A list of instances of | |
| | *ext_modules* | A list of Python extensions to | A list of instances of | |
| | | be built | :class:`distutils.core.Extension` | |
| | | be built | :class:`distutils.core.Extension` | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *classifiers* | A list of categories for the | The list of available | |
| | *classifiers* | A list of categories for the | The list of available | |
| | | package | categorizations is at | |
| | | package | categorizations is at | |
| | | | `<http://cheeseshop.python.org/pypi?:action=list_classifiers>`_. | |
| | | | http://pypi.python.org/pypi?:action=list_classifiers. | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *distclass* | the :class:`Distribution` | A subclass of | |
| | *distclass* | the :class:`Distribution` | A subclass of | |
| | | class to use | :class:`distutils.core.Distribution` | |
| | | class to use | :class:`distutils.core.Distribution` | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *script_name* | The name of the setup.py | a string | |
| | *script_name* | The name of the setup.py | a string | |
| | | script - defaults to | | |
| | | script - defaults to | | |
| | | ``sys.argv[0]`` | | |
| | | ``sys.argv[0]`` | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *script_args* | Arguments to supply to the | a list of strings | |
| | *script_args* | Arguments to supply to the | a list of strings | |
| | | setup script | | |
| | | setup script | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *options* | default options for the setup | a string | |
| | *options* | default options for the setup | a string | |
| | | script | | |
| | | script | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *license* | The license for the package | | |
| | *license* | The license for the package | a string | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *keywords* | Descriptive meta-data. See | | |
| | *keywords* | Descriptive meta-data, see | | |
| | | :pep:`314` | | |
| | | :pep:`314` | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *platforms* | | | |
| | *platforms* | | | |
| +--------------------+--------------------------------+------------------------------------------------------------------+ |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| | *cmdclass* | A mapping of command names to | a dictionary | |
| | *cmdclass* | A mapping of command names to | a dictionary | |
| | | :class:`Command` subclasses | | |
| | | :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 | | |
| +--------------------+--------------------------------+-------------------------------------------------------------+ |
| |
n | The list of available categorizations is at |
| `<http://cheeseshop.python.org/pypi?:action=list_classifiers>`_. |
| |
| |
n | .. function:: run_setup(script_name[, script_args=``None``, stop_after=``'run'``]) |
n | .. 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 run with :func:`execfile` ``sys.argv[0]`` |
| |
| .. 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` |
n | class) and Visual C++(:class:`MSVCCompiler` class). Note that it's perfectly |
n | 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? Mac OS X 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`). |
| |
| |
n | .. class:: CCompiler([verbose=``0``, dry_run=``0``, force=``0``]) |
n | .. 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 |
| 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. |
| |
| |
n | .. 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``]) |
n | .. 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. |
| |
| |
n | .. 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``]) |
n | .. 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. |
| |
| |
n | .. 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``]) |
n | .. 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. |
| |
| |
n | .. method:: CCompiler.preprocess(source[, output_file=``None``, macros=``None``, include_dirs=``None``, extra_preargs=``None``, extra_postargs=``None``]) |
n | .. 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. |
| |
| |
n | .. method:: CCompiler.executable_filename(basename[, strip_dir=``0``, output_dir=``''``]) |
n | .. 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. |
| |
| |
n | .. method:: CCompiler.library_filename(libname[, lib_type=``'static'``, strip_dir=``0``, output_dir=``''``]) |
n | .. 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`. |
| |
| |
n | .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=``0``, output_dir=``''``]) |
n | .. 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. |
| |
| |
n | .. method:: CCompiler.shared_object_filename(basename[, strip_dir=``0``, output_dir=``''``]) |
n | .. 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*. |
| |
| |
n | .. method:: CCompiler.execute(func, args[, msg=``None``, level=``1``]) |
n | .. 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. XXX see also. |
| |
| |
| .. method:: CCompiler.spawn(cmd) |
| |
| Invokes :func:`distutils.util.spawn`. This invokes an external process to run |
| the given command. XXX see also. |
| |
| |
n | .. method:: CCompiler.mkpath(name[, mode=``511``]) |
n | .. method:: CCompiler.mkpath(name[, mode=511]) |
| |
| Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any |
| missing ancestor directories. XXX see also. |
| |
| |
| .. method:: CCompiler.move_file(src, dst) |
| |
| Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. XXX see |
| also. |
| |
| |
n | .. method:: CCompiler.announce(msg[, level=``1``]) |
n | .. method:: CCompiler.announce(msg[, level=1]) |
| |
| Write a message using :func:`distutils.log.debug`. XXX see also. |
| |
| |
| .. 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} |
n | .. % |
n | .. % |
| .. % 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 |
| ================================================== |
| :synopsis: Metrowerks CodeWarrior support |
| |
| |
| Contains :class:`MWerksCompiler`, an implementation of the abstract |
| :class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X |
| Macintosh. Needs work to support CW on Windows or Mac OS X. |
| |
| .. % \subsection{Utility modules} |
n | .. % |
n | .. % |
| .. % The following modules all provide general utility functions. They haven't |
| .. % all been documented yet. |
| |
| |
| :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. |
| |
| |
n | .. function:: make_archive(base_name, format[, root_dir=``None``, base_dir=``None``, verbose=``0``, dry_run=``0``]) |
n | .. 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``, ``ztar``, or ``gztar``. *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. |
| |
| .. warning:: |
| |
| This should be changed to support bz2 files |
| |
| |
n | .. function:: make_tarball(base_name, base_dir[, compress=``'gzip'``, verbose=``0``, dry_run=``0``]) |
n | .. 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), ``'compress'``, |
| ``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named |
| by *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 (:file:`.gz`, :file:`.bz2` |
| or :file:`.Z`). Return the output filename. |
| |
| .. warning:: |
| |
| This should be replaced with calls to the :mod:`tarfile` module. |
| |
| |
n | .. function:: make_zipfile(base_name, base_dir[, verbose=``0``, dry_run=``0``]) |
n | .. 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_dir* + :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. |
| |
| |
| .. 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. |
| |
| |
n | .. function:: mkpath(name[, mode=``0777``, verbose=``0``, dry_run=``0``]) |
n | .. function:: mkpath(name[, mode=0777, 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. |
| |
| |
n | .. function:: create_tree(base_dir, files[, mode=``0777``, verbose=``0``, dry_run=``0``]) |
n | .. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0]) |
| |
| Create all the empty directories under *base_dir* needed to put *files* there. |
| *base_dir* is just the a 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`. |
| |
| |
n | .. function:: copy_tree(src, dst[preserve_mode=``1``, preserve_times=``1``, preserve_symlinks=``0``, update=``0``, verbose=``0``, dry_run=``0``]) |
n | .. 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 |
| |
| .. module:: distutils.file_util |
| :synopsis: Utility functions for operating on single files |
| |
| |
| This module contains some utility functions for operating on individual files. |
| |
| |
n | .. function:: copy_file(src, dst[preserve_mode=``1``, preserve_times=``1``, update=``0``, link=``None``, verbose=``0``, dry_run=``0``]) |
n | .. 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 |
n | file's mode (type and permission bits, or whatever is analogous on the current |
n | file's mode (type and permission bits, or whatever is analogous on the |
| platform) is copied. If *preserve_times* is true (the default), the last- |
| current platform) is copied. If *preserve_times* is true (the default), the |
| modified and last-access times are copied as well. If *update* is true, *src* |
| last-modified and last-access times are copied as well. If *update* is true, |
| will only be copied if *dst* does not exist, or if *dst* does exist but is older |
| *src* will only be copied if *dst* does not exist, or if *dst* does exist but |
| than *src*. |
| 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. |
| |
| |
| 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. |
| |
| |
n | .. function:: byte_compile(py_files[, optimize=``0``, force=``0``, prefix=``None``, base_dir=``None``, verbose=``1``, dry_run=``0``, direct=``None``]) |
n | .. 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 either :file:`.pyc` or |
| :file:`.pyo` files in the same directory. *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: |
| |
n | * ``0`` - don't optimize (generate :file:`.pyc`) |
n | * ``0`` - don't optimize (generate :file:`.pyc`) |
| |
| * ``1`` - normal optimization (like ``python -O``) |
| * ``1`` - normal optimization (like ``python -O``) |
| |
| * ``2`` - extra optimization (like ``python -OO``) |
| * ``2`` - extra optimization (like ``python -OO``) |
| |
| If *force* is true, all files are recompiled regardless of timestamps. |
| |
n | The source filename encoded in each bytecode file defaults to the filenames |
n | 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. |
| :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. |
| |
n | XXX: input{sysconfig} :XXX |
n | |
| :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. |
| |
| |
n | .. class:: TextFile([filename=``None``, file=``None``, **options]) |
n | .. 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. |
| |
| ``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. |
| |
| |
n | .. method:: XXX Class.initialize_options()(S) |
n | .. method:: Command.initialize_options()(S) |
| |
| et 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. |
| |
| |
n | .. method:: XXX Class.finalize_options() |
n | .. method:: Command.finalize_options() |
| |
n | Set final values for all the options that this command supports. This is always |
n | Set final values for all the options that this command supports. This is |
| called as late as possible, ie. after any option assignments from the command- |
| always called as late as possible, ie. after any option assignments from the |
| line or from other commands have been done. Thus, this is the place to to code |
| command-line or from other commands have been done. Thus, this is the place |
| option dependencies: if *foo* depends on *bar*, then it is safe to set *foo* |
| to to code option dependencies: if *foo* depends on *bar*, then it is safe to |
| from *bar* as long as *foo* still has the same value it was assigned in |
| set *foo* from *bar* as long as *foo* still has the same value it was |
| :meth:`initialize_options`. |
| assigned in :meth:`initialize_options`. |
| |
| |
n | .. method:: XXX Class.run() |
n | .. 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`. |
| |
| *sub_commands* formalizes the notion of a "family" of commands, eg. ``install`` |