1.. _api-reference: 2 3************* 4API Reference 5************* 6 7.. seealso:: 8 9 `New and changed setup.py arguments in setuptools`_ 10 The ``setuptools`` project adds new capabilities to the ``setup`` function 11 and other APIs, makes the API consistent across different Python versions, 12 and is hence recommended over using ``distutils`` directly. 13 14.. _New and changed setup.py arguments in setuptools: https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords 15 16.. include:: ./_setuptools_disclaimer.rst 17 18:mod:`distutils.core` --- Core Distutils functionality 19====================================================== 20 21.. module:: distutils.core 22 :synopsis: The core Distutils functionality 23 24 25The :mod:`distutils.core` module is the only module that needs to be installed 26to use the Distutils. It provides the :func:`setup` (which is called from the 27setup script). Indirectly provides the :class:`distutils.dist.Distribution` and 28:class:`distutils.cmd.Command` class. 29 30 31.. function:: setup(arguments) 32 33 The basic do-everything function that does most everything you could ever ask 34 for from a Distutils method. 35 36 The setup function takes a large number of arguments. These are laid out in the 37 following table. 38 39 .. tabularcolumns:: |l|L|L| 40 41 +--------------------+--------------------------------+-------------------------------------------------------------+ 42 | argument name | value | type | 43 +====================+================================+=============================================================+ 44 | *name* | The name of the package | a string | 45 +--------------------+--------------------------------+-------------------------------------------------------------+ 46 | *version* | The version number of the | a string | 47 | | package; see | | 48 | | :mod:`distutils.version` | | 49 +--------------------+--------------------------------+-------------------------------------------------------------+ 50 | *description* | A single line describing the | a string | 51 | | package | | 52 +--------------------+--------------------------------+-------------------------------------------------------------+ 53 | *long_description* | Longer description of the | a string | 54 | | package | | 55 +--------------------+--------------------------------+-------------------------------------------------------------+ 56 | *author* | The name of the package author | a string | 57 +--------------------+--------------------------------+-------------------------------------------------------------+ 58 | *author_email* | The email address of the | a string | 59 | | package author | | 60 +--------------------+--------------------------------+-------------------------------------------------------------+ 61 | *maintainer* | The name of the current | a string | 62 | | maintainer, if different from | | 63 | | the author. Note that if | | 64 | | the maintainer is provided, | | 65 | | distutils will use it as the | | 66 | | author in :file:`PKG-INFO` | | 67 +--------------------+--------------------------------+-------------------------------------------------------------+ 68 | *maintainer_email* | The email address of the | a string | 69 | | current maintainer, if | | 70 | | different from the author | | 71 +--------------------+--------------------------------+-------------------------------------------------------------+ 72 | *url* | A URL for the package | a string | 73 | | (homepage) | | 74 +--------------------+--------------------------------+-------------------------------------------------------------+ 75 | *download_url* | A URL to download the package | a string | 76 +--------------------+--------------------------------+-------------------------------------------------------------+ 77 | *packages* | A list of Python packages that | a list of strings | 78 | | distutils will manipulate | | 79 +--------------------+--------------------------------+-------------------------------------------------------------+ 80 | *py_modules* | A list of Python modules that | a list of strings | 81 | | distutils will manipulate | | 82 +--------------------+--------------------------------+-------------------------------------------------------------+ 83 | *scripts* | A list of standalone script | a list of strings | 84 | | files to be built and | | 85 | | installed | | 86 +--------------------+--------------------------------+-------------------------------------------------------------+ 87 | *ext_modules* | A list of Python extensions to | a list of instances of | 88 | | be built | :class:`distutils.core.Extension` | 89 +--------------------+--------------------------------+-------------------------------------------------------------+ 90 | *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI | 91 | | package | <https://pypi.org/classifiers>`_. | 92 +--------------------+--------------------------------+-------------------------------------------------------------+ 93 | *distclass* | the :class:`Distribution` | a subclass of | 94 | | class to use | :class:`distutils.core.Distribution` | 95 +--------------------+--------------------------------+-------------------------------------------------------------+ 96 | *script_name* | The name of the setup.py | a string | 97 | | script - defaults to | | 98 | | ``sys.argv[0]`` | | 99 +--------------------+--------------------------------+-------------------------------------------------------------+ 100 | *script_args* | Arguments to supply to the | a list of strings | 101 | | setup script | | 102 +--------------------+--------------------------------+-------------------------------------------------------------+ 103 | *options* | default options for the setup | a dictionary | 104 | | script | | 105 +--------------------+--------------------------------+-------------------------------------------------------------+ 106 | *license* | The license for the package | a string | 107 +--------------------+--------------------------------+-------------------------------------------------------------+ 108 | *keywords* | Descriptive meta-data, see | a list of strings or a comma-separated string | 109 | | :pep:`314` | | 110 +--------------------+--------------------------------+-------------------------------------------------------------+ 111 | *platforms* | | a list of strings or a comma-separated string | 112 +--------------------+--------------------------------+-------------------------------------------------------------+ 113 | *cmdclass* | A mapping of command names to | a dictionary | 114 | | :class:`Command` subclasses | | 115 +--------------------+--------------------------------+-------------------------------------------------------------+ 116 | *data_files* | A list of data files to | a list | 117 | | install | | 118 +--------------------+--------------------------------+-------------------------------------------------------------+ 119 | *package_dir* | A mapping of package to | a dictionary | 120 | | directory names | | 121 +--------------------+--------------------------------+-------------------------------------------------------------+ 122 123 124 125.. function:: run_setup(script_name[, script_args=None, stop_after='run']) 126 127 Run a setup script in a somewhat controlled environment, and return the 128 :class:`distutils.dist.Distribution` instance that drives things. This is 129 useful if you need to find out the distribution meta-data (passed as keyword 130 args from *script* to :func:`setup`), or the contents of the config files or 131 command-line. 132 133 *script_name* is a file that will be read and run with :func:`exec`. ``sys.argv[0]`` 134 will be replaced with *script* for the duration of the call. *script_args* is a 135 list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args* 136 for the duration of the call. 137 138 *stop_after* tells :func:`setup` when to stop processing; possible values: 139 140 .. tabularcolumns:: |l|L| 141 142 +---------------+---------------------------------------------+ 143 | value | description | 144 +===============+=============================================+ 145 | *init* | Stop after the :class:`Distribution` | 146 | | instance has been created and populated | 147 | | with the keyword arguments to :func:`setup` | 148 +---------------+---------------------------------------------+ 149 | *config* | Stop after config files have been parsed | 150 | | (and their data stored in the | 151 | | :class:`Distribution` instance) | 152 +---------------+---------------------------------------------+ 153 | *commandline* | Stop after the command-line | 154 | | (``sys.argv[1:]`` or *script_args*) have | 155 | | been parsed (and the data stored in the | 156 | | :class:`Distribution` instance.) | 157 +---------------+---------------------------------------------+ 158 | *run* | Stop after all commands have been run (the | 159 | | same as if :func:`setup` had been called | 160 | | in the usual way). This is the default | 161 | | value. | 162 +---------------+---------------------------------------------+ 163 164In addition, the :mod:`distutils.core` module exposed a number of classes that 165live elsewhere. 166 167* :class:`~distutils.extension.Extension` from :mod:`distutils.extension` 168 169* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd` 170 171* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist` 172 173A short description of each of these follows, but see the relevant module for 174the full reference. 175 176 177.. class:: Extension 178 179 The Extension class describes a single C or C++ extension module in a setup 180 script. It accepts the following keyword arguments in its constructor: 181 182 .. tabularcolumns:: |l|L|l| 183 184 +------------------------+--------------------------------+---------------------------+ 185 | argument name | value | type | 186 +========================+================================+===========================+ 187 | *name* | the full name of the | a string | 188 | | extension, including any | | 189 | | packages --- ie. *not* a | | 190 | | filename or pathname, but | | 191 | | Python dotted name | | 192 +------------------------+--------------------------------+---------------------------+ 193 | *sources* | list of source filenames, | a list of strings | 194 | | relative to the distribution | | 195 | | root (where the setup script | | 196 | | lives), in Unix form | | 197 | | (slash-separated) for | | 198 | | portability. | | 199 | | Source files may be C, C++, | | 200 | | SWIG (.i), platform-specific | | 201 | | resource files, or whatever | | 202 | | else is recognized by the | | 203 | | :command:`build_ext` command | | 204 | | as source for a Python | | 205 | | extension. | | 206 +------------------------+--------------------------------+---------------------------+ 207 | *include_dirs* | list of directories to search | a list of strings | 208 | | for C/C++ header files (in | | 209 | | Unix form for portability) | | 210 +------------------------+--------------------------------+---------------------------+ 211 | *define_macros* | list of macros to define; each | a list of tuples | 212 | | macro is defined using a | | 213 | | 2-tuple ``(name, value)``, | | 214 | | where *value* is | | 215 | | either the string to define it | | 216 | | to or ``None`` to define it | | 217 | | without a particular value | | 218 | | (equivalent of ``#define FOO`` | | 219 | | in source or :option:`!-DFOO` | | 220 | | on Unix C compiler command | | 221 | | line) | | 222 +------------------------+--------------------------------+---------------------------+ 223 | *undef_macros* | list of macros to undefine | a list of strings | 224 | | explicitly | | 225 +------------------------+--------------------------------+---------------------------+ 226 | *library_dirs* | list of directories to search | a list of strings | 227 | | for C/C++ libraries at link | | 228 | | time | | 229 +------------------------+--------------------------------+---------------------------+ 230 | *libraries* | list of library names (not | a list of strings | 231 | | filenames or paths) to link | | 232 | | against | | 233 +------------------------+--------------------------------+---------------------------+ 234 | *runtime_library_dirs* | list of directories to search | a list of strings | 235 | | for C/C++ libraries at run | | 236 | | time (for shared extensions, | | 237 | | this is when the extension is | | 238 | | loaded) | | 239 +------------------------+--------------------------------+---------------------------+ 240 | *extra_objects* | list of extra files to link | a list of strings | 241 | | with (eg. object files not | | 242 | | implied by 'sources', static | | 243 | | library that must be | | 244 | | explicitly specified, binary | | 245 | | resource files, etc.) | | 246 +------------------------+--------------------------------+---------------------------+ 247 | *extra_compile_args* | any extra platform- and | a list of strings | 248 | | compiler-specific information | | 249 | | to use when compiling the | | 250 | | source files in 'sources'. For | | 251 | | platforms and compilers where | | 252 | | a command line makes sense, | | 253 | | this is typically a list of | | 254 | | command-line arguments, but | | 255 | | for other platforms it could | | 256 | | be anything. | | 257 +------------------------+--------------------------------+---------------------------+ 258 | *extra_link_args* | any extra platform- and | a list of strings | 259 | | compiler-specific information | | 260 | | to use when linking object | | 261 | | files together to create the | | 262 | | extension (or to create a new | | 263 | | static Python interpreter). | | 264 | | Similar interpretation as for | | 265 | | 'extra_compile_args'. | | 266 +------------------------+--------------------------------+---------------------------+ 267 | *export_symbols* | list of symbols to be exported | a list of strings | 268 | | from a shared extension. Not | | 269 | | used on all platforms, and not | | 270 | | generally necessary for Python | | 271 | | extensions, which typically | | 272 | | export exactly one symbol: | | 273 | | ``init`` + extension_name. | | 274 +------------------------+--------------------------------+---------------------------+ 275 | *depends* | list of files that the | a list of strings | 276 | | extension depends on | | 277 +------------------------+--------------------------------+---------------------------+ 278 | *language* | extension language (i.e. | a string | 279 | | ``'c'``, ``'c++'``, | | 280 | | ``'objc'``). Will be detected | | 281 | | from the source extensions if | | 282 | | not provided. | | 283 +------------------------+--------------------------------+---------------------------+ 284 | *optional* | specifies that a build failure | a boolean | 285 | | in the extension should not | | 286 | | abort the build process, but | | 287 | | simply skip the extension. | | 288 +------------------------+--------------------------------+---------------------------+ 289 290 .. versionchanged:: 3.8 291 292 On Unix, C extensions are no longer linked to libpython except on 293 Android and Cygwin. 294 295 296.. class:: Distribution 297 298 A :class:`Distribution` describes how to build, install and package up a Python 299 software package. 300 301 See the :func:`setup` function for a list of keyword arguments accepted by the 302 Distribution constructor. :func:`setup` creates a Distribution instance. 303 304 .. versionchanged:: 3.7 305 :class:`~distutils.core.Distribution` now warns if ``classifiers``, 306 ``keywords`` and ``platforms`` fields are not specified as a list or 307 a string. 308 309.. class:: Command 310 311 A :class:`Command` class (or rather, an instance of one of its subclasses) 312 implement a single distutils command. 313 314 315:mod:`distutils.ccompiler` --- CCompiler base class 316=================================================== 317 318.. module:: distutils.ccompiler 319 :synopsis: Abstract CCompiler class 320 321 322This module provides the abstract base class for the :class:`CCompiler` 323classes. A :class:`CCompiler` instance can be used for all the compile and 324link steps needed to build a single project. Methods are provided to set 325options for the compiler --- macro definitions, include directories, link path, 326libraries and the like. 327 328This module provides the following functions. 329 330 331.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries) 332 333 Generate linker options for searching library directories and linking with 334 specific libraries. *libraries* and *library_dirs* are, respectively, lists of 335 library names (not filenames!) and search directories. Returns a list of 336 command-line options suitable for use with some compiler (depending on the two 337 format strings passed in). 338 339 340.. function:: gen_preprocess_options(macros, include_dirs) 341 342 Generate C pre-processor options (:option:`!-D`, :option:`!-U`, :option:`!-I`) as 343 used by at least two types of compilers: the typical Unix compiler and Visual 344 C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)`` 345 means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define 346 (:option:`!-D`) macro *name* to *value*. *include_dirs* is just a list of 347 directory names to be added to the header file search path (:option:`!-I`). 348 Returns a list of command-line options suitable for either Unix compilers or 349 Visual C++. 350 351 352.. function:: get_default_compiler(osname, platform) 353 354 Determine the default compiler to use for the given platform. 355 356 *osname* should be one of the standard Python OS names (i.e. the ones returned 357 by ``os.name``) and *platform* the common value returned by ``sys.platform`` for 358 the platform in question. 359 360 The default values are ``os.name`` and ``sys.platform`` in case the parameters 361 are not given. 362 363 364.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0) 365 366 Factory function to generate an instance of some CCompiler subclass for the 367 supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg. 368 ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for 369 that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the 370 default compilers are "traditional Unix interface" (:class:`UnixCCompiler` 371 class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly 372 possible to ask for a Unix compiler object under Windows, and a Microsoft 373 compiler object under Unix---if you supply a value for *compiler*, *plat* is 374 ignored. 375 376 .. % Is the posix/nt only thing still true? Mac OS X seems to work, and 377 .. % returns a UnixCCompiler instance. How to document this... hmm. 378 379 380.. function:: show_compilers() 381 382 Print list of available compilers (used by the :option:`!--help-compiler` options 383 to :command:`build`, :command:`build_ext`, :command:`build_clib`). 384 385 386.. class:: CCompiler([verbose=0, dry_run=0, force=0]) 387 388 The abstract base class :class:`CCompiler` defines the interface that must be 389 implemented by real compiler classes. The class also has some utility methods 390 used by several compiler classes. 391 392 The basic idea behind a compiler abstraction class is that each instance can be 393 used for all the compile/link steps in building a single project. Thus, 394 attributes common to all of those compile and link steps --- include 395 directories, macros to define, libraries to link against, etc. --- are 396 attributes of the compiler instance. To allow for variability in how individual 397 files are treated, most of those attributes may be varied on a per-compilation 398 or per-link basis. 399 400 The constructor for each subclass creates an instance of the Compiler object. 401 Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the 402 steps) and *force* (rebuild everything, regardless of dependencies). All of 403 these flags default to ``0`` (off). Note that you probably don't want to 404 instantiate :class:`CCompiler` or one of its subclasses directly - use the 405 :func:`distutils.CCompiler.new_compiler` factory function instead. 406 407 The following methods allow you to manually alter compiler options for the 408 instance of the Compiler class. 409 410 411 .. method:: CCompiler.add_include_dir(dir) 412 413 Add *dir* to the list of directories that will be searched for header files. 414 The compiler is instructed to search directories in the order in which they are 415 supplied by successive calls to :meth:`add_include_dir`. 416 417 418 .. method:: CCompiler.set_include_dirs(dirs) 419 420 Set the list of directories that will be searched to *dirs* (a list of strings). 421 Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to 422 :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`. 423 This does not affect any list of standard include directories that the compiler 424 may search by default. 425 426 427 .. method:: CCompiler.add_library(libname) 428 429 Add *libname* to the list of libraries that will be included in all links driven 430 by this compiler object. Note that *libname* should \*not\* be the name of a 431 file containing a library, but the name of the library itself: the actual 432 filename will be inferred by the linker, the compiler, or the compiler class 433 (depending on the platform). 434 435 The linker will be instructed to link against libraries in the order they were 436 supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly 437 valid to duplicate library names; the linker will be instructed to link against 438 libraries as many times as they are mentioned. 439 440 441 .. method:: CCompiler.set_libraries(libnames) 442 443 Set the list of libraries to be included in all links driven by this compiler 444 object to *libnames* (a list of strings). This does not affect any standard 445 system libraries that the linker may include by default. 446 447 448 .. method:: CCompiler.add_library_dir(dir) 449 450 Add *dir* to the list of directories that will be searched for libraries 451 specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be 452 instructed to search for libraries in the order they are supplied to 453 :meth:`add_library_dir` and/or :meth:`set_library_dirs`. 454 455 456 .. method:: CCompiler.set_library_dirs(dirs) 457 458 Set the list of library search directories to *dirs* (a list of strings). This 459 does not affect any standard library search path that the linker may search by 460 default. 461 462 463 .. method:: CCompiler.add_runtime_library_dir(dir) 464 465 Add *dir* to the list of directories that will be searched for shared libraries 466 at runtime. 467 468 469 .. method:: CCompiler.set_runtime_library_dirs(dirs) 470 471 Set the list of directories to search for shared libraries at runtime to *dirs* 472 (a list of strings). This does not affect any standard search path that the 473 runtime linker may search by default. 474 475 476 .. method:: CCompiler.define_macro(name[, value=None]) 477 478 Define a preprocessor macro for all compilations driven by this compiler object. 479 The optional parameter *value* should be a string; if it is not supplied, then 480 the macro will be defined without an explicit value and the exact outcome 481 depends on the compiler used. 482 483 .. XXX true? does ANSI say anything about this? 484 485 486 .. method:: CCompiler.undefine_macro(name) 487 488 Undefine a preprocessor macro for all compilations driven by this compiler 489 object. If the same macro is defined by :meth:`define_macro` and 490 undefined by :meth:`undefine_macro` the last call takes precedence 491 (including multiple redefinitions or undefinitions). If the macro is 492 redefined/undefined on a per-compilation basis (ie. in the call to 493 :meth:`compile`), then that takes precedence. 494 495 496 .. method:: CCompiler.add_link_object(object) 497 498 Add *object* to the list of object files (or analogues, such as explicitly named 499 library files or the output of "resource compilers") to be included in every 500 link driven by this compiler object. 501 502 503 .. method:: CCompiler.set_link_objects(objects) 504 505 Set the list of object files (or analogues) to be included in every link to 506 *objects*. This does not affect any standard object files that the linker may 507 include by default (such as system libraries). 508 509 The following methods implement methods for autodetection of compiler options, 510 providing some functionality similar to GNU :program:`autoconf`. 511 512 513 .. method:: CCompiler.detect_language(sources) 514 515 Detect the language of a given file, or list of files. Uses the instance 516 attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a 517 list) to do the job. 518 519 520 .. method:: CCompiler.find_library_file(dirs, lib[, debug=0]) 521 522 Search the specified list of directories for a static or shared library file 523 *lib* and return the full path to that file. If *debug* is true, look for a 524 debugging version (if that makes sense on the current platform). Return 525 ``None`` if *lib* wasn't found in any of the specified directories. 526 527 528 .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None]) 529 530 Return a boolean indicating whether *funcname* is supported on the current 531 platform. The optional arguments can be used to augment the compilation 532 environment by providing additional include files and paths and libraries and 533 paths. 534 535 536 .. method:: CCompiler.library_dir_option(dir) 537 538 Return the compiler option to add *dir* to the list of directories searched for 539 libraries. 540 541 542 .. method:: CCompiler.library_option(lib) 543 544 Return the compiler option to add *lib* to the list of libraries linked into the 545 shared library or executable. 546 547 548 .. method:: CCompiler.runtime_library_dir_option(dir) 549 550 Return the compiler option to add *dir* to the list of directories searched for 551 runtime libraries. 552 553 554 .. method:: CCompiler.set_executables(**args) 555 556 Define the executables (and options for them) that will be run to perform the 557 various stages of compilation. The exact set of executables that may be 558 specified here depends on the compiler class (via the 'executables' class 559 attribute), but most will have: 560 561 +--------------+------------------------------------------+ 562 | attribute | description | 563 +==============+==========================================+ 564 | *compiler* | the C/C++ compiler | 565 +--------------+------------------------------------------+ 566 | *linker_so* | linker used to create shared objects and | 567 | | libraries | 568 +--------------+------------------------------------------+ 569 | *linker_exe* | linker used to create binary executables | 570 +--------------+------------------------------------------+ 571 | *archiver* | static library creator | 572 +--------------+------------------------------------------+ 573 574 On platforms with a command-line (Unix, DOS/Windows), each of these is a string 575 that will be split into executable name and (optional) list of arguments. 576 (Splitting the string is done similarly to how Unix shells operate: words are 577 delimited by spaces, but quotes and backslashes can override this. See 578 :func:`distutils.util.split_quoted`.) 579 580 The following methods invoke stages in the build process. 581 582 583 .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None]) 584 585 Compile one or more source files. Generates object files (e.g. transforms a 586 :file:`.c` file to a :file:`.o` file.) 587 588 *sources* must be a list of filenames, most likely C/C++ files, but in reality 589 anything that can be handled by a particular compiler and compiler class (eg. 590 :class:`MSVCCompiler` can handle resource files in *sources*). Return a list of 591 object filenames, one per source filename in *sources*. Depending on the 592 implementation, not all source files will necessarily be compiled, but all 593 corresponding object filenames will be returned. 594 595 If *output_dir* is given, object files will be put under it, while retaining 596 their original path component. That is, :file:`foo/bar.c` normally compiles to 597 :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then 598 it would compile to :file:`build/foo/bar.o`. 599 600 *macros*, if given, must be a list of macro definitions. A macro definition is 601 either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines 602 a macro; if the value is ``None``, the macro is defined without an explicit 603 value. The 1-tuple case undefines a macro. Later 604 definitions/redefinitions/undefinitions take precedence. 605 606 *include_dirs*, if given, must be a list of strings, the directories to add to 607 the default include file search path for this compilation only. 608 609 *debug* is a boolean; if true, the compiler will be instructed to output debug 610 symbols in (or alongside) the object file(s). 611 612 *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms 613 that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most 614 likely lists of strings: extra command-line arguments to prepend/append to the 615 compiler command line. On other platforms, consult the implementation class 616 documentation. In any event, they are intended as an escape hatch for those 617 occasions when the abstract compiler framework doesn't cut the mustard. 618 619 *depends*, if given, is a list of filenames that all targets depend on. If a 620 source file is older than any file in depends, then the source file will be 621 recompiled. This supports dependency tracking, but only at a coarse 622 granularity. 623 624 Raises :exc:`CompileError` on failure. 625 626 627 .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None]) 628 629 Link a bunch of stuff together to create a static library file. The "bunch of 630 stuff" consists of the list of object files supplied as *objects*, the extra 631 object files supplied to :meth:`add_link_object` and/or 632 :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or 633 :meth:`set_libraries`, and the libraries supplied as *libraries* (if any). 634 635 *output_libname* should be a library name, not a filename; the filename will be 636 inferred from the library name. *output_dir* is the directory where the library 637 file will be put. 638 639 .. XXX defaults to what? 640 641 *debug* is a boolean; if true, debugging information will be included in the 642 library (note that on most platforms, it is the compile step where this matters: 643 the *debug* flag is included here just for consistency). 644 645 *target_lang* is the target language for which the given objects are being 646 compiled. This allows specific linkage time treatment of certain languages. 647 648 Raises :exc:`LibError` on failure. 649 650 651 .. 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]) 652 653 Link a bunch of stuff together to create an executable or shared library file. 654 655 The "bunch of stuff" consists of the list of object files supplied as *objects*. 656 *output_filename* should be a filename. If *output_dir* is supplied, 657 *output_filename* is relative to it (i.e. *output_filename* can provide 658 directory components if needed). 659 660 *libraries* is a list of libraries to link against. These are library names, 661 not filenames, since they're translated into filenames in a platform-specific 662 way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on 663 DOS/Windows). However, they can include a directory component, which means the 664 linker will look in that specific directory rather than searching all the normal 665 locations. 666 667 *library_dirs*, if supplied, should be a list of directories to search for 668 libraries that were specified as bare library names (ie. no directory 669 component). These are on top of the system default and those supplied to 670 :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs* 671 is a list of directories that will be embedded into the shared library and used 672 to search for other shared libraries that \*it\* depends on at run-time. (This 673 may only be relevant on Unix.) 674 675 *export_symbols* is a list of symbols that the shared library will export. 676 (This appears to be relevant only on Windows.) 677 678 *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the 679 slight distinction that it actually matters on most platforms (as opposed to 680 :meth:`create_static_lib`, which includes a *debug* flag mostly for form's 681 sake). 682 683 *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of 684 course that they supply command-line arguments for the particular linker being 685 used). 686 687 *target_lang* is the target language for which the given objects are being 688 compiled. This allows specific linkage time treatment of certain languages. 689 690 Raises :exc:`LinkError` on failure. 691 692 693 .. 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]) 694 695 Link an executable. *output_progname* is the name of the file executable, while 696 *objects* are a list of object filenames to link in. Other arguments are as for 697 the :meth:`link` method. 698 699 700 .. 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]) 701 702 Link a shared library. *output_libname* is the name of the output library, 703 while *objects* is a list of object filenames to link in. Other arguments are 704 as for the :meth:`link` method. 705 706 707 .. 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]) 708 709 Link a shared object. *output_filename* is the name of the shared object that 710 will be created, while *objects* is a list of object filenames to link in. 711 Other arguments are as for the :meth:`link` method. 712 713 714 .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None]) 715 716 Preprocess a single C/C++ source file, named in *source*. Output will be written 717 to file named *output_file*, or *stdout* if *output_file* not supplied. 718 *macros* is a list of macro definitions as for :meth:`compile`, which will 719 augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`. 720 *include_dirs* is a list of directory names that will be added to the default 721 list, in the same way as :meth:`add_include_dir`. 722 723 Raises :exc:`PreprocessError` on failure. 724 725 The following utility methods are defined by the :class:`CCompiler` class, for 726 use by the various concrete subclasses. 727 728 729 .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir='']) 730 731 Returns the filename of the executable for the given *basename*. Typically for 732 non-Windows platforms this is the same as the basename, while Windows will get 733 a :file:`.exe` added. 734 735 736 .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir='']) 737 738 Returns the filename for the given library name on the current platform. On Unix 739 a library with *lib_type* of ``'static'`` will typically be of the form 740 :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form 741 :file:`liblibname.so`. 742 743 744 .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir='']) 745 746 Returns the name of the object files for the given source files. 747 *source_filenames* should be a list of filenames. 748 749 750 .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir='']) 751 752 Returns the name of a shared object file for the given file name *basename*. 753 754 755 .. method:: CCompiler.execute(func, args[, msg=None, level=1]) 756 757 Invokes :func:`distutils.util.execute`. This method invokes a Python function 758 *func* with the given arguments *args*, after logging and taking into account 759 the *dry_run* flag. 760 761 762 .. method:: CCompiler.spawn(cmd) 763 764 Invokes :func:`distutils.util.spawn`. This invokes an external process to run 765 the given command. 766 767 768 .. method:: CCompiler.mkpath(name[, mode=511]) 769 770 Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any 771 missing ancestor directories. 772 773 774 .. method:: CCompiler.move_file(src, dst) 775 776 Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. 777 778 779 .. method:: CCompiler.announce(msg[, level=1]) 780 781 Write a message using :func:`distutils.log.debug`. 782 783 784 .. method:: CCompiler.warn(msg) 785 786 Write a warning message *msg* to standard error. 787 788 789 .. method:: CCompiler.debug_print(msg) 790 791 If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to 792 standard output, otherwise do nothing. 793 794.. % \subsection{Compiler-specific modules} 795.. % 796.. % The following modules implement concrete subclasses of the abstract 797.. % \class{CCompiler} class. They should not be instantiated directly, but should 798.. % be created using \function{distutils.ccompiler.new_compiler()} factory 799.. % function. 800 801 802:mod:`distutils.unixccompiler` --- Unix C Compiler 803================================================== 804 805.. module:: distutils.unixccompiler 806 :synopsis: UNIX C Compiler 807 808 809This module provides the :class:`UnixCCompiler` class, a subclass of 810:class:`CCompiler` that handles the typical Unix-style command-line C compiler: 811 812* macros defined with :option:`!-Dname[=value]` 813 814* macros undefined with :option:`!-Uname` 815 816* include search directories specified with :option:`!-Idir` 817 818* libraries specified with :option:`!-llib` 819 820* library search directories specified with :option:`!-Ldir` 821 822* compile handled by :program:`cc` (or similar) executable with :option:`!-c` 823 option: compiles :file:`.c` to :file:`.o` 824 825* link static library handled by :program:`ar` command (possibly with 826 :program:`ranlib`) 827 828* link shared library handled by :program:`cc` :option:`!-shared` 829 830 831:mod:`distutils.msvccompiler` --- Microsoft Compiler 832==================================================== 833 834.. module:: distutils.msvccompiler 835 :synopsis: Microsoft Compiler 836 837.. XXX: This is *waaaaay* out of date! 838 839This module provides :class:`MSVCCompiler`, an implementation of the abstract 840:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension 841modules need to be compiled with the same compiler that was used to compile 842Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python 8432.4 and 2.5, the compiler is Visual Studio .NET 2003. 844 845:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on 846its own. To override this choice, the environment variables *DISTUTILS_USE_SDK* 847and *MSSdk* must be both set. *MSSdk* indicates that the current environment has 848been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables 849had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates 850that the distutils user has made an explicit choice to override the compiler 851selection by :class:`MSVCCompiler`. 852 853 854:mod:`distutils.bcppcompiler` --- Borland Compiler 855================================================== 856 857.. module:: distutils.bcppcompiler 858 859 860This module provides :class:`BorlandCCompiler`, a subclass of the abstract 861:class:`CCompiler` class for the Borland C++ compiler. 862 863 864:mod:`distutils.cygwincompiler` --- Cygwin Compiler 865=================================================== 866 867.. module:: distutils.cygwinccompiler 868 869 870This module provides the :class:`CygwinCCompiler` class, a subclass of 871:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to 872Windows. It also contains the Mingw32CCompiler class which handles the mingw32 873port of GCC (same as cygwin in no-cygwin mode). 874 875 876:mod:`distutils.archive_util` --- Archiving utilities 877====================================================== 878 879.. module:: distutils.archive_util 880 :synopsis: Utility functions for creating archive files (tarballs, zip files, ...) 881 882 883This module provides a few functions for creating archive files, such as 884tarballs or zipfiles. 885 886 887.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0]) 888 889 Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of 890 the file to create, minus any format-specific extension; *format* is the 891 archive format: one of ``zip``, ``tar``, ``gztar``, ``bztar``, ``xztar``, or 892 ``ztar``. *root_dir* is a directory that will be the root directory of the 893 archive; ie. we typically ``chdir`` into *root_dir* before creating the 894 archive. *base_dir* is the directory where we start archiving from; ie. 895 *base_dir* will be the common prefix of all files and directories in the 896 archive. *root_dir* and *base_dir* both default to the current directory. 897 Returns the name of the archive file. 898 899 .. versionchanged:: 3.5 900 Added support for the ``xztar`` format. 901 902 903.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) 904 905 'Create an (optional compressed) archive as a tar file from all files in and 906 under *base_dir*. *compress* must be ``'gzip'`` (the default), 907 ``'bzip2'``, ``'xz'``, ``'compress'``, or ``None``. For the ``'compress'`` 908 method the compression utility named by :program:`compress` must be on the 909 default program search path, so this is probably Unix-specific. The output 910 tar file will be named :file:`base_dir.tar`, possibly plus the appropriate 911 compression extension (``.gz``, ``.bz2``, ``.xz`` or ``.Z``). Return the 912 output filename. 913 914 .. versionchanged:: 3.5 915 Added support for the ``xz`` compression. 916 917 918.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) 919 920 Create a zip file from all files in and under *base_dir*. The output zip file 921 will be named *base_name* + :file:`.zip`. Uses either the :mod:`zipfile` Python 922 module (if available) or the InfoZIP :file:`zip` utility (if installed and 923 found on the default search path). If neither tool is available, raises 924 :exc:`DistutilsExecError`. Returns the name of the output zip file. 925 926 927:mod:`distutils.dep_util` --- Dependency checking 928================================================= 929 930.. module:: distutils.dep_util 931 :synopsis: Utility functions for simple dependency checking 932 933 934This module provides functions for performing simple, timestamp-based 935dependency of files and groups of files; also, functions based entirely on such 936timestamp dependency analysis. 937 938 939.. function:: newer(source, target) 940 941 Return true if *source* exists and is more recently modified than *target*, or 942 if *source* exists and *target* doesn't. Return false if both exist and *target* 943 is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if 944 *source* does not exist. 945 946 947.. function:: newer_pairwise(sources, targets) 948 949 Walk two filename lists in parallel, testing if each source is newer than its 950 corresponding target. Return a pair of lists (*sources*, *targets*) where 951 source is newer than target, according to the semantics of :func:`newer`. 952 953 .. % % equivalent to a listcomp... 954 955 956.. function:: newer_group(sources, target[, missing='error']) 957 958 Return true if *target* is out-of-date with respect to any file listed in 959 *sources*. In other words, if *target* exists and is newer than every file in 960 *sources*, return false; otherwise return true. *missing* controls what we do 961 when a source file is missing; the default (``'error'``) is to blow up with an 962 :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently 963 drop any missing source files; if it is ``'newer'``, any missing source files 964 make us assume that *target* is out-of-date (this is handy in "dry-run" mode: 965 it'll make you pretend to carry out commands that wouldn't work because inputs 966 are missing, but that doesn't matter because you're not actually going to run 967 the commands). 968 969 970:mod:`distutils.dir_util` --- Directory tree operations 971======================================================= 972 973.. module:: distutils.dir_util 974 :synopsis: Utility functions for operating on directories and directory trees 975 976 977This module provides functions for operating on directories and trees of 978directories. 979 980 981.. function:: mkpath(name[, mode=0o777, verbose=0, dry_run=0]) 982 983 Create a directory and any missing ancestor directories. If the directory 984 already exists (or if *name* is the empty string, which means the current 985 directory, which of course exists), then do nothing. Raise 986 :exc:`DistutilsFileError` if unable to create some directory along the way (eg. 987 some sub-path exists, but is a file rather than a directory). If *verbose* is 988 true, print a one-line summary of each mkdir to stdout. Return the list of 989 directories actually created. 990 991 992.. function:: create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0]) 993 994 Create all the empty directories under *base_dir* needed to put *files* there. 995 *base_dir* is just the name of a directory which doesn't necessarily exist 996 yet; *files* is a list of filenames to be interpreted relative to *base_dir*. 997 *base_dir* + the directory portion of every file in *files* will be created if 998 it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for 999 :func:`mkpath`. 1000 1001 1002.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0]) 1003 1004 Copy an entire directory tree *src* to a new location *dst*. Both *src* and 1005 *dst* must be directory names. If *src* is not a directory, raise 1006 :exc:`DistutilsFileError`. If *dst* does not exist, it is created with 1007 :func:`mkpath`. The end result of the copy is that every file in *src* is 1008 copied to *dst*, and directories under *src* are recursively copied to *dst*. 1009 Return the list of files that were copied or might have been copied, using their 1010 output name. The return value is unaffected by *update* or *dry_run*: it is 1011 simply the list of all files under *src*, with the names changed to be under 1012 *dst*. 1013 1014 *preserve_mode* and *preserve_times* are the same as for 1015 :func:`distutils.file_util.copy_file`; note that they only apply to 1016 regular files, not to 1017 directories. If *preserve_symlinks* is true, symlinks will be copied as 1018 symlinks (on platforms that support them!); otherwise (the default), the 1019 destination of the symlink will be copied. *update* and *verbose* are the same 1020 as for :func:`copy_file`. 1021 1022 Files in *src* that begin with :file:`.nfs` are skipped (more information on 1023 these files is available in answer D2 of the `NFS FAQ page 1024 <http://nfs.sourceforge.net/#section_d>`_). 1025 1026 .. versionchanged:: 3.3.1 1027 NFS files are ignored. 1028 1029.. function:: remove_tree(directory[, verbose=0, dry_run=0]) 1030 1031 Recursively remove *directory* and all files and directories underneath it. Any 1032 errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is 1033 true). 1034 1035 1036:mod:`distutils.file_util` --- Single file operations 1037===================================================== 1038 1039.. module:: distutils.file_util 1040 :synopsis: Utility functions for operating on single files 1041 1042 1043This module contains some utility functions for operating on individual files. 1044 1045 1046.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0]) 1047 1048 Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there 1049 with the same name; otherwise, it must be a filename. (If the file exists, it 1050 will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the 1051 file's mode (type and permission bits, or whatever is analogous on the 1052 current platform) is copied. If *preserve_times* is true (the default), the 1053 last-modified and last-access times are copied as well. If *update* is true, 1054 *src* will only be copied if *dst* does not exist, or if *dst* does exist but 1055 is older than *src*. 1056 1057 *link* allows you to make hard links (using :func:`os.link`) or symbolic links 1058 (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or 1059 ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link* 1060 on systems that don't support it: :func:`copy_file` doesn't check if hard or 1061 symbolic linking is available. It uses :func:`_copy_file_contents` to copy file 1062 contents. 1063 1064 Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the 1065 output file, and *copied* is true if the file was copied (or would have been 1066 copied, if *dry_run* true). 1067 1068 .. % XXX if the destination file already exists, we clobber it if 1069 .. % copying, but blow up if linking. Hmmm. And I don't know what 1070 .. % macostools.copyfile() does. Should definitely be consistent, and 1071 .. % should probably blow up if destination exists and we would be 1072 .. % changing it (ie. it's not already a hard/soft link to src OR 1073 .. % (not update) and (src newer than dst)). 1074 1075 1076.. function:: move_file(src, dst[, verbose, dry_run]) 1077 1078 Move file *src* to *dst*. If *dst* is a directory, the file will be moved into 1079 it with the same name; otherwise, *src* is just renamed to *dst*. Returns the 1080 new full name of the file. 1081 1082 .. warning:: 1083 1084 Handles cross-device moves on Unix using :func:`copy_file`. What about 1085 other systems? 1086 1087 1088.. function:: write_file(filename, contents) 1089 1090 Create a file called *filename* and write *contents* (a sequence of strings 1091 without line terminators) to it. 1092 1093 1094:mod:`distutils.util` --- Miscellaneous other utility functions 1095=============================================================== 1096 1097.. module:: distutils.util 1098 :synopsis: Miscellaneous other utility functions 1099 1100 1101This module contains other assorted bits and pieces that don't fit into any 1102other utility module. 1103 1104 1105.. function:: get_platform() 1106 1107 Return a string that identifies the current platform. This is used mainly to 1108 distinguish platform-specific build directories and platform-specific built 1109 distributions. Typically includes the OS name and version and the 1110 architecture (as supplied by 'os.uname()'), although the exact information 1111 included depends on the OS; e.g., on Linux, the kernel version isn't 1112 particularly important. 1113 1114 Examples of returned values: 1115 1116 * ``linux-i586`` 1117 * ``linux-alpha`` 1118 * ``solaris-2.6-sun4u`` 1119 1120 For non-POSIX platforms, currently just returns ``sys.platform``. 1121 1122 For Mac OS X systems the OS version reflects the minimal version on which 1123 binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` 1124 during the build of Python), not the OS version of the current system. 1125 1126 For universal binary builds on Mac OS X the architecture value reflects 1127 the universal binary status instead of the architecture of the current 1128 processor. For 32-bit universal binaries the architecture is ``fat``, 1129 for 64-bit universal binaries the architecture is ``fat64``, and 1130 for 4-way universal binaries the architecture is ``universal``. Starting 1131 from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for 1132 a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for 1133 a universal build with the i386 and x86_64 architectures 1134 1135 Examples of returned values on Mac OS X: 1136 1137 * ``macosx-10.3-ppc`` 1138 1139 * ``macosx-10.3-fat`` 1140 1141 * ``macosx-10.5-universal`` 1142 1143 * ``macosx-10.6-intel`` 1144 1145 For AIX, Python 3.9 and later return a string starting with "aix", followed 1146 by additional fields (separated by ``'-'``) that represent the combined 1147 values of AIX Version, Release and Technology Level (first field), Build Date 1148 (second field), and bit-size (third field). Python 3.8 and earlier returned 1149 only a single additional field with the AIX Version and Release. 1150 1151 Examples of returned values on AIX: 1152 1153 * ``aix-5307-0747-32`` # 32-bit build on AIX ``oslevel -s``: 5300-07-00-0000 1154 1155 * ``aix-7105-1731-64`` # 64-bit build on AIX ``oslevel -s``: 7100-05-01-1731 1156 1157 * ``aix-7.2`` # Legacy form reported in Python 3.8 and earlier 1158 1159 .. versionchanged:: 3.9 1160 The AIX platform string format now also includes the technology level, 1161 build date, and ABI bit-size. 1162 1163 1164.. function:: convert_path(pathname) 1165 1166 Return 'pathname' as a name that will work on the native filesystem, i.e. split 1167 it on '/' and put it back together again using the current directory separator. 1168 Needed because filenames in the setup script are always supplied in Unix style, 1169 and have to be converted to the local convention before we can actually use them 1170 in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if 1171 *pathname* either starts or ends with a slash. 1172 1173 1174.. function:: change_root(new_root, pathname) 1175 1176 Return *pathname* with *new_root* prepended. If *pathname* is relative, this is 1177 equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making 1178 *pathname* relative and then joining the two, which is tricky on DOS/Windows. 1179 1180 1181.. function:: check_environ() 1182 1183 Ensure that 'os.environ' has all the environment variables we guarantee that 1184 users can use in config files, command-line options, etc. Currently this 1185 includes: 1186 1187 * :envvar:`HOME` - user's home directory (Unix only) 1188 * :envvar:`PLAT` - description of the current platform, including hardware and 1189 OS (see :func:`get_platform`) 1190 1191 1192.. function:: subst_vars(s, local_vars) 1193 1194 Perform shell/Perl-style variable substitution on *s*. Every occurrence of 1195 ``$`` followed by a name is considered a variable, and variable is substituted 1196 by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's 1197 not in *local_vars*. *os.environ* is first checked/augmented to guarantee that 1198 it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError` 1199 for any variables not found in either *local_vars* or ``os.environ``. 1200 1201 Note that this is not a fully-fledged string interpolation function. A valid 1202 ``$variable`` can consist only of upper and lower case letters, numbers and an 1203 underscore. No { } or ( ) style quoting is available. 1204 1205 1206.. function:: split_quoted(s) 1207 1208 Split a string up according to Unix shell-like rules for quotes and backslashes. 1209 In short: words are delimited by spaces, as long as those spaces are not escaped 1210 by a backslash, or inside a quoted string. Single and double quotes are 1211 equivalent, and the quote characters can be backslash-escaped. The backslash is 1212 stripped from any two-character escape sequence, leaving only the escaped 1213 character. The quote characters are stripped from any quoted string. Returns a 1214 list of words. 1215 1216 .. % Should probably be moved into the standard library. 1217 1218 1219.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0]) 1220 1221 Perform some action that affects the outside world (for instance, writing to the 1222 filesystem). Such actions are special because they are disabled by the 1223 *dry_run* flag. This method takes care of all that bureaucracy for you; all 1224 you have to do is supply the function to call and an argument tuple for it (to 1225 embody the "external action" being performed), and an optional message to print. 1226 1227 1228.. function:: strtobool(val) 1229 1230 Convert a string representation of truth to true (1) or false (0). 1231 1232 True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values 1233 are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises 1234 :exc:`ValueError` if *val* is anything else. 1235 1236 1237.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None]) 1238 1239 Byte-compile a collection of Python source files to :file:`.pyc` files in a 1240 :file:`__pycache__` subdirectory (see :pep:`3147` and :pep:`488`). 1241 *py_files* is a list of files to compile; any files that don't end in 1242 :file:`.py` are silently skipped. *optimize* must be one of the following: 1243 1244 * ``0`` - don't optimize 1245 * ``1`` - normal optimization (like ``python -O``) 1246 * ``2`` - extra optimization (like ``python -OO``) 1247 1248 If *force* is true, all files are recompiled regardless of timestamps. 1249 1250 The source filename encoded in each :term:`bytecode` file defaults to the filenames 1251 listed in *py_files*; you can modify these with *prefix* and *basedir*. 1252 *prefix* is a string that will be stripped off of each source filename, and 1253 *base_dir* is a directory name that will be prepended (after *prefix* is 1254 stripped). You can supply either or both (or neither) of *prefix* and 1255 *base_dir*, as you wish. 1256 1257 If *dry_run* is true, doesn't actually do anything that would affect the 1258 filesystem. 1259 1260 Byte-compilation is either done directly in this interpreter process with the 1261 standard :mod:`py_compile` module, or indirectly by writing a temporary script 1262 and executing it. Normally, you should let :func:`byte_compile` figure out to 1263 use direct compilation or not (see the source for details). The *direct* flag 1264 is used by the script generated in indirect mode; unless you know what you're 1265 doing, leave it set to ``None``. 1266 1267 .. versionchanged:: 3.2.3 1268 Create ``.pyc`` files with an :func:`import magic tag 1269 <imp.get_tag>` in their name, in a :file:`__pycache__` subdirectory 1270 instead of files without tag in the current directory. 1271 1272 .. versionchanged:: 3.5 1273 Create ``.pyc`` files according to :pep:`488`. 1274 1275 1276.. function:: rfc822_escape(header) 1277 1278 Return a version of *header* escaped for inclusion in an :rfc:`822` header, by 1279 ensuring there are 8 spaces space after each newline. Note that it does no other 1280 modification of the string. 1281 1282 .. % this _can_ be replaced 1283 1284.. % \subsection{Distutils objects} 1285 1286 1287:mod:`distutils.dist` --- The Distribution class 1288================================================ 1289 1290.. module:: distutils.dist 1291 :synopsis: Provides the Distribution class, which represents the module distribution being 1292 built/installed/distributed 1293 1294 1295This module provides the :class:`~distutils.core.Distribution` class, which 1296represents the module distribution being built/installed/distributed. 1297 1298 1299:mod:`distutils.extension` --- The Extension class 1300================================================== 1301 1302.. module:: distutils.extension 1303 :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup 1304 scripts 1305 1306 1307This module provides the :class:`Extension` class, used to describe C/C++ 1308extension modules in setup scripts. 1309 1310.. % \subsection{Ungrouped modules} 1311.. % The following haven't been moved into a more appropriate section yet. 1312 1313 1314:mod:`distutils.debug` --- Distutils debug mode 1315=============================================== 1316 1317.. module:: distutils.debug 1318 :synopsis: Provides the debug flag for distutils 1319 1320 1321This module provides the DEBUG flag. 1322 1323 1324:mod:`distutils.errors` --- Distutils exceptions 1325================================================ 1326 1327.. module:: distutils.errors 1328 :synopsis: Provides standard distutils exceptions 1329 1330 1331Provides exceptions used by the Distutils modules. Note that Distutils modules 1332may raise standard exceptions; in particular, SystemExit is usually raised for 1333errors that are obviously the end-user's fault (eg. bad command-line arguments). 1334 1335This module is safe to use in ``from ... import *`` mode; it only exports 1336symbols whose names start with ``Distutils`` and end with ``Error``. 1337 1338 1339:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module 1340=========================================================================== 1341 1342.. module:: distutils.fancy_getopt 1343 :synopsis: Additional getopt functionality 1344 1345 1346This module provides a wrapper around the standard :mod:`getopt` module that 1347provides the following additional features: 1348 1349* short and long options are tied together 1350 1351* options have help strings, so :func:`fancy_getopt` could potentially create a 1352 complete usage summary 1353 1354* options set attributes of a passed-in object 1355 1356* boolean options can have "negative aliases" --- eg. if :option:`!--quiet` is 1357 the "negative alias" of :option:`!--verbose`, then :option:`!--quiet` on the 1358 command line sets *verbose* to false. 1359 1360.. function:: fancy_getopt(options, negative_opt, object, args) 1361 1362 Wrapper function. *options* is a list of ``(long_option, short_option, 1363 help_string)`` 3-tuples as described in the constructor for 1364 :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names 1365 to option names, both the key and value should be in the *options* list. 1366 *object* is an object which will be used to store values (see the :meth:`getopt` 1367 method of the :class:`FancyGetopt` class). *args* is the argument list. Will use 1368 ``sys.argv[1:]`` if you pass ``None`` as *args*. 1369 1370 1371.. function:: wrap_text(text, width) 1372 1373 Wraps *text* to less than *width* wide. 1374 1375 1376.. class:: FancyGetopt([option_table=None]) 1377 1378 The option_table is a list of 3-tuples: ``(long_option, short_option, 1379 help_string)`` 1380 1381 If an option takes an argument, its *long_option* should have ``'='`` appended; 1382 *short_option* should just be a single character, no ``':'`` in any case. 1383 *short_option* should be ``None`` if a *long_option* doesn't have a 1384 corresponding *short_option*. All option tuples must have long options. 1385 1386The :class:`FancyGetopt` class provides the following methods: 1387 1388 1389.. method:: FancyGetopt.getopt([args=None, object=None]) 1390 1391 Parse command-line options in args. Store as attributes on *object*. 1392 1393 If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is 1394 ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores 1395 option values there, and returns a tuple ``(args, object)``. If *object* is 1396 supplied, it is modified in place and :func:`getopt` just returns *args*; in 1397 both cases, the returned *args* is a modified copy of the passed-in *args* list, 1398 which is left untouched. 1399 1400 .. % and args returned are? 1401 1402 1403.. method:: FancyGetopt.get_option_order() 1404 1405 Returns the list of ``(option, value)`` tuples processed by the previous run of 1406 :meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called 1407 yet. 1408 1409 1410.. method:: FancyGetopt.generate_help([header=None]) 1411 1412 Generate help text (a list of strings, one per suggested line of output) from 1413 the option table for this :class:`FancyGetopt` object. 1414 1415 If supplied, prints the supplied *header* at the top of the help. 1416 1417 1418:mod:`distutils.filelist` --- The FileList class 1419================================================ 1420 1421.. module:: distutils.filelist 1422 :synopsis: The FileList class, used for poking about the file system and 1423 building lists of files. 1424 1425 1426This module provides the :class:`FileList` class, used for poking about the 1427filesystem and building lists of files. 1428 1429 1430:mod:`distutils.log` --- Simple :pep:`282`-style logging 1431======================================================== 1432 1433.. module:: distutils.log 1434 :synopsis: A simple logging mechanism, :pep:`282`-style 1435 1436 1437:mod:`distutils.spawn` --- Spawn a sub-process 1438============================================== 1439 1440.. module:: distutils.spawn 1441 :synopsis: Provides the spawn() function 1442 1443 1444This module provides the :func:`spawn` function, a front-end to various 1445platform-specific functions for launching another program in a sub-process. 1446Also provides :func:`find_executable` to search the path for a given executable 1447name. 1448 1449 1450:mod:`distutils.sysconfig` --- System configuration information 1451=============================================================== 1452 1453.. module:: distutils.sysconfig 1454 :synopsis: Low-level access to configuration information of the Python interpreter. 1455.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 1456.. moduleauthor:: Greg Ward <gward@python.net> 1457.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 1458 1459 1460The :mod:`distutils.sysconfig` module provides access to Python's low-level 1461configuration information. The specific configuration variables available 1462depend heavily on the platform and configuration. The specific variables depend 1463on the build process for the specific version of Python being run; the variables 1464are those found in the :file:`Makefile` and configuration header that are 1465installed with Python on Unix systems. The configuration header is called 1466:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` 1467for earlier versions of Python. 1468 1469Some additional functions are provided which perform some useful manipulations 1470for other parts of the :mod:`distutils` package. 1471 1472 1473.. data:: PREFIX 1474 1475 The result of ``os.path.normpath(sys.prefix)``. 1476 1477 1478.. data:: EXEC_PREFIX 1479 1480 The result of ``os.path.normpath(sys.exec_prefix)``. 1481 1482 1483.. function:: get_config_var(name) 1484 1485 Return the value of a single variable. This is equivalent to 1486 ``get_config_vars().get(name)``. 1487 1488 1489.. function:: get_config_vars(...) 1490 1491 Return a set of variable definitions. If there are no arguments, this returns a 1492 dictionary mapping names of configuration variables to values. If arguments are 1493 provided, they should be strings, and the return value will be a sequence giving 1494 the associated values. If a given name does not have a corresponding value, 1495 ``None`` will be included for that variable. 1496 1497 1498.. function:: get_config_h_filename() 1499 1500 Return the full path name of the configuration header. For Unix, this will be 1501 the header generated by the :program:`configure` script; for other platforms the 1502 header will have been supplied directly by the Python source distribution. The 1503 file is a platform-specific text file. 1504 1505 1506.. function:: get_makefile_filename() 1507 1508 Return the full path name of the :file:`Makefile` used to build Python. For 1509 Unix, this will be a file generated by the :program:`configure` script; the 1510 meaning for other platforms will vary. The file is a platform-specific text 1511 file, if it exists. This function is only useful on POSIX platforms. 1512 1513 1514.. function:: get_python_inc([plat_specific[, prefix]]) 1515 1516 Return the directory for either the general or platform-dependent C include 1517 files. If *plat_specific* is true, the platform-dependent include directory is 1518 returned; if false or omitted, the platform-independent directory is returned. 1519 If *prefix* is given, it is used as either the prefix instead of 1520 :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if 1521 *plat_specific* is true. 1522 1523 1524.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) 1525 1526 Return the directory for either the general or platform-dependent library 1527 installation. If *plat_specific* is true, the platform-dependent include 1528 directory is returned; if false or omitted, the platform-independent directory 1529 is returned. If *prefix* is given, it is used as either the prefix instead of 1530 :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if 1531 *plat_specific* is true. If *standard_lib* is true, the directory for the 1532 standard library is returned rather than the directory for the installation of 1533 third-party extensions. 1534 1535The following function is only intended for use within the :mod:`distutils` 1536package. 1537 1538 1539.. function:: customize_compiler(compiler) 1540 1541 Do any platform-specific customization of a 1542 :class:`distutils.ccompiler.CCompiler` instance. 1543 1544 This function is only needed on Unix at this time, but should be called 1545 consistently to support forward-compatibility. It inserts the information that 1546 varies across Unix flavors and is stored in Python's :file:`Makefile`. This 1547 information includes the selected compiler, compiler and linker options, and the 1548 extension used by the linker for shared objects. 1549 1550This function is even more special-purpose, and should only be used from 1551Python's own build procedures. 1552 1553 1554.. function:: set_python_build() 1555 1556 Inform the :mod:`distutils.sysconfig` module that it is being used as part of 1557 the build process for Python. This changes a lot of relative locations for 1558 files, allowing them to be located in the build area rather than in an installed 1559 Python. 1560 1561 1562:mod:`distutils.text_file` --- The TextFile class 1563================================================= 1564 1565.. module:: distutils.text_file 1566 :synopsis: Provides the TextFile class, a simple interface to text files 1567 1568 1569This module provides the :class:`TextFile` class, which gives an interface to 1570text files that (optionally) takes care of stripping comments, ignoring blank 1571lines, and joining lines with backslashes. 1572 1573 1574.. class:: TextFile([filename=None, file=None, **options]) 1575 1576 This class provides a file-like object that takes care of all the things you 1577 commonly want to do when processing a text file that has some line-by-line 1578 syntax: strip comments (as long as ``#`` is your comment character), skip blank 1579 lines, join adjacent lines by escaping the newline (ie. backslash at end of 1580 line), strip leading and/or trailing whitespace. All of these are optional and 1581 independently controllable. 1582 1583 The class provides a :meth:`warn` method so you can generate warning messages 1584 that report physical line number, even if the logical line in question spans 1585 multiple physical lines. Also provides :meth:`unreadline` for implementing 1586 line-at-a-time lookahead. 1587 1588 :class:`TextFile` instances are create with either *filename*, *file*, or both. 1589 :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a 1590 string, and *file* a file object (or something that provides :meth:`readline` 1591 and :meth:`close` methods). It is recommended that you supply at least 1592 *filename*, so that :class:`TextFile` can include it in warning messages. If 1593 *file* is not supplied, :class:`TextFile` creates its own using the 1594 :func:`open` built-in function. 1595 1596 The options are all boolean, and affect the values returned by :meth:`readline` 1597 1598 .. tabularcolumns:: |l|L|l| 1599 1600 +------------------+--------------------------------+---------+ 1601 | option name | description | default | 1602 +==================+================================+=========+ 1603 | *strip_comments* | strip from ``'#'`` to | true | 1604 | | end-of-line, as well as any | | 1605 | | whitespace leading up to the | | 1606 | | ``'#'``\ ---unless it is | | 1607 | | escaped by a backslash | | 1608 +------------------+--------------------------------+---------+ 1609 | *lstrip_ws* | strip leading whitespace from | false | 1610 | | each line before returning it | | 1611 +------------------+--------------------------------+---------+ 1612 | *rstrip_ws* | strip trailing whitespace | true | 1613 | | (including line terminator!) | | 1614 | | from each line before | | 1615 | | returning it. | | 1616 +------------------+--------------------------------+---------+ 1617 | *skip_blanks* | skip lines that are empty | true | 1618 | | \*after\* stripping comments | | 1619 | | and whitespace. (If both | | 1620 | | lstrip_ws and rstrip_ws are | | 1621 | | false, then some lines may | | 1622 | | consist of solely whitespace: | | 1623 | | these will \*not\* be skipped, | | 1624 | | even if *skip_blanks* is | | 1625 | | true.) | | 1626 +------------------+--------------------------------+---------+ 1627 | *join_lines* | if a backslash is the last | false | 1628 | | non-newline character on a | | 1629 | | line after stripping comments | | 1630 | | and whitespace, join the | | 1631 | | following line to it to form | | 1632 | | one logical line; if N | | 1633 | | consecutive lines end with a | | 1634 | | backslash, then N+1 physical | | 1635 | | lines will be joined to form | | 1636 | | one logical line. | | 1637 +------------------+--------------------------------+---------+ 1638 | *collapse_join* | strip leading whitespace from | false | 1639 | | lines that are joined to their | | 1640 | | predecessor; only matters if | | 1641 | | ``(join_lines and not | | 1642 | | lstrip_ws)`` | | 1643 +------------------+--------------------------------+---------+ 1644 1645 Note that since *rstrip_ws* can strip the trailing newline, the semantics of 1646 :meth:`readline` must differ from those of the built-in file object's 1647 :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for 1648 end-of-file: an empty string might just be a blank line (or an all-whitespace 1649 line), if *rstrip_ws* is true but *skip_blanks* is not. 1650 1651 1652 .. method:: TextFile.open(filename) 1653 1654 Open a new file *filename*. This overrides any *file* or *filename* 1655 constructor arguments. 1656 1657 1658 .. method:: TextFile.close() 1659 1660 Close the current file and forget everything we know about it (including the 1661 filename and the current line number). 1662 1663 1664 .. method:: TextFile.warn(msg[,line=None]) 1665 1666 Print (to stderr) a warning message tied to the current logical line in the 1667 current file. If the current logical line in the file spans multiple physical 1668 lines, the warning refers to the whole range, such as ``"lines 3-5"``. If 1669 *line* is supplied, it overrides the current line number; it may be a list or 1670 tuple to indicate a range of physical lines, or an integer for a single 1671 physical line. 1672 1673 1674 .. method:: TextFile.readline() 1675 1676 Read and return a single logical line from the current file (or from an internal 1677 buffer if lines have previously been "unread" with :meth:`unreadline`). If the 1678 *join_lines* option is true, this may involve reading multiple physical lines 1679 concatenated into a single string. Updates the current line number, so calling 1680 :meth:`warn` after :meth:`readline` emits a warning about the physical line(s) 1681 just read. Returns ``None`` on end-of-file, since the empty string can occur 1682 if *rstrip_ws* is true but *strip_blanks* is not. 1683 1684 1685 .. method:: TextFile.readlines() 1686 1687 Read and return the list of all logical lines remaining in the current file. 1688 This updates the current line number to the last line of the file. 1689 1690 1691 .. method:: TextFile.unreadline(line) 1692 1693 Push *line* (a string) onto an internal buffer that will be checked by future 1694 :meth:`readline` calls. Handy for implementing a parser with line-at-a-time 1695 lookahead. Note that lines that are "unread" with :meth:`unreadline` are not 1696 subsequently re-cleansed (whitespace stripped, or whatever) when read with 1697 :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call 1698 to :meth:`readline`, the lines will be returned most in most recent first order. 1699 1700 1701:mod:`distutils.version` --- Version number classes 1702=================================================== 1703 1704.. module:: distutils.version 1705 :synopsis: Implements classes that represent module version numbers. 1706 1707 1708.. % todo 1709.. % \section{Distutils Commands} 1710.. % 1711.. % This part of Distutils implements the various Distutils commands, such 1712.. % as \code{build}, \code{install} \&c. Each command is implemented as a 1713.. % separate module, with the command name as the name of the module. 1714 1715 1716:mod:`distutils.cmd` --- Abstract base class for Distutils commands 1717=================================================================== 1718 1719.. module:: distutils.cmd 1720 :synopsis: Provides the abstract base class :class:`~distutils.cmd.Command`. This class 1721 is subclassed by the modules in the distutils.command subpackage. 1722 1723 1724This module supplies the abstract base class :class:`Command`. 1725 1726 1727.. class:: Command(dist) 1728 1729 Abstract base class for defining command classes, the "worker bees" of the 1730 Distutils. A useful analogy for command classes is to think of them as 1731 subroutines with local variables called *options*. The options are declared 1732 in :meth:`initialize_options` and defined (given their final values) in 1733 :meth:`finalize_options`, both of which must be defined by every command 1734 class. The distinction between the two is necessary because option values 1735 might come from the outside world (command line, config file, ...), and any 1736 options dependent on other options must be computed after these outside 1737 influences have been processed --- hence :meth:`finalize_options`. The body 1738 of the subroutine, where it does all its work based on the values of its 1739 options, is the :meth:`run` method, which must also be implemented by every 1740 command class. 1741 1742 The class constructor takes a single argument *dist*, a 1743 :class:`~distutils.core.Distribution` instance. 1744 1745 1746Creating a new Distutils command 1747================================ 1748 1749This section outlines the steps to create a new Distutils command. 1750 1751A new command lives in a module in the :mod:`distutils.command` package. There 1752is a sample template in that directory called :file:`command_template`. Copy 1753this file to a new module with the same name as the new command you're 1754implementing. This module should implement a class with the same name as the 1755module (and the command). So, for instance, to create the command 1756``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy 1757:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit 1758it so that it's implementing the class :class:`peel_banana`, a subclass of 1759:class:`distutils.cmd.Command`. 1760 1761Subclasses of :class:`Command` must define the following methods. 1762 1763.. method:: Command.initialize_options() 1764 1765 Set default values for all the options that this command supports. Note that 1766 these defaults may be overridden by other commands, by the setup script, by 1767 config files, or by the command-line. Thus, this is not the place to code 1768 dependencies between options; generally, :meth:`initialize_options` 1769 implementations are just a bunch of ``self.foo = None`` assignments. 1770 1771 1772.. method:: Command.finalize_options() 1773 1774 Set final values for all the options that this command supports. This is 1775 always called as late as possible, ie. after any option assignments from the 1776 command-line or from other commands have been done. Thus, this is the place 1777 to code option dependencies: if *foo* depends on *bar*, then it is safe to 1778 set *foo* from *bar* as long as *foo* still has the same value it was 1779 assigned in :meth:`initialize_options`. 1780 1781 1782.. method:: Command.run() 1783 1784 A command's raison d'etre: carry out the action it exists to perform, controlled 1785 by the options initialized in :meth:`initialize_options`, customized by other 1786 commands, the setup script, the command-line, and config files, and finalized in 1787 :meth:`finalize_options`. All terminal output and filesystem interaction should 1788 be done by :meth:`run`. 1789 1790 1791.. attribute:: Command.sub_commands 1792 1793 *sub_commands* formalizes the notion of a "family" of commands, 1794 e.g. ``install`` as the parent with sub-commands ``install_lib``, 1795 ``install_headers``, etc. The parent of a family of commands defines 1796 *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, 1797 predicate)``, with *command_name* a string and *predicate* a function, a 1798 string or ``None``. *predicate* is a method of the parent command that 1799 determines whether the corresponding command is applicable in the current 1800 situation. (E.g. ``install_headers`` is only applicable if we have any C 1801 header files to install.) If *predicate* is ``None``, that command is always 1802 applicable. 1803 1804 *sub_commands* is usually defined at the *end* of a class, because 1805 predicates can be methods of the class, so they must already have been 1806 defined. The canonical example is the :command:`install` command. 1807 1808 1809:mod:`distutils.command` --- Individual Distutils commands 1810========================================================== 1811 1812.. module:: distutils.command 1813 :synopsis: Contains one module for each standard Distutils command. 1814 1815 1816.. % \subsubsection{Individual Distutils commands} 1817.. % todo 1818 1819 1820:mod:`distutils.command.bdist` --- Build a binary installer 1821=========================================================== 1822 1823.. module:: distutils.command.bdist 1824 :synopsis: Build a binary installer for a package 1825 1826 1827.. % todo 1828 1829 1830:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers 1831============================================================================= 1832 1833.. module:: distutils.command.bdist_packager 1834 :synopsis: Abstract base class for packagers 1835 1836 1837.. % todo 1838 1839 1840:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer 1841================================================================ 1842 1843.. module:: distutils.command.bdist_dumb 1844 :synopsis: Build a "dumb" installer - a simple archive of files 1845 1846 1847.. % todo 1848 1849 1850:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package 1851================================================================================= 1852 1853.. module:: distutils.command.bdist_msi 1854 :synopsis: Build a binary distribution as a Windows MSI file 1855 1856.. class:: bdist_msi 1857 1858.. deprecated:: 3.9 1859 Use bdist_wheel (wheel packages) instead. 1860 1861 Builds a `Windows Installer`_ (.msi) binary package. 1862 1863 .. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx 1864 1865 In most cases, the ``bdist_msi`` installer is a better choice than the 1866 ``bdist_wininst`` installer, because it provides better support for 1867 Win64 platforms, allows administrators to perform non-interactive 1868 installations, and allows installation through group policies. 1869 1870 1871:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM 1872=========================================================================================== 1873 1874.. module:: distutils.command.bdist_rpm 1875 :synopsis: Build a binary distribution as a Redhat RPM and SRPM 1876 1877 1878.. % todo 1879 1880 1881:mod:`distutils.command.bdist_wininst` --- Build a Windows installer 1882==================================================================== 1883 1884.. module:: distutils.command.bdist_wininst 1885 :synopsis: Build a Windows installer 1886 1887.. deprecated:: 3.8 1888 Use bdist_wheel (wheel packages) instead. 1889 1890 1891.. % todo 1892 1893 1894:mod:`distutils.command.sdist` --- Build a source distribution 1895============================================================== 1896 1897.. module:: distutils.command.sdist 1898 :synopsis: Build a source distribution 1899 1900 1901.. % todo 1902 1903 1904:mod:`distutils.command.build` --- Build all files of a package 1905=============================================================== 1906 1907.. module:: distutils.command.build 1908 :synopsis: Build all files of a package 1909 1910 1911.. % todo 1912 1913 1914:mod:`distutils.command.build_clib` --- Build any C libraries in a package 1915========================================================================== 1916 1917.. module:: distutils.command.build_clib 1918 :synopsis: Build any C libraries in a package 1919 1920 1921.. % todo 1922 1923 1924:mod:`distutils.command.build_ext` --- Build any extensions in a package 1925======================================================================== 1926 1927.. module:: distutils.command.build_ext 1928 :synopsis: Build any extensions in a package 1929 1930 1931.. % todo 1932 1933 1934:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package 1935=========================================================================== 1936 1937.. module:: distutils.command.build_py 1938 :synopsis: Build the .py/.pyc files of a package 1939 1940 1941.. class:: build_py 1942 1943.. class:: build_py_2to3 1944 1945 Alternative implementation of build_py which also runs the 1946 2to3 conversion library on each .py file that is going to be 1947 installed. To use this in a setup.py file for a distribution 1948 that is designed to run with both Python 2.x and 3.x, add:: 1949 1950 try: 1951 from distutils.command.build_py import build_py_2to3 as build_py 1952 except ImportError: 1953 from distutils.command.build_py import build_py 1954 1955 to your setup.py, and later:: 1956 1957 cmdclass = {'build_py': build_py} 1958 1959 to the invocation of setup(). 1960 1961 1962:mod:`distutils.command.build_scripts` --- Build the scripts of a package 1963========================================================================= 1964 1965.. module:: distutils.command.build_scripts 1966 :synopsis: Build the scripts of a package 1967 1968 1969.. % todo 1970 1971 1972:mod:`distutils.command.clean` --- Clean a package build area 1973============================================================= 1974 1975.. module:: distutils.command.clean 1976 :synopsis: Clean a package build area 1977 1978This command removes the temporary files created by :command:`build` 1979and its subcommands, like intermediary compiled object files. With 1980the ``--all`` option, the complete build directory will be removed. 1981 1982Extension modules built :ref:`in place <distutils-build-ext-inplace>` 1983will not be cleaned, as they are not in the build directory. 1984 1985 1986:mod:`distutils.command.config` --- Perform package configuration 1987================================================================= 1988 1989.. module:: distutils.command.config 1990 :synopsis: Perform package configuration 1991 1992 1993.. % todo 1994 1995 1996:mod:`distutils.command.install` --- Install a package 1997====================================================== 1998 1999.. module:: distutils.command.install 2000 :synopsis: Install a package 2001 2002 2003.. % todo 2004 2005 2006:mod:`distutils.command.install_data` --- Install data files from a package 2007=========================================================================== 2008 2009.. module:: distutils.command.install_data 2010 :synopsis: Install data files from a package 2011 2012 2013.. % todo 2014 2015 2016:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package 2017====================================================================================== 2018 2019.. module:: distutils.command.install_headers 2020 :synopsis: Install C/C++ header files from a package 2021 2022 2023.. % todo 2024 2025 2026:mod:`distutils.command.install_lib` --- Install library files from a package 2027============================================================================= 2028 2029.. module:: distutils.command.install_lib 2030 :synopsis: Install library files from a package 2031 2032 2033.. % todo 2034 2035 2036:mod:`distutils.command.install_scripts` --- Install script files from a package 2037================================================================================ 2038 2039.. module:: distutils.command.install_scripts 2040 :synopsis: Install script files from a package 2041 2042 2043.. % todo 2044 2045 2046:mod:`distutils.command.register` --- Register a module with the Python Package Index 2047===================================================================================== 2048 2049.. module:: distutils.command.register 2050 :synopsis: Register a module with the Python Package Index 2051 2052 2053The ``register`` command registers the package with the Python Package Index. 2054This is described in more detail in :pep:`301`. 2055 2056.. % todo 2057 2058 2059:mod:`distutils.command.check` --- Check the meta-data of a package 2060=================================================================== 2061 2062.. module:: distutils.command.check 2063 :synopsis: Check the meta-data of a package 2064 2065 2066The ``check`` command performs some tests on the meta-data of a package. 2067For example, it verifies that all required meta-data are provided as 2068the arguments passed to the :func:`setup` function. 2069 2070.. % todo 2071