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? macOS 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 macOS 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 macOS 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 macOS: 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.. deprecated:: 3.10 1456 :mod:`distutils.sysconfig` has been merged into :mod:`sysconfig`. 1457.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 1458.. moduleauthor:: Greg Ward <gward@python.net> 1459.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org> 1460 1461 1462The :mod:`distutils.sysconfig` module provides access to Python's low-level 1463configuration information. The specific configuration variables available 1464depend heavily on the platform and configuration. The specific variables depend 1465on the build process for the specific version of Python being run; the variables 1466are those found in the :file:`Makefile` and configuration header that are 1467installed with Python on Unix systems. The configuration header is called 1468:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` 1469for earlier versions of Python. 1470 1471Some additional functions are provided which perform some useful manipulations 1472for other parts of the :mod:`distutils` package. 1473 1474 1475.. data:: PREFIX 1476 1477 The result of ``os.path.normpath(sys.prefix)``. 1478 1479 1480.. data:: EXEC_PREFIX 1481 1482 The result of ``os.path.normpath(sys.exec_prefix)``. 1483 1484 1485.. function:: get_config_var(name) 1486 1487 Return the value of a single variable. This is equivalent to 1488 ``get_config_vars().get(name)``. 1489 1490 1491.. function:: get_config_vars(...) 1492 1493 Return a set of variable definitions. If there are no arguments, this returns a 1494 dictionary mapping names of configuration variables to values. If arguments are 1495 provided, they should be strings, and the return value will be a sequence giving 1496 the associated values. If a given name does not have a corresponding value, 1497 ``None`` will be included for that variable. 1498 1499 1500.. function:: get_config_h_filename() 1501 1502 Return the full path name of the configuration header. For Unix, this will be 1503 the header generated by the :program:`configure` script; for other platforms the 1504 header will have been supplied directly by the Python source distribution. The 1505 file is a platform-specific text file. 1506 1507 1508.. function:: get_makefile_filename() 1509 1510 Return the full path name of the :file:`Makefile` used to build Python. For 1511 Unix, this will be a file generated by the :program:`configure` script; the 1512 meaning for other platforms will vary. The file is a platform-specific text 1513 file, if it exists. This function is only useful on POSIX platforms. 1514 1515The following functions are deprecated together with this module and they 1516have no direct replacement. 1517 1518 1519.. function:: get_python_inc([plat_specific[, prefix]]) 1520 1521 Return the directory for either the general or platform-dependent C include 1522 files. If *plat_specific* is true, the platform-dependent include directory is 1523 returned; if false or omitted, the platform-independent directory is returned. 1524 If *prefix* is given, it is used as either the prefix instead of 1525 :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if 1526 *plat_specific* is true. 1527 1528 1529.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) 1530 1531 Return the directory for either the general or platform-dependent library 1532 installation. If *plat_specific* is true, the platform-dependent include 1533 directory is returned; if false or omitted, the platform-independent directory 1534 is returned. If *prefix* is given, it is used as either the prefix instead of 1535 :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if 1536 *plat_specific* is true. If *standard_lib* is true, the directory for the 1537 standard library is returned rather than the directory for the installation of 1538 third-party extensions. 1539 1540The following function is only intended for use within the :mod:`distutils` 1541package. 1542 1543 1544.. function:: customize_compiler(compiler) 1545 1546 Do any platform-specific customization of a 1547 :class:`distutils.ccompiler.CCompiler` instance. 1548 1549 This function is only needed on Unix at this time, but should be called 1550 consistently to support forward-compatibility. It inserts the information that 1551 varies across Unix flavors and is stored in Python's :file:`Makefile`. This 1552 information includes the selected compiler, compiler and linker options, and the 1553 extension used by the linker for shared objects. 1554 1555This function is even more special-purpose, and should only be used from 1556Python's own build procedures. 1557 1558 1559.. function:: set_python_build() 1560 1561 Inform the :mod:`distutils.sysconfig` module that it is being used as part of 1562 the build process for Python. This changes a lot of relative locations for 1563 files, allowing them to be located in the build area rather than in an installed 1564 Python. 1565 1566 1567:mod:`distutils.text_file` --- The TextFile class 1568================================================= 1569 1570.. module:: distutils.text_file 1571 :synopsis: Provides the TextFile class, a simple interface to text files 1572 1573 1574This module provides the :class:`TextFile` class, which gives an interface to 1575text files that (optionally) takes care of stripping comments, ignoring blank 1576lines, and joining lines with backslashes. 1577 1578 1579.. class:: TextFile([filename=None, file=None, **options]) 1580 1581 This class provides a file-like object that takes care of all the things you 1582 commonly want to do when processing a text file that has some line-by-line 1583 syntax: strip comments (as long as ``#`` is your comment character), skip blank 1584 lines, join adjacent lines by escaping the newline (ie. backslash at end of 1585 line), strip leading and/or trailing whitespace. All of these are optional and 1586 independently controllable. 1587 1588 The class provides a :meth:`warn` method so you can generate warning messages 1589 that report physical line number, even if the logical line in question spans 1590 multiple physical lines. Also provides :meth:`unreadline` for implementing 1591 line-at-a-time lookahead. 1592 1593 :class:`TextFile` instances are create with either *filename*, *file*, or both. 1594 :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a 1595 string, and *file* a file object (or something that provides :meth:`readline` 1596 and :meth:`close` methods). It is recommended that you supply at least 1597 *filename*, so that :class:`TextFile` can include it in warning messages. If 1598 *file* is not supplied, :class:`TextFile` creates its own using the 1599 :func:`open` built-in function. 1600 1601 The options are all boolean, and affect the values returned by :meth:`readline` 1602 1603 .. tabularcolumns:: |l|L|l| 1604 1605 +------------------+--------------------------------+---------+ 1606 | option name | description | default | 1607 +==================+================================+=========+ 1608 | *strip_comments* | strip from ``'#'`` to | true | 1609 | | end-of-line, as well as any | | 1610 | | whitespace leading up to the | | 1611 | | ``'#'``\ ---unless it is | | 1612 | | escaped by a backslash | | 1613 +------------------+--------------------------------+---------+ 1614 | *lstrip_ws* | strip leading whitespace from | false | 1615 | | each line before returning it | | 1616 +------------------+--------------------------------+---------+ 1617 | *rstrip_ws* | strip trailing whitespace | true | 1618 | | (including line terminator!) | | 1619 | | from each line before | | 1620 | | returning it. | | 1621 +------------------+--------------------------------+---------+ 1622 | *skip_blanks* | skip lines that are empty | true | 1623 | | \*after\* stripping comments | | 1624 | | and whitespace. (If both | | 1625 | | lstrip_ws and rstrip_ws are | | 1626 | | false, then some lines may | | 1627 | | consist of solely whitespace: | | 1628 | | these will \*not\* be skipped, | | 1629 | | even if *skip_blanks* is | | 1630 | | true.) | | 1631 +------------------+--------------------------------+---------+ 1632 | *join_lines* | if a backslash is the last | false | 1633 | | non-newline character on a | | 1634 | | line after stripping comments | | 1635 | | and whitespace, join the | | 1636 | | following line to it to form | | 1637 | | one logical line; if N | | 1638 | | consecutive lines end with a | | 1639 | | backslash, then N+1 physical | | 1640 | | lines will be joined to form | | 1641 | | one logical line. | | 1642 +------------------+--------------------------------+---------+ 1643 | *collapse_join* | strip leading whitespace from | false | 1644 | | lines that are joined to their | | 1645 | | predecessor; only matters if | | 1646 | | ``(join_lines and not | | 1647 | | lstrip_ws)`` | | 1648 +------------------+--------------------------------+---------+ 1649 1650 Note that since *rstrip_ws* can strip the trailing newline, the semantics of 1651 :meth:`readline` must differ from those of the built-in file object's 1652 :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for 1653 end-of-file: an empty string might just be a blank line (or an all-whitespace 1654 line), if *rstrip_ws* is true but *skip_blanks* is not. 1655 1656 1657 .. method:: TextFile.open(filename) 1658 1659 Open a new file *filename*. This overrides any *file* or *filename* 1660 constructor arguments. 1661 1662 1663 .. method:: TextFile.close() 1664 1665 Close the current file and forget everything we know about it (including the 1666 filename and the current line number). 1667 1668 1669 .. method:: TextFile.warn(msg[,line=None]) 1670 1671 Print (to stderr) a warning message tied to the current logical line in the 1672 current file. If the current logical line in the file spans multiple physical 1673 lines, the warning refers to the whole range, such as ``"lines 3-5"``. If 1674 *line* is supplied, it overrides the current line number; it may be a list or 1675 tuple to indicate a range of physical lines, or an integer for a single 1676 physical line. 1677 1678 1679 .. method:: TextFile.readline() 1680 1681 Read and return a single logical line from the current file (or from an internal 1682 buffer if lines have previously been "unread" with :meth:`unreadline`). If the 1683 *join_lines* option is true, this may involve reading multiple physical lines 1684 concatenated into a single string. Updates the current line number, so calling 1685 :meth:`warn` after :meth:`readline` emits a warning about the physical line(s) 1686 just read. Returns ``None`` on end-of-file, since the empty string can occur 1687 if *rstrip_ws* is true but *strip_blanks* is not. 1688 1689 1690 .. method:: TextFile.readlines() 1691 1692 Read and return the list of all logical lines remaining in the current file. 1693 This updates the current line number to the last line of the file. 1694 1695 1696 .. method:: TextFile.unreadline(line) 1697 1698 Push *line* (a string) onto an internal buffer that will be checked by future 1699 :meth:`readline` calls. Handy for implementing a parser with line-at-a-time 1700 lookahead. Note that lines that are "unread" with :meth:`unreadline` are not 1701 subsequently re-cleansed (whitespace stripped, or whatever) when read with 1702 :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call 1703 to :meth:`readline`, the lines will be returned most in most recent first order. 1704 1705 1706:mod:`distutils.version` --- Version number classes 1707=================================================== 1708 1709.. module:: distutils.version 1710 :synopsis: Implements classes that represent module version numbers. 1711 1712 1713.. % todo 1714.. % \section{Distutils Commands} 1715.. % 1716.. % This part of Distutils implements the various Distutils commands, such 1717.. % as \code{build}, \code{install} \&c. Each command is implemented as a 1718.. % separate module, with the command name as the name of the module. 1719 1720 1721:mod:`distutils.cmd` --- Abstract base class for Distutils commands 1722=================================================================== 1723 1724.. module:: distutils.cmd 1725 :synopsis: Provides the abstract base class :class:`~distutils.cmd.Command`. This class 1726 is subclassed by the modules in the distutils.command subpackage. 1727 1728 1729This module supplies the abstract base class :class:`Command`. 1730 1731 1732.. class:: Command(dist) 1733 1734 Abstract base class for defining command classes, the "worker bees" of the 1735 Distutils. A useful analogy for command classes is to think of them as 1736 subroutines with local variables called *options*. The options are declared 1737 in :meth:`initialize_options` and defined (given their final values) in 1738 :meth:`finalize_options`, both of which must be defined by every command 1739 class. The distinction between the two is necessary because option values 1740 might come from the outside world (command line, config file, ...), and any 1741 options dependent on other options must be computed after these outside 1742 influences have been processed --- hence :meth:`finalize_options`. The body 1743 of the subroutine, where it does all its work based on the values of its 1744 options, is the :meth:`run` method, which must also be implemented by every 1745 command class. 1746 1747 The class constructor takes a single argument *dist*, a 1748 :class:`~distutils.core.Distribution` instance. 1749 1750 1751Creating a new Distutils command 1752================================ 1753 1754This section outlines the steps to create a new Distutils command. 1755 1756A new command lives in a module in the :mod:`distutils.command` package. There 1757is a sample template in that directory called :file:`command_template`. Copy 1758this file to a new module with the same name as the new command you're 1759implementing. This module should implement a class with the same name as the 1760module (and the command). So, for instance, to create the command 1761``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy 1762:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit 1763it so that it's implementing the class :class:`peel_banana`, a subclass of 1764:class:`distutils.cmd.Command`. 1765 1766Subclasses of :class:`Command` must define the following methods. 1767 1768.. method:: Command.initialize_options() 1769 1770 Set default values for all the options that this command supports. Note that 1771 these defaults may be overridden by other commands, by the setup script, by 1772 config files, or by the command-line. Thus, this is not the place to code 1773 dependencies between options; generally, :meth:`initialize_options` 1774 implementations are just a bunch of ``self.foo = None`` assignments. 1775 1776 1777.. method:: Command.finalize_options() 1778 1779 Set final values for all the options that this command supports. This is 1780 always called as late as possible, ie. after any option assignments from the 1781 command-line or from other commands have been done. Thus, this is the place 1782 to code option dependencies: if *foo* depends on *bar*, then it is safe to 1783 set *foo* from *bar* as long as *foo* still has the same value it was 1784 assigned in :meth:`initialize_options`. 1785 1786 1787.. method:: Command.run() 1788 1789 A command's raison d'etre: carry out the action it exists to perform, controlled 1790 by the options initialized in :meth:`initialize_options`, customized by other 1791 commands, the setup script, the command-line, and config files, and finalized in 1792 :meth:`finalize_options`. All terminal output and filesystem interaction should 1793 be done by :meth:`run`. 1794 1795 1796.. attribute:: Command.sub_commands 1797 1798 *sub_commands* formalizes the notion of a "family" of commands, 1799 e.g. ``install`` as the parent with sub-commands ``install_lib``, 1800 ``install_headers``, etc. The parent of a family of commands defines 1801 *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, 1802 predicate)``, with *command_name* a string and *predicate* a function, a 1803 string or ``None``. *predicate* is a method of the parent command that 1804 determines whether the corresponding command is applicable in the current 1805 situation. (E.g. ``install_headers`` is only applicable if we have any C 1806 header files to install.) If *predicate* is ``None``, that command is always 1807 applicable. 1808 1809 *sub_commands* is usually defined at the *end* of a class, because 1810 predicates can be methods of the class, so they must already have been 1811 defined. The canonical example is the :command:`install` command. 1812 1813 1814:mod:`distutils.command` --- Individual Distutils commands 1815========================================================== 1816 1817.. module:: distutils.command 1818 :synopsis: Contains one module for each standard Distutils command. 1819 1820 1821.. % \subsubsection{Individual Distutils commands} 1822.. % todo 1823 1824 1825:mod:`distutils.command.bdist` --- Build a binary installer 1826=========================================================== 1827 1828.. module:: distutils.command.bdist 1829 :synopsis: Build a binary installer for a package 1830 1831 1832.. % todo 1833 1834 1835:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers 1836============================================================================= 1837 1838.. module:: distutils.command.bdist_packager 1839 :synopsis: Abstract base class for packagers 1840 1841 1842.. % todo 1843 1844 1845:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer 1846================================================================ 1847 1848.. module:: distutils.command.bdist_dumb 1849 :synopsis: Build a "dumb" installer - a simple archive of files 1850 1851 1852.. % todo 1853 1854 1855:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package 1856================================================================================= 1857 1858.. module:: distutils.command.bdist_msi 1859 :synopsis: Build a binary distribution as a Windows MSI file 1860 1861.. class:: bdist_msi 1862 1863.. deprecated:: 3.9 1864 Use bdist_wheel (wheel packages) instead. 1865 1866 Builds a `Windows Installer`_ (.msi) binary package. 1867 1868 .. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx 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.sdist` --- Build a source distribution 1882============================================================== 1883 1884.. module:: distutils.command.sdist 1885 :synopsis: Build a source distribution 1886 1887 1888.. % todo 1889 1890 1891:mod:`distutils.command.build` --- Build all files of a package 1892=============================================================== 1893 1894.. module:: distutils.command.build 1895 :synopsis: Build all files of a package 1896 1897 1898.. % todo 1899 1900 1901:mod:`distutils.command.build_clib` --- Build any C libraries in a package 1902========================================================================== 1903 1904.. module:: distutils.command.build_clib 1905 :synopsis: Build any C libraries in a package 1906 1907 1908.. % todo 1909 1910 1911:mod:`distutils.command.build_ext` --- Build any extensions in a package 1912======================================================================== 1913 1914.. module:: distutils.command.build_ext 1915 :synopsis: Build any extensions in a package 1916 1917 1918.. % todo 1919 1920 1921:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package 1922=========================================================================== 1923 1924.. module:: distutils.command.build_py 1925 :synopsis: Build the .py/.pyc files of a package 1926 1927 1928.. class:: build_py 1929 1930.. class:: build_py_2to3 1931 1932 Alternative implementation of build_py which also runs the 1933 2to3 conversion library on each .py file that is going to be 1934 installed. To use this in a setup.py file for a distribution 1935 that is designed to run with both Python 2.x and 3.x, add:: 1936 1937 try: 1938 from distutils.command.build_py import build_py_2to3 as build_py 1939 except ImportError: 1940 from distutils.command.build_py import build_py 1941 1942 to your setup.py, and later:: 1943 1944 cmdclass = {'build_py': build_py} 1945 1946 to the invocation of setup(). 1947 1948 1949:mod:`distutils.command.build_scripts` --- Build the scripts of a package 1950========================================================================= 1951 1952.. module:: distutils.command.build_scripts 1953 :synopsis: Build the scripts of a package 1954 1955 1956.. % todo 1957 1958 1959:mod:`distutils.command.clean` --- Clean a package build area 1960============================================================= 1961 1962.. module:: distutils.command.clean 1963 :synopsis: Clean a package build area 1964 1965This command removes the temporary files created by :command:`build` 1966and its subcommands, like intermediary compiled object files. With 1967the ``--all`` option, the complete build directory will be removed. 1968 1969Extension modules built :ref:`in place <distutils-build-ext-inplace>` 1970will not be cleaned, as they are not in the build directory. 1971 1972 1973:mod:`distutils.command.config` --- Perform package configuration 1974================================================================= 1975 1976.. module:: distutils.command.config 1977 :synopsis: Perform package configuration 1978 1979 1980.. % todo 1981 1982 1983:mod:`distutils.command.install` --- Install a package 1984====================================================== 1985 1986.. module:: distutils.command.install 1987 :synopsis: Install a package 1988 1989 1990.. % todo 1991 1992 1993:mod:`distutils.command.install_data` --- Install data files from a package 1994=========================================================================== 1995 1996.. module:: distutils.command.install_data 1997 :synopsis: Install data files from a package 1998 1999 2000.. % todo 2001 2002 2003:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package 2004====================================================================================== 2005 2006.. module:: distutils.command.install_headers 2007 :synopsis: Install C/C++ header files from a package 2008 2009 2010.. % todo 2011 2012 2013:mod:`distutils.command.install_lib` --- Install library files from a package 2014============================================================================= 2015 2016.. module:: distutils.command.install_lib 2017 :synopsis: Install library files from a package 2018 2019 2020.. % todo 2021 2022 2023:mod:`distutils.command.install_scripts` --- Install script files from a package 2024================================================================================ 2025 2026.. module:: distutils.command.install_scripts 2027 :synopsis: Install script files from a package 2028 2029 2030.. % todo 2031 2032 2033:mod:`distutils.command.register` --- Register a module with the Python Package Index 2034===================================================================================== 2035 2036.. module:: distutils.command.register 2037 :synopsis: Register a module with the Python Package Index 2038 2039 2040The ``register`` command registers the package with the Python Package Index. 2041This is described in more detail in :pep:`301`. 2042 2043.. % todo 2044 2045 2046:mod:`distutils.command.check` --- Check the meta-data of a package 2047=================================================================== 2048 2049.. module:: distutils.command.check 2050 :synopsis: Check the meta-data of a package 2051 2052 2053The ``check`` command performs some tests on the meta-data of a package. 2054For example, it verifies that all required meta-data are provided as 2055the arguments passed to the :func:`setup` function. 2056 2057.. % todo 2058