From 822a6db9d1b4d38ad9356f91300ffcebb03c3b16 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 15 Aug 2007 14:28:01 +0000 Subject: [PATCH 001/330] Move the 2.6 reST doc tree in place. --- apiref.rst | 1976 ++++++++++++++++++++++++++++++++++++++++++++++ builtdist.rst | 405 ++++++++++ commandref.rst | 104 +++ configfile.rst | 130 +++ examples.rst | 241 ++++++ extending.rst | 96 +++ index.rst | 30 + introduction.rst | 208 +++++ packageindex.rst | 65 ++ setupscript.rst | 669 ++++++++++++++++ sourcedist.rst | 207 +++++ uploading.rst | 37 + 12 files changed, 4168 insertions(+) create mode 100644 apiref.rst create mode 100644 builtdist.rst create mode 100644 commandref.rst create mode 100644 configfile.rst create mode 100644 examples.rst create mode 100644 extending.rst create mode 100644 index.rst create mode 100644 introduction.rst create mode 100644 packageindex.rst create mode 100644 setupscript.rst create mode 100644 sourcedist.rst create mode 100644 uploading.rst diff --git a/apiref.rst b/apiref.rst new file mode 100644 index 0000000000..bc5d2b03d7 --- /dev/null +++ b/apiref.rst @@ -0,0 +1,1976 @@ +.. _api-reference: + +************* +API Reference +************* + + +:mod:`distutils.core` --- Core Distutils functionality +====================================================== + +.. module:: distutils.core + :synopsis: The core Distutils functionality + + +The :mod:`distutils.core` module is the only module that needs to be installed +to use the Distutils. It provides the :func:`setup` (which is called from the +setup script). Indirectly provides the :class:`distutils.dist.Distribution` and +:class:`distutils.cmd.Command` class. + + +.. function:: setup(arguments) + + The basic do-everything function that does most everything you could ever ask + for from a Distutils method. See XXXXX + + The setup function takes a large number of arguments. These are laid out in the + following table. + + +--------------------+--------------------------------+-------------------------------------------------------------+ + | argument name | value | type | + +====================+================================+=============================================================+ + | *name* | The name of the package | a string | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *version* | The version number of the | See :mod:`distutils.version` | + | | package | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *description* | A single line describing the | a string | + | | package | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *long_description* | Longer description of the | a string | + | | package | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *author* | The name of the package author | a string | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *author_email* | The email address of the | a string | + | | package author | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *maintainer* | The name of the current | a string | + | | maintainer, if different from | | + | | the author | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *maintainer_email* | The email address of the | | + | | current maintainer, if | | + | | different from the author | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *url* | A URL for the package | a URL | + | | (homepage) | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *download_url* | A URL to download the package | a URL | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *packages* | A list of Python packages that | a list of strings | + | | distutils will manipulate | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *py_modules* | A list of Python modules that | a list of strings | + | | distutils will manipulate | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *scripts* | A list of standalone script | a list of strings | + | | files to be built and | | + | | installed | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *ext_modules* | A list of Python extensions to | A list of instances of | + | | be built | :class:`distutils.core.Extension` | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *classifiers* | A list of categories for the | The list of available | + | | package | categorizations is at | + | | | http://cheeseshop.python.org/pypi?:action=list_classifiers. | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *distclass* | the :class:`Distribution` | A subclass of | + | | class to use | :class:`distutils.core.Distribution` | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *script_name* | The name of the setup.py | a string | + | | script - defaults to | | + | | ``sys.argv[0]`` | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *script_args* | Arguments to supply to the | a list of strings | + | | setup script | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *options* | default options for the setup | a string | + | | script | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *license* | The license for the package | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *keywords* | Descriptive meta-data. See | | + | | :pep:`314` | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *platforms* | | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *cmdclass* | A mapping of command names to | a dictionary | + | | :class:`Command` subclasses | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + + +.. function:: run_setup(script_name[, script_args=None, stop_after='run']) + + Run a setup script in a somewhat controlled environment, and return the + :class:`distutils.dist.Distribution` instance that drives things. This is + useful if you need to find out the distribution meta-data (passed as keyword + args from *script* to :func:`setup`), or the contents of the config files or + command-line. + + *script_name* is a file that will be run with :func:`execfile` ``sys.argv[0]`` + will be replaced with *script* for the duration of the call. *script_args* is a + list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args* + for the duration of the call. + + *stop_after* tells :func:`setup` when to stop processing; possible values: + + +---------------+---------------------------------------------+ + | value | description | + +===============+=============================================+ + | *init* | Stop after the :class:`Distribution` | + | | instance has been created and populated | + | | with the keyword arguments to :func:`setup` | + +---------------+---------------------------------------------+ + | *config* | Stop after config files have been parsed | + | | (and their data stored in the | + | | :class:`Distribution` instance) | + +---------------+---------------------------------------------+ + | *commandline* | Stop after the command-line | + | | (``sys.argv[1:]`` or *script_args*) have | + | | been parsed (and the data stored in the | + | | :class:`Distribution` instance.) | + +---------------+---------------------------------------------+ + | *run* | Stop after all commands have been run (the | + | | same as if :func:`setup` had been called | + | | in the usual way). This is the default | + | | value. | + +---------------+---------------------------------------------+ + +In addition, the :mod:`distutils.core` module exposed a number of classes that +live elsewhere. + +* :class:`Extension` from :mod:`distutils.extension` + +* :class:`Command` from :mod:`distutils.cmd` + +* :class:`Distribution` from :mod:`distutils.dist` + +A short description of each of these follows, but see the relevant module for +the full reference. + + +.. class:: Extension + + The Extension class describes a single C or C++extension module in a setup + script. It accepts the following keyword arguments in its constructor + + +------------------------+--------------------------------+---------------------------+ + | argument name | value | type | + +========================+================================+===========================+ + | *name* | the full name of the | string | + | | extension, including any | | + | | packages --- ie. *not* a | | + | | filename or pathname, but | | + | | Python dotted name | | + +------------------------+--------------------------------+---------------------------+ + | *sources* | list of source filenames, | string | + | | relative to the distribution | | + | | root (where the setup script | | + | | lives), in Unix form (slash- | | + | | separated) for portability. | | + | | Source files may be C, C++, | | + | | SWIG (.i), platform-specific | | + | | resource files, or whatever | | + | | else is recognized by the | | + | | :command:`build_ext` command | | + | | as source for a Python | | + | | extension. | | + +------------------------+--------------------------------+---------------------------+ + | *include_dirs* | list of directories to search | string | + | | for C/C++ header files (in | | + | | Unix form for portability) | | + +------------------------+--------------------------------+---------------------------+ + | *define_macros* | list of macros to define; each | (string,string) tuple or | + | | macro is defined using a | (name,``None``) | + | | 2-tuple, where 'value' is | | + | | either the string to define it | | + | | to or ``None`` to define it | | + | | without a particular value | | + | | (equivalent of ``#define FOO`` | | + | | in source or :option:`-DFOO` | | + | | on Unix C compiler command | | + | | line) | | + +------------------------+--------------------------------+---------------------------+ + | *undef_macros* | list of macros to undefine | string | + | | explicitly | | + +------------------------+--------------------------------+---------------------------+ + | *library_dirs* | list of directories to search | string | + | | for C/C++ libraries at link | | + | | time | | + +------------------------+--------------------------------+---------------------------+ + | *libraries* | list of library names (not | string | + | | filenames or paths) to link | | + | | against | | + +------------------------+--------------------------------+---------------------------+ + | *runtime_library_dirs* | list of directories to search | string | + | | for C/C++ libraries at run | | + | | time (for shared extensions, | | + | | this is when the extension is | | + | | loaded) | | + +------------------------+--------------------------------+---------------------------+ + | *extra_objects* | list of extra files to link | string | + | | with (eg. object files not | | + | | implied by 'sources', static | | + | | library that must be | | + | | explicitly specified, binary | | + | | resource files, etc.) | | + +------------------------+--------------------------------+---------------------------+ + | *extra_compile_args* | any extra platform- and | string | + | | compiler-specific information | | + | | to use when compiling the | | + | | source files in 'sources'. For | | + | | platforms and compilers where | | + | | a command line makes sense, | | + | | this is typically a list of | | + | | command-line arguments, but | | + | | for other platforms it could | | + | | be anything. | | + +------------------------+--------------------------------+---------------------------+ + | *extra_link_args* | any extra platform- and | string | + | | compiler-specific information | | + | | to use when linking object | | + | | files together to create the | | + | | extension (or to create a new | | + | | static Python interpreter). | | + | | Similar interpretation as for | | + | | 'extra_compile_args'. | | + +------------------------+--------------------------------+---------------------------+ + | *export_symbols* | list of symbols to be exported | string | + | | from a shared extension. Not | | + | | used on all platforms, and not | | + | | generally necessary for Python | | + | | extensions, which typically | | + | | export exactly one symbol: | | + | | ``init`` + extension_name. | | + +------------------------+--------------------------------+---------------------------+ + | *depends* | list of files that the | string | + | | extension depends on | | + +------------------------+--------------------------------+---------------------------+ + | *language* | extension language (i.e. | string | + | | ``'c'``, ``'c++'``, | | + | | ``'objc'``). Will be detected | | + | | from the source extensions if | | + | | not provided. | | + +------------------------+--------------------------------+---------------------------+ + + +.. class:: Distribution + + A :class:`Distribution` describes how to build, install and package up a Python + software package. + + See the :func:`setup` function for a list of keyword arguments accepted by the + Distribution constructor. :func:`setup` creates a Distribution instance. + + +.. class:: Command + + A :class:`Command` class (or rather, an instance of one of its subclasses) + implement a single distutils command. + + +:mod:`distutils.ccompiler` --- CCompiler base class +=================================================== + +.. module:: distutils.ccompiler + :synopsis: Abstract CCompiler class + + +This module provides the abstract base class for the :class:`CCompiler` +classes. A :class:`CCompiler` instance can be used for all the compile and +link steps needed to build a single project. Methods are provided to set +options for the compiler --- macro definitions, include directories, link path, +libraries and the like. + +This module provides the following functions. + + +.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries) + + Generate linker options for searching library directories and linking with + specific libraries. *libraries* and *library_dirs* are, respectively, lists of + library names (not filenames!) and search directories. Returns a list of + command-line options suitable for use with some compiler (depending on the two + format strings passed in). + + +.. function:: gen_preprocess_options(macros, include_dirs) + + Generate C pre-processor options (:option:`-D`, :option:`-U`, :option:`-I`) as + used by at least two types of compilers: the typical Unix compiler and Visual + C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)`` + means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means define + (:option:`-D`) macro *name* to *value*. *include_dirs* is just a list of + directory names to be added to the header file search path (:option:`-I`). + Returns a list of command-line options suitable for either Unix compilers or + Visual C++. + + +.. function:: get_default_compiler(osname, platform) + + Determine the default compiler to use for the given platform. + + *osname* should be one of the standard Python OS names (i.e. the ones returned + by ``os.name``) and *platform* the common value returned by ``sys.platform`` for + the platform in question. + + The default values are ``os.name`` and ``sys.platform`` in case the parameters + are not given. + + +.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0) + + Factory function to generate an instance of some CCompiler subclass for the + supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg. + ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for + that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the + default compilers are "traditional Unix interface" (:class:`UnixCCompiler` + class) and Visual C++(:class:`MSVCCompiler` class). Note that it's perfectly + possible to ask for a Unix compiler object under Windows, and a Microsoft + compiler object under Unix---if you supply a value for *compiler*, *plat* is + ignored. + + .. % Is the posix/nt only thing still true? Mac OS X seems to work, and + .. % returns a UnixCCompiler instance. How to document this... hmm. + + +.. function:: show_compilers() + + Print list of available compilers (used by the :option:`--help-compiler` options + to :command:`build`, :command:`build_ext`, :command:`build_clib`). + + +.. class:: CCompiler([verbose=0, dry_run=0, force=0]) + + The abstract base class :class:`CCompiler` defines the interface that must be + implemented by real compiler classes. The class also has some utility methods + used by several compiler classes. + + The basic idea behind a compiler abstraction class is that each instance can be + used for all the compile/link steps in building a single project. Thus, + attributes common to all of those compile and link steps --- include + directories, macros to define, libraries to link against, etc. --- are + attributes of the compiler instance. To allow for variability in how individual + files are treated, most of those attributes may be varied on a per-compilation + or per-link basis. + + The constructor for each subclass creates an instance of the Compiler object. + Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the + steps) and *force* (rebuild everything, regardless of dependencies). All of + these flags default to ``0`` (off). Note that you probably don't want to + instantiate :class:`CCompiler` or one of its subclasses directly - use the + :func:`distutils.CCompiler.new_compiler` factory function instead. + + The following methods allow you to manually alter compiler options for the + instance of the Compiler class. + + + .. method:: CCompiler.add_include_dir(dir) + + Add *dir* to the list of directories that will be searched for header files. + The compiler is instructed to search directories in the order in which they are + supplied by successive calls to :meth:`add_include_dir`. + + + .. method:: CCompiler.set_include_dirs(dirs) + + Set the list of directories that will be searched to *dirs* (a list of strings). + Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to + :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`. + This does not affect any list of standard include directories that the compiler + may search by default. + + + .. method:: CCompiler.add_library(libname) + + Add *libname* to the list of libraries that will be included in all links driven + by this compiler object. Note that *libname* should \*not\* be the name of a + file containing a library, but the name of the library itself: the actual + filename will be inferred by the linker, the compiler, or the compiler class + (depending on the platform). + + The linker will be instructed to link against libraries in the order they were + supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly + valid to duplicate library names; the linker will be instructed to link against + libraries as many times as they are mentioned. + + + .. method:: CCompiler.set_libraries(libnames) + + Set the list of libraries to be included in all links driven by this compiler + object to *libnames* (a list of strings). This does not affect any standard + system libraries that the linker may include by default. + + + .. method:: CCompiler.add_library_dir(dir) + + Add *dir* to the list of directories that will be searched for libraries + specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be + instructed to search for libraries in the order they are supplied to + :meth:`add_library_dir` and/or :meth:`set_library_dirs`. + + + .. method:: CCompiler.set_library_dirs(dirs) + + Set the list of library search directories to *dirs* (a list of strings). This + does not affect any standard library search path that the linker may search by + default. + + + .. method:: CCompiler.add_runtime_library_dir(dir) + + Add *dir* to the list of directories that will be searched for shared libraries + at runtime. + + + .. method:: CCompiler.set_runtime_library_dirs(dirs) + + Set the list of directories to search for shared libraries at runtime to *dirs* + (a list of strings). This does not affect any standard search path that the + runtime linker may search by default. + + + .. method:: CCompiler.define_macro(name[, value=None]) + + Define a preprocessor macro for all compilations driven by this compiler object. + The optional parameter *value* should be a string; if it is not supplied, then + the macro will be defined without an explicit value and the exact outcome + depends on the compiler used (XXX true? does ANSI say anything about this?) + + + .. method:: CCompiler.undefine_macro(name) + + Undefine a preprocessor macro for all compilations driven by this compiler + object. If the same macro is defined by :meth:`define_macro` and + undefined by :meth:`undefine_macro` the last call takes precedence + (including multiple redefinitions or undefinitions). If the macro is + redefined/undefined on a per-compilation basis (ie. in the call to + :meth:`compile`), then that takes precedence. + + + .. method:: CCompiler.add_link_object(object) + + Add *object* to the list of object files (or analogues, such as explicitly named + library files or the output of "resource compilers") to be included in every + link driven by this compiler object. + + + .. method:: CCompiler.set_link_objects(objects) + + Set the list of object files (or analogues) to be included in every link to + *objects*. This does not affect any standard object files that the linker may + include by default (such as system libraries). + + The following methods implement methods for autodetection of compiler options, + providing some functionality similar to GNU :program:`autoconf`. + + + .. method:: CCompiler.detect_language(sources) + + Detect the language of a given file, or list of files. Uses the instance + attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a + list) to do the job. + + + .. method:: CCompiler.find_library_file(dirs, lib[, debug=0]) + + Search the specified list of directories for a static or shared library file + *lib* and return the full path to that file. If *debug* is true, look for a + debugging version (if that makes sense on the current platform). Return + ``None`` if *lib* wasn't found in any of the specified directories. + + + .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None]) + + Return a boolean indicating whether *funcname* is supported on the current + platform. The optional arguments can be used to augment the compilation + environment by providing additional include files and paths and libraries and + paths. + + + .. method:: CCompiler.library_dir_option(dir) + + Return the compiler option to add *dir* to the list of directories searched for + libraries. + + + .. method:: CCompiler.library_option(lib) + + Return the compiler option to add *dir* to the list of libraries linked into the + shared library or executable. + + + .. method:: CCompiler.runtime_library_dir_option(dir) + + Return the compiler option to add *dir* to the list of directories searched for + runtime libraries. + + + .. method:: CCompiler.set_executables(**args) + + Define the executables (and options for them) that will be run to perform the + various stages of compilation. The exact set of executables that may be + specified here depends on the compiler class (via the 'executables' class + attribute), but most will have: + + +--------------+------------------------------------------+ + | attribute | description | + +==============+==========================================+ + | *compiler* | the C/C++ compiler | + +--------------+------------------------------------------+ + | *linker_so* | linker used to create shared objects and | + | | libraries | + +--------------+------------------------------------------+ + | *linker_exe* | linker used to create binary executables | + +--------------+------------------------------------------+ + | *archiver* | static library creator | + +--------------+------------------------------------------+ + + On platforms with a command-line (Unix, DOS/Windows), each of these is a string + that will be split into executable name and (optional) list of arguments. + (Splitting the string is done similarly to how Unix shells operate: words are + delimited by spaces, but quotes and backslashes can override this. See + :func:`distutils.util.split_quoted`.) + + The following methods invoke stages in the build process. + + + .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None]) + + Compile one or more source files. Generates object files (e.g. transforms a + :file:`.c` file to a :file:`.o` file.) + + *sources* must be a list of filenames, most likely C/C++ files, but in reality + anything that can be handled by a particular compiler and compiler class (eg. + :class:`MSVCCompiler` can handle resource files in *sources*). Return a list of + object filenames, one per source filename in *sources*. Depending on the + implementation, not all source files will necessarily be compiled, but all + corresponding object filenames will be returned. + + If *output_dir* is given, object files will be put under it, while retaining + their original path component. That is, :file:`foo/bar.c` normally compiles to + :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then + it would compile to :file:`build/foo/bar.o`. + + *macros*, if given, must be a list of macro definitions. A macro definition is + either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines + a macro; if the value is ``None``, the macro is defined without an explicit + value. The 1-tuple case undefines a macro. Later + definitions/redefinitions/undefinitions take precedence. + + *include_dirs*, if given, must be a list of strings, the directories to add to + the default include file search path for this compilation only. + + *debug* is a boolean; if true, the compiler will be instructed to output debug + symbols in (or alongside) the object file(s). + + *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms + that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most + likely lists of strings: extra command-line arguments to prepend/append to the + compiler command line. On other platforms, consult the implementation class + documentation. In any event, they are intended as an escape hatch for those + occasions when the abstract compiler framework doesn't cut the mustard. + + *depends*, if given, is a list of filenames that all targets depend on. If a + source file is older than any file in depends, then the source file will be + recompiled. This supports dependency tracking, but only at a coarse + granularity. + + Raises :exc:`CompileError` on failure. + + + .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None]) + + Link a bunch of stuff together to create a static library file. The "bunch of + stuff" consists of the list of object files supplied as *objects*, the extra + object files supplied to :meth:`add_link_object` and/or + :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or + :meth:`set_libraries`, and the libraries supplied as *libraries* (if any). + + *output_libname* should be a library name, not a filename; the filename will be + inferred from the library name. *output_dir* is the directory where the library + file will be put. XXX defaults to what? + + *debug* is a boolean; if true, debugging information will be included in the + library (note that on most platforms, it is the compile step where this matters: + the *debug* flag is included here just for consistency). + + *target_lang* is the target language for which the given objects are being + compiled. This allows specific linkage time treatment of certain languages. + + Raises :exc:`LibError` on failure. + + + .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) + + Link a bunch of stuff together to create an executable or shared library file. + + The "bunch of stuff" consists of the list of object files supplied as *objects*. + *output_filename* should be a filename. If *output_dir* is supplied, + *output_filename* is relative to it (i.e. *output_filename* can provide + directory components if needed). + + *libraries* is a list of libraries to link against. These are library names, + not filenames, since they're translated into filenames in a platform-specific + way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on + DOS/Windows). However, they can include a directory component, which means the + linker will look in that specific directory rather than searching all the normal + locations. + + *library_dirs*, if supplied, should be a list of directories to search for + libraries that were specified as bare library names (ie. no directory + component). These are on top of the system default and those supplied to + :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs* + is a list of directories that will be embedded into the shared library and used + to search for other shared libraries that \*it\* depends on at run-time. (This + may only be relevant on Unix.) + + *export_symbols* is a list of symbols that the shared library will export. + (This appears to be relevant only on Windows.) + + *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the + slight distinction that it actually matters on most platforms (as opposed to + :meth:`create_static_lib`, which includes a *debug* flag mostly for form's + sake). + + *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of + course that they supply command-line arguments for the particular linker being + used). + + *target_lang* is the target language for which the given objects are being + compiled. This allows specific linkage time treatment of certain languages. + + Raises :exc:`LinkError` on failure. + + + .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None]) + + Link an executable. *output_progname* is the name of the file executable, while + *objects* are a list of object filenames to link in. Other arguments are as for + the :meth:`link` method. + + + .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) + + Link a shared library. *output_libname* is the name of the output library, + while *objects* is a list of object filenames to link in. Other arguments are + as for the :meth:`link` method. + + + .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) + + Link a shared object. *output_filename* is the name of the shared object that + will be created, while *objects* is a list of object filenames to link in. + Other arguments are as for the :meth:`link` method. + + + .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None]) + + Preprocess a single C/C++ source file, named in *source*. Output will be written + to file named *output_file*, or *stdout* if *output_file* not supplied. + *macros* is a list of macro definitions as for :meth:`compile`, which will + augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`. + *include_dirs* is a list of directory names that will be added to the default + list, in the same way as :meth:`add_include_dir`. + + Raises :exc:`PreprocessError` on failure. + + The following utility methods are defined by the :class:`CCompiler` class, for + use by the various concrete subclasses. + + + .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir='']) + + Returns the filename of the executable for the given *basename*. Typically for + non-Windows platforms this is the same as the basename, while Windows will get + a :file:`.exe` added. + + + .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir='']) + + Returns the filename for the given library name on the current platform. On Unix + a library with *lib_type* of ``'static'`` will typically be of the form + :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form + :file:`liblibname.so`. + + + .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir='']) + + Returns the name of the object files for the given source files. + *source_filenames* should be a list of filenames. + + + .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir='']) + + Returns the name of a shared object file for the given file name *basename*. + + + .. method:: CCompiler.execute(func, args[, msg=None, level=1]) + + Invokes :func:`distutils.util.execute` This method invokes a Python function + *func* with the given arguments *args*, after logging and taking into account + the *dry_run* flag. XXX see also. + + + .. method:: CCompiler.spawn(cmd) + + Invokes :func:`distutils.util.spawn`. This invokes an external process to run + the given command. XXX see also. + + + .. method:: CCompiler.mkpath(name[, mode=511]) + + Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any + missing ancestor directories. XXX see also. + + + .. method:: CCompiler.move_file(src, dst) + + Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. XXX see + also. + + + .. method:: CCompiler.announce(msg[, level=1]) + + Write a message using :func:`distutils.log.debug`. XXX see also. + + + .. method:: CCompiler.warn(msg) + + Write a warning message *msg* to standard error. + + + .. method:: CCompiler.debug_print(msg) + + If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to + standard output, otherwise do nothing. + +.. % \subsection{Compiler-specific modules} +.. % +.. % The following modules implement concrete subclasses of the abstract +.. % \class{CCompiler} class. They should not be instantiated directly, but should +.. % be created using \function{distutils.ccompiler.new_compiler()} factory +.. % function. + + +:mod:`distutils.unixccompiler` --- Unix C Compiler +================================================== + +.. module:: distutils.unixccompiler + :synopsis: UNIX C Compiler + + +This module provides the :class:`UnixCCompiler` class, a subclass of +:class:`CCompiler` that handles the typical Unix-style command-line C compiler: + +* macros defined with :option:`-Dname[=value]` + +* macros undefined with :option:`-Uname` + +* include search directories specified with :option:`-Idir` + +* libraries specified with :option:`-llib` + +* library search directories specified with :option:`-Ldir` + +* compile handled by :program:`cc` (or similar) executable with :option:`-c` + option: compiles :file:`.c` to :file:`.o` + +* link static library handled by :program:`ar` command (possibly with + :program:`ranlib`) + +* link shared library handled by :program:`cc` :option:`-shared` + + +:mod:`distutils.msvccompiler` --- Microsoft Compiler +==================================================== + +.. module:: distutils.msvccompiler + :synopsis: Microsoft Compiler + + +This module provides :class:`MSVCCompiler`, an implementation of the abstract +:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension +modules need to be compiled with the same compiler that was used to compile +Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python +2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium +binaries are created using the Platform SDK. + +:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on +its own. To override this choice, the environment variables *DISTUTILS_USE_SDK* +and *MSSdk* must be both set. *MSSdk* indicates that the current environment has +been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables +had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates +that the distutils user has made an explicit choice to override the compiler +selection by :class:`MSVCCompiler`. + + +:mod:`distutils.bcppcompiler` --- Borland Compiler +================================================== + +.. module:: distutils.bcppcompiler + + +This module provides :class:`BorlandCCompiler`, an subclass of the abstract +:class:`CCompiler` class for the Borland C++ compiler. + + +:mod:`distutils.cygwincompiler` --- Cygwin Compiler +=================================================== + +.. module:: distutils.cygwinccompiler + + +This module provides the :class:`CygwinCCompiler` class, a subclass of +:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to +Windows. It also contains the Mingw32CCompiler class which handles the mingw32 +port of GCC (same as cygwin in no-cygwin mode). + + +:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler +=================================================== + +.. module:: distutils.emxccompiler + :synopsis: OS/2 EMX Compiler support + + +This module provides the EMXCCompiler class, a subclass of +:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2. + + +:mod:`distutils.mwerkscompiler` --- Metrowerks CodeWarrior support +================================================================== + +.. module:: distutils.mwerkscompiler + :synopsis: Metrowerks CodeWarrior support + + +Contains :class:`MWerksCompiler`, an implementation of the abstract +:class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X +Macintosh. Needs work to support CW on Windows or Mac OS X. + +.. % \subsection{Utility modules} +.. % +.. % The following modules all provide general utility functions. They haven't +.. % all been documented yet. + + +:mod:`distutils.archive_util` --- Archiving utilities +====================================================== + +.. module:: distutils.archive_util + :synopsis: Utility functions for creating archive files (tarballs, zip files, ...) + + +This module provides a few functions for creating archive files, such as +tarballs or zipfiles. + + +.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0]) + + Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of + the file to create, minus any format-specific extension; *format* is the + archive format: one of ``zip``, ``tar``, ``ztar``, or ``gztar``. *root_dir* is + a directory that will be the root directory of the archive; ie. we typically + ``chdir`` into *root_dir* before creating the archive. *base_dir* is the + directory where we start archiving from; ie. *base_dir* will be the common + prefix of all files and directories in the archive. *root_dir* and *base_dir* + both default to the current directory. Returns the name of the archive file. + + .. warning:: + + This should be changed to support bz2 files + + +.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) + + 'Create an (optional compressed) archive as a tar file from all files in and + under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``, + ``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named + by *compress* must be on the default program search path, so this is probably + Unix-specific. The output tar file will be named :file:`base_dir.tar`, + possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2` + or :file:`.Z`). Return the output filename. + + .. warning:: + + This should be replaced with calls to the :mod:`tarfile` module. + + +.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) + + Create a zip file from all files in and under *base_dir*. The output zip file + will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python + module (if available) or the InfoZIP :file:`zip` utility (if installed and + found on the default search path). If neither tool is available, raises + :exc:`DistutilsExecError`. Returns the name of the output zip file. + + +:mod:`distutils.dep_util` --- Dependency checking +================================================= + +.. module:: distutils.dep_util + :synopsis: Utility functions for simple dependency checking + + +This module provides functions for performing simple, timestamp-based +dependency of files and groups of files; also, functions based entirely on such +timestamp dependency analysis. + + +.. function:: newer(source, target) + + Return true if *source* exists and is more recently modified than *target*, or + if *source* exists and *target* doesn't. Return false if both exist and *target* + is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if + *source* does not exist. + + +.. function:: newer_pairwise(sources, targets) + + Walk two filename lists in parallel, testing if each source is newer than its + corresponding target. Return a pair of lists (*sources*, *targets*) where + source is newer than target, according to the semantics of :func:`newer` + + .. % % equivalent to a listcomp... + + +.. function:: newer_group(sources, target[, missing='error']) + + Return true if *target* is out-of-date with respect to any file listed in + *sources* In other words, if *target* exists and is newer than every file in + *sources*, return false; otherwise return true. *missing* controls what we do + when a source file is missing; the default (``'error'``) is to blow up with an + :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently + drop any missing source files; if it is ``'newer'``, any missing source files + make us assume that *target* is out-of-date (this is handy in "dry-run" mode: + it'll make you pretend to carry out commands that wouldn't work because inputs + are missing, but that doesn't matter because you're not actually going to run + the commands). + + +:mod:`distutils.dir_util` --- Directory tree operations +======================================================= + +.. module:: distutils.dir_util + :synopsis: Utility functions for operating on directories and directory trees + + +This module provides functions for operating on directories and trees of +directories. + + +.. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0]) + + Create a directory and any missing ancestor directories. If the directory + already exists (or if *name* is the empty string, which means the current + directory, which of course exists), then do nothing. Raise + :exc:`DistutilsFileError` if unable to create some directory along the way (eg. + some sub-path exists, but is a file rather than a directory). If *verbose* is + true, print a one-line summary of each mkdir to stdout. Return the list of + directories actually created. + + +.. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0]) + + Create all the empty directories under *base_dir* needed to put *files* there. + *base_dir* is just the a name of a directory which doesn't necessarily exist + yet; *files* is a list of filenames to be interpreted relative to *base_dir*. + *base_dir* + the directory portion of every file in *files* will be created if + it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for + :func:`mkpath`. + + +.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0]) + + Copy an entire directory tree *src* to a new location *dst*. Both *src* and + *dst* must be directory names. If *src* is not a directory, raise + :exc:`DistutilsFileError`. If *dst* does not exist, it is created with + :func:`mkpath`. The end result of the copy is that every file in *src* is + copied to *dst*, and directories under *src* are recursively copied to *dst*. + Return the list of files that were copied or might have been copied, using their + output name. The return value is unaffected by *update* or *dry_run*: it is + simply the list of all files under *src*, with the names changed to be under + *dst*. + + *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in + :mod:`distutils.file_util`; note that they only apply to regular files, not to + directories. If *preserve_symlinks* is true, symlinks will be copied as + symlinks (on platforms that support them!); otherwise (the default), the + destination of the symlink will be copied. *update* and *verbose* are the same + as for :func:`copy_file`. + + +.. function:: remove_tree(directory[, verbose=0, dry_run=0]) + + Recursively remove *directory* and all files and directories underneath it. Any + errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is + true). + +**\*\*** Some of this could be replaced with the shutil module? **\*\*** + + +:mod:`distutils.file_util` --- Single file operations +===================================================== + +.. module:: distutils.file_util + :synopsis: Utility functions for operating on single files + + +This module contains some utility functions for operating on individual files. + + +.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0]) + + Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there + with the same name; otherwise, it must be a filename. (If the file exists, it + will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the + file's mode (type and permission bits, or whatever is analogous on the + current platform) is copied. If *preserve_times* is true (the default), the + last-modified and last-access times are copied as well. If *update* is true, + *src* will only be copied if *dst* does not exist, or if *dst* does exist but + is older than *src*. + + *link* allows you to make hard links (using :func:`os.link`) or symbolic links + (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or + ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link* + on systems that don't support it: :func:`copy_file` doesn't check if hard or + symbolic linking is available. It uses :func:`_copy_file_contents` to copy file + contents. + + Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the + output file, and *copied* is true if the file was copied (or would have been + copied, if *dry_run* true). + + .. % XXX if the destination file already exists, we clobber it if + .. % copying, but blow up if linking. Hmmm. And I don't know what + .. % macostools.copyfile() does. Should definitely be consistent, and + .. % should probably blow up if destination exists and we would be + .. % changing it (ie. it's not already a hard/soft link to src OR + .. % (not update) and (src newer than dst)). + + +.. function:: move_file(src, dst[, verbose, dry_run]) + + Move file *src* to *dst*. If *dst* is a directory, the file will be moved into + it with the same name; otherwise, *src* is just renamed to *dst*. Returns the + new full name of the file. + + .. warning:: + + Handles cross-device moves on Unix using :func:`copy_file`. What about other + systems??? + + +.. function:: write_file(filename, contents) + + Create a file called *filename* and write *contents* (a sequence of strings + without line terminators) to it. + + +:mod:`distutils.util` --- Miscellaneous other utility functions +=============================================================== + +.. module:: distutils.util + :synopsis: Miscellaneous other utility functions + + +This module contains other assorted bits and pieces that don't fit into any +other utility module. + + +.. function:: get_platform() + + Return a string that identifies the current platform. This is used mainly to + distinguish platform-specific build directories and platform-specific built + distributions. Typically includes the OS name and version and the architecture + (as supplied by 'os.uname()'), although the exact information included depends + on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only + runs on SGI hardware), but for Linux the kernel version isn't particularly + important. + + Examples of returned values: + + * ``linux-i586`` + * ``linux-alpha`` + * ``solaris-2.6-sun4u`` + * ``irix-5.3`` + * ``irix64-6.2`` + + For non-POSIX platforms, currently just returns ``sys.platform``. + + .. % XXX isn't this also provided by some other non-distutils module? + + +.. function:: convert_path(pathname) + + Return 'pathname' as a name that will work on the native filesystem, i.e. split + it on '/' and put it back together again using the current directory separator. + Needed because filenames in the setup script are always supplied in Unix style, + and have to be converted to the local convention before we can actually use them + in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if + *pathname* either starts or ends with a slash. + + +.. function:: change_root(new_root, pathname) + + Return *pathname* with *new_root* prepended. If *pathname* is relative, this is + equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making + *pathname* relative and then joining the two, which is tricky on DOS/Windows. + + +.. function:: check_environ() + + Ensure that 'os.environ' has all the environment variables we guarantee that + users can use in config files, command-line options, etc. Currently this + includes: + + * :envvar:`HOME` - user's home directory (Unix only) + * :envvar:`PLAT` - description of the current platform, including hardware and + OS (see :func:`get_platform`) + + +.. function:: subst_vars(s, local_vars) + + Perform shell/Perl-style variable substitution on *s*. Every occurrence of + ``$`` followed by a name is considered a variable, and variable is substituted + by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's + not in *local_vars*. *os.environ* is first checked/augmented to guarantee that + it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError` + for any variables not found in either *local_vars* or ``os.environ``. + + Note that this is not a fully-fledged string interpolation function. A valid + ``$variable`` can consist only of upper and lower case letters, numbers and an + underscore. No { } or ( ) style quoting is available. + + +.. function:: grok_environment_error(exc[, prefix='error: ']) + + Generate a useful error message from an :exc:`EnvironmentError` (:exc:`IOError` + or :exc:`OSError`) exception object. Handles Python 1.5.1 and later styles, + and does what it can to deal with exception objects that don't have a filename + (which happens when the error is due to a two-file operation, such as + :func:`rename` or :func:`link`). Returns the error message as a string + prefixed with *prefix*. + + +.. function:: split_quoted(s) + + Split a string up according to Unix shell-like rules for quotes and backslashes. + In short: words are delimited by spaces, as long as those spaces are not escaped + by a backslash, or inside a quoted string. Single and double quotes are + equivalent, and the quote characters can be backslash-escaped. The backslash is + stripped from any two-character escape sequence, leaving only the escaped + character. The quote characters are stripped from any quoted string. Returns a + list of words. + + .. % Should probably be moved into the standard library. + + +.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0]) + + Perform some action that affects the outside world (for instance, writing to the + filesystem). Such actions are special because they are disabled by the + *dry_run* flag. This method takes care of all that bureaucracy for you; all + you have to do is supply the function to call and an argument tuple for it (to + embody the "external action" being performed), and an optional message to print. + + +.. function:: strtobool(val) + + Convert a string representation of truth to true (1) or false (0). + + True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values + are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises + :exc:`ValueError` if *val* is anything else. + + +.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None]) + + Byte-compile a collection of Python source files to either :file:`.pyc` or + :file:`.pyo` files in the same directory. *py_files* is a list of files to + compile; any files that don't end in :file:`.py` are silently skipped. + *optimize* must be one of the following: + + * ``0`` - don't optimize (generate :file:`.pyc`) + * ``1`` - normal optimization (like ``python -O``) + * ``2`` - extra optimization (like ``python -OO``) + + If *force* is true, all files are recompiled regardless of timestamps. + + The source filename encoded in each bytecode file defaults to the filenames + listed in *py_files*; you can modify these with *prefix* and *basedir*. + *prefix* is a string that will be stripped off of each source filename, and + *base_dir* is a directory name that will be prepended (after *prefix* is + stripped). You can supply either or both (or neither) of *prefix* and + *base_dir*, as you wish. + + If *dry_run* is true, doesn't actually do anything that would affect the + filesystem. + + Byte-compilation is either done directly in this interpreter process with the + standard :mod:`py_compile` module, or indirectly by writing a temporary script + and executing it. Normally, you should let :func:`byte_compile` figure out to + use direct compilation or not (see the source for details). The *direct* flag + is used by the script generated in indirect mode; unless you know what you're + doing, leave it set to ``None``. + + +.. function:: rfc822_escape(header) + + Return a version of *header* escaped for inclusion in an :rfc:`822` header, by + ensuring there are 8 spaces space after each newline. Note that it does no other + modification of the string. + + .. % this _can_ be replaced + +.. % \subsection{Distutils objects} + + +:mod:`distutils.dist` --- The Distribution class +================================================ + +.. module:: distutils.dist + :synopsis: Provides the Distribution class, which represents the module distribution being + built/installed/distributed + + +This module provides the :class:`Distribution` class, which represents the +module distribution being built/installed/distributed. + + +:mod:`distutils.extension` --- The Extension class +================================================== + +.. module:: distutils.extension + :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup + scripts + + +This module provides the :class:`Extension` class, used to describe C/C++ +extension modules in setup scripts. + +.. % \subsection{Ungrouped modules} +.. % The following haven't been moved into a more appropriate section yet. + + +:mod:`distutils.debug` --- Distutils debug mode +=============================================== + +.. module:: distutils.debug + :synopsis: Provides the debug flag for distutils + + +This module provides the DEBUG flag. + + +:mod:`distutils.errors` --- Distutils exceptions +================================================ + +.. module:: distutils.errors + :synopsis: Provides standard distutils exceptions + + +Provides exceptions used by the Distutils modules. Note that Distutils modules +may raise standard exceptions; in particular, SystemExit is usually raised for +errors that are obviously the end-user's fault (eg. bad command-line arguments). + +This module is safe to use in ``from ... import *`` mode; it only exports +symbols whose names start with ``Distutils`` and end with ``Error``. + + +:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module +=========================================================================== + +.. module:: distutils.fancy_getopt + :synopsis: Additional getopt functionality + + +This module provides a wrapper around the standard :mod:`getopt` module that +provides the following additional features: + +* short and long options are tied together + +* options have help strings, so :func:`fancy_getopt` could potentially create a + complete usage summary + +* options set attributes of a passed-in object + +* boolean options can have "negative aliases" --- eg. if :option:`--quiet` is + the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the + command line sets *verbose* to false. + +**\*\*** Should be replaced with :mod:`optik` (which is also now known as +:mod:`optparse` in Python 2.3 and later). **\*\*** + + +.. function:: fancy_getopt(options, negative_opt, object, args) + + Wrapper function. *options* is a list of ``(long_option, short_option, + help_string)`` 3-tuples as described in the constructor for + :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names + to option names, both the key and value should be in the *options* list. + *object* is an object which will be used to store values (see the :meth:`getopt` + method of the :class:`FancyGetopt` class). *args* is the argument list. Will use + ``sys.argv[1:]`` if you pass ``None`` as *args*. + + +.. function:: wrap_text(text, width) + + Wraps *text* to less than *width* wide. + + .. warning:: + + Should be replaced with :mod:`textwrap` (which is available in Python 2.3 and + later). + + +.. class:: FancyGetopt([option_table=None]) + + The option_table is a list of 3-tuples: ``(long_option, short_option, + help_string)`` + + If an option takes an argument, its *long_option* should have ``'='`` appended; + *short_option* should just be a single character, no ``':'`` in any case. + *short_option* should be ``None`` if a *long_option* doesn't have a + corresponding *short_option*. All option tuples must have long options. + +The :class:`FancyGetopt` class provides the following methods: + + +.. method:: FancyGetopt.getopt([args=None, object=None]) + + Parse command-line options in args. Store as attributes on *object*. + + If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is + ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores + option values there, and returns a tuple ``(args, object)``. If *object* is + supplied, it is modified in place and :func:`getopt` just returns *args*; in + both cases, the returned *args* is a modified copy of the passed-in *args* list, + which is left untouched. + + .. % and args returned are? + + +.. method:: FancyGetopt.get_option_order() + + Returns the list of ``(option, value)`` tuples processed by the previous run of + :meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called + yet. + + +.. method:: FancyGetopt.generate_help([header=None]) + + Generate help text (a list of strings, one per suggested line of output) from + the option table for this :class:`FancyGetopt` object. + + If supplied, prints the supplied *header* at the top of the help. + + +:mod:`distutils.filelist` --- The FileList class +================================================ + +.. module:: distutils.filelist + :synopsis: The FileList class, used for poking about the file system and building lists of + files. + + +This module provides the :class:`FileList` class, used for poking about the +filesystem and building lists of files. + + +:mod:`distutils.log` --- Simple PEP 282-style logging +===================================================== + +.. module:: distutils.log + :synopsis: A simple logging mechanism, 282-style + + +.. warning:: + + Should be replaced with standard :mod:`logging` module. + +.. % \subsubsection{\module{} --- } +.. % \declaremodule{standard}{distutils.magic} +.. % \modulesynopsis{ } + + +:mod:`distutils.spawn` --- Spawn a sub-process +============================================== + +.. module:: distutils.spawn + :synopsis: Provides the spawn() function + + +This module provides the :func:`spawn` function, a front-end to various +platform-specific functions for launching another program in a sub-process. +Also provides :func:`find_executable` to search the path for a given executable +name. + + +:mod:`distutils.sysconfig` --- System configuration information +=============================================================== + +.. module:: distutils.sysconfig + :synopsis: Low-level access to configuration information of the Python interpreter. +.. moduleauthor:: Fred L. Drake, Jr. +.. moduleauthor:: Greg Ward +.. sectionauthor:: Fred L. Drake, Jr. + + +The :mod:`distutils.sysconfig` module provides access to Python's low-level +configuration information. The specific configuration variables available +depend heavily on the platform and configuration. The specific variables depend +on the build process for the specific version of Python being run; the variables +are those found in the :file:`Makefile` and configuration header that are +installed with Python on Unix systems. The configuration header is called +:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` +for earlier versions of Python. + +Some additional functions are provided which perform some useful manipulations +for other parts of the :mod:`distutils` package. + + +.. data:: PREFIX + + The result of ``os.path.normpath(sys.prefix)``. + + +.. data:: EXEC_PREFIX + + The result of ``os.path.normpath(sys.exec_prefix)``. + + +.. function:: get_config_var(name) + + Return the value of a single variable. This is equivalent to + ``get_config_vars().get(name)``. + + +.. function:: get_config_vars(...) + + Return a set of variable definitions. If there are no arguments, this returns a + dictionary mapping names of configuration variables to values. If arguments are + provided, they should be strings, and the return value will be a sequence giving + the associated values. If a given name does not have a corresponding value, + ``None`` will be included for that variable. + + +.. function:: get_config_h_filename() + + Return the full path name of the configuration header. For Unix, this will be + the header generated by the :program:`configure` script; for other platforms the + header will have been supplied directly by the Python source distribution. The + file is a platform-specific text file. + + +.. function:: get_makefile_filename() + + Return the full path name of the :file:`Makefile` used to build Python. For + Unix, this will be a file generated by the :program:`configure` script; the + meaning for other platforms will vary. The file is a platform-specific text + file, if it exists. This function is only useful on POSIX platforms. + + +.. function:: get_python_inc([plat_specific[, prefix]]) + + Return the directory for either the general or platform-dependent C include + files. If *plat_specific* is true, the platform-dependent include directory is + returned; if false or omitted, the platform-independent directory is returned. + If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. + + +.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) + + Return the directory for either the general or platform-dependent library + installation. If *plat_specific* is true, the platform-dependent include + directory is returned; if false or omitted, the platform-independent directory + is returned. If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. If *standard_lib* is true, the directory for the + standard library is returned rather than the directory for the installation of + third-party extensions. + +The following function is only intended for use within the :mod:`distutils` +package. + + +.. function:: customize_compiler(compiler) + + Do any platform-specific customization of a + :class:`distutils.ccompiler.CCompiler` instance. + + This function is only needed on Unix at this time, but should be called + consistently to support forward-compatibility. It inserts the information that + varies across Unix flavors and is stored in Python's :file:`Makefile`. This + information includes the selected compiler, compiler and linker options, and the + extension used by the linker for shared objects. + +This function is even more special-purpose, and should only be used from +Python's own build procedures. + + +.. function:: set_python_build() + + Inform the :mod:`distutils.sysconfig` module that it is being used as part of + the build process for Python. This changes a lot of relative locations for + files, allowing them to be located in the build area rather than in an installed + Python. + + +:mod:`distutils.text_file` --- The TextFile class +================================================= + +.. module:: distutils.text_file + :synopsis: provides the TextFile class, a simple interface to text files + + +This module provides the :class:`TextFile` class, which gives an interface to +text files that (optionally) takes care of stripping comments, ignoring blank +lines, and joining lines with backslashes. + + +.. class:: TextFile([filename=None, file=None, **options]) + + This class provides a file-like object that takes care of all the things you + commonly want to do when processing a text file that has some line-by-line + syntax: strip comments (as long as ``#`` is your comment character), skip blank + lines, join adjacent lines by escaping the newline (ie. backslash at end of + line), strip leading and/or trailing whitespace. All of these are optional and + independently controllable. + + The class provides a :meth:`warn` method so you can generate warning messages + that report physical line number, even if the logical line in question spans + multiple physical lines. Also provides :meth:`unreadline` for implementing + line-at-a-time lookahead. + + :class:`TextFile` instances are create with either *filename*, *file*, or both. + :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a + string, and *file* a file object (or something that provides :meth:`readline` + and :meth:`close` methods). It is recommended that you supply at least + *filename*, so that :class:`TextFile` can include it in warning messages. If + *file* is not supplied, :class:`TextFile` creates its own using the + :func:`open` built-in function. + + The options are all boolean, and affect the values returned by :meth:`readline` + + +------------------+--------------------------------+---------+ + | option name | description | default | + +==================+================================+=========+ + | *strip_comments* | strip from ``'#'`` to end-of- | true | + | | line, as well as any | | + | | whitespace leading up to the | | + | | ``'#'``\ ---unless it is | | + | | escaped by a backslash | | + +------------------+--------------------------------+---------+ + | *lstrip_ws* | strip leading whitespace from | false | + | | each line before returning it | | + +------------------+--------------------------------+---------+ + | *rstrip_ws* | strip trailing whitespace | true | + | | (including line terminator!) | | + | | from each line before | | + | | returning it. | | + +------------------+--------------------------------+---------+ + | *skip_blanks* | skip lines that are empty | true | + | | \*after\* stripping comments | | + | | and whitespace. (If both | | + | | lstrip_ws and rstrip_ws are | | + | | false, then some lines may | | + | | consist of solely whitespace: | | + | | these will \*not\* be skipped, | | + | | even if *skip_blanks* is | | + | | true.) | | + +------------------+--------------------------------+---------+ + | *join_lines* | if a backslash is the last | false | + | | non-newline character on a | | + | | line after stripping comments | | + | | and whitespace, join the | | + | | following line to it to form | | + | | one logical line; if N | | + | | consecutive lines end with a | | + | | backslash, then N+1 physical | | + | | lines will be joined to form | | + | | one logical line. | | + +------------------+--------------------------------+---------+ + | *collapse_join* | strip leading whitespace from | false | + | | lines that are joined to their | | + | | predecessor; only matters if | | + | | ``(join_lines and not | | + | | lstrip_ws)`` | | + +------------------+--------------------------------+---------+ + + Note that since *rstrip_ws* can strip the trailing newline, the semantics of + :meth:`readline` must differ from those of the builtin file object's + :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for + end-of-file: an empty string might just be a blank line (or an all-whitespace + line), if *rstrip_ws* is true but *skip_blanks* is not. + + + .. method:: TextFile.open(filename) + + Open a new file *filename*. This overrides any *file* or *filename* constructor + arguments. + + + .. method:: TextFile.close() + + Close the current file and forget everything we know about it (including the + filename and the current line number). + + + .. method:: TextFile.warn(msg[,line=None]) + + Print (to stderr) a warning message tied to the current logical line in the + current file. If the current logical line in the file spans multiple physical + lines, the warning refers to the whole range, such as ``"lines 3-5"``. If + *line* is supplied, it overrides the current line number; it may be a list or + tuple to indicate a range of physical lines, or an integer for a single + physical line. + + + .. method:: TextFile.readline() + + Read and return a single logical line from the current file (or from an internal + buffer if lines have previously been "unread" with :meth:`unreadline`). If the + *join_lines* option is true, this may involve reading multiple physical lines + concatenated into a single string. Updates the current line number, so calling + :meth:`warn` after :meth:`readline` emits a warning about the physical line(s) + just read. Returns ``None`` on end-of-file, since the empty string can occur + if *rstrip_ws* is true but *strip_blanks* is not. + + + .. method:: TextFile.readlines() + + Read and return the list of all logical lines remaining in the current file. + This updates the current line number to the last line of the file. + + + .. method:: TextFile.unreadline(line) + + Push *line* (a string) onto an internal buffer that will be checked by future + :meth:`readline` calls. Handy for implementing a parser with line-at-a-time + lookahead. Note that lines that are "unread" with :meth:`unreadline` are not + subsequently re-cleansed (whitespace stripped, or whatever) when read with + :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call + to :meth:`readline`, the lines will be returned most in most recent first order. + + +:mod:`distutils.version` --- Version number classes +=================================================== + +.. module:: distutils.version + :synopsis: implements classes that represent module version numbers. + + +.. % todo +.. % \section{Distutils Commands} +.. % +.. % This part of Distutils implements the various Distutils commands, such +.. % as \code{build}, \code{install} \&c. Each command is implemented as a +.. % separate module, with the command name as the name of the module. + + +:mod:`distutils.cmd` --- Abstract base class for Distutils commands +=================================================================== + +.. module:: distutils.cmd + :synopsis: This module provides the abstract base class Command. This class is subclassed + by the modules in the distutils.command subpackage. + + +This module supplies the abstract base class :class:`Command`. + + +.. class:: Command(dist) + + Abstract base class for defining command classes, the "worker bees" of the + Distutils. A useful analogy for command classes is to think of them as + subroutines with local variables called *options*. The options are declared in + :meth:`initialize_options` and defined (given their final values) in + :meth:`finalize_options`, both of which must be defined by every command class. + The distinction between the two is necessary because option values might come + from the outside world (command line, config file, ...), and any options + dependent on other options must be computed after these outside influences have + been processed --- hence :meth:`finalize_options`. The body of the subroutine, + where it does all its work based on the values of its options, is the + :meth:`run` method, which must also be implemented by every command class. + + The class constructor takes a single argument *dist*, a :class:`Distribution` + instance. + + +:mod:`distutils.command` --- Individual Distutils commands +========================================================== + +.. module:: distutils.command + :synopsis: This subpackage contains one module for each standard Distutils command. + + +.. % \subsubsection{Individual Distutils commands} +.. % todo + + +:mod:`distutils.command.bdist` --- Build a binary installer +=========================================================== + +.. module:: distutils.command.bdist + :synopsis: Build a binary installer for a package + + +.. % todo + + +:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers +============================================================================= + +.. module:: distutils.command.bdist_packager + :synopsis: Abstract base class for packagers + + +.. % todo + + +:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer +================================================================ + +.. module:: distutils.command.bdist_dumb + :synopsis: Build a "dumb" installer - a simple archive of files + + +.. % todo + + +:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package +================================================================================= + +.. module:: distutils.command.bdist_msi + :synopsis: Build a binary distribution as a Windows MSI file + + +.. % todo + + +:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM +=========================================================================================== + +.. module:: distutils.command.bdist_rpm + :synopsis: Build a binary distribution as a Redhat RPM and SRPM + + +.. % todo + + +:mod:`distutils.command.bdist_wininst` --- Build a Windows installer +==================================================================== + +.. module:: distutils.command.bdist_wininst + :synopsis: Build a Windows installer + + +.. % todo + + +:mod:`distutils.command.sdist` --- Build a source distribution +============================================================== + +.. module:: distutils.command.sdist + :synopsis: Build a source distribution + + +.. % todo + + +:mod:`distutils.command.build` --- Build all files of a package +=============================================================== + +.. module:: distutils.command.build + :synopsis: Build all files of a package + + +.. % todo + + +:mod:`distutils.command.build_clib` --- Build any C libraries in a package +========================================================================== + +.. module:: distutils.command.build_clib + :synopsis: Build any C libraries in a package + + +.. % todo + + +:mod:`distutils.command.build_ext` --- Build any extensions in a package +======================================================================== + +.. module:: distutils.command.build_ext + :synopsis: Build any extensions in a package + + +.. % todo + + +:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package +=========================================================================== + +.. module:: distutils.command.build_py + :synopsis: Build the .py/.pyc files of a package + + +.. % todo + + +:mod:`distutils.command.build_scripts` --- Build the scripts of a package +========================================================================= + +.. module:: distutils.command.build_scripts + :synopsis: Build the scripts of a package + + +.. % todo + + +:mod:`distutils.command.clean` --- Clean a package build area +============================================================= + +.. module:: distutils.command.clean + :synopsis: Clean a package build area + + +.. % todo + + +:mod:`distutils.command.config` --- Perform package configuration +================================================================= + +.. module:: distutils.command.config + :synopsis: Perform package configuration + + +.. % todo + + +:mod:`distutils.command.install` --- Install a package +====================================================== + +.. module:: distutils.command.install + :synopsis: Install a package + + +.. % todo + + +:mod:`distutils.command.install_data` --- Install data files from a package +=========================================================================== + +.. module:: distutils.command.install_data + :synopsis: Install data files from a package + + +.. % todo + + +:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package +====================================================================================== + +.. module:: distutils.command.install_headers + :synopsis: Install C/C++ header files from a package + + +.. % todo + + +:mod:`distutils.command.install_lib` --- Install library files from a package +============================================================================= + +.. module:: distutils.command.install_lib + :synopsis: Install library files from a package + + +.. % todo + + +:mod:`distutils.command.install_scripts` --- Install script files from a package +================================================================================ + +.. module:: distutils.command.install_scripts + :synopsis: Install script files from a package + + +.. % todo + + +:mod:`distutils.command.register` --- Register a module with the Python Package Index +===================================================================================== + +.. module:: distutils.command.register + :synopsis: Register a module with the Python Package Index + + +The ``register`` command registers the package with the Python Package Index. +This is described in more detail in :pep:`301`. + +.. % todo + + +Creating a new Distutils command +================================ + +This section outlines the steps to create a new Distutils command. + +A new command lives in a module in the :mod:`distutils.command` package. There +is a sample template in that directory called :file:`command_template`. Copy +this file to a new module with the same name as the new command you're +implementing. This module should implement a class with the same name as the +module (and the command). So, for instance, to create the command +``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy +:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit +it so that it's implementing the class :class:`peel_banana`, a subclass of +:class:`distutils.cmd.Command`. + +Subclasses of :class:`Command` must define the following methods. + + +.. method:: Command.initialize_options()(S) + + et default values for all the options that this command supports. Note that + these defaults may be overridden by other commands, by the setup script, by + config files, or by the command-line. Thus, this is not the place to code + dependencies between options; generally, :meth:`initialize_options` + implementations are just a bunch of ``self.foo = None`` assignments. + + +.. method:: Command.finalize_options() + + Set final values for all the options that this command supports. This is + always called as late as possible, ie. after any option assignments from the + command-line or from other commands have been done. Thus, this is the place + to to code option dependencies: if *foo* depends on *bar*, then it is safe to + set *foo* from *bar* as long as *foo* still has the same value it was + assigned in :meth:`initialize_options`. + + +.. method:: Command.run() + + A command's raison d'etre: carry out the action it exists to perform, controlled + by the options initialized in :meth:`initialize_options`, customized by other + commands, the setup script, the command-line, and config files, and finalized in + :meth:`finalize_options`. All terminal output and filesystem interaction should + be done by :meth:`run`. + +*sub_commands* formalizes the notion of a "family" of commands, eg. ``install`` +as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The +parent of a family of commands defines *sub_commands* as a class attribute; it's +a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string +and *predicate* an unbound method, a string or None. *predicate* is a method of +the parent command that determines whether the corresponding command is +applicable in the current situation. (Eg. we ``install_headers`` is only +applicable if we have any C header files to install.) If *predicate* is None, +that command is always applicable. + +*sub_commands* is usually defined at the \*end\* of a class, because predicates +can be unbound methods, so they must already have been defined. The canonical +example is the :command:`install` command. diff --git a/builtdist.rst b/builtdist.rst new file mode 100644 index 0000000000..b40ddeb369 --- /dev/null +++ b/builtdist.rst @@ -0,0 +1,405 @@ +.. _built-dist: + +**************************** +Creating Built Distributions +**************************** + +A "built distribution" is what you're probably used to thinking of either as a +"binary package" or an "installer" (depending on your background). It's not +necessarily binary, though, because it might contain only Python source code +and/or byte-code; and we don't call it a package, because that word is already +spoken for in Python. (And "installer" is a term specific to the world of +mainstream desktop systems.) + +A built distribution is how you make life as easy as possible for installers of +your module distribution: for users of RPM-based Linux systems, it's a binary +RPM; for Windows users, it's an executable installer; for Debian-based Linux +users, it's a Debian package; and so forth. Obviously, no one person will be +able to create built distributions for every platform under the sun, so the +Distutils are designed to enable module developers to concentrate on their +specialty---writing code and creating source distributions---while an +intermediary species called *packagers* springs up to turn source distributions +into built distributions for as many platforms as there are packagers. + +Of course, the module developer could be his own packager; or the packager could +be a volunteer "out there" somewhere who has access to a platform which the +original developer does not; or it could be software periodically grabbing new +source distributions and turning them into built distributions for as many +platforms as the software has access to. Regardless of who they are, a packager +uses the setup script and the :command:`bdist` command family to generate built +distributions. + +As a simple example, if I run the following command in the Distutils source +tree:: + + python setup.py bdist + +then the Distutils builds my module distribution (the Distutils itself in this +case), does a "fake" installation (also in the :file:`build` directory), and +creates the default type of built distribution for my platform. The default +format for built distributions is a "dumb" tar file on Unix, and a simple +executable installer on Windows. (That tar file is considered "dumb" because it +has to be unpacked in a specific location to work.) + +Thus, the above command on a Unix system creates +:file:`Distutils-1.0.{plat}.tar.gz`; unpacking this tarball from the right place +installs the Distutils just as though you had downloaded the source distribution +and run ``python setup.py install``. (The "right place" is either the root of +the filesystem or Python's :file:`{prefix}` directory, depending on the options +given to the :command:`bdist_dumb` command; the default is to make dumb +distributions relative to :file:`{prefix}`.) + +Obviously, for pure Python distributions, this isn't any simpler than just +running ``python setup.py install``\ ---but for non-pure distributions, which +include extensions that would need to be compiled, it can mean the difference +between someone being able to use your extensions or not. And creating "smart" +built distributions, such as an RPM package or an executable installer for +Windows, is far more convenient for users even if your distribution doesn't +include any extensions. + +The :command:`bdist` command has a :option:`--formats` option, similar to the +:command:`sdist` command, which you can use to select the types of built +distribution to generate: for example, :: + + python setup.py bdist --format=zip + +would, when run on a Unix system, create :file:`Distutils-1.0.{plat}.zip`\ +---again, this archive would be unpacked from the root directory to install the +Distutils. + +The available formats for built distributions are: + ++-------------+------------------------------+---------+ +| Format | Description | Notes | ++=============+==============================+=========+ +| ``gztar`` | gzipped tar file | (1),(3) | +| | (:file:`.tar.gz`) | | ++-------------+------------------------------+---------+ +| ``ztar`` | compressed tar file | \(3) | +| | (:file:`.tar.Z`) | | ++-------------+------------------------------+---------+ +| ``tar`` | tar file (:file:`.tar`) | \(3) | ++-------------+------------------------------+---------+ +| ``zip`` | zip file (:file:`.zip`) | \(4) | ++-------------+------------------------------+---------+ +| ``rpm`` | RPM | \(5) | ++-------------+------------------------------+---------+ +| ``pkgtool`` | Solaris :program:`pkgtool` | | ++-------------+------------------------------+---------+ +| ``sdux`` | HP-UX :program:`swinstall` | | ++-------------+------------------------------+---------+ +| ``rpm`` | RPM | \(5) | ++-------------+------------------------------+---------+ +| ``wininst`` | self-extracting ZIP file for | (2),(4) | +| | Windows | | ++-------------+------------------------------+---------+ + +Notes: + +(1) + default on Unix + +(2) + default on Windows + + **\*\*** to-do! **\*\*** + +(3) + requires external utilities: :program:`tar` and possibly one of :program:`gzip`, + :program:`bzip2`, or :program:`compress` + +(4) + requires either external :program:`zip` utility or :mod:`zipfile` module (part + of the standard Python library since Python 1.6) + +(5) + requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm + --version`` to find out which version you have) + +You don't have to use the :command:`bdist` command with the :option:`--formats` +option; you can also use the command that directly implements the format you're +interested in. Some of these :command:`bdist` "sub-commands" actually generate +several similar formats; for instance, the :command:`bdist_dumb` command +generates all the "dumb" archive formats (``tar``, ``ztar``, ``gztar``, and +``zip``), and :command:`bdist_rpm` generates both binary and source RPMs. The +:command:`bdist` sub-commands, and the formats generated by each, are: + ++--------------------------+-----------------------+ +| Command | Formats | ++==========================+=======================+ +| :command:`bdist_dumb` | tar, ztar, gztar, zip | ++--------------------------+-----------------------+ +| :command:`bdist_rpm` | rpm, srpm | ++--------------------------+-----------------------+ +| :command:`bdist_wininst` | wininst | ++--------------------------+-----------------------+ + +The following sections give details on the individual :command:`bdist_\*` +commands. + + +.. _creating-dumb: + +Creating dumb built distributions +================================= + +**\*\*** Need to document absolute vs. prefix-relative packages here, but first +I have to implement it! **\*\*** + + +.. _creating-rpms: + +Creating RPM packages +===================== + +The RPM format is used by many popular Linux distributions, including Red Hat, +SuSE, and Mandrake. If one of these (or any of the other RPM-based Linux +distributions) is your usual environment, creating RPM packages for other users +of that same distribution is trivial. Depending on the complexity of your module +distribution and differences between Linux distributions, you may also be able +to create RPMs that work on different RPM-based distributions. + +The usual way to create an RPM of your module distribution is to run the +:command:`bdist_rpm` command:: + + python setup.py bdist_rpm + +or the :command:`bdist` command with the :option:`--format` option:: + + python setup.py bdist --formats=rpm + +The former allows you to specify RPM-specific options; the latter allows you to +easily specify multiple formats in one run. If you need to do both, you can +explicitly specify multiple :command:`bdist_\*` commands and their options:: + + python setup.py bdist_rpm --packager="John Doe " \ + bdist_wininst --target_version="2.0" + +Creating RPM packages is driven by a :file:`.spec` file, much as using the +Distutils is driven by the setup script. To make your life easier, the +:command:`bdist_rpm` command normally creates a :file:`.spec` file based on the +information you supply in the setup script, on the command line, and in any +Distutils configuration files. Various options and sections in the +:file:`.spec` file are derived from options in the setup script as follows: + ++------------------------------------------+----------------------------------------------+ +| RPM :file:`.spec` file option or section | Distutils setup script option | ++==========================================+==============================================+ +| Name | :option:`name` | ++------------------------------------------+----------------------------------------------+ +| Summary (in preamble) | :option:`description` | ++------------------------------------------+----------------------------------------------+ +| Version | :option:`version` | ++------------------------------------------+----------------------------------------------+ +| Vendor | :option:`author` and :option:`author_email`, | +| | or --- & :option:`maintainer` and | +| | :option:`maintainer_email` | ++------------------------------------------+----------------------------------------------+ +| Copyright | :option:`licence` | ++------------------------------------------+----------------------------------------------+ +| Url | :option:`url` | ++------------------------------------------+----------------------------------------------+ +| %description (section) | :option:`long_description` | ++------------------------------------------+----------------------------------------------+ + +Additionally, there are many options in :file:`.spec` files that don't have +corresponding options in the setup script. Most of these are handled through +options to the :command:`bdist_rpm` command as follows: + ++-------------------------------+-----------------------------+-------------------------+ +| RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value | +| or section | | | ++===============================+=============================+=========================+ +| Release | :option:`release` | "1" | ++-------------------------------+-----------------------------+-------------------------+ +| Group | :option:`group` | "Development/Libraries" | ++-------------------------------+-----------------------------+-------------------------+ +| Vendor | :option:`vendor` | (see above) | ++-------------------------------+-----------------------------+-------------------------+ +| Packager | :option:`packager` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Provides | :option:`provides` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Requires | :option:`requires` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Conflicts | :option:`conflicts` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Obsoletes | :option:`obsoletes` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Distribution | :option:`distribution_name` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| BuildRequires | :option:`build_requires` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Icon | :option:`icon` | (none) | ++-------------------------------+-----------------------------+-------------------------+ + +Obviously, supplying even a few of these options on the command-line would be +tedious and error-prone, so it's usually best to put them in the setup +configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If +you distribute or package many Python module distributions, you might want to +put options that apply to all of them in your personal Distutils configuration +file (:file:`~/.pydistutils.cfg`). + +There are three steps to building a binary RPM package, all of which are +handled automatically by the Distutils: + +#. create a :file:`.spec` file, which describes the package (analogous to the + Distutils setup script; in fact, much of the information in the setup script + winds up in the :file:`.spec` file) + +#. create the source RPM + +#. create the "binary" RPM (which may or may not contain binary code, depending + on whether your module distribution contains Python extensions) + +Normally, RPM bundles the last two steps together; when you use the Distutils, +all three steps are typically bundled together. + +If you wish, you can separate these three steps. You can use the +:option:`--spec-only` option to make :command:`bdist_rpm` just create the +:file:`.spec` file and exit; in this case, the :file:`.spec` file will be +written to the "distribution directory"---normally :file:`dist/`, but +customizable with the :option:`--dist-dir` option. (Normally, the :file:`.spec` +file winds up deep in the "build tree," in a temporary directory created by +:command:`bdist_rpm`.) + +.. % \XXX{this isn't implemented yet---is it needed?!} +.. % You can also specify a custom \file{.spec} file with the +.. % \longprogramopt{spec-file} option; used in conjunction with +.. % \longprogramopt{spec-only}, this gives you an opportunity to customize +.. % the \file{.spec} file manually: +.. % +.. % \ begin{verbatim} +.. % > python setup.py bdist_rpm --spec-only +.. % # ...edit dist/FooBar-1.0.spec +.. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec +.. % \ end{verbatim} +.. % +.. % (Although a better way to do this is probably to override the standard +.. % \command{bdist\_rpm} command with one that writes whatever else you want +.. % to the \file{.spec} file.) + + +.. _creating-wininst: + +Creating Windows Installers +=========================== + +Executable installers are the natural format for binary distributions on +Windows. They display a nice graphical user interface, display some information +about the module distribution to be installed taken from the metadata in the +setup script, let the user select a few options, and start or cancel the +installation. + +Since the metadata is taken from the setup script, creating Windows installers +is usually as easy as running:: + + python setup.py bdist_wininst + +or the :command:`bdist` command with the :option:`--formats` option:: + + python setup.py bdist --formats=wininst + +If you have a pure module distribution (only containing pure Python modules and +packages), the resulting installer will be version independent and have a name +like :file:`foo-1.0.win32.exe`. These installers can even be created on Unix or +Mac OS platforms. + +If you have a non-pure distribution, the extensions can only be created on a +Windows platform, and will be Python version dependent. The installer filename +will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`. You +have to create a separate installer for every Python version you want to +support. + +The installer will try to compile pure modules into bytecode after installation +on the target system in normal and optimizing mode. If you don't want this to +happen for some reason, you can run the :command:`bdist_wininst` command with +the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` +option. + +By default the installer will display the cool "Python Powered" logo when it is +run, but you can also supply your own bitmap which must be a Windows +:file:`.bmp` file with the :option:`--bitmap` option. + +The installer will also display a large title on the desktop background window +when it is run, which is constructed from the name of your distribution and the +version number. This can be changed to another text by using the +:option:`--title` option. + +The installer file will be written to the "distribution directory" --- normally +:file:`dist/`, but customizable with the :option:`--dist-dir` option. + + +.. _postinstallation-script: + +The Postinstallation script +--------------------------- + +Starting with Python 2.3, a postinstallation script can be specified which the +:option:`--install-script` option. The basename of the script must be +specified, and the script filename must also be listed in the scripts argument +to the setup function. + +This script will be run at installation time on the target system after all the +files have been copied, with ``argv[1]`` set to :option:`-install`, and again at +uninstallation time before the files are removed with ``argv[1]`` set to +:option:`-remove`. + +The installation script runs embedded in the windows installer, every output +(``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be +displayed in the GUI after the script has finished. + +Some functions especially useful in this context are available as additional +built-in functions in the installation script. + + +.. function:: directory_created(path) + file_created(path) + + These functions should be called when a directory or file is created by the + postinstall script at installation time. It will register *path* with the + uninstaller, so that it will be removed when the distribution is uninstalled. + To be safe, directories are only removed if they are empty. + + +.. function:: get_special_folder_path(csidl_string) + + This function can be used to retrieve special folder locations on Windows like + the Start Menu or the Desktop. It returns the full path to the folder. + *csidl_string* must be one of the following strings:: + + "CSIDL_APPDATA" + + "CSIDL_COMMON_STARTMENU" + "CSIDL_STARTMENU" + + "CSIDL_COMMON_DESKTOPDIRECTORY" + "CSIDL_DESKTOPDIRECTORY" + + "CSIDL_COMMON_STARTUP" + "CSIDL_STARTUP" + + "CSIDL_COMMON_PROGRAMS" + "CSIDL_PROGRAMS" + + "CSIDL_FONTS" + + If the folder cannot be retrieved, :exc:`OSError` is raised. + + Which folders are available depends on the exact Windows version, and probably + also the configuration. For details refer to Microsoft's documentation of the + :cfunc:`SHGetSpecialFolderPath` function. + + +.. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) + + This function creates a shortcut. *target* is the path to the program to be + started by the shortcut. *description* is the description of the shortcut. + *filename* is the title of the shortcut that the user will see. *arguments* + specifies the command line arguments, if any. *workdir* is the working directory + for the program. *iconpath* is the file containing the icon for the shortcut, + and *iconindex* is the index of the icon in the file *iconpath*. Again, for + details consult the Microsoft documentation for the :class:`IShellLink` + interface. + + diff --git a/commandref.rst b/commandref.rst new file mode 100644 index 0000000000..f5f02204c5 --- /dev/null +++ b/commandref.rst @@ -0,0 +1,104 @@ +.. _reference: + +***************** +Command Reference +***************** + +.. % \section{Building modules: the \protect\command{build} command family} +.. % \label{build-cmds} +.. % \subsubsection{\protect\command{build}} +.. % \label{build-cmd} +.. % \subsubsection{\protect\command{build\_py}} +.. % \label{build-py-cmd} +.. % \subsubsection{\protect\command{build\_ext}} +.. % \label{build-ext-cmd} +.. % \subsubsection{\protect\command{build\_clib}} +.. % \label{build-clib-cmd} + + +.. _install-cmd: + +Installing modules: the :command:`install` command family +========================================================= + +The install command ensures that the build commands have been run and then runs +the subcommands :command:`install_lib`, :command:`install_data` and +:command:`install_scripts`. + +.. % \subsubsection{\protect\command{install\_lib}} +.. % \label{install-lib-cmd} + + +.. _install-data-cmd: + +:command:`install_data` +----------------------- + +This command installs all data files provided with the distribution. + + +.. _install-scripts-cmd: + +:command:`install_scripts` +-------------------------- + +This command installs all (Python) scripts in the distribution. + +.. % \subsection{Cleaning up: the \protect\command{clean} command} +.. % \label{clean-cmd} + + +.. _sdist-cmd: + +Creating a source distribution: the :command:`sdist` command +============================================================ + +**\*\*** fragment moved down from above: needs context! **\*\*** + +The manifest template commands are: + ++-------------------------------------------+-----------------------------------------------+ +| Command | Description | ++===========================================+===============================================+ +| :command:`include pat1 pat2 ...` | include all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`prune dir` | exclude all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ +| :command:`graft dir` | include all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ + +The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of +regular filename characters, ``?`` matches any single regular filename +character, and ``[range]`` matches any of the characters in *range* (e.g., +``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename +character" is platform-specific: on Unix it is anything except slash; on Windows +anything except backslash or colon; on Mac OS 9 anything except colon. + +**\*\*** Windows support not there yet **\*\*** + +.. % \section{Creating a built distribution: the +.. % \protect\command{bdist} command family} +.. % \label{bdist-cmds} + +.. % \subsection{\protect\command{bdist}} +.. % \subsection{\protect\command{bdist\_dumb}} +.. % \subsection{\protect\command{bdist\_rpm}} +.. % \subsection{\protect\command{bdist\_wininst}} + + diff --git a/configfile.rst b/configfile.rst new file mode 100644 index 0000000000..0ccd5fd3e8 --- /dev/null +++ b/configfile.rst @@ -0,0 +1,130 @@ +.. _setup-config: + +************************************ +Writing the Setup Configuration File +************************************ + +Often, it's not possible to write down everything needed to build a distribution +*a priori*: you may need to get some information from the user, or from the +user's system, in order to proceed. As long as that information is fairly +simple---a list of directories to search for C header files or libraries, for +example---then providing a configuration file, :file:`setup.cfg`, for users to +edit is a cheap and easy way to solicit it. Configuration files also let you +provide default values for any command option, which the installer can then +override either on the command-line or by editing the config file. + +The setup configuration file is a useful middle-ground between the setup script +---which, ideally, would be opaque to installers [#]_---and the command-line to +the setup script, which is outside of your control and entirely up to the +installer. In fact, :file:`setup.cfg` (and any other Distutils configuration +files present on the target system) are processed after the contents of the +setup script, but before the command-line. This has several useful +consequences: + +.. % (If you have more advanced needs, such as determining which extensions +.. % to build based on what capabilities are present on the target system, +.. % then you need the Distutils ``auto-configuration'' facility. This +.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature +.. % or stable enough yet for real-world use.) + +* installers can override some of what you put in :file:`setup.py` by editing + :file:`setup.cfg` + +* you can provide non-standard defaults for options that are not easily set in + :file:`setup.py` + +* installers can override anything in :file:`setup.cfg` using the command-line + options to :file:`setup.py` + +The basic syntax of the configuration file is simple:: + + [command] + option=value + ... + +where *command* is one of the Distutils commands (e.g. :command:`build_py`, +:command:`install`), and *option* is one of the options that command supports. +Any number of options can be supplied for each command, and any number of +command sections can be included in the file. Blank lines are ignored, as are +comments, which run from a ``'#'`` character until the end of the line. Long +option values can be split across multiple lines simply by indenting the +continuation lines. + +You can find out the list of options supported by a particular command with the +universal :option:`--help` option, e.g. :: + + > python setup.py --help build_ext + [...] + Options for 'build_ext' command: + --build-lib (-b) directory for compiled extension modules + --build-temp (-t) directory for temporary files (build by-products) + --inplace (-i) ignore build-lib and put compiled extensions into the + source directory alongside your pure Python modules + --include-dirs (-I) list of directories to search for header files + --define (-D) C preprocessor macros to define + --undef (-U) C preprocessor macros to undefine + --swig-opts list of SWIG command line options + [...] + +Note that an option spelled :option:`--foo-bar` on the command-line is spelled +:option:`foo_bar` in configuration files. + +For example, say you want your extensions to be built "in-place"---that is, you +have an extension :mod:`pkg.ext`, and you want the compiled extension file +(:file:`ext.so` on Unix, say) to be put in the same source directory as your +pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the +:option:`--inplace` option on the command-line to ensure this:: + + python setup.py build_ext --inplace + +But this requires that you always specify the :command:`build_ext` command +explicitly, and remember to provide :option:`--inplace`. An easier way is to +"set and forget" this option, by encoding it in :file:`setup.cfg`, the +configuration file for this distribution:: + + [build_ext] + inplace=1 + +This will affect all builds of this module distribution, whether or not you +explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in +your source distribution, it will also affect end-user builds---which is +probably a bad idea for this option, since always building extensions in-place +would break installation of the module distribution. In certain peculiar cases, +though, modules are built right in their installation directory, so this is +conceivably a useful ability. (Distributing extensions that expect to be built +in their installation directory is almost always a bad idea, though.) + +Another example: certain commands take a lot of options that don't change from +run to run; for example, :command:`bdist_rpm` needs to know everything required +to generate a "spec" file for creating an RPM distribution. Some of this +information comes from the setup script, and some is automatically generated by +the Distutils (such as the list of files installed). But some of it has to be +supplied as options to :command:`bdist_rpm`, which would be very tedious to do +on the command-line for every run. Hence, here is a snippet from the Distutils' +own :file:`setup.cfg`:: + + [bdist_rpm] + release = 1 + packager = Greg Ward + doc_files = CHANGES.txt + README.txt + USAGE.txt + doc/ + examples/ + +Note that the :option:`doc_files` option is simply a whitespace-separated string +split across multiple lines for readability. + + +.. seealso:: + + :ref:`inst-config-syntax` in "Installing Python Modules" + More information on the configuration files is available in the manual for + system administrators. + + +.. rubric:: Footnotes + +.. [#] This ideal probably won't be achieved until auto-configuration is fully + supported by the Distutils. + diff --git a/examples.rst b/examples.rst new file mode 100644 index 0000000000..4e4adc56d2 --- /dev/null +++ b/examples.rst @@ -0,0 +1,241 @@ +.. _examples: + +******** +Examples +******** + +This chapter provides a number of basic examples to help get started with +distutils. Additional information about using distutils can be found in the +Distutils Cookbook. + + +.. seealso:: + + `Distutils Cookbook `_ + Collection of recipes showing how to achieve more control over distutils. + + +.. _pure-mod: + +Pure Python distribution (by module) +==================================== + +If you're just distributing a couple of modules, especially if they don't live +in a particular package, you can specify them individually using the +:option:`py_modules` option in the setup script. + +In the simplest case, you'll have two files to worry about: a setup script and +the single module you're distributing, :file:`foo.py` in this example:: + + / + setup.py + foo.py + +(In all diagrams in this section, ** will refer to the distribution root +directory.) A minimal setup script to describe this situation would be:: + + from distutils.core import setup + setup(name='foo', + version='1.0', + py_modules=['foo'], + ) + +Note that the name of the distribution is specified independently with the +:option:`name` option, and there's no rule that says it has to be the same as +the name of the sole module in the distribution (although that's probably a good +convention to follow). However, the distribution name is used to generate +filenames, so you should stick to letters, digits, underscores, and hyphens. + +Since :option:`py_modules` is a list, you can of course specify multiple +modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your +setup might look like this:: + + / + setup.py + foo.py + bar.py + +and the setup script might be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + py_modules=['foo', 'bar'], + ) + +You can put module source files into another directory, but if you have enough +modules to do that, it's probably easier to specify modules by package rather +than listing them individually. + + +.. _pure-pkg: + +Pure Python distribution (by package) +===================================== + +If you have more than a couple of modules to distribute, especially if they are +in multiple packages, it's probably easier to specify whole packages rather than +individual modules. This works even if your modules are not in a package; you +can just tell the Distutils to process modules from the root package, and that +works the same as any other package (except that you don't have to have an +:file:`__init__.py` file). + +The setup script from the last example could also be written as :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + packages=[''], + ) + +(The empty string stands for the root package.) + +If those two files are moved into a subdirectory, but remain in the root +package, e.g.:: + + / + setup.py + src/ foo.py + bar.py + +then you would still specify the root package, but you have to tell the +Distutils where source files in the root package live:: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + package_dir={'': 'src'}, + packages=[''], + ) + +More typically, though, you will want to distribute multiple modules in the same +package (or in sub-packages). For example, if the :mod:`foo` and :mod:`bar` +modules belong in package :mod:`foobar`, one way to layout your source tree is +:: + + / + setup.py + foobar/ + __init__.py + foo.py + bar.py + +This is in fact the default layout expected by the Distutils, and the one that +requires the least work to describe in your setup script:: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + packages=['foobar'], + ) + +If you want to put modules in directories not named for their package, then you +need to use the :option:`package_dir` option again. For example, if the +:file:`src` directory holds modules in the :mod:`foobar` package:: + + / + setup.py + src/ + __init__.py + foo.py + bar.py + +an appropriate setup script would be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + package_dir={'foobar': 'src'}, + packages=['foobar'], + ) + +Or, you might put modules from your main package right in the distribution +root:: + + / + setup.py + __init__.py + foo.py + bar.py + +in which case your setup script would be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + package_dir={'foobar': ''}, + packages=['foobar'], + ) + +(The empty string also stands for the current directory.) + +If you have sub-packages, they must be explicitly listed in :option:`packages`, +but any entries in :option:`package_dir` automatically extend to sub-packages. +(In other words, the Distutils does *not* scan your source tree, trying to +figure out which directories correspond to Python packages by looking for +:file:`__init__.py` files.) Thus, if the default layout grows a sub-package:: + + / + setup.py + foobar/ + __init__.py + foo.py + bar.py + subfoo/ + __init__.py + blah.py + +then the corresponding setup script would be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + packages=['foobar', 'foobar.subfoo'], + ) + +(Again, the empty string in :option:`package_dir` stands for the current +directory.) + + +.. _single-ext: + +Single extension module +======================= + +Extension modules are specified using the :option:`ext_modules` option. +:option:`package_dir` has no effect on where extension source files are found; +it only affects the source for pure Python modules. The simplest case, a +single extension module in a single C source file, is:: + + / + setup.py + foo.c + +If the :mod:`foo` extension belongs in the root package, the setup script for +this could be :: + + from distutils.core import setup + from distutils.extension import Extension + setup(name='foobar', + version='1.0', + ext_modules=[Extension('foo', ['foo.c'])], + ) + +If the extension actually belongs in a package, say :mod:`foopkg`, then + +With exactly the same source tree layout, this extension can be put in the +:mod:`foopkg` package simply by changing the name of the extension:: + + from distutils.core import setup + from distutils.extension import Extension + setup(name='foobar', + version='1.0', + ext_modules=[Extension('foopkg.foo', ['foo.c'])], + ) + +.. % \section{Multiple extension modules} +.. % \label{multiple-ext} + +.. % \section{Putting it all together} + + diff --git a/extending.rst b/extending.rst new file mode 100644 index 0000000000..a2930c77df --- /dev/null +++ b/extending.rst @@ -0,0 +1,96 @@ +.. _extending: + +******************* +Extending Distutils +******************* + +Distutils can be extended in various ways. Most extensions take the form of new +commands or replacements for existing commands. New commands may be written to +support new types of platform-specific packaging, for example, while +replacements for existing commands may be made to modify details of how the +command operates on a package. + +Most extensions of the distutils are made within :file:`setup.py` scripts that +want to modify existing commands; many simply add a few file extensions that +should be copied into packages in addition to :file:`.py` files as a +convenience. + +Most distutils command implementations are subclasses of the :class:`Command` +class from :mod:`distutils.cmd`. New commands may directly inherit from +:class:`Command`, while replacements often derive from :class:`Command` +indirectly, directly subclassing the command they are replacing. Commands are +required to derive from :class:`Command`. + +.. % \section{Extending existing commands} +.. % \label{extend-existing} + +.. % \section{Writing new commands} +.. % \label{new-commands} +.. % \XXX{Would an uninstall command be a good example here?} + + +Integrating new commands +======================== + +There are different ways to integrate new command implementations into +distutils. The most difficult is to lobby for the inclusion of the new features +in distutils itself, and wait for (and require) a version of Python that +provides that support. This is really hard for many reasons. + +The most common, and possibly the most reasonable for most needs, is to include +the new implementations with your :file:`setup.py` script, and cause the +:func:`distutils.core.setup` function use them:: + + from distutils.command.build_py import build_py as _build_py + from distutils.core import setup + + class build_py(_build_py): + """Specialized Python source builder.""" + + # implement whatever needs to be different... + + setup(cmdclass={'build_py': build_py}, + ...) + +This approach is most valuable if the new implementations must be used to use a +particular package, as everyone interested in the package will need to have the +new command implementation. + +Beginning with Python 2.4, a third option is available, intended to allow new +commands to be added which can support existing :file:`setup.py` scripts without +requiring modifications to the Python installation. This is expected to allow +third-party extensions to provide support for additional packaging systems, but +the commands can be used for anything distutils commands can be used for. A new +configuration option, :option:`command_packages` (command-line option +:option:`--command-packages`), can be used to specify additional packages to be +searched for modules implementing commands. Like all distutils options, this +can be specified on the command line or in a configuration file. This option +can only be set in the ``[global]`` section of a configuration file, or before +any commands on the command line. If set in a configuration file, it can be +overridden from the command line; setting it to an empty string on the command +line causes the default to be used. This should never be set in a configuration +file provided with a package. + +This new option can be used to add any number of packages to the list of +packages searched for command implementations; multiple package names should be +separated by commas. When not specified, the search is only performed in the +:mod:`distutils.command` package. When :file:`setup.py` is run with the option +:option:`--command-packages` :option:`distcmds,buildcmds`, however, the packages +:mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched +in that order. New commands are expected to be implemented in modules of the +same name as the command by classes sharing the same name. Given the example +command line option above, the command :command:`bdist_openpkg` could be +implemented by the class :class:`distcmds.bdist_openpkg.bdist_openpkg` or +:class:`buildcmds.bdist_openpkg.bdist_openpkg`. + + +Adding new distribution types +============================= + +Commands that create distributions (files in the :file:`dist/` directory) need +to add ``(command, filename)`` pairs to ``self.distribution.dist_files`` so that +:command:`upload` can upload it to PyPI. The *filename* in the pair contains no +path information, only the name of the file itself. In dry-run mode, pairs +should still be added to represent what would have been created. + + diff --git a/index.rst b/index.rst new file mode 100644 index 0000000000..6d82c847bb --- /dev/null +++ b/index.rst @@ -0,0 +1,30 @@ +.. _distutils-index: + +############################### + Distributing Python Modules +############################### + +:Authors: Greg Ward, Anthony Baxter +:Email: distutils-sig@python.org +:Release: |version| +:Date: |today| + +This document describes the Python Distribution Utilities ("Distutils") from +the module developer's point of view, describing how to use the Distutils to +make Python modules and extensions easily available to a wider audience with +very little overhead for build/release/install mechanics. + +.. toctree:: + :maxdepth: 2 + + introduction.rst + setupscript.rst + configfile.rst + sourcedist.rst + builtdist.rst + packageindex.rst + uploading.rst + examples.rst + extending.rst + commandref.rst + apiref.rst diff --git a/introduction.rst b/introduction.rst new file mode 100644 index 0000000000..b772b01004 --- /dev/null +++ b/introduction.rst @@ -0,0 +1,208 @@ +.. _distutils-intro: + +**************************** +An Introduction to Distutils +**************************** + +This document covers using the Distutils to distribute your Python modules, +concentrating on the role of developer/distributor: if you're looking for +information on installing Python modules, you should refer to the +:ref:`install-index` chapter. + + +.. _distutils-concepts: + +Concepts & Terminology +====================== + +Using the Distutils is quite simple, both for module developers and for +users/administrators installing third-party modules. As a developer, your +responsibilities (apart from writing solid, well-documented and well-tested +code, of course!) are: + +* write a setup script (:file:`setup.py` by convention) + +* (optional) write a setup configuration file + +* create a source distribution + +* (optional) create one or more built (binary) distributions + +Each of these tasks is covered in this document. + +Not all module developers have access to a multitude of platforms, so it's not +always feasible to expect them to create a multitude of built distributions. It +is hoped that a class of intermediaries, called *packagers*, will arise to +address this need. Packagers will take source distributions released by module +developers, build them on one or more platforms, and release the resulting built +distributions. Thus, users on the most popular platforms will be able to +install most popular Python module distributions in the most natural way for +their platform, without having to run a single setup script or compile a line of +code. + + +.. _distutils-simple-example: + +A Simple Example +================ + +The setup script is usually quite simple, although since it's written in Python, +there are no arbitrary limits to what you can do with it, though you should be +careful about putting arbitrarily expensive operations in your setup script. +Unlike, say, Autoconf-style configure scripts, the setup script may be run +multiple times in the course of building and installing your module +distribution. + +If all you want to do is distribute a module called :mod:`foo`, contained in a +file :file:`foo.py`, then your setup script can be as simple as this:: + + from distutils.core import setup + setup(name='foo', + version='1.0', + py_modules=['foo'], + ) + +Some observations: + +* most information that you supply to the Distutils is supplied as keyword + arguments to the :func:`setup` function + +* those keyword arguments fall into two categories: package metadata (name, + version number) and information about what's in the package (a list of pure + Python modules, in this case) + +* modules are specified by module name, not filename (the same will hold true + for packages and extensions) + +* it's recommended that you supply a little more metadata, in particular your + name, email address and a URL for the project (see section :ref:`setup-script` + for an example) + +To create a source distribution for this module, you would create a setup +script, :file:`setup.py`, containing the above code, and run:: + + python setup.py sdist + +which will create an archive file (e.g., tarball on Unix, ZIP file on Windows) +containing your setup script :file:`setup.py`, and your module :file:`foo.py`. +The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and +will unpack into a directory :file:`foo-1.0`. + +If an end-user wishes to install your :mod:`foo` module, all she has to do is +download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the +:file:`foo-1.0` directory---run :: + + python setup.py install + +which will ultimately copy :file:`foo.py` to the appropriate directory for +third-party modules in their Python installation. + +This simple example demonstrates some fundamental concepts of the Distutils. +First, both developers and installers have the same basic user interface, i.e. +the setup script. The difference is which Distutils *commands* they use: the +:command:`sdist` command is almost exclusively for module developers, while +:command:`install` is more often for installers (although most developers will +want to install their own code occasionally). + +If you want to make things really easy for your users, you can create one or +more built distributions for them. For instance, if you are running on a +Windows machine, and want to make things easy for other Windows users, you can +create an executable installer (the most appropriate type of built distribution +for this platform) with the :command:`bdist_wininst` command. For example:: + + python setup.py bdist_wininst + +will create an executable installer, :file:`foo-1.0.win32.exe`, in the current +directory. + +Other useful built distribution formats are RPM, implemented by the +:command:`bdist_rpm` command, Solaris :program:`pkgtool` +(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall` +(:command:`bdist_sdux`). For example, the following command will create an RPM +file called :file:`foo-1.0.noarch.rpm`:: + + python setup.py bdist_rpm + +(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore +this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or +Mandrake Linux.) + +You can find out what distribution formats are available at any time by running +:: + + python setup.py bdist --help-formats + + +.. _python-terms: + +General Python terminology +========================== + +If you're reading this document, you probably have a good idea of what modules, +extensions, and so forth are. Nevertheless, just to be sure that everyone is +operating from a common starting point, we offer the following glossary of +common Python terms: + +module + the basic unit of code reusability in Python: a block of code imported by some + other code. Three types of modules concern us here: pure Python modules, + extension modules, and packages. + +pure Python module + a module written in Python and contained in a single :file:`.py` file (and + possibly associated :file:`.pyc` and/or :file:`.pyo` files). Sometimes referred + to as a "pure module." + +extension module + a module written in the low-level language of the Python implementation: C/C++ + for Python, Java for Jython. Typically contained in a single dynamically + loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python + extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python + extensions on Windows, or a Java class file for Jython extensions. (Note that + currently, the Distutils only handles C/C++ extensions for Python.) + +package + a module that contains other modules; typically contained in a directory in the + filesystem and distinguished from other directories by the presence of a file + :file:`__init__.py`. + +root package + the root of the hierarchy of packages. (This isn't really a package, since it + doesn't have an :file:`__init__.py` file. But we have to call it something.) + The vast majority of the standard library is in the root package, as are many + small, standalone third-party modules that don't belong to a larger module + collection. Unlike regular packages, modules in the root package can be found in + many directories: in fact, every directory listed in ``sys.path`` contributes + modules to the root package. + + +.. _distutils-term: + +Distutils-specific terminology +============================== + +The following terms apply more specifically to the domain of distributing Python +modules using the Distutils: + +module distribution + a collection of Python modules distributed together as a single downloadable + resource and meant to be installed *en masse*. Examples of some well-known + module distributions are Numeric Python, PyXML, PIL (the Python Imaging + Library), or mxBase. (This would be called a *package*, except that term is + already taken in the Python context: a single module distribution may contain + zero, one, or many Python packages.) + +pure module distribution + a module distribution that contains only pure Python modules and packages. + Sometimes referred to as a "pure distribution." + +non-pure module distribution + a module distribution that contains at least one extension module. Sometimes + referred to as a "non-pure distribution." + +distribution root + the top-level directory of your source tree (or source distribution); the + directory where :file:`setup.py` exists. Generally :file:`setup.py` will be + run from this directory. + + diff --git a/packageindex.rst b/packageindex.rst new file mode 100644 index 0000000000..f0f886bcc9 --- /dev/null +++ b/packageindex.rst @@ -0,0 +1,65 @@ +.. _package-index: + +********************************** +Registering with the Package Index +********************************** + +The Python Package Index (PyPI) holds meta-data describing distributions +packaged with distutils. The distutils command :command:`register` is used to +submit your distribution's meta-data to the index. It is invoked as follows:: + + python setup.py register + +Distutils will respond with the following prompt:: + + running register + We need to know who you are, so please choose either: + 1. use your existing login, + 2. register as a new user, + 3. have the server generate a new password for you (and email it to you), or + 4. quit + Your selection [default 1]: + +Note: if your username and password are saved locally, you will not see this +menu. + +If you have not registered with PyPI, then you will need to do so now. You +should choose option 2, and enter your details as required. Soon after +submitting your details, you will receive an email which will be used to confirm +your registration. + +Once you are registered, you may choose option 1 from the menu. You will be +prompted for your PyPI username and password, and :command:`register` will then +submit your meta-data to the index. + +You may submit any number of versions of your distribution to the index. If you +alter the meta-data for a particular version, you may submit it again and the +index will be updated. + +PyPI holds a record for each (name, version) combination submitted. The first +user to submit information for a given name is designated the Owner of that +name. They may submit changes through the :command:`register` command or through +the web interface. They may also designate other users as Owners or Maintainers. +Maintainers may edit the package information, but not designate other Owners or +Maintainers. + +By default PyPI will list all versions of a given package. To hide certain +versions, the Hidden property should be set to yes. This must be edited through +the web interface. + + +.. _pypirc: + +The .pypirc file +================ + +The format of the :file:`.pypirc` file is formated as follows:: + + [server-login] + repository: + username: + password: + +*repository* can be ommitted and defaults to ``http://www.python.org/pypi``. + + diff --git a/setupscript.rst b/setupscript.rst new file mode 100644 index 0000000000..26f50e6cd5 --- /dev/null +++ b/setupscript.rst @@ -0,0 +1,669 @@ +.. _setup-script: + +************************ +Writing the Setup Script +************************ + +The setup script is the centre of all activity in building, distributing, and +installing modules using the Distutils. The main purpose of the setup script is +to describe your module distribution to the Distutils, so that the various +commands that operate on your modules do the right thing. As we saw in section +:ref:`distutils-simple-example` above, the setup script consists mainly of a call to +:func:`setup`, and most information supplied to the Distutils by the module +developer is supplied as keyword arguments to :func:`setup`. + +Here's a slightly more involved example, which we'll follow for the next couple +of sections: the Distutils' own setup script. (Keep in mind that although the +Distutils are included with Python 1.6 and later, they also have an independent +existence so that Python 1.5.2 users can use them to install other module +distributions. The Distutils' own setup script, shown here, is used to install +the package into Python 1.5.2.) :: + + #!/usr/bin/env python + + from distutils.core import setup + + setup(name='Distutils', + version='1.0', + description='Python Distribution Utilities', + author='Greg Ward', + author_email='gward@python.net', + url='http://www.python.org/sigs/distutils-sig/', + packages=['distutils', 'distutils.command'], + ) + +There are only two differences between this and the trivial one-file +distribution presented in section :ref:`distutils-simple-example`: more metadata, and the +specification of pure Python modules by package, rather than by module. This is +important since the Distutils consist of a couple of dozen modules split into +(so far) two packages; an explicit list of every module would be tedious to +generate and difficult to maintain. For more information on the additional +meta-data, see section :ref:`meta-data`. + +Note that any pathnames (files or directories) supplied in the setup script +should be written using the Unix convention, i.e. slash-separated. The +Distutils will take care of converting this platform-neutral representation into +whatever is appropriate on your current platform before actually using the +pathname. This makes your setup script portable across operating systems, which +of course is one of the major goals of the Distutils. In this spirit, all +pathnames in this document are slash-separated. (Mac OS 9 programmers should +keep in mind that the *absence* of a leading slash indicates a relative path, +the opposite of the Mac OS convention with colons.) + +This, of course, only applies to pathnames given to Distutils functions. If +you, for example, use standard Python functions such as :func:`glob.glob` or +:func:`os.listdir` to specify files, you should be careful to write portable +code instead of hardcoding path separators:: + + glob.glob(os.path.join('mydir', 'subdir', '*.html')) + os.listdir(os.path.join('mydir', 'subdir')) + + +.. _listing-packages: + +Listing whole packages +====================== + +The :option:`packages` option tells the Distutils to process (build, distribute, +install, etc.) all pure Python modules found in each package mentioned in the +:option:`packages` list. In order to do this, of course, there has to be a +correspondence between package names and directories in the filesystem. The +default correspondence is the most obvious one, i.e. package :mod:`distutils` is +found in the directory :file:`distutils` relative to the distribution root. +Thus, when you say ``packages = ['foo']`` in your setup script, you are +promising that the Distutils will find a file :file:`foo/__init__.py` (which +might be spelled differently on your system, but you get the idea) relative to +the directory where your setup script lives. If you break this promise, the +Distutils will issue a warning but still process the broken package anyways. + +If you use a different convention to lay out your source directory, that's no +problem: you just have to supply the :option:`package_dir` option to tell the +Distutils about your convention. For example, say you keep all Python source +under :file:`lib`, so that modules in the "root package" (i.e., not in any +package at all) are in :file:`lib`, modules in the :mod:`foo` package are in +:file:`lib/foo`, and so forth. Then you would put :: + + package_dir = {'': 'lib'} + +in your setup script. The keys to this dictionary are package names, and an +empty package name stands for the root package. The values are directory names +relative to your distribution root. In this case, when you say ``packages = +['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists. + +Another possible convention is to put the :mod:`foo` package right in +:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be +written in the setup script as :: + + package_dir = {'foo': 'lib'} + +A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly +applies to all packages below *package*, so the :mod:`foo.bar` case is +automatically handled here. In this example, having ``packages = ['foo', +'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and +:file:`lib/bar/__init__.py`. (Keep in mind that although :option:`package_dir` +applies recursively, you must explicitly list all packages in +:option:`packages`: the Distutils will *not* recursively scan your source tree +looking for any directory with an :file:`__init__.py` file.) + + +.. _listing-modules: + +Listing individual modules +========================== + +For a small module distribution, you might prefer to list all modules rather +than listing packages---especially the case of a single module that goes in the +"root package" (i.e., no package at all). This simplest case was shown in +section :ref:`distutils-simple-example`; here is a slightly more involved example:: + + py_modules = ['mod1', 'pkg.mod2'] + +This describes two modules, one of them in the "root" package, the other in the +:mod:`pkg` package. Again, the default package/directory layout implies that +these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and +that :file:`pkg/__init__.py` exists as well. And again, you can override the +package/directory correspondence using the :option:`package_dir` option. + + +.. _describing-extensions: + +Describing extension modules +============================ + +Just as writing Python extension modules is a bit more complicated than writing +pure Python modules, describing them to the Distutils is a bit more complicated. +Unlike pure modules, it's not enough just to list modules or packages and expect +the Distutils to go out and find the right files; you have to specify the +extension name, source file(s), and any compile/link requirements (include +directories, libraries to link with, etc.). + +.. % XXX read over this section + +All of this is done through another keyword argument to :func:`setup`, the +:option:`ext_modules` option. :option:`ext_modules` is just a list of +:class:`Extension` instances, each of which describes a single extension module. +Suppose your distribution includes a single extension, called :mod:`foo` and +implemented by :file:`foo.c`. If no additional instructions to the +compiler/linker are needed, describing this extension is quite simple:: + + Extension('foo', ['foo.c']) + +The :class:`Extension` class can be imported from :mod:`distutils.core` along +with :func:`setup`. Thus, the setup script for a module distribution that +contains only this one extension and nothing else might be:: + + from distutils.core import setup, Extension + setup(name='foo', + version='1.0', + ext_modules=[Extension('foo', ['foo.c'])], + ) + +The :class:`Extension` class (actually, the underlying extension-building +machinery implemented by the :command:`build_ext` command) supports a great deal +of flexibility in describing Python extensions, which is explained in the +following sections. + + +Extension names and packages +---------------------------- + +The first argument to the :class:`Extension` constructor is always the name of +the extension, including any package names. For example, :: + + Extension('foo', ['src/foo1.c', 'src/foo2.c']) + +describes an extension that lives in the root package, while :: + + Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) + +describes the same extension in the :mod:`pkg` package. The source files and +resulting object code are identical in both cases; the only difference is where +in the filesystem (and therefore where in Python's namespace hierarchy) the +resulting extension lives. + +If you have a number of extensions all in the same package (or all under the +same base package), use the :option:`ext_package` keyword argument to +:func:`setup`. For example, :: + + setup(... + ext_package='pkg', + ext_modules=[Extension('foo', ['foo.c']), + Extension('subpkg.bar', ['bar.c'])], + ) + +will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to +:mod:`pkg.subpkg.bar`. + + +Extension source files +---------------------- + +The second argument to the :class:`Extension` constructor is a list of source +files. Since the Distutils currently only support C, C++, and Objective-C +extensions, these are normally C/C++/Objective-C source files. (Be sure to use +appropriate extensions to distinguish C++\ source files: :file:`.cc` and +:file:`.cpp` seem to be recognized by both Unix and Windows compilers.) + +However, you can also include SWIG interface (:file:`.i`) files in the list; the +:command:`build_ext` command knows how to deal with SWIG extensions: it will run +SWIG on the interface file and compile the resulting C/C++ file into your +extension. + +**\*\*** SWIG support is rough around the edges and largely untested! **\*\*** + +This warning notwithstanding, options to SWIG can be currently passed like +this:: + + setup(... + ext_modules=[Extension('_foo', ['foo.i'], + swig_opts=['-modern', '-I../include'])], + py_modules=['foo'], + ) + +Or on the commandline like this:: + + > python setup.py build_ext --swig-opts="-modern -I../include" + +On some platforms, you can include non-source files that are processed by the +compiler and included in your extension. Currently, this just means Windows +message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for +Visual C++. These will be compiled to binary resource (:file:`.res`) files and +linked into the executable. + + +Preprocessor options +-------------------- + +Three optional arguments to :class:`Extension` will help if you need to specify +include directories to search or preprocessor macros to define/undefine: +``include_dirs``, ``define_macros``, and ``undef_macros``. + +For example, if your extension requires header files in the :file:`include` +directory under your distribution root, use the ``include_dirs`` option:: + + Extension('foo', ['foo.c'], include_dirs=['include']) + +You can specify absolute directories there; if you know that your extension will +only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get +away with :: + + Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11']) + +You should avoid this sort of non-portable usage if you plan to distribute your +code: it's probably better to write C code like :: + + #include + +If you need to include header files from some other Python extension, you can +take advantage of the fact that header files are installed in a consistent way +by the Distutils :command:`install_header` command. For example, the Numerical +Python header files are installed (on a standard Unix installation) to +:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ +according to your platform and Python installation.) Since the Python include +directory---\ :file:`/usr/local/include/python1.5` in this case---is always +included in the search path when building Python extensions, the best approach +is to write C code like :: + + #include + +If you must put the :file:`Numerical` include directory right into your header +search path, though, you can find that directory using the Distutils +:mod:`distutils.sysconfig` module:: + + from distutils.sysconfig import get_python_inc + incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical') + setup(..., + Extension(..., include_dirs=[incdir]), + ) + +Even though this is quite portable---it will work on any Python installation, +regardless of platform---it's probably easier to just write your C code in the +sensible way. + +You can define and undefine pre-processor macros with the ``define_macros`` and +``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)`` +tuples, where ``name`` is the name of the macro to define (a string) and +``value`` is its value: either a string or ``None``. (Defining a macro ``FOO`` +to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with +most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is +just a list of macros to undefine. + +For example:: + + Extension(..., + define_macros=[('NDEBUG', '1'), + ('HAVE_STRFTIME', None)], + undef_macros=['HAVE_FOO', 'HAVE_BAR']) + +is the equivalent of having this at the top of every C source file:: + + #define NDEBUG 1 + #define HAVE_STRFTIME + #undef HAVE_FOO + #undef HAVE_BAR + + +Library options +--------------- + +You can also specify the libraries to link against when building your extension, +and the directories to search for those libraries. The ``libraries`` option is +a list of libraries to link against, ``library_dirs`` is a list of directories +to search for libraries at link-time, and ``runtime_library_dirs`` is a list of +directories to search for shared (dynamically loaded) libraries at run-time. + +For example, if you need to link against libraries known to be in the standard +library search path on target systems :: + + Extension(..., + libraries=['gdbm', 'readline']) + +If you need to link with libraries in a non-standard location, you'll have to +include the location in ``library_dirs``:: + + Extension(..., + library_dirs=['/usr/X11R6/lib'], + libraries=['X11', 'Xt']) + +(Again, this sort of non-portable construct should be avoided if you intend to +distribute your code.) + +**\*\*** Should mention clib libraries here or somewhere else! **\*\*** + + +Other options +------------- + +There are still some other options which can be used to handle special cases. + +The :option:`extra_objects` option is a list of object files to be passed to the +linker. These files must not have extensions, as the default extension for the +compiler is used. + +:option:`extra_compile_args` and :option:`extra_link_args` can be used to +specify additional command line options for the respective compiler and linker +command lines. + +:option:`export_symbols` is only useful on Windows. It can contain a list of +symbols (functions or variables) to be exported. This option is not needed when +building compiled extensions: Distutils will automatically add ``initmodule`` +to the list of exported symbols. + + +Relationships between Distributions and Packages +================================================ + +A distribution may relate to packages in three specific ways: + +#. It can require packages or modules. + +#. It can provide packages or modules. + +#. It can obsolete packages or modules. + +These relationships can be specified using keyword arguments to the +:func:`distutils.core.setup` function. + +Dependencies on other Python modules and packages can be specified by supplying +the *requires* keyword argument to :func:`setup`. The value must be a list of +strings. Each string specifies a package that is required, and optionally what +versions are sufficient. + +To specify that any version of a module or package is required, the string +should consist entirely of the module or package name. Examples include +``'mymodule'`` and ``'xml.parsers.expat'``. + +If specific versions are required, a sequence of qualifiers can be supplied in +parentheses. Each qualifier may consist of a comparison operator and a version +number. The accepted comparison operators are:: + + < > == + <= >= != + +These can be combined by using multiple qualifiers separated by commas (and +optional whitespace). In this case, all of the qualifiers must be matched; a +logical AND is used to combine the evaluations. + +Let's look at a bunch of examples: + ++-------------------------+----------------------------------------------+ +| Requires Expression | Explanation | ++=========================+==============================================+ +| ``==1.0`` | Only version ``1.0`` is compatible | ++-------------------------+----------------------------------------------+ +| ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` | +| | is compatible, except ``1.5.1`` | ++-------------------------+----------------------------------------------+ + +Now that we can specify dependencies, we also need to be able to specify what we +provide that other distributions can require. This is done using the *provides* +keyword argument to :func:`setup`. The value for this keyword is a list of +strings, each of which names a Python module or package, and optionally +identifies the version. If the version is not specified, it is assumed to match +that of the distribution. + +Some examples: + ++---------------------+----------------------------------------------+ +| Provides Expression | Explanation | ++=====================+==============================================+ +| ``mypkg`` | Provide ``mypkg``, using the distribution | +| | version | ++---------------------+----------------------------------------------+ +| ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of | +| | the distribution version | ++---------------------+----------------------------------------------+ + +A package can declare that it obsoletes other packages using the *obsoletes* +keyword argument. The value for this is similar to that of the *requires* +keyword: a list of strings giving module or package specifiers. Each specifier +consists of a module or package name optionally followed by one or more version +qualifiers. Version qualifiers are given in parentheses after the module or +package name. + +The versions identified by the qualifiers are those that are obsoleted by the +distribution being described. If no qualifiers are given, all versions of the +named module or package are understood to be obsoleted. + + +Installing Scripts +================== + +So far we have been dealing with pure and non-pure Python modules, which are +usually not run by themselves but imported by scripts. + +Scripts are files containing Python source code, intended to be started from the +command line. Scripts don't require Distutils to do anything very complicated. +The only clever feature is that if the first line of the script starts with +``#!`` and contains the word "python", the Distutils will adjust the first line +to refer to the current interpreter location. By default, it is replaced with +the current interpreter location. The :option:`--executable` (or :option:`-e`) +option will allow the interpreter path to be explicitly overridden. + +The :option:`scripts` option simply is a list of files to be handled in this +way. From the PyXML setup script:: + + setup(... + scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] + ) + + +Installing Package Data +======================= + +Often, additional files need to be installed into a package. These files are +often data that's closely related to the package's implementation, or text files +containing documentation that might be of interest to programmers using the +package. These files are called :dfn:`package data`. + +Package data can be added to packages using the ``package_data`` keyword +argument to the :func:`setup` function. The value must be a mapping from +package name to a list of relative path names that should be copied into the +package. The paths are interpreted as relative to the directory containing the +package (information from the ``package_dir`` mapping is used if appropriate); +that is, the files are expected to be part of the package in the source +directories. They may contain glob patterns as well. + +The path names may contain directory portions; any necessary directories will be +created in the installation. + +For example, if a package should contain a subdirectory with several data files, +the files can be arranged like this in the source tree:: + + setup.py + src/ + mypkg/ + __init__.py + module.py + data/ + tables.dat + spoons.dat + forks.dat + +The corresponding call to :func:`setup` might be:: + + setup(..., + packages=['mypkg'], + package_dir={'mypkg': 'src/mypkg'}, + package_data={'mypkg': ['data/*.dat']}, + ) + +.. versionadded:: 2.4 + + +Installing Additional Files +=========================== + +The :option:`data_files` option can be used to specify additional files needed +by the module distribution: configuration files, message catalogs, data files, +anything which doesn't fit in the previous categories. + +:option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the +following way:: + + setup(... + data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), + ('config', ['cfg/data.cfg']), + ('/etc/init.d', ['init-script'])] + ) + +Note that you can specify the directory names where the data files will be +installed, but you cannot rename the data files themselves. + +Each (*directory*, *files*) pair in the sequence specifies the installation +directory and the files to install there. If *directory* is a relative path, it +is interpreted relative to the installation prefix (Python's ``sys.prefix`` for +pure-Python packages, ``sys.exec_prefix`` for packages that contain extension +modules). Each file name in *files* is interpreted relative to the +:file:`setup.py` script at the top of the package source distribution. No +directory information from *files* is used to determine the final location of +the installed file; only the name of the file is used. + +You can specify the :option:`data_files` options as a simple sequence of files +without specifying a target directory, but this is not recommended, and the +:command:`install` command will print a warning in this case. To install data +files directly in the target directory, an empty string should be given as the +directory. + + +.. _meta-data: + +Additional meta-data +==================== + +The setup script may include additional meta-data beyond the name and version. +This information includes: + ++----------------------+---------------------------+-----------------+--------+ +| Meta-Data | Description | Value | Notes | ++======================+===========================+=================+========+ +| ``name`` | name of the package | short string | \(1) | ++----------------------+---------------------------+-----------------+--------+ +| ``version`` | version of this release | short string | (1)(2) | ++----------------------+---------------------------+-----------------+--------+ +| ``author`` | package author's name | short string | \(3) | ++----------------------+---------------------------+-----------------+--------+ +| ``author_email`` | email address of the | email address | \(3) | +| | package author | | | ++----------------------+---------------------------+-----------------+--------+ +| ``maintainer`` | package maintainer's name | short string | \(3) | ++----------------------+---------------------------+-----------------+--------+ +| ``maintainer_email`` | email address of the | email address | \(3) | +| | package maintainer | | | ++----------------------+---------------------------+-----------------+--------+ +| ``url`` | home page for the package | URL | \(1) | ++----------------------+---------------------------+-----------------+--------+ +| ``description`` | short, summary | short string | | +| | description of the | | | +| | package | | | ++----------------------+---------------------------+-----------------+--------+ +| ``long_description`` | longer description of the | long string | | +| | package | | | ++----------------------+---------------------------+-----------------+--------+ +| ``download_url`` | location where the | URL | \(4) | +| | package may be downloaded | | | ++----------------------+---------------------------+-----------------+--------+ +| ``classifiers`` | a list of classifiers | list of strings | \(4) | ++----------------------+---------------------------+-----------------+--------+ + +Notes: + +(1) + These fields are required. + +(2) + It is recommended that versions take the form *major.minor[.patch[.sub]]*. + +(3) + Either the author or the maintainer must be identified. + +(4) + These fields should not be used if your package is to be compatible with Python + versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website + `_. + +'short string' + A single line of text, not more than 200 characters. + +'long string' + Multiple lines of plain text in reStructuredText format (see + http://docutils.sf.net/). + +'list of strings' + See below. + +None of the string values may be Unicode. + +Encoding the version information is an art in itself. Python packages generally +adhere to the version format *major.minor[.patch][sub]*. The major number is 0 +for initial, experimental releases of software. It is incremented for releases +that represent major milestones in a package. The minor number is incremented +when important new features are added to the package. The patch number +increments when bug-fix releases are made. Additional trailing version +information is sometimes used to indicate sub-releases. These are +"a1,a2,...,aN" (for alpha releases, where functionality and API may change), +"b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN" +(for final pre-release release testing). Some examples: + +0.1.0 + the first, experimental release of a package + +1.0.1a2 + the second alpha release of the first patch version of 1.0 + +:option:`classifiers` are specified in a python list:: + + setup(... + classifiers=[ + 'Development Status :: 4 - Beta', + 'Environment :: Console', + 'Environment :: Web Environment', + 'Intended Audience :: End Users/Desktop', + 'Intended Audience :: Developers', + 'Intended Audience :: System Administrators', + 'License :: OSI Approved :: Python Software Foundation License', + 'Operating System :: MacOS :: MacOS X', + 'Operating System :: Microsoft :: Windows', + 'Operating System :: POSIX', + 'Programming Language :: Python', + 'Topic :: Communications :: Email', + 'Topic :: Office/Business', + 'Topic :: Software Development :: Bug Tracking', + ], + ) + +If you wish to include classifiers in your :file:`setup.py` file and also wish +to remain backwards-compatible with Python releases prior to 2.2.3, then you can +include the following code fragment in your :file:`setup.py` before the +:func:`setup` call. :: + + # patch distutils if it can't cope with the "classifiers" or + # "download_url" keywords + from sys import version + if version < '2.2.3': + from distutils.dist import DistributionMetadata + DistributionMetadata.classifiers = None + DistributionMetadata.download_url = None + + +Debugging the setup script +========================== + +Sometimes things go wrong, and the setup script doesn't do what the developer +wants. + +Distutils catches any exceptions when running the setup script, and print a +simple error message before the script is terminated. The motivation for this +behaviour is to not confuse administrators who don't know much about Python and +are trying to install a package. If they get a big long traceback from deep +inside the guts of Distutils, they may think the package or the Python +installation is broken because they don't read all the way down to the bottom +and see that it's a permission problem. + +On the other hand, this doesn't help the developer to find the cause of the +failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set +to anything except an empty string, and distutils will now print detailed +information what it is doing, and prints the full traceback in case an exception +occurs. + + diff --git a/sourcedist.rst b/sourcedist.rst new file mode 100644 index 0000000000..9f15870ccd --- /dev/null +++ b/sourcedist.rst @@ -0,0 +1,207 @@ +.. _source-dist: + +****************************** +Creating a Source Distribution +****************************** + +As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command +to create a source distribution. In the simplest case, :: + + python setup.py sdist + +(assuming you haven't specified any :command:`sdist` options in the setup script +or config file), :command:`sdist` creates the archive of the default format for +the current platform. The default format is a gzip'ed tar file +(:file:`.tar.gz`) on Unix, and ZIP file on Windows. + +You can specify as many formats as you like using the :option:`--formats` +option, for example:: + + python setup.py sdist --formats=gztar,zip + +to create a gzipped tarball and a zip file. The available formats are: + ++-----------+-------------------------+---------+ +| Format | Description | Notes | ++===========+=========================+=========+ +| ``zip`` | zip file (:file:`.zip`) | (1),(3) | ++-----------+-------------------------+---------+ +| ``gztar`` | gzip'ed tar file | (2),(4) | +| | (:file:`.tar.gz`) | | ++-----------+-------------------------+---------+ +| ``bztar`` | bzip2'ed tar file | \(4) | +| | (:file:`.tar.bz2`) | | ++-----------+-------------------------+---------+ +| ``ztar`` | compressed tar file | \(4) | +| | (:file:`.tar.Z`) | | ++-----------+-------------------------+---------+ +| ``tar`` | tar file (:file:`.tar`) | \(4) | ++-----------+-------------------------+---------+ + +Notes: + +(1) + default on Windows + +(2) + default on Unix + +(3) + requires either external :program:`zip` utility or :mod:`zipfile` module (part + of the standard Python library since Python 1.6) + +(4) + requires external utilities: :program:`tar` and possibly one of :program:`gzip`, + :program:`bzip2`, or :program:`compress` + + +.. _manifest: + +Specifying the files to distribute +================================== + +If you don't supply an explicit list of files (or instructions on how to +generate one), the :command:`sdist` command puts a minimal default set into the +source distribution: + +* all Python source files implied by the :option:`py_modules` and + :option:`packages` options + +* all C source files mentioned in the :option:`ext_modules` or + :option:`libraries` options ( + + **\*\*** getting C library sources currently broken---no + :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) + +* scripts identified by the :option:`scripts` option + +* anything that looks like a test script: :file:`test/test\*.py` (currently, the + Distutils don't do anything with test scripts except include them in source + distributions, but in the future there will be a standard for testing Python + module distributions) + +* :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever you + called your setup script), and :file:`setup.cfg` + +Sometimes this is enough, but usually you will want to specify additional files +to distribute. The typical way to do this is to write a *manifest template*, +called :file:`MANIFEST.in` by default. The manifest template is just a list of +instructions for how to generate your manifest file, :file:`MANIFEST`, which is +the exact list of files to include in your source distribution. The +:command:`sdist` command processes this template and generates a manifest based +on its instructions and what it finds in the filesystem. + +If you prefer to roll your own manifest file, the format is simple: one filename +per line, regular files (or symlinks to them) only. If you do supply your own +:file:`MANIFEST`, you must specify everything: the default set of files +described above does not apply in this case. + +The manifest template has one command per line, where each command specifies a +set of files to include or exclude from the source distribution. For an +example, again we turn to the Distutils' own manifest template:: + + include *.txt + recursive-include examples *.txt *.py + prune examples/sample?/build + +The meanings should be fairly clear: include all files in the distribution root +matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory +matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching +:file:`examples/sample?/build`. All of this is done *after* the standard +include set, so you can exclude files from the standard set with explicit +instructions in the manifest template. (Or, you can use the +:option:`--no-defaults` option to disable the standard set entirely.) There are +several other commands available in the manifest template mini-language; see +section :ref:`sdist-cmd`. + +The order of commands in the manifest template matters: initially, we have the +list of default files as described above, and each command in the template adds +to or removes from that list of files. Once we have fully processed the +manifest template, we remove files that should not be included in the source +distribution: + +* all files in the Distutils "build" tree (default :file:`build/`) + +* all files in directories named :file:`RCS`, :file:`CVS` or :file:`.svn` + +Now we have our complete list of files, which is written to the manifest for +future reference, and then used to build the source distribution archive(s). + +You can disable the default set of included files with the +:option:`--no-defaults` option, and you can disable the standard exclude set +with :option:`--no-prune`. + +Following the Distutils' own manifest template, let's trace how the +:command:`sdist` command builds the list of files to include in the Distutils +source distribution: + +#. include all Python source files in the :file:`distutils` and + :file:`distutils/command` subdirectories (because packages corresponding to + those two directories were mentioned in the :option:`packages` option in the + setup script---see section :ref:`setup-script`) + +#. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard + files) + +#. include :file:`test/test\*.py` (standard files) + +#. include :file:`\*.txt` in the distribution root (this will find + :file:`README.txt` a second time, but such redundancies are weeded out later) + +#. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree + under :file:`examples`, + +#. exclude all files in the sub-trees starting at directories matching + :file:`examples/sample?/build`\ ---this may exclude files included by the + previous two steps, so it's important that the ``prune`` command in the manifest + template comes after the ``recursive-include`` command + +#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS` and + :file:`.svn` directories + +Just like in the setup script, file and directory names in the manifest template +should always be slash-separated; the Distutils will take care of converting +them to the standard representation on your platform. That way, the manifest +template is portable across operating systems. + + +.. _manifest-options: + +Manifest-related options +======================== + +The normal course of operations for the :command:`sdist` command is as follows: + +* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` + and create the manifest + +* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest + with just the default file set + +* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more + recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading + :file:`MANIFEST.in` + +* use the list of files now in :file:`MANIFEST` (either just generated or read + in) to create the source distribution archive(s) + +There are a couple of options that modify this behaviour. First, use the +:option:`--no-defaults` and :option:`--no-prune` to disable the standard +"include" and "exclude" sets. + +Second, you might want to force the manifest to be regenerated---for example, if +you have added or removed files or directories that match an existing pattern in +the manifest template, you should regenerate the manifest:: + + python setup.py sdist --force-manifest + +Or, you might just want to (re)generate the manifest, but not create a source +distribution:: + + python setup.py sdist --manifest-only + +:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a +shortcut for :option:`--manifest-only`, and :option:`-f` for +:option:`--force-manifest`. + + diff --git a/uploading.rst b/uploading.rst new file mode 100644 index 0000000000..0b82184c48 --- /dev/null +++ b/uploading.rst @@ -0,0 +1,37 @@ +.. _package-upload: + +*************************************** +Uploading Packages to the Package Index +*************************************** + +.. versionadded:: 2.5 + +The Python Package Index (PyPI) not only stores the package info, but also the +package data if the author of the package wishes to. The distutils command +:command:`upload` pushes the distribution files to PyPI. + +The command is invoked immediately after building one or more distribution +files. For example, the command :: + + python setup.py sdist bdist_wininst upload + +will cause the source distribution and the Windows installer to be uploaded to +PyPI. Note that these will be uploaded even if they are built using an earlier +invocation of :file:`setup.py`, but that only distributions named on the command +line for the invocation including the :command:`upload` command are uploaded. + +The :command:`upload` command uses the username, password, and repository URL +from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this +file). + +You can use the :option:`--sign` option to tell :command:`upload` to sign each +uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must +be available for execution on the system :envvar:`PATH`. You can also specify +which key to use for signing using the :option:`--identity=*name*` option. + +Other :command:`upload` options include :option:`--repository=*url*` (which +lets you override the repository setting from :file:`$HOME/.pypirc`), and +:option:`--show-response` (which displays the full response text from the PyPI +server for help in debugging upload problems). + + From 7055f01891a484d4319d8651ca6bd57673f3c30c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 15 Aug 2007 14:28:22 +0000 Subject: [PATCH 002/330] Move the 3k reST doc tree in place. --- apiref.rst | 1976 ++++++++++++++++++++++++++++++++++++++++++++++ builtdist.rst | 405 ++++++++++ commandref.rst | 104 +++ configfile.rst | 130 +++ examples.rst | 241 ++++++ extending.rst | 96 +++ index.rst | 30 + introduction.rst | 208 +++++ packageindex.rst | 65 ++ setupscript.rst | 669 ++++++++++++++++ sourcedist.rst | 207 +++++ uploading.rst | 37 + 12 files changed, 4168 insertions(+) create mode 100644 apiref.rst create mode 100644 builtdist.rst create mode 100644 commandref.rst create mode 100644 configfile.rst create mode 100644 examples.rst create mode 100644 extending.rst create mode 100644 index.rst create mode 100644 introduction.rst create mode 100644 packageindex.rst create mode 100644 setupscript.rst create mode 100644 sourcedist.rst create mode 100644 uploading.rst diff --git a/apiref.rst b/apiref.rst new file mode 100644 index 0000000000..c8e57fde0b --- /dev/null +++ b/apiref.rst @@ -0,0 +1,1976 @@ +.. _api-reference: + +************* +API Reference +************* + + +:mod:`distutils.core` --- Core Distutils functionality +====================================================== + +.. module:: distutils.core + :synopsis: The core Distutils functionality + + +The :mod:`distutils.core` module is the only module that needs to be installed +to use the Distutils. It provides the :func:`setup` (which is called from the +setup script). Indirectly provides the :class:`distutils.dist.Distribution` and +:class:`distutils.cmd.Command` class. + + +.. function:: setup(arguments) + + The basic do-everything function that does most everything you could ever ask + for from a Distutils method. See XXXXX + + The setup function takes a large number of arguments. These are laid out in the + following table. + + +--------------------+--------------------------------+-------------------------------------------------------------+ + | argument name | value | type | + +====================+================================+=============================================================+ + | *name* | The name of the package | a string | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *version* | The version number of the | See :mod:`distutils.version` | + | | package | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *description* | A single line describing the | a string | + | | package | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *long_description* | Longer description of the | a string | + | | package | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *author* | The name of the package author | a string | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *author_email* | The email address of the | a string | + | | package author | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *maintainer* | The name of the current | a string | + | | maintainer, if different from | | + | | the author | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *maintainer_email* | The email address of the | | + | | current maintainer, if | | + | | different from the author | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *url* | A URL for the package | a URL | + | | (homepage) | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *download_url* | A URL to download the package | a URL | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *packages* | A list of Python packages that | a list of strings | + | | distutils will manipulate | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *py_modules* | A list of Python modules that | a list of strings | + | | distutils will manipulate | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *scripts* | A list of standalone script | a list of strings | + | | files to be built and | | + | | installed | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *ext_modules* | A list of Python extensions to | A list of instances of | + | | be built | :class:`distutils.core.Extension` | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *classifiers* | A list of categories for the | The list of available | + | | package | categorizations is at | + | | | http://cheeseshop.python.org/pypi?:action=list_classifiers. | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *distclass* | the :class:`Distribution` | A subclass of | + | | class to use | :class:`distutils.core.Distribution` | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *script_name* | The name of the setup.py | a string | + | | script - defaults to | | + | | ``sys.argv[0]`` | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *script_args* | Arguments to supply to the | a list of strings | + | | setup script | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *options* | default options for the setup | a string | + | | script | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *license* | The license for the package | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *keywords* | Descriptive meta-data. See | | + | | :pep:`314` | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *platforms* | | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *cmdclass* | A mapping of command names to | a dictionary | + | | :class:`Command` subclasses | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + + +.. function:: run_setup(script_name[, script_args=None, stop_after='run']) + + Run a setup script in a somewhat controlled environment, and return the + :class:`distutils.dist.Distribution` instance that drives things. This is + useful if you need to find out the distribution meta-data (passed as keyword + args from *script* to :func:`setup`), or the contents of the config files or + command-line. + + *script_name* is a file that will be read and run with :func:`exec`. ``sys.argv[0]`` + will be replaced with *script* for the duration of the call. *script_args* is a + list of strings; if supplied, ``sys.argv[1:]`` will be replaced by *script_args* + for the duration of the call. + + *stop_after* tells :func:`setup` when to stop processing; possible values: + + +---------------+---------------------------------------------+ + | value | description | + +===============+=============================================+ + | *init* | Stop after the :class:`Distribution` | + | | instance has been created and populated | + | | with the keyword arguments to :func:`setup` | + +---------------+---------------------------------------------+ + | *config* | Stop after config files have been parsed | + | | (and their data stored in the | + | | :class:`Distribution` instance) | + +---------------+---------------------------------------------+ + | *commandline* | Stop after the command-line | + | | (``sys.argv[1:]`` or *script_args*) have | + | | been parsed (and the data stored in the | + | | :class:`Distribution` instance.) | + +---------------+---------------------------------------------+ + | *run* | Stop after all commands have been run (the | + | | same as if :func:`setup` had been called | + | | in the usual way). This is the default | + | | value. | + +---------------+---------------------------------------------+ + +In addition, the :mod:`distutils.core` module exposed a number of classes that +live elsewhere. + +* :class:`Extension` from :mod:`distutils.extension` + +* :class:`Command` from :mod:`distutils.cmd` + +* :class:`Distribution` from :mod:`distutils.dist` + +A short description of each of these follows, but see the relevant module for +the full reference. + + +.. class:: Extension + + The Extension class describes a single C or C++extension module in a setup + script. It accepts the following keyword arguments in its constructor + + +------------------------+--------------------------------+---------------------------+ + | argument name | value | type | + +========================+================================+===========================+ + | *name* | the full name of the | string | + | | extension, including any | | + | | packages --- ie. *not* a | | + | | filename or pathname, but | | + | | Python dotted name | | + +------------------------+--------------------------------+---------------------------+ + | *sources* | list of source filenames, | string | + | | relative to the distribution | | + | | root (where the setup script | | + | | lives), in Unix form (slash- | | + | | separated) for portability. | | + | | Source files may be C, C++, | | + | | SWIG (.i), platform-specific | | + | | resource files, or whatever | | + | | else is recognized by the | | + | | :command:`build_ext` command | | + | | as source for a Python | | + | | extension. | | + +------------------------+--------------------------------+---------------------------+ + | *include_dirs* | list of directories to search | string | + | | for C/C++ header files (in | | + | | Unix form for portability) | | + +------------------------+--------------------------------+---------------------------+ + | *define_macros* | list of macros to define; each | (string,string) tuple or | + | | macro is defined using a | (name,``None``) | + | | 2-tuple, where 'value' is | | + | | either the string to define it | | + | | to or ``None`` to define it | | + | | without a particular value | | + | | (equivalent of ``#define FOO`` | | + | | in source or :option:`-DFOO` | | + | | on Unix C compiler command | | + | | line) | | + +------------------------+--------------------------------+---------------------------+ + | *undef_macros* | list of macros to undefine | string | + | | explicitly | | + +------------------------+--------------------------------+---------------------------+ + | *library_dirs* | list of directories to search | string | + | | for C/C++ libraries at link | | + | | time | | + +------------------------+--------------------------------+---------------------------+ + | *libraries* | list of library names (not | string | + | | filenames or paths) to link | | + | | against | | + +------------------------+--------------------------------+---------------------------+ + | *runtime_library_dirs* | list of directories to search | string | + | | for C/C++ libraries at run | | + | | time (for shared extensions, | | + | | this is when the extension is | | + | | loaded) | | + +------------------------+--------------------------------+---------------------------+ + | *extra_objects* | list of extra files to link | string | + | | with (eg. object files not | | + | | implied by 'sources', static | | + | | library that must be | | + | | explicitly specified, binary | | + | | resource files, etc.) | | + +------------------------+--------------------------------+---------------------------+ + | *extra_compile_args* | any extra platform- and | string | + | | compiler-specific information | | + | | to use when compiling the | | + | | source files in 'sources'. For | | + | | platforms and compilers where | | + | | a command line makes sense, | | + | | this is typically a list of | | + | | command-line arguments, but | | + | | for other platforms it could | | + | | be anything. | | + +------------------------+--------------------------------+---------------------------+ + | *extra_link_args* | any extra platform- and | string | + | | compiler-specific information | | + | | to use when linking object | | + | | files together to create the | | + | | extension (or to create a new | | + | | static Python interpreter). | | + | | Similar interpretation as for | | + | | 'extra_compile_args'. | | + +------------------------+--------------------------------+---------------------------+ + | *export_symbols* | list of symbols to be exported | string | + | | from a shared extension. Not | | + | | used on all platforms, and not | | + | | generally necessary for Python | | + | | extensions, which typically | | + | | export exactly one symbol: | | + | | ``init`` + extension_name. | | + +------------------------+--------------------------------+---------------------------+ + | *depends* | list of files that the | string | + | | extension depends on | | + +------------------------+--------------------------------+---------------------------+ + | *language* | extension language (i.e. | string | + | | ``'c'``, ``'c++'``, | | + | | ``'objc'``). Will be detected | | + | | from the source extensions if | | + | | not provided. | | + +------------------------+--------------------------------+---------------------------+ + + +.. class:: Distribution + + A :class:`Distribution` describes how to build, install and package up a Python + software package. + + See the :func:`setup` function for a list of keyword arguments accepted by the + Distribution constructor. :func:`setup` creates a Distribution instance. + + +.. class:: Command + + A :class:`Command` class (or rather, an instance of one of its subclasses) + implement a single distutils command. + + +:mod:`distutils.ccompiler` --- CCompiler base class +=================================================== + +.. module:: distutils.ccompiler + :synopsis: Abstract CCompiler class + + +This module provides the abstract base class for the :class:`CCompiler` +classes. A :class:`CCompiler` instance can be used for all the compile and +link steps needed to build a single project. Methods are provided to set +options for the compiler --- macro definitions, include directories, link path, +libraries and the like. + +This module provides the following functions. + + +.. function:: gen_lib_options(compiler, library_dirs, runtime_library_dirs, libraries) + + Generate linker options for searching library directories and linking with + specific libraries. *libraries* and *library_dirs* are, respectively, lists of + library names (not filenames!) and search directories. Returns a list of + command-line options suitable for use with some compiler (depending on the two + format strings passed in). + + +.. function:: gen_preprocess_options(macros, include_dirs) + + Generate C pre-processor options (:option:`-D`, :option:`-U`, :option:`-I`) as + used by at least two types of compilers: the typical Unix compiler and Visual + C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)`` + means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means define + (:option:`-D`) macro *name* to *value*. *include_dirs* is just a list of + directory names to be added to the header file search path (:option:`-I`). + Returns a list of command-line options suitable for either Unix compilers or + Visual C++. + + +.. function:: get_default_compiler(osname, platform) + + Determine the default compiler to use for the given platform. + + *osname* should be one of the standard Python OS names (i.e. the ones returned + by ``os.name``) and *platform* the common value returned by ``sys.platform`` for + the platform in question. + + The default values are ``os.name`` and ``sys.platform`` in case the parameters + are not given. + + +.. function:: new_compiler(plat=None, compiler=None, verbose=0, dry_run=0, force=0) + + Factory function to generate an instance of some CCompiler subclass for the + supplied platform/compiler combination. *plat* defaults to ``os.name`` (eg. + ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for + that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the + default compilers are "traditional Unix interface" (:class:`UnixCCompiler` + class) and Visual C++(:class:`MSVCCompiler` class). Note that it's perfectly + possible to ask for a Unix compiler object under Windows, and a Microsoft + compiler object under Unix---if you supply a value for *compiler*, *plat* is + ignored. + + .. % Is the posix/nt only thing still true? Mac OS X seems to work, and + .. % returns a UnixCCompiler instance. How to document this... hmm. + + +.. function:: show_compilers() + + Print list of available compilers (used by the :option:`--help-compiler` options + to :command:`build`, :command:`build_ext`, :command:`build_clib`). + + +.. class:: CCompiler([verbose=0, dry_run=0, force=0]) + + The abstract base class :class:`CCompiler` defines the interface that must be + implemented by real compiler classes. The class also has some utility methods + used by several compiler classes. + + The basic idea behind a compiler abstraction class is that each instance can be + used for all the compile/link steps in building a single project. Thus, + attributes common to all of those compile and link steps --- include + directories, macros to define, libraries to link against, etc. --- are + attributes of the compiler instance. To allow for variability in how individual + files are treated, most of those attributes may be varied on a per-compilation + or per-link basis. + + The constructor for each subclass creates an instance of the Compiler object. + Flags are *verbose* (show verbose output), *dry_run* (don't actually execute the + steps) and *force* (rebuild everything, regardless of dependencies). All of + these flags default to ``0`` (off). Note that you probably don't want to + instantiate :class:`CCompiler` or one of its subclasses directly - use the + :func:`distutils.CCompiler.new_compiler` factory function instead. + + The following methods allow you to manually alter compiler options for the + instance of the Compiler class. + + + .. method:: CCompiler.add_include_dir(dir) + + Add *dir* to the list of directories that will be searched for header files. + The compiler is instructed to search directories in the order in which they are + supplied by successive calls to :meth:`add_include_dir`. + + + .. method:: CCompiler.set_include_dirs(dirs) + + Set the list of directories that will be searched to *dirs* (a list of strings). + Overrides any preceding calls to :meth:`add_include_dir`; subsequent calls to + :meth:`add_include_dir` add to the list passed to :meth:`set_include_dirs`. + This does not affect any list of standard include directories that the compiler + may search by default. + + + .. method:: CCompiler.add_library(libname) + + Add *libname* to the list of libraries that will be included in all links driven + by this compiler object. Note that *libname* should \*not\* be the name of a + file containing a library, but the name of the library itself: the actual + filename will be inferred by the linker, the compiler, or the compiler class + (depending on the platform). + + The linker will be instructed to link against libraries in the order they were + supplied to :meth:`add_library` and/or :meth:`set_libraries`. It is perfectly + valid to duplicate library names; the linker will be instructed to link against + libraries as many times as they are mentioned. + + + .. method:: CCompiler.set_libraries(libnames) + + Set the list of libraries to be included in all links driven by this compiler + object to *libnames* (a list of strings). This does not affect any standard + system libraries that the linker may include by default. + + + .. method:: CCompiler.add_library_dir(dir) + + Add *dir* to the list of directories that will be searched for libraries + specified to :meth:`add_library` and :meth:`set_libraries`. The linker will be + instructed to search for libraries in the order they are supplied to + :meth:`add_library_dir` and/or :meth:`set_library_dirs`. + + + .. method:: CCompiler.set_library_dirs(dirs) + + Set the list of library search directories to *dirs* (a list of strings). This + does not affect any standard library search path that the linker may search by + default. + + + .. method:: CCompiler.add_runtime_library_dir(dir) + + Add *dir* to the list of directories that will be searched for shared libraries + at runtime. + + + .. method:: CCompiler.set_runtime_library_dirs(dirs) + + Set the list of directories to search for shared libraries at runtime to *dirs* + (a list of strings). This does not affect any standard search path that the + runtime linker may search by default. + + + .. method:: CCompiler.define_macro(name[, value=None]) + + Define a preprocessor macro for all compilations driven by this compiler object. + The optional parameter *value* should be a string; if it is not supplied, then + the macro will be defined without an explicit value and the exact outcome + depends on the compiler used (XXX true? does ANSI say anything about this?) + + + .. method:: CCompiler.undefine_macro(name) + + Undefine a preprocessor macro for all compilations driven by this compiler + object. If the same macro is defined by :meth:`define_macro` and + undefined by :meth:`undefine_macro` the last call takes precedence + (including multiple redefinitions or undefinitions). If the macro is + redefined/undefined on a per-compilation basis (ie. in the call to + :meth:`compile`), then that takes precedence. + + + .. method:: CCompiler.add_link_object(object) + + Add *object* to the list of object files (or analogues, such as explicitly named + library files or the output of "resource compilers") to be included in every + link driven by this compiler object. + + + .. method:: CCompiler.set_link_objects(objects) + + Set the list of object files (or analogues) to be included in every link to + *objects*. This does not affect any standard object files that the linker may + include by default (such as system libraries). + + The following methods implement methods for autodetection of compiler options, + providing some functionality similar to GNU :program:`autoconf`. + + + .. method:: CCompiler.detect_language(sources) + + Detect the language of a given file, or list of files. Uses the instance + attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a + list) to do the job. + + + .. method:: CCompiler.find_library_file(dirs, lib[, debug=0]) + + Search the specified list of directories for a static or shared library file + *lib* and return the full path to that file. If *debug* is true, look for a + debugging version (if that makes sense on the current platform). Return + ``None`` if *lib* wasn't found in any of the specified directories. + + + .. method:: CCompiler.has_function(funcname [, includes=None, include_dirs=None, libraries=None, library_dirs=None]) + + Return a boolean indicating whether *funcname* is supported on the current + platform. The optional arguments can be used to augment the compilation + environment by providing additional include files and paths and libraries and + paths. + + + .. method:: CCompiler.library_dir_option(dir) + + Return the compiler option to add *dir* to the list of directories searched for + libraries. + + + .. method:: CCompiler.library_option(lib) + + Return the compiler option to add *dir* to the list of libraries linked into the + shared library or executable. + + + .. method:: CCompiler.runtime_library_dir_option(dir) + + Return the compiler option to add *dir* to the list of directories searched for + runtime libraries. + + + .. method:: CCompiler.set_executables(**args) + + Define the executables (and options for them) that will be run to perform the + various stages of compilation. The exact set of executables that may be + specified here depends on the compiler class (via the 'executables' class + attribute), but most will have: + + +--------------+------------------------------------------+ + | attribute | description | + +==============+==========================================+ + | *compiler* | the C/C++ compiler | + +--------------+------------------------------------------+ + | *linker_so* | linker used to create shared objects and | + | | libraries | + +--------------+------------------------------------------+ + | *linker_exe* | linker used to create binary executables | + +--------------+------------------------------------------+ + | *archiver* | static library creator | + +--------------+------------------------------------------+ + + On platforms with a command-line (Unix, DOS/Windows), each of these is a string + that will be split into executable name and (optional) list of arguments. + (Splitting the string is done similarly to how Unix shells operate: words are + delimited by spaces, but quotes and backslashes can override this. See + :func:`distutils.util.split_quoted`.) + + The following methods invoke stages in the build process. + + + .. method:: CCompiler.compile(sources[, output_dir=None, macros=None, include_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, depends=None]) + + Compile one or more source files. Generates object files (e.g. transforms a + :file:`.c` file to a :file:`.o` file.) + + *sources* must be a list of filenames, most likely C/C++ files, but in reality + anything that can be handled by a particular compiler and compiler class (eg. + :class:`MSVCCompiler` can handle resource files in *sources*). Return a list of + object filenames, one per source filename in *sources*. Depending on the + implementation, not all source files will necessarily be compiled, but all + corresponding object filenames will be returned. + + If *output_dir* is given, object files will be put under it, while retaining + their original path component. That is, :file:`foo/bar.c` normally compiles to + :file:`foo/bar.o` (for a Unix implementation); if *output_dir* is *build*, then + it would compile to :file:`build/foo/bar.o`. + + *macros*, if given, must be a list of macro definitions. A macro definition is + either a ``(name, value)`` 2-tuple or a ``(name,)`` 1-tuple. The former defines + a macro; if the value is ``None``, the macro is defined without an explicit + value. The 1-tuple case undefines a macro. Later + definitions/redefinitions/undefinitions take precedence. + + *include_dirs*, if given, must be a list of strings, the directories to add to + the default include file search path for this compilation only. + + *debug* is a boolean; if true, the compiler will be instructed to output debug + symbols in (or alongside) the object file(s). + + *extra_preargs* and *extra_postargs* are implementation-dependent. On platforms + that have the notion of a command-line (e.g. Unix, DOS/Windows), they are most + likely lists of strings: extra command-line arguments to prepend/append to the + compiler command line. On other platforms, consult the implementation class + documentation. In any event, they are intended as an escape hatch for those + occasions when the abstract compiler framework doesn't cut the mustard. + + *depends*, if given, is a list of filenames that all targets depend on. If a + source file is older than any file in depends, then the source file will be + recompiled. This supports dependency tracking, but only at a coarse + granularity. + + Raises :exc:`CompileError` on failure. + + + .. method:: CCompiler.create_static_lib(objects, output_libname[, output_dir=None, debug=0, target_lang=None]) + + Link a bunch of stuff together to create a static library file. The "bunch of + stuff" consists of the list of object files supplied as *objects*, the extra + object files supplied to :meth:`add_link_object` and/or + :meth:`set_link_objects`, the libraries supplied to :meth:`add_library` and/or + :meth:`set_libraries`, and the libraries supplied as *libraries* (if any). + + *output_libname* should be a library name, not a filename; the filename will be + inferred from the library name. *output_dir* is the directory where the library + file will be put. XXX defaults to what? + + *debug* is a boolean; if true, debugging information will be included in the + library (note that on most platforms, it is the compile step where this matters: + the *debug* flag is included here just for consistency). + + *target_lang* is the target language for which the given objects are being + compiled. This allows specific linkage time treatment of certain languages. + + Raises :exc:`LibError` on failure. + + + .. method:: CCompiler.link(target_desc, objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) + + Link a bunch of stuff together to create an executable or shared library file. + + The "bunch of stuff" consists of the list of object files supplied as *objects*. + *output_filename* should be a filename. If *output_dir* is supplied, + *output_filename* is relative to it (i.e. *output_filename* can provide + directory components if needed). + + *libraries* is a list of libraries to link against. These are library names, + not filenames, since they're translated into filenames in a platform-specific + way (eg. *foo* becomes :file:`libfoo.a` on Unix and :file:`foo.lib` on + DOS/Windows). However, they can include a directory component, which means the + linker will look in that specific directory rather than searching all the normal + locations. + + *library_dirs*, if supplied, should be a list of directories to search for + libraries that were specified as bare library names (ie. no directory + component). These are on top of the system default and those supplied to + :meth:`add_library_dir` and/or :meth:`set_library_dirs`. *runtime_library_dirs* + is a list of directories that will be embedded into the shared library and used + to search for other shared libraries that \*it\* depends on at run-time. (This + may only be relevant on Unix.) + + *export_symbols* is a list of symbols that the shared library will export. + (This appears to be relevant only on Windows.) + + *debug* is as for :meth:`compile` and :meth:`create_static_lib`, with the + slight distinction that it actually matters on most platforms (as opposed to + :meth:`create_static_lib`, which includes a *debug* flag mostly for form's + sake). + + *extra_preargs* and *extra_postargs* are as for :meth:`compile` (except of + course that they supply command-line arguments for the particular linker being + used). + + *target_lang* is the target language for which the given objects are being + compiled. This allows specific linkage time treatment of certain languages. + + Raises :exc:`LinkError` on failure. + + + .. method:: CCompiler.link_executable(objects, output_progname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, debug=0, extra_preargs=None, extra_postargs=None, target_lang=None]) + + Link an executable. *output_progname* is the name of the file executable, while + *objects* are a list of object filenames to link in. Other arguments are as for + the :meth:`link` method. + + + .. method:: CCompiler.link_shared_lib(objects, output_libname[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) + + Link a shared library. *output_libname* is the name of the output library, + while *objects* is a list of object filenames to link in. Other arguments are + as for the :meth:`link` method. + + + .. method:: CCompiler.link_shared_object(objects, output_filename[, output_dir=None, libraries=None, library_dirs=None, runtime_library_dirs=None, export_symbols=None, debug=0, extra_preargs=None, extra_postargs=None, build_temp=None, target_lang=None]) + + Link a shared object. *output_filename* is the name of the shared object that + will be created, while *objects* is a list of object filenames to link in. + Other arguments are as for the :meth:`link` method. + + + .. method:: CCompiler.preprocess(source[, output_file=None, macros=None, include_dirs=None, extra_preargs=None, extra_postargs=None]) + + Preprocess a single C/C++ source file, named in *source*. Output will be written + to file named *output_file*, or *stdout* if *output_file* not supplied. + *macros* is a list of macro definitions as for :meth:`compile`, which will + augment the macros set with :meth:`define_macro` and :meth:`undefine_macro`. + *include_dirs* is a list of directory names that will be added to the default + list, in the same way as :meth:`add_include_dir`. + + Raises :exc:`PreprocessError` on failure. + + The following utility methods are defined by the :class:`CCompiler` class, for + use by the various concrete subclasses. + + + .. method:: CCompiler.executable_filename(basename[, strip_dir=0, output_dir='']) + + Returns the filename of the executable for the given *basename*. Typically for + non-Windows platforms this is the same as the basename, while Windows will get + a :file:`.exe` added. + + + .. method:: CCompiler.library_filename(libname[, lib_type='static', strip_dir=0, output_dir='']) + + Returns the filename for the given library name on the current platform. On Unix + a library with *lib_type* of ``'static'`` will typically be of the form + :file:`liblibname.a`, while a *lib_type* of ``'dynamic'`` will be of the form + :file:`liblibname.so`. + + + .. method:: CCompiler.object_filenames(source_filenames[, strip_dir=0, output_dir='']) + + Returns the name of the object files for the given source files. + *source_filenames* should be a list of filenames. + + + .. method:: CCompiler.shared_object_filename(basename[, strip_dir=0, output_dir='']) + + Returns the name of a shared object file for the given file name *basename*. + + + .. method:: CCompiler.execute(func, args[, msg=None, level=1]) + + Invokes :func:`distutils.util.execute` This method invokes a Python function + *func* with the given arguments *args*, after logging and taking into account + the *dry_run* flag. XXX see also. + + + .. method:: CCompiler.spawn(cmd) + + Invokes :func:`distutils.util.spawn`. This invokes an external process to run + the given command. XXX see also. + + + .. method:: CCompiler.mkpath(name[, mode=511]) + + Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any + missing ancestor directories. XXX see also. + + + .. method:: CCompiler.move_file(src, dst) + + Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. XXX see + also. + + + .. method:: CCompiler.announce(msg[, level=1]) + + Write a message using :func:`distutils.log.debug`. XXX see also. + + + .. method:: CCompiler.warn(msg) + + Write a warning message *msg* to standard error. + + + .. method:: CCompiler.debug_print(msg) + + If the *debug* flag is set on this :class:`CCompiler` instance, print *msg* to + standard output, otherwise do nothing. + +.. % \subsection{Compiler-specific modules} +.. % +.. % The following modules implement concrete subclasses of the abstract +.. % \class{CCompiler} class. They should not be instantiated directly, but should +.. % be created using \function{distutils.ccompiler.new_compiler()} factory +.. % function. + + +:mod:`distutils.unixccompiler` --- Unix C Compiler +================================================== + +.. module:: distutils.unixccompiler + :synopsis: UNIX C Compiler + + +This module provides the :class:`UnixCCompiler` class, a subclass of +:class:`CCompiler` that handles the typical Unix-style command-line C compiler: + +* macros defined with :option:`-Dname[=value]` + +* macros undefined with :option:`-Uname` + +* include search directories specified with :option:`-Idir` + +* libraries specified with :option:`-llib` + +* library search directories specified with :option:`-Ldir` + +* compile handled by :program:`cc` (or similar) executable with :option:`-c` + option: compiles :file:`.c` to :file:`.o` + +* link static library handled by :program:`ar` command (possibly with + :program:`ranlib`) + +* link shared library handled by :program:`cc` :option:`-shared` + + +:mod:`distutils.msvccompiler` --- Microsoft Compiler +==================================================== + +.. module:: distutils.msvccompiler + :synopsis: Microsoft Compiler + + +This module provides :class:`MSVCCompiler`, an implementation of the abstract +:class:`CCompiler` class for Microsoft Visual Studio. Typically, extension +modules need to be compiled with the same compiler that was used to compile +Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python +2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium +binaries are created using the Platform SDK. + +:class:`MSVCCompiler` will normally choose the right compiler, linker etc. on +its own. To override this choice, the environment variables *DISTUTILS_USE_SDK* +and *MSSdk* must be both set. *MSSdk* indicates that the current environment has +been setup by the SDK's ``SetEnv.Cmd`` script, or that the environment variables +had been registered when the SDK was installed; *DISTUTILS_USE_SDK* indicates +that the distutils user has made an explicit choice to override the compiler +selection by :class:`MSVCCompiler`. + + +:mod:`distutils.bcppcompiler` --- Borland Compiler +================================================== + +.. module:: distutils.bcppcompiler + + +This module provides :class:`BorlandCCompiler`, an subclass of the abstract +:class:`CCompiler` class for the Borland C++ compiler. + + +:mod:`distutils.cygwincompiler` --- Cygwin Compiler +=================================================== + +.. module:: distutils.cygwinccompiler + + +This module provides the :class:`CygwinCCompiler` class, a subclass of +:class:`UnixCCompiler` that handles the Cygwin port of the GNU C compiler to +Windows. It also contains the Mingw32CCompiler class which handles the mingw32 +port of GCC (same as cygwin in no-cygwin mode). + + +:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler +=================================================== + +.. module:: distutils.emxccompiler + :synopsis: OS/2 EMX Compiler support + + +This module provides the EMXCCompiler class, a subclass of +:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2. + + +:mod:`distutils.mwerkscompiler` --- Metrowerks CodeWarrior support +================================================================== + +.. module:: distutils.mwerkscompiler + :synopsis: Metrowerks CodeWarrior support + + +Contains :class:`MWerksCompiler`, an implementation of the abstract +:class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X +Macintosh. Needs work to support CW on Windows or Mac OS X. + +.. % \subsection{Utility modules} +.. % +.. % The following modules all provide general utility functions. They haven't +.. % all been documented yet. + + +:mod:`distutils.archive_util` --- Archiving utilities +====================================================== + +.. module:: distutils.archive_util + :synopsis: Utility functions for creating archive files (tarballs, zip files, ...) + + +This module provides a few functions for creating archive files, such as +tarballs or zipfiles. + + +.. function:: make_archive(base_name, format[, root_dir=None, base_dir=None, verbose=0, dry_run=0]) + + Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of + the file to create, minus any format-specific extension; *format* is the + archive format: one of ``zip``, ``tar``, ``ztar``, or ``gztar``. *root_dir* is + a directory that will be the root directory of the archive; ie. we typically + ``chdir`` into *root_dir* before creating the archive. *base_dir* is the + directory where we start archiving from; ie. *base_dir* will be the common + prefix of all files and directories in the archive. *root_dir* and *base_dir* + both default to the current directory. Returns the name of the archive file. + + .. warning:: + + This should be changed to support bz2 files + + +.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) + + 'Create an (optional compressed) archive as a tar file from all files in and + under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``, + ``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named + by *compress* must be on the default program search path, so this is probably + Unix-specific. The output tar file will be named :file:`base_dir.tar`, + possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2` + or :file:`.Z`). Return the output filename. + + .. warning:: + + This should be replaced with calls to the :mod:`tarfile` module. + + +.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) + + Create a zip file from all files in and under *base_dir*. The output zip file + will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python + module (if available) or the InfoZIP :file:`zip` utility (if installed and + found on the default search path). If neither tool is available, raises + :exc:`DistutilsExecError`. Returns the name of the output zip file. + + +:mod:`distutils.dep_util` --- Dependency checking +================================================= + +.. module:: distutils.dep_util + :synopsis: Utility functions for simple dependency checking + + +This module provides functions for performing simple, timestamp-based +dependency of files and groups of files; also, functions based entirely on such +timestamp dependency analysis. + + +.. function:: newer(source, target) + + Return true if *source* exists and is more recently modified than *target*, or + if *source* exists and *target* doesn't. Return false if both exist and *target* + is the same age or newer than *source*. Raise :exc:`DistutilsFileError` if + *source* does not exist. + + +.. function:: newer_pairwise(sources, targets) + + Walk two filename lists in parallel, testing if each source is newer than its + corresponding target. Return a pair of lists (*sources*, *targets*) where + source is newer than target, according to the semantics of :func:`newer` + + .. % % equivalent to a listcomp... + + +.. function:: newer_group(sources, target[, missing='error']) + + Return true if *target* is out-of-date with respect to any file listed in + *sources* In other words, if *target* exists and is newer than every file in + *sources*, return false; otherwise return true. *missing* controls what we do + when a source file is missing; the default (``'error'``) is to blow up with an + :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently + drop any missing source files; if it is ``'newer'``, any missing source files + make us assume that *target* is out-of-date (this is handy in "dry-run" mode: + it'll make you pretend to carry out commands that wouldn't work because inputs + are missing, but that doesn't matter because you're not actually going to run + the commands). + + +:mod:`distutils.dir_util` --- Directory tree operations +======================================================= + +.. module:: distutils.dir_util + :synopsis: Utility functions for operating on directories and directory trees + + +This module provides functions for operating on directories and trees of +directories. + + +.. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0]) + + Create a directory and any missing ancestor directories. If the directory + already exists (or if *name* is the empty string, which means the current + directory, which of course exists), then do nothing. Raise + :exc:`DistutilsFileError` if unable to create some directory along the way (eg. + some sub-path exists, but is a file rather than a directory). If *verbose* is + true, print a one-line summary of each mkdir to stdout. Return the list of + directories actually created. + + +.. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0]) + + Create all the empty directories under *base_dir* needed to put *files* there. + *base_dir* is just the a name of a directory which doesn't necessarily exist + yet; *files* is a list of filenames to be interpreted relative to *base_dir*. + *base_dir* + the directory portion of every file in *files* will be created if + it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for + :func:`mkpath`. + + +.. function:: copy_tree(src, dst[, preserve_mode=1, preserve_times=1, preserve_symlinks=0, update=0, verbose=0, dry_run=0]) + + Copy an entire directory tree *src* to a new location *dst*. Both *src* and + *dst* must be directory names. If *src* is not a directory, raise + :exc:`DistutilsFileError`. If *dst* does not exist, it is created with + :func:`mkpath`. The end result of the copy is that every file in *src* is + copied to *dst*, and directories under *src* are recursively copied to *dst*. + Return the list of files that were copied or might have been copied, using their + output name. The return value is unaffected by *update* or *dry_run*: it is + simply the list of all files under *src*, with the names changed to be under + *dst*. + + *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in + :mod:`distutils.file_util`; note that they only apply to regular files, not to + directories. If *preserve_symlinks* is true, symlinks will be copied as + symlinks (on platforms that support them!); otherwise (the default), the + destination of the symlink will be copied. *update* and *verbose* are the same + as for :func:`copy_file`. + + +.. function:: remove_tree(directory[, verbose=0, dry_run=0]) + + Recursively remove *directory* and all files and directories underneath it. Any + errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is + true). + +**\*\*** Some of this could be replaced with the shutil module? **\*\*** + + +:mod:`distutils.file_util` --- Single file operations +===================================================== + +.. module:: distutils.file_util + :synopsis: Utility functions for operating on single files + + +This module contains some utility functions for operating on individual files. + + +.. function:: copy_file(src, dst[, preserve_mode=1, preserve_times=1, update=0, link=None, verbose=0, dry_run=0]) + + Copy file *src* to *dst*. If *dst* is a directory, then *src* is copied there + with the same name; otherwise, it must be a filename. (If the file exists, it + will be ruthlessly clobbered.) If *preserve_mode* is true (the default), the + file's mode (type and permission bits, or whatever is analogous on the + current platform) is copied. If *preserve_times* is true (the default), the + last-modified and last-access times are copied as well. If *update* is true, + *src* will only be copied if *dst* does not exist, or if *dst* does exist but + is older than *src*. + + *link* allows you to make hard links (using :func:`os.link`) or symbolic links + (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or + ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link* + on systems that don't support it: :func:`copy_file` doesn't check if hard or + symbolic linking is available. It uses :func:`_copy_file_contents` to copy file + contents. + + Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the + output file, and *copied* is true if the file was copied (or would have been + copied, if *dry_run* true). + + .. % XXX if the destination file already exists, we clobber it if + .. % copying, but blow up if linking. Hmmm. And I don't know what + .. % macostools.copyfile() does. Should definitely be consistent, and + .. % should probably blow up if destination exists and we would be + .. % changing it (ie. it's not already a hard/soft link to src OR + .. % (not update) and (src newer than dst)). + + +.. function:: move_file(src, dst[, verbose, dry_run]) + + Move file *src* to *dst*. If *dst* is a directory, the file will be moved into + it with the same name; otherwise, *src* is just renamed to *dst*. Returns the + new full name of the file. + + .. warning:: + + Handles cross-device moves on Unix using :func:`copy_file`. What about other + systems??? + + +.. function:: write_file(filename, contents) + + Create a file called *filename* and write *contents* (a sequence of strings + without line terminators) to it. + + +:mod:`distutils.util` --- Miscellaneous other utility functions +=============================================================== + +.. module:: distutils.util + :synopsis: Miscellaneous other utility functions + + +This module contains other assorted bits and pieces that don't fit into any +other utility module. + + +.. function:: get_platform() + + Return a string that identifies the current platform. This is used mainly to + distinguish platform-specific build directories and platform-specific built + distributions. Typically includes the OS name and version and the architecture + (as supplied by 'os.uname()'), although the exact information included depends + on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only + runs on SGI hardware), but for Linux the kernel version isn't particularly + important. + + Examples of returned values: + + * ``linux-i586`` + * ``linux-alpha`` + * ``solaris-2.6-sun4u`` + * ``irix-5.3`` + * ``irix64-6.2`` + + For non-POSIX platforms, currently just returns ``sys.platform``. + + .. % XXX isn't this also provided by some other non-distutils module? + + +.. function:: convert_path(pathname) + + Return 'pathname' as a name that will work on the native filesystem, i.e. split + it on '/' and put it back together again using the current directory separator. + Needed because filenames in the setup script are always supplied in Unix style, + and have to be converted to the local convention before we can actually use them + in the filesystem. Raises :exc:`ValueError` on non-Unix-ish systems if + *pathname* either starts or ends with a slash. + + +.. function:: change_root(new_root, pathname) + + Return *pathname* with *new_root* prepended. If *pathname* is relative, this is + equivalent to ``os.path.join(new_root,pathname)`` Otherwise, it requires making + *pathname* relative and then joining the two, which is tricky on DOS/Windows. + + +.. function:: check_environ() + + Ensure that 'os.environ' has all the environment variables we guarantee that + users can use in config files, command-line options, etc. Currently this + includes: + + * :envvar:`HOME` - user's home directory (Unix only) + * :envvar:`PLAT` - description of the current platform, including hardware and + OS (see :func:`get_platform`) + + +.. function:: subst_vars(s, local_vars) + + Perform shell/Perl-style variable substitution on *s*. Every occurrence of + ``$`` followed by a name is considered a variable, and variable is substituted + by the value found in the *local_vars* dictionary, or in ``os.environ`` if it's + not in *local_vars*. *os.environ* is first checked/augmented to guarantee that + it contains certain values: see :func:`check_environ`. Raise :exc:`ValueError` + for any variables not found in either *local_vars* or ``os.environ``. + + Note that this is not a fully-fledged string interpolation function. A valid + ``$variable`` can consist only of upper and lower case letters, numbers and an + underscore. No { } or ( ) style quoting is available. + + +.. function:: grok_environment_error(exc[, prefix='error: ']) + + Generate a useful error message from an :exc:`EnvironmentError` (:exc:`IOError` + or :exc:`OSError`) exception object. Handles Python 1.5.1 and later styles, + and does what it can to deal with exception objects that don't have a filename + (which happens when the error is due to a two-file operation, such as + :func:`rename` or :func:`link`). Returns the error message as a string + prefixed with *prefix*. + + +.. function:: split_quoted(s) + + Split a string up according to Unix shell-like rules for quotes and backslashes. + In short: words are delimited by spaces, as long as those spaces are not escaped + by a backslash, or inside a quoted string. Single and double quotes are + equivalent, and the quote characters can be backslash-escaped. The backslash is + stripped from any two-character escape sequence, leaving only the escaped + character. The quote characters are stripped from any quoted string. Returns a + list of words. + + .. % Should probably be moved into the standard library. + + +.. function:: execute(func, args[, msg=None, verbose=0, dry_run=0]) + + Perform some action that affects the outside world (for instance, writing to the + filesystem). Such actions are special because they are disabled by the + *dry_run* flag. This method takes care of all that bureaucracy for you; all + you have to do is supply the function to call and an argument tuple for it (to + embody the "external action" being performed), and an optional message to print. + + +.. function:: strtobool(val) + + Convert a string representation of truth to true (1) or false (0). + + True values are ``y``, ``yes``, ``t``, ``true``, ``on`` and ``1``; false values + are ``n``, ``no``, ``f``, ``false``, ``off`` and ``0``. Raises + :exc:`ValueError` if *val* is anything else. + + +.. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None]) + + Byte-compile a collection of Python source files to either :file:`.pyc` or + :file:`.pyo` files in the same directory. *py_files* is a list of files to + compile; any files that don't end in :file:`.py` are silently skipped. + *optimize* must be one of the following: + + * ``0`` - don't optimize (generate :file:`.pyc`) + * ``1`` - normal optimization (like ``python -O``) + * ``2`` - extra optimization (like ``python -OO``) + + If *force* is true, all files are recompiled regardless of timestamps. + + The source filename encoded in each bytecode file defaults to the filenames + listed in *py_files*; you can modify these with *prefix* and *basedir*. + *prefix* is a string that will be stripped off of each source filename, and + *base_dir* is a directory name that will be prepended (after *prefix* is + stripped). You can supply either or both (or neither) of *prefix* and + *base_dir*, as you wish. + + If *dry_run* is true, doesn't actually do anything that would affect the + filesystem. + + Byte-compilation is either done directly in this interpreter process with the + standard :mod:`py_compile` module, or indirectly by writing a temporary script + and executing it. Normally, you should let :func:`byte_compile` figure out to + use direct compilation or not (see the source for details). The *direct* flag + is used by the script generated in indirect mode; unless you know what you're + doing, leave it set to ``None``. + + +.. function:: rfc822_escape(header) + + Return a version of *header* escaped for inclusion in an :rfc:`822` header, by + ensuring there are 8 spaces space after each newline. Note that it does no other + modification of the string. + + .. % this _can_ be replaced + +.. % \subsection{Distutils objects} + + +:mod:`distutils.dist` --- The Distribution class +================================================ + +.. module:: distutils.dist + :synopsis: Provides the Distribution class, which represents the module distribution being + built/installed/distributed + + +This module provides the :class:`Distribution` class, which represents the +module distribution being built/installed/distributed. + + +:mod:`distutils.extension` --- The Extension class +================================================== + +.. module:: distutils.extension + :synopsis: Provides the Extension class, used to describe C/C++ extension modules in setup + scripts + + +This module provides the :class:`Extension` class, used to describe C/C++ +extension modules in setup scripts. + +.. % \subsection{Ungrouped modules} +.. % The following haven't been moved into a more appropriate section yet. + + +:mod:`distutils.debug` --- Distutils debug mode +=============================================== + +.. module:: distutils.debug + :synopsis: Provides the debug flag for distutils + + +This module provides the DEBUG flag. + + +:mod:`distutils.errors` --- Distutils exceptions +================================================ + +.. module:: distutils.errors + :synopsis: Provides standard distutils exceptions + + +Provides exceptions used by the Distutils modules. Note that Distutils modules +may raise standard exceptions; in particular, SystemExit is usually raised for +errors that are obviously the end-user's fault (eg. bad command-line arguments). + +This module is safe to use in ``from ... import *`` mode; it only exports +symbols whose names start with ``Distutils`` and end with ``Error``. + + +:mod:`distutils.fancy_getopt` --- Wrapper around the standard getopt module +=========================================================================== + +.. module:: distutils.fancy_getopt + :synopsis: Additional getopt functionality + + +This module provides a wrapper around the standard :mod:`getopt` module that +provides the following additional features: + +* short and long options are tied together + +* options have help strings, so :func:`fancy_getopt` could potentially create a + complete usage summary + +* options set attributes of a passed-in object + +* boolean options can have "negative aliases" --- eg. if :option:`--quiet` is + the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the + command line sets *verbose* to false. + +**\*\*** Should be replaced with :mod:`optik` (which is also now known as +:mod:`optparse` in Python 2.3 and later). **\*\*** + + +.. function:: fancy_getopt(options, negative_opt, object, args) + + Wrapper function. *options* is a list of ``(long_option, short_option, + help_string)`` 3-tuples as described in the constructor for + :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names + to option names, both the key and value should be in the *options* list. + *object* is an object which will be used to store values (see the :meth:`getopt` + method of the :class:`FancyGetopt` class). *args* is the argument list. Will use + ``sys.argv[1:]`` if you pass ``None`` as *args*. + + +.. function:: wrap_text(text, width) + + Wraps *text* to less than *width* wide. + + .. warning:: + + Should be replaced with :mod:`textwrap` (which is available in Python 2.3 and + later). + + +.. class:: FancyGetopt([option_table=None]) + + The option_table is a list of 3-tuples: ``(long_option, short_option, + help_string)`` + + If an option takes an argument, its *long_option* should have ``'='`` appended; + *short_option* should just be a single character, no ``':'`` in any case. + *short_option* should be ``None`` if a *long_option* doesn't have a + corresponding *short_option*. All option tuples must have long options. + +The :class:`FancyGetopt` class provides the following methods: + + +.. method:: FancyGetopt.getopt([args=None, object=None]) + + Parse command-line options in args. Store as attributes on *object*. + + If *args* is ``None`` or not supplied, uses ``sys.argv[1:]``. If *object* is + ``None`` or not supplied, creates a new :class:`OptionDummy` instance, stores + option values there, and returns a tuple ``(args, object)``. If *object* is + supplied, it is modified in place and :func:`getopt` just returns *args*; in + both cases, the returned *args* is a modified copy of the passed-in *args* list, + which is left untouched. + + .. % and args returned are? + + +.. method:: FancyGetopt.get_option_order() + + Returns the list of ``(option, value)`` tuples processed by the previous run of + :meth:`getopt` Raises :exc:`RuntimeError` if :meth:`getopt` hasn't been called + yet. + + +.. method:: FancyGetopt.generate_help([header=None]) + + Generate help text (a list of strings, one per suggested line of output) from + the option table for this :class:`FancyGetopt` object. + + If supplied, prints the supplied *header* at the top of the help. + + +:mod:`distutils.filelist` --- The FileList class +================================================ + +.. module:: distutils.filelist + :synopsis: The FileList class, used for poking about the file system and building lists of + files. + + +This module provides the :class:`FileList` class, used for poking about the +filesystem and building lists of files. + + +:mod:`distutils.log` --- Simple PEP 282-style logging +===================================================== + +.. module:: distutils.log + :synopsis: A simple logging mechanism, 282-style + + +.. warning:: + + Should be replaced with standard :mod:`logging` module. + +.. % \subsubsection{\module{} --- } +.. % \declaremodule{standard}{distutils.magic} +.. % \modulesynopsis{ } + + +:mod:`distutils.spawn` --- Spawn a sub-process +============================================== + +.. module:: distutils.spawn + :synopsis: Provides the spawn() function + + +This module provides the :func:`spawn` function, a front-end to various +platform-specific functions for launching another program in a sub-process. +Also provides :func:`find_executable` to search the path for a given executable +name. + + +:mod:`distutils.sysconfig` --- System configuration information +=============================================================== + +.. module:: distutils.sysconfig + :synopsis: Low-level access to configuration information of the Python interpreter. +.. moduleauthor:: Fred L. Drake, Jr. +.. moduleauthor:: Greg Ward +.. sectionauthor:: Fred L. Drake, Jr. + + +The :mod:`distutils.sysconfig` module provides access to Python's low-level +configuration information. The specific configuration variables available +depend heavily on the platform and configuration. The specific variables depend +on the build process for the specific version of Python being run; the variables +are those found in the :file:`Makefile` and configuration header that are +installed with Python on Unix systems. The configuration header is called +:file:`pyconfig.h` for Python versions starting with 2.2, and :file:`config.h` +for earlier versions of Python. + +Some additional functions are provided which perform some useful manipulations +for other parts of the :mod:`distutils` package. + + +.. data:: PREFIX + + The result of ``os.path.normpath(sys.prefix)``. + + +.. data:: EXEC_PREFIX + + The result of ``os.path.normpath(sys.exec_prefix)``. + + +.. function:: get_config_var(name) + + Return the value of a single variable. This is equivalent to + ``get_config_vars().get(name)``. + + +.. function:: get_config_vars(...) + + Return a set of variable definitions. If there are no arguments, this returns a + dictionary mapping names of configuration variables to values. If arguments are + provided, they should be strings, and the return value will be a sequence giving + the associated values. If a given name does not have a corresponding value, + ``None`` will be included for that variable. + + +.. function:: get_config_h_filename() + + Return the full path name of the configuration header. For Unix, this will be + the header generated by the :program:`configure` script; for other platforms the + header will have been supplied directly by the Python source distribution. The + file is a platform-specific text file. + + +.. function:: get_makefile_filename() + + Return the full path name of the :file:`Makefile` used to build Python. For + Unix, this will be a file generated by the :program:`configure` script; the + meaning for other platforms will vary. The file is a platform-specific text + file, if it exists. This function is only useful on POSIX platforms. + + +.. function:: get_python_inc([plat_specific[, prefix]]) + + Return the directory for either the general or platform-dependent C include + files. If *plat_specific* is true, the platform-dependent include directory is + returned; if false or omitted, the platform-independent directory is returned. + If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. + + +.. function:: get_python_lib([plat_specific[, standard_lib[, prefix]]]) + + Return the directory for either the general or platform-dependent library + installation. If *plat_specific* is true, the platform-dependent include + directory is returned; if false or omitted, the platform-independent directory + is returned. If *prefix* is given, it is used as either the prefix instead of + :const:`PREFIX`, or as the exec-prefix instead of :const:`EXEC_PREFIX` if + *plat_specific* is true. If *standard_lib* is true, the directory for the + standard library is returned rather than the directory for the installation of + third-party extensions. + +The following function is only intended for use within the :mod:`distutils` +package. + + +.. function:: customize_compiler(compiler) + + Do any platform-specific customization of a + :class:`distutils.ccompiler.CCompiler` instance. + + This function is only needed on Unix at this time, but should be called + consistently to support forward-compatibility. It inserts the information that + varies across Unix flavors and is stored in Python's :file:`Makefile`. This + information includes the selected compiler, compiler and linker options, and the + extension used by the linker for shared objects. + +This function is even more special-purpose, and should only be used from +Python's own build procedures. + + +.. function:: set_python_build() + + Inform the :mod:`distutils.sysconfig` module that it is being used as part of + the build process for Python. This changes a lot of relative locations for + files, allowing them to be located in the build area rather than in an installed + Python. + + +:mod:`distutils.text_file` --- The TextFile class +================================================= + +.. module:: distutils.text_file + :synopsis: provides the TextFile class, a simple interface to text files + + +This module provides the :class:`TextFile` class, which gives an interface to +text files that (optionally) takes care of stripping comments, ignoring blank +lines, and joining lines with backslashes. + + +.. class:: TextFile([filename=None, file=None, **options]) + + This class provides a file-like object that takes care of all the things you + commonly want to do when processing a text file that has some line-by-line + syntax: strip comments (as long as ``#`` is your comment character), skip blank + lines, join adjacent lines by escaping the newline (ie. backslash at end of + line), strip leading and/or trailing whitespace. All of these are optional and + independently controllable. + + The class provides a :meth:`warn` method so you can generate warning messages + that report physical line number, even if the logical line in question spans + multiple physical lines. Also provides :meth:`unreadline` for implementing + line-at-a-time lookahead. + + :class:`TextFile` instances are create with either *filename*, *file*, or both. + :exc:`RuntimeError` is raised if both are ``None``. *filename* should be a + string, and *file* a file object (or something that provides :meth:`readline` + and :meth:`close` methods). It is recommended that you supply at least + *filename*, so that :class:`TextFile` can include it in warning messages. If + *file* is not supplied, :class:`TextFile` creates its own using the + :func:`open` built-in function. + + The options are all boolean, and affect the values returned by :meth:`readline` + + +------------------+--------------------------------+---------+ + | option name | description | default | + +==================+================================+=========+ + | *strip_comments* | strip from ``'#'`` to end-of- | true | + | | line, as well as any | | + | | whitespace leading up to the | | + | | ``'#'``\ ---unless it is | | + | | escaped by a backslash | | + +------------------+--------------------------------+---------+ + | *lstrip_ws* | strip leading whitespace from | false | + | | each line before returning it | | + +------------------+--------------------------------+---------+ + | *rstrip_ws* | strip trailing whitespace | true | + | | (including line terminator!) | | + | | from each line before | | + | | returning it. | | + +------------------+--------------------------------+---------+ + | *skip_blanks* | skip lines that are empty | true | + | | \*after\* stripping comments | | + | | and whitespace. (If both | | + | | lstrip_ws and rstrip_ws are | | + | | false, then some lines may | | + | | consist of solely whitespace: | | + | | these will \*not\* be skipped, | | + | | even if *skip_blanks* is | | + | | true.) | | + +------------------+--------------------------------+---------+ + | *join_lines* | if a backslash is the last | false | + | | non-newline character on a | | + | | line after stripping comments | | + | | and whitespace, join the | | + | | following line to it to form | | + | | one logical line; if N | | + | | consecutive lines end with a | | + | | backslash, then N+1 physical | | + | | lines will be joined to form | | + | | one logical line. | | + +------------------+--------------------------------+---------+ + | *collapse_join* | strip leading whitespace from | false | + | | lines that are joined to their | | + | | predecessor; only matters if | | + | | ``(join_lines and not | | + | | lstrip_ws)`` | | + +------------------+--------------------------------+---------+ + + Note that since *rstrip_ws* can strip the trailing newline, the semantics of + :meth:`readline` must differ from those of the builtin file object's + :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for + end-of-file: an empty string might just be a blank line (or an all-whitespace + line), if *rstrip_ws* is true but *skip_blanks* is not. + + + .. method:: TextFile.open(filename) + + Open a new file *filename*. This overrides any *file* or *filename* constructor + arguments. + + + .. method:: TextFile.close() + + Close the current file and forget everything we know about it (including the + filename and the current line number). + + + .. method:: TextFile.warn(msg[,line=None]) + + Print (to stderr) a warning message tied to the current logical line in the + current file. If the current logical line in the file spans multiple physical + lines, the warning refers to the whole range, such as ``"lines 3-5"``. If + *line* is supplied, it overrides the current line number; it may be a list or + tuple to indicate a range of physical lines, or an integer for a single + physical line. + + + .. method:: TextFile.readline() + + Read and return a single logical line from the current file (or from an internal + buffer if lines have previously been "unread" with :meth:`unreadline`). If the + *join_lines* option is true, this may involve reading multiple physical lines + concatenated into a single string. Updates the current line number, so calling + :meth:`warn` after :meth:`readline` emits a warning about the physical line(s) + just read. Returns ``None`` on end-of-file, since the empty string can occur + if *rstrip_ws* is true but *strip_blanks* is not. + + + .. method:: TextFile.readlines() + + Read and return the list of all logical lines remaining in the current file. + This updates the current line number to the last line of the file. + + + .. method:: TextFile.unreadline(line) + + Push *line* (a string) onto an internal buffer that will be checked by future + :meth:`readline` calls. Handy for implementing a parser with line-at-a-time + lookahead. Note that lines that are "unread" with :meth:`unreadline` are not + subsequently re-cleansed (whitespace stripped, or whatever) when read with + :meth:`readline`. If multiple calls are made to :meth:`unreadline` before a call + to :meth:`readline`, the lines will be returned most in most recent first order. + + +:mod:`distutils.version` --- Version number classes +=================================================== + +.. module:: distutils.version + :synopsis: implements classes that represent module version numbers. + + +.. % todo +.. % \section{Distutils Commands} +.. % +.. % This part of Distutils implements the various Distutils commands, such +.. % as \code{build}, \code{install} \&c. Each command is implemented as a +.. % separate module, with the command name as the name of the module. + + +:mod:`distutils.cmd` --- Abstract base class for Distutils commands +=================================================================== + +.. module:: distutils.cmd + :synopsis: This module provides the abstract base class Command. This class is subclassed + by the modules in the distutils.command subpackage. + + +This module supplies the abstract base class :class:`Command`. + + +.. class:: Command(dist) + + Abstract base class for defining command classes, the "worker bees" of the + Distutils. A useful analogy for command classes is to think of them as + subroutines with local variables called *options*. The options are declared in + :meth:`initialize_options` and defined (given their final values) in + :meth:`finalize_options`, both of which must be defined by every command class. + The distinction between the two is necessary because option values might come + from the outside world (command line, config file, ...), and any options + dependent on other options must be computed after these outside influences have + been processed --- hence :meth:`finalize_options`. The body of the subroutine, + where it does all its work based on the values of its options, is the + :meth:`run` method, which must also be implemented by every command class. + + The class constructor takes a single argument *dist*, a :class:`Distribution` + instance. + + +:mod:`distutils.command` --- Individual Distutils commands +========================================================== + +.. module:: distutils.command + :synopsis: This subpackage contains one module for each standard Distutils command. + + +.. % \subsubsection{Individual Distutils commands} +.. % todo + + +:mod:`distutils.command.bdist` --- Build a binary installer +=========================================================== + +.. module:: distutils.command.bdist + :synopsis: Build a binary installer for a package + + +.. % todo + + +:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers +============================================================================= + +.. module:: distutils.command.bdist_packager + :synopsis: Abstract base class for packagers + + +.. % todo + + +:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer +================================================================ + +.. module:: distutils.command.bdist_dumb + :synopsis: Build a "dumb" installer - a simple archive of files + + +.. % todo + + +:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package +================================================================================= + +.. module:: distutils.command.bdist_msi + :synopsis: Build a binary distribution as a Windows MSI file + + +.. % todo + + +:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM +=========================================================================================== + +.. module:: distutils.command.bdist_rpm + :synopsis: Build a binary distribution as a Redhat RPM and SRPM + + +.. % todo + + +:mod:`distutils.command.bdist_wininst` --- Build a Windows installer +==================================================================== + +.. module:: distutils.command.bdist_wininst + :synopsis: Build a Windows installer + + +.. % todo + + +:mod:`distutils.command.sdist` --- Build a source distribution +============================================================== + +.. module:: distutils.command.sdist + :synopsis: Build a source distribution + + +.. % todo + + +:mod:`distutils.command.build` --- Build all files of a package +=============================================================== + +.. module:: distutils.command.build + :synopsis: Build all files of a package + + +.. % todo + + +:mod:`distutils.command.build_clib` --- Build any C libraries in a package +========================================================================== + +.. module:: distutils.command.build_clib + :synopsis: Build any C libraries in a package + + +.. % todo + + +:mod:`distutils.command.build_ext` --- Build any extensions in a package +======================================================================== + +.. module:: distutils.command.build_ext + :synopsis: Build any extensions in a package + + +.. % todo + + +:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package +=========================================================================== + +.. module:: distutils.command.build_py + :synopsis: Build the .py/.pyc files of a package + + +.. % todo + + +:mod:`distutils.command.build_scripts` --- Build the scripts of a package +========================================================================= + +.. module:: distutils.command.build_scripts + :synopsis: Build the scripts of a package + + +.. % todo + + +:mod:`distutils.command.clean` --- Clean a package build area +============================================================= + +.. module:: distutils.command.clean + :synopsis: Clean a package build area + + +.. % todo + + +:mod:`distutils.command.config` --- Perform package configuration +================================================================= + +.. module:: distutils.command.config + :synopsis: Perform package configuration + + +.. % todo + + +:mod:`distutils.command.install` --- Install a package +====================================================== + +.. module:: distutils.command.install + :synopsis: Install a package + + +.. % todo + + +:mod:`distutils.command.install_data` --- Install data files from a package +=========================================================================== + +.. module:: distutils.command.install_data + :synopsis: Install data files from a package + + +.. % todo + + +:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package +====================================================================================== + +.. module:: distutils.command.install_headers + :synopsis: Install C/C++ header files from a package + + +.. % todo + + +:mod:`distutils.command.install_lib` --- Install library files from a package +============================================================================= + +.. module:: distutils.command.install_lib + :synopsis: Install library files from a package + + +.. % todo + + +:mod:`distutils.command.install_scripts` --- Install script files from a package +================================================================================ + +.. module:: distutils.command.install_scripts + :synopsis: Install script files from a package + + +.. % todo + + +:mod:`distutils.command.register` --- Register a module with the Python Package Index +===================================================================================== + +.. module:: distutils.command.register + :synopsis: Register a module with the Python Package Index + + +The ``register`` command registers the package with the Python Package Index. +This is described in more detail in :pep:`301`. + +.. % todo + + +Creating a new Distutils command +================================ + +This section outlines the steps to create a new Distutils command. + +A new command lives in a module in the :mod:`distutils.command` package. There +is a sample template in that directory called :file:`command_template`. Copy +this file to a new module with the same name as the new command you're +implementing. This module should implement a class with the same name as the +module (and the command). So, for instance, to create the command +``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy +:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit +it so that it's implementing the class :class:`peel_banana`, a subclass of +:class:`distutils.cmd.Command`. + +Subclasses of :class:`Command` must define the following methods. + + +.. method:: Command.initialize_options()(S) + + et default values for all the options that this command supports. Note that + these defaults may be overridden by other commands, by the setup script, by + config files, or by the command-line. Thus, this is not the place to code + dependencies between options; generally, :meth:`initialize_options` + implementations are just a bunch of ``self.foo = None`` assignments. + + +.. method:: Command.finalize_options() + + Set final values for all the options that this command supports. This is + always called as late as possible, ie. after any option assignments from the + command-line or from other commands have been done. Thus, this is the place + to to code option dependencies: if *foo* depends on *bar*, then it is safe to + set *foo* from *bar* as long as *foo* still has the same value it was + assigned in :meth:`initialize_options`. + + +.. method:: Command.run() + + A command's raison d'etre: carry out the action it exists to perform, controlled + by the options initialized in :meth:`initialize_options`, customized by other + commands, the setup script, the command-line, and config files, and finalized in + :meth:`finalize_options`. All terminal output and filesystem interaction should + be done by :meth:`run`. + +*sub_commands* formalizes the notion of a "family" of commands, eg. ``install`` +as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The +parent of a family of commands defines *sub_commands* as a class attribute; it's +a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string +and *predicate* an unbound method, a string or None. *predicate* is a method of +the parent command that determines whether the corresponding command is +applicable in the current situation. (Eg. we ``install_headers`` is only +applicable if we have any C header files to install.) If *predicate* is None, +that command is always applicable. + +*sub_commands* is usually defined at the \*end\* of a class, because predicates +can be unbound methods, so they must already have been defined. The canonical +example is the :command:`install` command. diff --git a/builtdist.rst b/builtdist.rst new file mode 100644 index 0000000000..b40ddeb369 --- /dev/null +++ b/builtdist.rst @@ -0,0 +1,405 @@ +.. _built-dist: + +**************************** +Creating Built Distributions +**************************** + +A "built distribution" is what you're probably used to thinking of either as a +"binary package" or an "installer" (depending on your background). It's not +necessarily binary, though, because it might contain only Python source code +and/or byte-code; and we don't call it a package, because that word is already +spoken for in Python. (And "installer" is a term specific to the world of +mainstream desktop systems.) + +A built distribution is how you make life as easy as possible for installers of +your module distribution: for users of RPM-based Linux systems, it's a binary +RPM; for Windows users, it's an executable installer; for Debian-based Linux +users, it's a Debian package; and so forth. Obviously, no one person will be +able to create built distributions for every platform under the sun, so the +Distutils are designed to enable module developers to concentrate on their +specialty---writing code and creating source distributions---while an +intermediary species called *packagers* springs up to turn source distributions +into built distributions for as many platforms as there are packagers. + +Of course, the module developer could be his own packager; or the packager could +be a volunteer "out there" somewhere who has access to a platform which the +original developer does not; or it could be software periodically grabbing new +source distributions and turning them into built distributions for as many +platforms as the software has access to. Regardless of who they are, a packager +uses the setup script and the :command:`bdist` command family to generate built +distributions. + +As a simple example, if I run the following command in the Distutils source +tree:: + + python setup.py bdist + +then the Distutils builds my module distribution (the Distutils itself in this +case), does a "fake" installation (also in the :file:`build` directory), and +creates the default type of built distribution for my platform. The default +format for built distributions is a "dumb" tar file on Unix, and a simple +executable installer on Windows. (That tar file is considered "dumb" because it +has to be unpacked in a specific location to work.) + +Thus, the above command on a Unix system creates +:file:`Distutils-1.0.{plat}.tar.gz`; unpacking this tarball from the right place +installs the Distutils just as though you had downloaded the source distribution +and run ``python setup.py install``. (The "right place" is either the root of +the filesystem or Python's :file:`{prefix}` directory, depending on the options +given to the :command:`bdist_dumb` command; the default is to make dumb +distributions relative to :file:`{prefix}`.) + +Obviously, for pure Python distributions, this isn't any simpler than just +running ``python setup.py install``\ ---but for non-pure distributions, which +include extensions that would need to be compiled, it can mean the difference +between someone being able to use your extensions or not. And creating "smart" +built distributions, such as an RPM package or an executable installer for +Windows, is far more convenient for users even if your distribution doesn't +include any extensions. + +The :command:`bdist` command has a :option:`--formats` option, similar to the +:command:`sdist` command, which you can use to select the types of built +distribution to generate: for example, :: + + python setup.py bdist --format=zip + +would, when run on a Unix system, create :file:`Distutils-1.0.{plat}.zip`\ +---again, this archive would be unpacked from the root directory to install the +Distutils. + +The available formats for built distributions are: + ++-------------+------------------------------+---------+ +| Format | Description | Notes | ++=============+==============================+=========+ +| ``gztar`` | gzipped tar file | (1),(3) | +| | (:file:`.tar.gz`) | | ++-------------+------------------------------+---------+ +| ``ztar`` | compressed tar file | \(3) | +| | (:file:`.tar.Z`) | | ++-------------+------------------------------+---------+ +| ``tar`` | tar file (:file:`.tar`) | \(3) | ++-------------+------------------------------+---------+ +| ``zip`` | zip file (:file:`.zip`) | \(4) | ++-------------+------------------------------+---------+ +| ``rpm`` | RPM | \(5) | ++-------------+------------------------------+---------+ +| ``pkgtool`` | Solaris :program:`pkgtool` | | ++-------------+------------------------------+---------+ +| ``sdux`` | HP-UX :program:`swinstall` | | ++-------------+------------------------------+---------+ +| ``rpm`` | RPM | \(5) | ++-------------+------------------------------+---------+ +| ``wininst`` | self-extracting ZIP file for | (2),(4) | +| | Windows | | ++-------------+------------------------------+---------+ + +Notes: + +(1) + default on Unix + +(2) + default on Windows + + **\*\*** to-do! **\*\*** + +(3) + requires external utilities: :program:`tar` and possibly one of :program:`gzip`, + :program:`bzip2`, or :program:`compress` + +(4) + requires either external :program:`zip` utility or :mod:`zipfile` module (part + of the standard Python library since Python 1.6) + +(5) + requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm + --version`` to find out which version you have) + +You don't have to use the :command:`bdist` command with the :option:`--formats` +option; you can also use the command that directly implements the format you're +interested in. Some of these :command:`bdist` "sub-commands" actually generate +several similar formats; for instance, the :command:`bdist_dumb` command +generates all the "dumb" archive formats (``tar``, ``ztar``, ``gztar``, and +``zip``), and :command:`bdist_rpm` generates both binary and source RPMs. The +:command:`bdist` sub-commands, and the formats generated by each, are: + ++--------------------------+-----------------------+ +| Command | Formats | ++==========================+=======================+ +| :command:`bdist_dumb` | tar, ztar, gztar, zip | ++--------------------------+-----------------------+ +| :command:`bdist_rpm` | rpm, srpm | ++--------------------------+-----------------------+ +| :command:`bdist_wininst` | wininst | ++--------------------------+-----------------------+ + +The following sections give details on the individual :command:`bdist_\*` +commands. + + +.. _creating-dumb: + +Creating dumb built distributions +================================= + +**\*\*** Need to document absolute vs. prefix-relative packages here, but first +I have to implement it! **\*\*** + + +.. _creating-rpms: + +Creating RPM packages +===================== + +The RPM format is used by many popular Linux distributions, including Red Hat, +SuSE, and Mandrake. If one of these (or any of the other RPM-based Linux +distributions) is your usual environment, creating RPM packages for other users +of that same distribution is trivial. Depending on the complexity of your module +distribution and differences between Linux distributions, you may also be able +to create RPMs that work on different RPM-based distributions. + +The usual way to create an RPM of your module distribution is to run the +:command:`bdist_rpm` command:: + + python setup.py bdist_rpm + +or the :command:`bdist` command with the :option:`--format` option:: + + python setup.py bdist --formats=rpm + +The former allows you to specify RPM-specific options; the latter allows you to +easily specify multiple formats in one run. If you need to do both, you can +explicitly specify multiple :command:`bdist_\*` commands and their options:: + + python setup.py bdist_rpm --packager="John Doe " \ + bdist_wininst --target_version="2.0" + +Creating RPM packages is driven by a :file:`.spec` file, much as using the +Distutils is driven by the setup script. To make your life easier, the +:command:`bdist_rpm` command normally creates a :file:`.spec` file based on the +information you supply in the setup script, on the command line, and in any +Distutils configuration files. Various options and sections in the +:file:`.spec` file are derived from options in the setup script as follows: + ++------------------------------------------+----------------------------------------------+ +| RPM :file:`.spec` file option or section | Distutils setup script option | ++==========================================+==============================================+ +| Name | :option:`name` | ++------------------------------------------+----------------------------------------------+ +| Summary (in preamble) | :option:`description` | ++------------------------------------------+----------------------------------------------+ +| Version | :option:`version` | ++------------------------------------------+----------------------------------------------+ +| Vendor | :option:`author` and :option:`author_email`, | +| | or --- & :option:`maintainer` and | +| | :option:`maintainer_email` | ++------------------------------------------+----------------------------------------------+ +| Copyright | :option:`licence` | ++------------------------------------------+----------------------------------------------+ +| Url | :option:`url` | ++------------------------------------------+----------------------------------------------+ +| %description (section) | :option:`long_description` | ++------------------------------------------+----------------------------------------------+ + +Additionally, there are many options in :file:`.spec` files that don't have +corresponding options in the setup script. Most of these are handled through +options to the :command:`bdist_rpm` command as follows: + ++-------------------------------+-----------------------------+-------------------------+ +| RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value | +| or section | | | ++===============================+=============================+=========================+ +| Release | :option:`release` | "1" | ++-------------------------------+-----------------------------+-------------------------+ +| Group | :option:`group` | "Development/Libraries" | ++-------------------------------+-----------------------------+-------------------------+ +| Vendor | :option:`vendor` | (see above) | ++-------------------------------+-----------------------------+-------------------------+ +| Packager | :option:`packager` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Provides | :option:`provides` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Requires | :option:`requires` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Conflicts | :option:`conflicts` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Obsoletes | :option:`obsoletes` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Distribution | :option:`distribution_name` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| BuildRequires | :option:`build_requires` | (none) | ++-------------------------------+-----------------------------+-------------------------+ +| Icon | :option:`icon` | (none) | ++-------------------------------+-----------------------------+-------------------------+ + +Obviously, supplying even a few of these options on the command-line would be +tedious and error-prone, so it's usually best to put them in the setup +configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If +you distribute or package many Python module distributions, you might want to +put options that apply to all of them in your personal Distutils configuration +file (:file:`~/.pydistutils.cfg`). + +There are three steps to building a binary RPM package, all of which are +handled automatically by the Distutils: + +#. create a :file:`.spec` file, which describes the package (analogous to the + Distutils setup script; in fact, much of the information in the setup script + winds up in the :file:`.spec` file) + +#. create the source RPM + +#. create the "binary" RPM (which may or may not contain binary code, depending + on whether your module distribution contains Python extensions) + +Normally, RPM bundles the last two steps together; when you use the Distutils, +all three steps are typically bundled together. + +If you wish, you can separate these three steps. You can use the +:option:`--spec-only` option to make :command:`bdist_rpm` just create the +:file:`.spec` file and exit; in this case, the :file:`.spec` file will be +written to the "distribution directory"---normally :file:`dist/`, but +customizable with the :option:`--dist-dir` option. (Normally, the :file:`.spec` +file winds up deep in the "build tree," in a temporary directory created by +:command:`bdist_rpm`.) + +.. % \XXX{this isn't implemented yet---is it needed?!} +.. % You can also specify a custom \file{.spec} file with the +.. % \longprogramopt{spec-file} option; used in conjunction with +.. % \longprogramopt{spec-only}, this gives you an opportunity to customize +.. % the \file{.spec} file manually: +.. % +.. % \ begin{verbatim} +.. % > python setup.py bdist_rpm --spec-only +.. % # ...edit dist/FooBar-1.0.spec +.. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec +.. % \ end{verbatim} +.. % +.. % (Although a better way to do this is probably to override the standard +.. % \command{bdist\_rpm} command with one that writes whatever else you want +.. % to the \file{.spec} file.) + + +.. _creating-wininst: + +Creating Windows Installers +=========================== + +Executable installers are the natural format for binary distributions on +Windows. They display a nice graphical user interface, display some information +about the module distribution to be installed taken from the metadata in the +setup script, let the user select a few options, and start or cancel the +installation. + +Since the metadata is taken from the setup script, creating Windows installers +is usually as easy as running:: + + python setup.py bdist_wininst + +or the :command:`bdist` command with the :option:`--formats` option:: + + python setup.py bdist --formats=wininst + +If you have a pure module distribution (only containing pure Python modules and +packages), the resulting installer will be version independent and have a name +like :file:`foo-1.0.win32.exe`. These installers can even be created on Unix or +Mac OS platforms. + +If you have a non-pure distribution, the extensions can only be created on a +Windows platform, and will be Python version dependent. The installer filename +will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`. You +have to create a separate installer for every Python version you want to +support. + +The installer will try to compile pure modules into bytecode after installation +on the target system in normal and optimizing mode. If you don't want this to +happen for some reason, you can run the :command:`bdist_wininst` command with +the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` +option. + +By default the installer will display the cool "Python Powered" logo when it is +run, but you can also supply your own bitmap which must be a Windows +:file:`.bmp` file with the :option:`--bitmap` option. + +The installer will also display a large title on the desktop background window +when it is run, which is constructed from the name of your distribution and the +version number. This can be changed to another text by using the +:option:`--title` option. + +The installer file will be written to the "distribution directory" --- normally +:file:`dist/`, but customizable with the :option:`--dist-dir` option. + + +.. _postinstallation-script: + +The Postinstallation script +--------------------------- + +Starting with Python 2.3, a postinstallation script can be specified which the +:option:`--install-script` option. The basename of the script must be +specified, and the script filename must also be listed in the scripts argument +to the setup function. + +This script will be run at installation time on the target system after all the +files have been copied, with ``argv[1]`` set to :option:`-install`, and again at +uninstallation time before the files are removed with ``argv[1]`` set to +:option:`-remove`. + +The installation script runs embedded in the windows installer, every output +(``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be +displayed in the GUI after the script has finished. + +Some functions especially useful in this context are available as additional +built-in functions in the installation script. + + +.. function:: directory_created(path) + file_created(path) + + These functions should be called when a directory or file is created by the + postinstall script at installation time. It will register *path* with the + uninstaller, so that it will be removed when the distribution is uninstalled. + To be safe, directories are only removed if they are empty. + + +.. function:: get_special_folder_path(csidl_string) + + This function can be used to retrieve special folder locations on Windows like + the Start Menu or the Desktop. It returns the full path to the folder. + *csidl_string* must be one of the following strings:: + + "CSIDL_APPDATA" + + "CSIDL_COMMON_STARTMENU" + "CSIDL_STARTMENU" + + "CSIDL_COMMON_DESKTOPDIRECTORY" + "CSIDL_DESKTOPDIRECTORY" + + "CSIDL_COMMON_STARTUP" + "CSIDL_STARTUP" + + "CSIDL_COMMON_PROGRAMS" + "CSIDL_PROGRAMS" + + "CSIDL_FONTS" + + If the folder cannot be retrieved, :exc:`OSError` is raised. + + Which folders are available depends on the exact Windows version, and probably + also the configuration. For details refer to Microsoft's documentation of the + :cfunc:`SHGetSpecialFolderPath` function. + + +.. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) + + This function creates a shortcut. *target* is the path to the program to be + started by the shortcut. *description* is the description of the shortcut. + *filename* is the title of the shortcut that the user will see. *arguments* + specifies the command line arguments, if any. *workdir* is the working directory + for the program. *iconpath* is the file containing the icon for the shortcut, + and *iconindex* is the index of the icon in the file *iconpath*. Again, for + details consult the Microsoft documentation for the :class:`IShellLink` + interface. + + diff --git a/commandref.rst b/commandref.rst new file mode 100644 index 0000000000..f5f02204c5 --- /dev/null +++ b/commandref.rst @@ -0,0 +1,104 @@ +.. _reference: + +***************** +Command Reference +***************** + +.. % \section{Building modules: the \protect\command{build} command family} +.. % \label{build-cmds} +.. % \subsubsection{\protect\command{build}} +.. % \label{build-cmd} +.. % \subsubsection{\protect\command{build\_py}} +.. % \label{build-py-cmd} +.. % \subsubsection{\protect\command{build\_ext}} +.. % \label{build-ext-cmd} +.. % \subsubsection{\protect\command{build\_clib}} +.. % \label{build-clib-cmd} + + +.. _install-cmd: + +Installing modules: the :command:`install` command family +========================================================= + +The install command ensures that the build commands have been run and then runs +the subcommands :command:`install_lib`, :command:`install_data` and +:command:`install_scripts`. + +.. % \subsubsection{\protect\command{install\_lib}} +.. % \label{install-lib-cmd} + + +.. _install-data-cmd: + +:command:`install_data` +----------------------- + +This command installs all data files provided with the distribution. + + +.. _install-scripts-cmd: + +:command:`install_scripts` +-------------------------- + +This command installs all (Python) scripts in the distribution. + +.. % \subsection{Cleaning up: the \protect\command{clean} command} +.. % \label{clean-cmd} + + +.. _sdist-cmd: + +Creating a source distribution: the :command:`sdist` command +============================================================ + +**\*\*** fragment moved down from above: needs context! **\*\*** + +The manifest template commands are: + ++-------------------------------------------+-----------------------------------------------+ +| Command | Description | ++===========================================+===============================================+ +| :command:`include pat1 pat2 ...` | include all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`prune dir` | exclude all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ +| :command:`graft dir` | include all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ + +The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of +regular filename characters, ``?`` matches any single regular filename +character, and ``[range]`` matches any of the characters in *range* (e.g., +``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename +character" is platform-specific: on Unix it is anything except slash; on Windows +anything except backslash or colon; on Mac OS 9 anything except colon. + +**\*\*** Windows support not there yet **\*\*** + +.. % \section{Creating a built distribution: the +.. % \protect\command{bdist} command family} +.. % \label{bdist-cmds} + +.. % \subsection{\protect\command{bdist}} +.. % \subsection{\protect\command{bdist\_dumb}} +.. % \subsection{\protect\command{bdist\_rpm}} +.. % \subsection{\protect\command{bdist\_wininst}} + + diff --git a/configfile.rst b/configfile.rst new file mode 100644 index 0000000000..0ccd5fd3e8 --- /dev/null +++ b/configfile.rst @@ -0,0 +1,130 @@ +.. _setup-config: + +************************************ +Writing the Setup Configuration File +************************************ + +Often, it's not possible to write down everything needed to build a distribution +*a priori*: you may need to get some information from the user, or from the +user's system, in order to proceed. As long as that information is fairly +simple---a list of directories to search for C header files or libraries, for +example---then providing a configuration file, :file:`setup.cfg`, for users to +edit is a cheap and easy way to solicit it. Configuration files also let you +provide default values for any command option, which the installer can then +override either on the command-line or by editing the config file. + +The setup configuration file is a useful middle-ground between the setup script +---which, ideally, would be opaque to installers [#]_---and the command-line to +the setup script, which is outside of your control and entirely up to the +installer. In fact, :file:`setup.cfg` (and any other Distutils configuration +files present on the target system) are processed after the contents of the +setup script, but before the command-line. This has several useful +consequences: + +.. % (If you have more advanced needs, such as determining which extensions +.. % to build based on what capabilities are present on the target system, +.. % then you need the Distutils ``auto-configuration'' facility. This +.. % started to appear in Distutils 0.9 but, as of this writing, isn't mature +.. % or stable enough yet for real-world use.) + +* installers can override some of what you put in :file:`setup.py` by editing + :file:`setup.cfg` + +* you can provide non-standard defaults for options that are not easily set in + :file:`setup.py` + +* installers can override anything in :file:`setup.cfg` using the command-line + options to :file:`setup.py` + +The basic syntax of the configuration file is simple:: + + [command] + option=value + ... + +where *command* is one of the Distutils commands (e.g. :command:`build_py`, +:command:`install`), and *option* is one of the options that command supports. +Any number of options can be supplied for each command, and any number of +command sections can be included in the file. Blank lines are ignored, as are +comments, which run from a ``'#'`` character until the end of the line. Long +option values can be split across multiple lines simply by indenting the +continuation lines. + +You can find out the list of options supported by a particular command with the +universal :option:`--help` option, e.g. :: + + > python setup.py --help build_ext + [...] + Options for 'build_ext' command: + --build-lib (-b) directory for compiled extension modules + --build-temp (-t) directory for temporary files (build by-products) + --inplace (-i) ignore build-lib and put compiled extensions into the + source directory alongside your pure Python modules + --include-dirs (-I) list of directories to search for header files + --define (-D) C preprocessor macros to define + --undef (-U) C preprocessor macros to undefine + --swig-opts list of SWIG command line options + [...] + +Note that an option spelled :option:`--foo-bar` on the command-line is spelled +:option:`foo_bar` in configuration files. + +For example, say you want your extensions to be built "in-place"---that is, you +have an extension :mod:`pkg.ext`, and you want the compiled extension file +(:file:`ext.so` on Unix, say) to be put in the same source directory as your +pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the +:option:`--inplace` option on the command-line to ensure this:: + + python setup.py build_ext --inplace + +But this requires that you always specify the :command:`build_ext` command +explicitly, and remember to provide :option:`--inplace`. An easier way is to +"set and forget" this option, by encoding it in :file:`setup.cfg`, the +configuration file for this distribution:: + + [build_ext] + inplace=1 + +This will affect all builds of this module distribution, whether or not you +explicitly specify :command:`build_ext`. If you include :file:`setup.cfg` in +your source distribution, it will also affect end-user builds---which is +probably a bad idea for this option, since always building extensions in-place +would break installation of the module distribution. In certain peculiar cases, +though, modules are built right in their installation directory, so this is +conceivably a useful ability. (Distributing extensions that expect to be built +in their installation directory is almost always a bad idea, though.) + +Another example: certain commands take a lot of options that don't change from +run to run; for example, :command:`bdist_rpm` needs to know everything required +to generate a "spec" file for creating an RPM distribution. Some of this +information comes from the setup script, and some is automatically generated by +the Distutils (such as the list of files installed). But some of it has to be +supplied as options to :command:`bdist_rpm`, which would be very tedious to do +on the command-line for every run. Hence, here is a snippet from the Distutils' +own :file:`setup.cfg`:: + + [bdist_rpm] + release = 1 + packager = Greg Ward + doc_files = CHANGES.txt + README.txt + USAGE.txt + doc/ + examples/ + +Note that the :option:`doc_files` option is simply a whitespace-separated string +split across multiple lines for readability. + + +.. seealso:: + + :ref:`inst-config-syntax` in "Installing Python Modules" + More information on the configuration files is available in the manual for + system administrators. + + +.. rubric:: Footnotes + +.. [#] This ideal probably won't be achieved until auto-configuration is fully + supported by the Distutils. + diff --git a/examples.rst b/examples.rst new file mode 100644 index 0000000000..4e4adc56d2 --- /dev/null +++ b/examples.rst @@ -0,0 +1,241 @@ +.. _examples: + +******** +Examples +******** + +This chapter provides a number of basic examples to help get started with +distutils. Additional information about using distutils can be found in the +Distutils Cookbook. + + +.. seealso:: + + `Distutils Cookbook `_ + Collection of recipes showing how to achieve more control over distutils. + + +.. _pure-mod: + +Pure Python distribution (by module) +==================================== + +If you're just distributing a couple of modules, especially if they don't live +in a particular package, you can specify them individually using the +:option:`py_modules` option in the setup script. + +In the simplest case, you'll have two files to worry about: a setup script and +the single module you're distributing, :file:`foo.py` in this example:: + + / + setup.py + foo.py + +(In all diagrams in this section, ** will refer to the distribution root +directory.) A minimal setup script to describe this situation would be:: + + from distutils.core import setup + setup(name='foo', + version='1.0', + py_modules=['foo'], + ) + +Note that the name of the distribution is specified independently with the +:option:`name` option, and there's no rule that says it has to be the same as +the name of the sole module in the distribution (although that's probably a good +convention to follow). However, the distribution name is used to generate +filenames, so you should stick to letters, digits, underscores, and hyphens. + +Since :option:`py_modules` is a list, you can of course specify multiple +modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your +setup might look like this:: + + / + setup.py + foo.py + bar.py + +and the setup script might be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + py_modules=['foo', 'bar'], + ) + +You can put module source files into another directory, but if you have enough +modules to do that, it's probably easier to specify modules by package rather +than listing them individually. + + +.. _pure-pkg: + +Pure Python distribution (by package) +===================================== + +If you have more than a couple of modules to distribute, especially if they are +in multiple packages, it's probably easier to specify whole packages rather than +individual modules. This works even if your modules are not in a package; you +can just tell the Distutils to process modules from the root package, and that +works the same as any other package (except that you don't have to have an +:file:`__init__.py` file). + +The setup script from the last example could also be written as :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + packages=[''], + ) + +(The empty string stands for the root package.) + +If those two files are moved into a subdirectory, but remain in the root +package, e.g.:: + + / + setup.py + src/ foo.py + bar.py + +then you would still specify the root package, but you have to tell the +Distutils where source files in the root package live:: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + package_dir={'': 'src'}, + packages=[''], + ) + +More typically, though, you will want to distribute multiple modules in the same +package (or in sub-packages). For example, if the :mod:`foo` and :mod:`bar` +modules belong in package :mod:`foobar`, one way to layout your source tree is +:: + + / + setup.py + foobar/ + __init__.py + foo.py + bar.py + +This is in fact the default layout expected by the Distutils, and the one that +requires the least work to describe in your setup script:: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + packages=['foobar'], + ) + +If you want to put modules in directories not named for their package, then you +need to use the :option:`package_dir` option again. For example, if the +:file:`src` directory holds modules in the :mod:`foobar` package:: + + / + setup.py + src/ + __init__.py + foo.py + bar.py + +an appropriate setup script would be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + package_dir={'foobar': 'src'}, + packages=['foobar'], + ) + +Or, you might put modules from your main package right in the distribution +root:: + + / + setup.py + __init__.py + foo.py + bar.py + +in which case your setup script would be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + package_dir={'foobar': ''}, + packages=['foobar'], + ) + +(The empty string also stands for the current directory.) + +If you have sub-packages, they must be explicitly listed in :option:`packages`, +but any entries in :option:`package_dir` automatically extend to sub-packages. +(In other words, the Distutils does *not* scan your source tree, trying to +figure out which directories correspond to Python packages by looking for +:file:`__init__.py` files.) Thus, if the default layout grows a sub-package:: + + / + setup.py + foobar/ + __init__.py + foo.py + bar.py + subfoo/ + __init__.py + blah.py + +then the corresponding setup script would be :: + + from distutils.core import setup + setup(name='foobar', + version='1.0', + packages=['foobar', 'foobar.subfoo'], + ) + +(Again, the empty string in :option:`package_dir` stands for the current +directory.) + + +.. _single-ext: + +Single extension module +======================= + +Extension modules are specified using the :option:`ext_modules` option. +:option:`package_dir` has no effect on where extension source files are found; +it only affects the source for pure Python modules. The simplest case, a +single extension module in a single C source file, is:: + + / + setup.py + foo.c + +If the :mod:`foo` extension belongs in the root package, the setup script for +this could be :: + + from distutils.core import setup + from distutils.extension import Extension + setup(name='foobar', + version='1.0', + ext_modules=[Extension('foo', ['foo.c'])], + ) + +If the extension actually belongs in a package, say :mod:`foopkg`, then + +With exactly the same source tree layout, this extension can be put in the +:mod:`foopkg` package simply by changing the name of the extension:: + + from distutils.core import setup + from distutils.extension import Extension + setup(name='foobar', + version='1.0', + ext_modules=[Extension('foopkg.foo', ['foo.c'])], + ) + +.. % \section{Multiple extension modules} +.. % \label{multiple-ext} + +.. % \section{Putting it all together} + + diff --git a/extending.rst b/extending.rst new file mode 100644 index 0000000000..a2930c77df --- /dev/null +++ b/extending.rst @@ -0,0 +1,96 @@ +.. _extending: + +******************* +Extending Distutils +******************* + +Distutils can be extended in various ways. Most extensions take the form of new +commands or replacements for existing commands. New commands may be written to +support new types of platform-specific packaging, for example, while +replacements for existing commands may be made to modify details of how the +command operates on a package. + +Most extensions of the distutils are made within :file:`setup.py` scripts that +want to modify existing commands; many simply add a few file extensions that +should be copied into packages in addition to :file:`.py` files as a +convenience. + +Most distutils command implementations are subclasses of the :class:`Command` +class from :mod:`distutils.cmd`. New commands may directly inherit from +:class:`Command`, while replacements often derive from :class:`Command` +indirectly, directly subclassing the command they are replacing. Commands are +required to derive from :class:`Command`. + +.. % \section{Extending existing commands} +.. % \label{extend-existing} + +.. % \section{Writing new commands} +.. % \label{new-commands} +.. % \XXX{Would an uninstall command be a good example here?} + + +Integrating new commands +======================== + +There are different ways to integrate new command implementations into +distutils. The most difficult is to lobby for the inclusion of the new features +in distutils itself, and wait for (and require) a version of Python that +provides that support. This is really hard for many reasons. + +The most common, and possibly the most reasonable for most needs, is to include +the new implementations with your :file:`setup.py` script, and cause the +:func:`distutils.core.setup` function use them:: + + from distutils.command.build_py import build_py as _build_py + from distutils.core import setup + + class build_py(_build_py): + """Specialized Python source builder.""" + + # implement whatever needs to be different... + + setup(cmdclass={'build_py': build_py}, + ...) + +This approach is most valuable if the new implementations must be used to use a +particular package, as everyone interested in the package will need to have the +new command implementation. + +Beginning with Python 2.4, a third option is available, intended to allow new +commands to be added which can support existing :file:`setup.py` scripts without +requiring modifications to the Python installation. This is expected to allow +third-party extensions to provide support for additional packaging systems, but +the commands can be used for anything distutils commands can be used for. A new +configuration option, :option:`command_packages` (command-line option +:option:`--command-packages`), can be used to specify additional packages to be +searched for modules implementing commands. Like all distutils options, this +can be specified on the command line or in a configuration file. This option +can only be set in the ``[global]`` section of a configuration file, or before +any commands on the command line. If set in a configuration file, it can be +overridden from the command line; setting it to an empty string on the command +line causes the default to be used. This should never be set in a configuration +file provided with a package. + +This new option can be used to add any number of packages to the list of +packages searched for command implementations; multiple package names should be +separated by commas. When not specified, the search is only performed in the +:mod:`distutils.command` package. When :file:`setup.py` is run with the option +:option:`--command-packages` :option:`distcmds,buildcmds`, however, the packages +:mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched +in that order. New commands are expected to be implemented in modules of the +same name as the command by classes sharing the same name. Given the example +command line option above, the command :command:`bdist_openpkg` could be +implemented by the class :class:`distcmds.bdist_openpkg.bdist_openpkg` or +:class:`buildcmds.bdist_openpkg.bdist_openpkg`. + + +Adding new distribution types +============================= + +Commands that create distributions (files in the :file:`dist/` directory) need +to add ``(command, filename)`` pairs to ``self.distribution.dist_files`` so that +:command:`upload` can upload it to PyPI. The *filename* in the pair contains no +path information, only the name of the file itself. In dry-run mode, pairs +should still be added to represent what would have been created. + + diff --git a/index.rst b/index.rst new file mode 100644 index 0000000000..6d82c847bb --- /dev/null +++ b/index.rst @@ -0,0 +1,30 @@ +.. _distutils-index: + +############################### + Distributing Python Modules +############################### + +:Authors: Greg Ward, Anthony Baxter +:Email: distutils-sig@python.org +:Release: |version| +:Date: |today| + +This document describes the Python Distribution Utilities ("Distutils") from +the module developer's point of view, describing how to use the Distutils to +make Python modules and extensions easily available to a wider audience with +very little overhead for build/release/install mechanics. + +.. toctree:: + :maxdepth: 2 + + introduction.rst + setupscript.rst + configfile.rst + sourcedist.rst + builtdist.rst + packageindex.rst + uploading.rst + examples.rst + extending.rst + commandref.rst + apiref.rst diff --git a/introduction.rst b/introduction.rst new file mode 100644 index 0000000000..b772b01004 --- /dev/null +++ b/introduction.rst @@ -0,0 +1,208 @@ +.. _distutils-intro: + +**************************** +An Introduction to Distutils +**************************** + +This document covers using the Distutils to distribute your Python modules, +concentrating on the role of developer/distributor: if you're looking for +information on installing Python modules, you should refer to the +:ref:`install-index` chapter. + + +.. _distutils-concepts: + +Concepts & Terminology +====================== + +Using the Distutils is quite simple, both for module developers and for +users/administrators installing third-party modules. As a developer, your +responsibilities (apart from writing solid, well-documented and well-tested +code, of course!) are: + +* write a setup script (:file:`setup.py` by convention) + +* (optional) write a setup configuration file + +* create a source distribution + +* (optional) create one or more built (binary) distributions + +Each of these tasks is covered in this document. + +Not all module developers have access to a multitude of platforms, so it's not +always feasible to expect them to create a multitude of built distributions. It +is hoped that a class of intermediaries, called *packagers*, will arise to +address this need. Packagers will take source distributions released by module +developers, build them on one or more platforms, and release the resulting built +distributions. Thus, users on the most popular platforms will be able to +install most popular Python module distributions in the most natural way for +their platform, without having to run a single setup script or compile a line of +code. + + +.. _distutils-simple-example: + +A Simple Example +================ + +The setup script is usually quite simple, although since it's written in Python, +there are no arbitrary limits to what you can do with it, though you should be +careful about putting arbitrarily expensive operations in your setup script. +Unlike, say, Autoconf-style configure scripts, the setup script may be run +multiple times in the course of building and installing your module +distribution. + +If all you want to do is distribute a module called :mod:`foo`, contained in a +file :file:`foo.py`, then your setup script can be as simple as this:: + + from distutils.core import setup + setup(name='foo', + version='1.0', + py_modules=['foo'], + ) + +Some observations: + +* most information that you supply to the Distutils is supplied as keyword + arguments to the :func:`setup` function + +* those keyword arguments fall into two categories: package metadata (name, + version number) and information about what's in the package (a list of pure + Python modules, in this case) + +* modules are specified by module name, not filename (the same will hold true + for packages and extensions) + +* it's recommended that you supply a little more metadata, in particular your + name, email address and a URL for the project (see section :ref:`setup-script` + for an example) + +To create a source distribution for this module, you would create a setup +script, :file:`setup.py`, containing the above code, and run:: + + python setup.py sdist + +which will create an archive file (e.g., tarball on Unix, ZIP file on Windows) +containing your setup script :file:`setup.py`, and your module :file:`foo.py`. +The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and +will unpack into a directory :file:`foo-1.0`. + +If an end-user wishes to install your :mod:`foo` module, all she has to do is +download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the +:file:`foo-1.0` directory---run :: + + python setup.py install + +which will ultimately copy :file:`foo.py` to the appropriate directory for +third-party modules in their Python installation. + +This simple example demonstrates some fundamental concepts of the Distutils. +First, both developers and installers have the same basic user interface, i.e. +the setup script. The difference is which Distutils *commands* they use: the +:command:`sdist` command is almost exclusively for module developers, while +:command:`install` is more often for installers (although most developers will +want to install their own code occasionally). + +If you want to make things really easy for your users, you can create one or +more built distributions for them. For instance, if you are running on a +Windows machine, and want to make things easy for other Windows users, you can +create an executable installer (the most appropriate type of built distribution +for this platform) with the :command:`bdist_wininst` command. For example:: + + python setup.py bdist_wininst + +will create an executable installer, :file:`foo-1.0.win32.exe`, in the current +directory. + +Other useful built distribution formats are RPM, implemented by the +:command:`bdist_rpm` command, Solaris :program:`pkgtool` +(:command:`bdist_pkgtool`), and HP-UX :program:`swinstall` +(:command:`bdist_sdux`). For example, the following command will create an RPM +file called :file:`foo-1.0.noarch.rpm`:: + + python setup.py bdist_rpm + +(The :command:`bdist_rpm` command uses the :command:`rpm` executable, therefore +this has to be run on an RPM-based system such as Red Hat Linux, SuSE Linux, or +Mandrake Linux.) + +You can find out what distribution formats are available at any time by running +:: + + python setup.py bdist --help-formats + + +.. _python-terms: + +General Python terminology +========================== + +If you're reading this document, you probably have a good idea of what modules, +extensions, and so forth are. Nevertheless, just to be sure that everyone is +operating from a common starting point, we offer the following glossary of +common Python terms: + +module + the basic unit of code reusability in Python: a block of code imported by some + other code. Three types of modules concern us here: pure Python modules, + extension modules, and packages. + +pure Python module + a module written in Python and contained in a single :file:`.py` file (and + possibly associated :file:`.pyc` and/or :file:`.pyo` files). Sometimes referred + to as a "pure module." + +extension module + a module written in the low-level language of the Python implementation: C/C++ + for Python, Java for Jython. Typically contained in a single dynamically + loadable pre-compiled file, e.g. a shared object (:file:`.so`) file for Python + extensions on Unix, a DLL (given the :file:`.pyd` extension) for Python + extensions on Windows, or a Java class file for Jython extensions. (Note that + currently, the Distutils only handles C/C++ extensions for Python.) + +package + a module that contains other modules; typically contained in a directory in the + filesystem and distinguished from other directories by the presence of a file + :file:`__init__.py`. + +root package + the root of the hierarchy of packages. (This isn't really a package, since it + doesn't have an :file:`__init__.py` file. But we have to call it something.) + The vast majority of the standard library is in the root package, as are many + small, standalone third-party modules that don't belong to a larger module + collection. Unlike regular packages, modules in the root package can be found in + many directories: in fact, every directory listed in ``sys.path`` contributes + modules to the root package. + + +.. _distutils-term: + +Distutils-specific terminology +============================== + +The following terms apply more specifically to the domain of distributing Python +modules using the Distutils: + +module distribution + a collection of Python modules distributed together as a single downloadable + resource and meant to be installed *en masse*. Examples of some well-known + module distributions are Numeric Python, PyXML, PIL (the Python Imaging + Library), or mxBase. (This would be called a *package*, except that term is + already taken in the Python context: a single module distribution may contain + zero, one, or many Python packages.) + +pure module distribution + a module distribution that contains only pure Python modules and packages. + Sometimes referred to as a "pure distribution." + +non-pure module distribution + a module distribution that contains at least one extension module. Sometimes + referred to as a "non-pure distribution." + +distribution root + the top-level directory of your source tree (or source distribution); the + directory where :file:`setup.py` exists. Generally :file:`setup.py` will be + run from this directory. + + diff --git a/packageindex.rst b/packageindex.rst new file mode 100644 index 0000000000..f0f886bcc9 --- /dev/null +++ b/packageindex.rst @@ -0,0 +1,65 @@ +.. _package-index: + +********************************** +Registering with the Package Index +********************************** + +The Python Package Index (PyPI) holds meta-data describing distributions +packaged with distutils. The distutils command :command:`register` is used to +submit your distribution's meta-data to the index. It is invoked as follows:: + + python setup.py register + +Distutils will respond with the following prompt:: + + running register + We need to know who you are, so please choose either: + 1. use your existing login, + 2. register as a new user, + 3. have the server generate a new password for you (and email it to you), or + 4. quit + Your selection [default 1]: + +Note: if your username and password are saved locally, you will not see this +menu. + +If you have not registered with PyPI, then you will need to do so now. You +should choose option 2, and enter your details as required. Soon after +submitting your details, you will receive an email which will be used to confirm +your registration. + +Once you are registered, you may choose option 1 from the menu. You will be +prompted for your PyPI username and password, and :command:`register` will then +submit your meta-data to the index. + +You may submit any number of versions of your distribution to the index. If you +alter the meta-data for a particular version, you may submit it again and the +index will be updated. + +PyPI holds a record for each (name, version) combination submitted. The first +user to submit information for a given name is designated the Owner of that +name. They may submit changes through the :command:`register` command or through +the web interface. They may also designate other users as Owners or Maintainers. +Maintainers may edit the package information, but not designate other Owners or +Maintainers. + +By default PyPI will list all versions of a given package. To hide certain +versions, the Hidden property should be set to yes. This must be edited through +the web interface. + + +.. _pypirc: + +The .pypirc file +================ + +The format of the :file:`.pypirc` file is formated as follows:: + + [server-login] + repository: + username: + password: + +*repository* can be ommitted and defaults to ``http://www.python.org/pypi``. + + diff --git a/setupscript.rst b/setupscript.rst new file mode 100644 index 0000000000..26f50e6cd5 --- /dev/null +++ b/setupscript.rst @@ -0,0 +1,669 @@ +.. _setup-script: + +************************ +Writing the Setup Script +************************ + +The setup script is the centre of all activity in building, distributing, and +installing modules using the Distutils. The main purpose of the setup script is +to describe your module distribution to the Distutils, so that the various +commands that operate on your modules do the right thing. As we saw in section +:ref:`distutils-simple-example` above, the setup script consists mainly of a call to +:func:`setup`, and most information supplied to the Distutils by the module +developer is supplied as keyword arguments to :func:`setup`. + +Here's a slightly more involved example, which we'll follow for the next couple +of sections: the Distutils' own setup script. (Keep in mind that although the +Distutils are included with Python 1.6 and later, they also have an independent +existence so that Python 1.5.2 users can use them to install other module +distributions. The Distutils' own setup script, shown here, is used to install +the package into Python 1.5.2.) :: + + #!/usr/bin/env python + + from distutils.core import setup + + setup(name='Distutils', + version='1.0', + description='Python Distribution Utilities', + author='Greg Ward', + author_email='gward@python.net', + url='http://www.python.org/sigs/distutils-sig/', + packages=['distutils', 'distutils.command'], + ) + +There are only two differences between this and the trivial one-file +distribution presented in section :ref:`distutils-simple-example`: more metadata, and the +specification of pure Python modules by package, rather than by module. This is +important since the Distutils consist of a couple of dozen modules split into +(so far) two packages; an explicit list of every module would be tedious to +generate and difficult to maintain. For more information on the additional +meta-data, see section :ref:`meta-data`. + +Note that any pathnames (files or directories) supplied in the setup script +should be written using the Unix convention, i.e. slash-separated. The +Distutils will take care of converting this platform-neutral representation into +whatever is appropriate on your current platform before actually using the +pathname. This makes your setup script portable across operating systems, which +of course is one of the major goals of the Distutils. In this spirit, all +pathnames in this document are slash-separated. (Mac OS 9 programmers should +keep in mind that the *absence* of a leading slash indicates a relative path, +the opposite of the Mac OS convention with colons.) + +This, of course, only applies to pathnames given to Distutils functions. If +you, for example, use standard Python functions such as :func:`glob.glob` or +:func:`os.listdir` to specify files, you should be careful to write portable +code instead of hardcoding path separators:: + + glob.glob(os.path.join('mydir', 'subdir', '*.html')) + os.listdir(os.path.join('mydir', 'subdir')) + + +.. _listing-packages: + +Listing whole packages +====================== + +The :option:`packages` option tells the Distutils to process (build, distribute, +install, etc.) all pure Python modules found in each package mentioned in the +:option:`packages` list. In order to do this, of course, there has to be a +correspondence between package names and directories in the filesystem. The +default correspondence is the most obvious one, i.e. package :mod:`distutils` is +found in the directory :file:`distutils` relative to the distribution root. +Thus, when you say ``packages = ['foo']`` in your setup script, you are +promising that the Distutils will find a file :file:`foo/__init__.py` (which +might be spelled differently on your system, but you get the idea) relative to +the directory where your setup script lives. If you break this promise, the +Distutils will issue a warning but still process the broken package anyways. + +If you use a different convention to lay out your source directory, that's no +problem: you just have to supply the :option:`package_dir` option to tell the +Distutils about your convention. For example, say you keep all Python source +under :file:`lib`, so that modules in the "root package" (i.e., not in any +package at all) are in :file:`lib`, modules in the :mod:`foo` package are in +:file:`lib/foo`, and so forth. Then you would put :: + + package_dir = {'': 'lib'} + +in your setup script. The keys to this dictionary are package names, and an +empty package name stands for the root package. The values are directory names +relative to your distribution root. In this case, when you say ``packages = +['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists. + +Another possible convention is to put the :mod:`foo` package right in +:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be +written in the setup script as :: + + package_dir = {'foo': 'lib'} + +A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly +applies to all packages below *package*, so the :mod:`foo.bar` case is +automatically handled here. In this example, having ``packages = ['foo', +'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and +:file:`lib/bar/__init__.py`. (Keep in mind that although :option:`package_dir` +applies recursively, you must explicitly list all packages in +:option:`packages`: the Distutils will *not* recursively scan your source tree +looking for any directory with an :file:`__init__.py` file.) + + +.. _listing-modules: + +Listing individual modules +========================== + +For a small module distribution, you might prefer to list all modules rather +than listing packages---especially the case of a single module that goes in the +"root package" (i.e., no package at all). This simplest case was shown in +section :ref:`distutils-simple-example`; here is a slightly more involved example:: + + py_modules = ['mod1', 'pkg.mod2'] + +This describes two modules, one of them in the "root" package, the other in the +:mod:`pkg` package. Again, the default package/directory layout implies that +these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and +that :file:`pkg/__init__.py` exists as well. And again, you can override the +package/directory correspondence using the :option:`package_dir` option. + + +.. _describing-extensions: + +Describing extension modules +============================ + +Just as writing Python extension modules is a bit more complicated than writing +pure Python modules, describing them to the Distutils is a bit more complicated. +Unlike pure modules, it's not enough just to list modules or packages and expect +the Distutils to go out and find the right files; you have to specify the +extension name, source file(s), and any compile/link requirements (include +directories, libraries to link with, etc.). + +.. % XXX read over this section + +All of this is done through another keyword argument to :func:`setup`, the +:option:`ext_modules` option. :option:`ext_modules` is just a list of +:class:`Extension` instances, each of which describes a single extension module. +Suppose your distribution includes a single extension, called :mod:`foo` and +implemented by :file:`foo.c`. If no additional instructions to the +compiler/linker are needed, describing this extension is quite simple:: + + Extension('foo', ['foo.c']) + +The :class:`Extension` class can be imported from :mod:`distutils.core` along +with :func:`setup`. Thus, the setup script for a module distribution that +contains only this one extension and nothing else might be:: + + from distutils.core import setup, Extension + setup(name='foo', + version='1.0', + ext_modules=[Extension('foo', ['foo.c'])], + ) + +The :class:`Extension` class (actually, the underlying extension-building +machinery implemented by the :command:`build_ext` command) supports a great deal +of flexibility in describing Python extensions, which is explained in the +following sections. + + +Extension names and packages +---------------------------- + +The first argument to the :class:`Extension` constructor is always the name of +the extension, including any package names. For example, :: + + Extension('foo', ['src/foo1.c', 'src/foo2.c']) + +describes an extension that lives in the root package, while :: + + Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) + +describes the same extension in the :mod:`pkg` package. The source files and +resulting object code are identical in both cases; the only difference is where +in the filesystem (and therefore where in Python's namespace hierarchy) the +resulting extension lives. + +If you have a number of extensions all in the same package (or all under the +same base package), use the :option:`ext_package` keyword argument to +:func:`setup`. For example, :: + + setup(... + ext_package='pkg', + ext_modules=[Extension('foo', ['foo.c']), + Extension('subpkg.bar', ['bar.c'])], + ) + +will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to +:mod:`pkg.subpkg.bar`. + + +Extension source files +---------------------- + +The second argument to the :class:`Extension` constructor is a list of source +files. Since the Distutils currently only support C, C++, and Objective-C +extensions, these are normally C/C++/Objective-C source files. (Be sure to use +appropriate extensions to distinguish C++\ source files: :file:`.cc` and +:file:`.cpp` seem to be recognized by both Unix and Windows compilers.) + +However, you can also include SWIG interface (:file:`.i`) files in the list; the +:command:`build_ext` command knows how to deal with SWIG extensions: it will run +SWIG on the interface file and compile the resulting C/C++ file into your +extension. + +**\*\*** SWIG support is rough around the edges and largely untested! **\*\*** + +This warning notwithstanding, options to SWIG can be currently passed like +this:: + + setup(... + ext_modules=[Extension('_foo', ['foo.i'], + swig_opts=['-modern', '-I../include'])], + py_modules=['foo'], + ) + +Or on the commandline like this:: + + > python setup.py build_ext --swig-opts="-modern -I../include" + +On some platforms, you can include non-source files that are processed by the +compiler and included in your extension. Currently, this just means Windows +message text (:file:`.mc`) files and resource definition (:file:`.rc`) files for +Visual C++. These will be compiled to binary resource (:file:`.res`) files and +linked into the executable. + + +Preprocessor options +-------------------- + +Three optional arguments to :class:`Extension` will help if you need to specify +include directories to search or preprocessor macros to define/undefine: +``include_dirs``, ``define_macros``, and ``undef_macros``. + +For example, if your extension requires header files in the :file:`include` +directory under your distribution root, use the ``include_dirs`` option:: + + Extension('foo', ['foo.c'], include_dirs=['include']) + +You can specify absolute directories there; if you know that your extension will +only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get +away with :: + + Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11']) + +You should avoid this sort of non-portable usage if you plan to distribute your +code: it's probably better to write C code like :: + + #include + +If you need to include header files from some other Python extension, you can +take advantage of the fact that header files are installed in a consistent way +by the Distutils :command:`install_header` command. For example, the Numerical +Python header files are installed (on a standard Unix installation) to +:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ +according to your platform and Python installation.) Since the Python include +directory---\ :file:`/usr/local/include/python1.5` in this case---is always +included in the search path when building Python extensions, the best approach +is to write C code like :: + + #include + +If you must put the :file:`Numerical` include directory right into your header +search path, though, you can find that directory using the Distutils +:mod:`distutils.sysconfig` module:: + + from distutils.sysconfig import get_python_inc + incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical') + setup(..., + Extension(..., include_dirs=[incdir]), + ) + +Even though this is quite portable---it will work on any Python installation, +regardless of platform---it's probably easier to just write your C code in the +sensible way. + +You can define and undefine pre-processor macros with the ``define_macros`` and +``undef_macros`` options. ``define_macros`` takes a list of ``(name, value)`` +tuples, where ``name`` is the name of the macro to define (a string) and +``value`` is its value: either a string or ``None``. (Defining a macro ``FOO`` +to ``None`` is the equivalent of a bare ``#define FOO`` in your C source: with +most compilers, this sets ``FOO`` to the string ``1``.) ``undef_macros`` is +just a list of macros to undefine. + +For example:: + + Extension(..., + define_macros=[('NDEBUG', '1'), + ('HAVE_STRFTIME', None)], + undef_macros=['HAVE_FOO', 'HAVE_BAR']) + +is the equivalent of having this at the top of every C source file:: + + #define NDEBUG 1 + #define HAVE_STRFTIME + #undef HAVE_FOO + #undef HAVE_BAR + + +Library options +--------------- + +You can also specify the libraries to link against when building your extension, +and the directories to search for those libraries. The ``libraries`` option is +a list of libraries to link against, ``library_dirs`` is a list of directories +to search for libraries at link-time, and ``runtime_library_dirs`` is a list of +directories to search for shared (dynamically loaded) libraries at run-time. + +For example, if you need to link against libraries known to be in the standard +library search path on target systems :: + + Extension(..., + libraries=['gdbm', 'readline']) + +If you need to link with libraries in a non-standard location, you'll have to +include the location in ``library_dirs``:: + + Extension(..., + library_dirs=['/usr/X11R6/lib'], + libraries=['X11', 'Xt']) + +(Again, this sort of non-portable construct should be avoided if you intend to +distribute your code.) + +**\*\*** Should mention clib libraries here or somewhere else! **\*\*** + + +Other options +------------- + +There are still some other options which can be used to handle special cases. + +The :option:`extra_objects` option is a list of object files to be passed to the +linker. These files must not have extensions, as the default extension for the +compiler is used. + +:option:`extra_compile_args` and :option:`extra_link_args` can be used to +specify additional command line options for the respective compiler and linker +command lines. + +:option:`export_symbols` is only useful on Windows. It can contain a list of +symbols (functions or variables) to be exported. This option is not needed when +building compiled extensions: Distutils will automatically add ``initmodule`` +to the list of exported symbols. + + +Relationships between Distributions and Packages +================================================ + +A distribution may relate to packages in three specific ways: + +#. It can require packages or modules. + +#. It can provide packages or modules. + +#. It can obsolete packages or modules. + +These relationships can be specified using keyword arguments to the +:func:`distutils.core.setup` function. + +Dependencies on other Python modules and packages can be specified by supplying +the *requires* keyword argument to :func:`setup`. The value must be a list of +strings. Each string specifies a package that is required, and optionally what +versions are sufficient. + +To specify that any version of a module or package is required, the string +should consist entirely of the module or package name. Examples include +``'mymodule'`` and ``'xml.parsers.expat'``. + +If specific versions are required, a sequence of qualifiers can be supplied in +parentheses. Each qualifier may consist of a comparison operator and a version +number. The accepted comparison operators are:: + + < > == + <= >= != + +These can be combined by using multiple qualifiers separated by commas (and +optional whitespace). In this case, all of the qualifiers must be matched; a +logical AND is used to combine the evaluations. + +Let's look at a bunch of examples: + ++-------------------------+----------------------------------------------+ +| Requires Expression | Explanation | ++=========================+==============================================+ +| ``==1.0`` | Only version ``1.0`` is compatible | ++-------------------------+----------------------------------------------+ +| ``>1.0, !=1.5.1, <2.0`` | Any version after ``1.0`` and before ``2.0`` | +| | is compatible, except ``1.5.1`` | ++-------------------------+----------------------------------------------+ + +Now that we can specify dependencies, we also need to be able to specify what we +provide that other distributions can require. This is done using the *provides* +keyword argument to :func:`setup`. The value for this keyword is a list of +strings, each of which names a Python module or package, and optionally +identifies the version. If the version is not specified, it is assumed to match +that of the distribution. + +Some examples: + ++---------------------+----------------------------------------------+ +| Provides Expression | Explanation | ++=====================+==============================================+ +| ``mypkg`` | Provide ``mypkg``, using the distribution | +| | version | ++---------------------+----------------------------------------------+ +| ``mypkg (1.1)`` | Provide ``mypkg`` version 1.1, regardless of | +| | the distribution version | ++---------------------+----------------------------------------------+ + +A package can declare that it obsoletes other packages using the *obsoletes* +keyword argument. The value for this is similar to that of the *requires* +keyword: a list of strings giving module or package specifiers. Each specifier +consists of a module or package name optionally followed by one or more version +qualifiers. Version qualifiers are given in parentheses after the module or +package name. + +The versions identified by the qualifiers are those that are obsoleted by the +distribution being described. If no qualifiers are given, all versions of the +named module or package are understood to be obsoleted. + + +Installing Scripts +================== + +So far we have been dealing with pure and non-pure Python modules, which are +usually not run by themselves but imported by scripts. + +Scripts are files containing Python source code, intended to be started from the +command line. Scripts don't require Distutils to do anything very complicated. +The only clever feature is that if the first line of the script starts with +``#!`` and contains the word "python", the Distutils will adjust the first line +to refer to the current interpreter location. By default, it is replaced with +the current interpreter location. The :option:`--executable` (or :option:`-e`) +option will allow the interpreter path to be explicitly overridden. + +The :option:`scripts` option simply is a list of files to be handled in this +way. From the PyXML setup script:: + + setup(... + scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] + ) + + +Installing Package Data +======================= + +Often, additional files need to be installed into a package. These files are +often data that's closely related to the package's implementation, or text files +containing documentation that might be of interest to programmers using the +package. These files are called :dfn:`package data`. + +Package data can be added to packages using the ``package_data`` keyword +argument to the :func:`setup` function. The value must be a mapping from +package name to a list of relative path names that should be copied into the +package. The paths are interpreted as relative to the directory containing the +package (information from the ``package_dir`` mapping is used if appropriate); +that is, the files are expected to be part of the package in the source +directories. They may contain glob patterns as well. + +The path names may contain directory portions; any necessary directories will be +created in the installation. + +For example, if a package should contain a subdirectory with several data files, +the files can be arranged like this in the source tree:: + + setup.py + src/ + mypkg/ + __init__.py + module.py + data/ + tables.dat + spoons.dat + forks.dat + +The corresponding call to :func:`setup` might be:: + + setup(..., + packages=['mypkg'], + package_dir={'mypkg': 'src/mypkg'}, + package_data={'mypkg': ['data/*.dat']}, + ) + +.. versionadded:: 2.4 + + +Installing Additional Files +=========================== + +The :option:`data_files` option can be used to specify additional files needed +by the module distribution: configuration files, message catalogs, data files, +anything which doesn't fit in the previous categories. + +:option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the +following way:: + + setup(... + data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), + ('config', ['cfg/data.cfg']), + ('/etc/init.d', ['init-script'])] + ) + +Note that you can specify the directory names where the data files will be +installed, but you cannot rename the data files themselves. + +Each (*directory*, *files*) pair in the sequence specifies the installation +directory and the files to install there. If *directory* is a relative path, it +is interpreted relative to the installation prefix (Python's ``sys.prefix`` for +pure-Python packages, ``sys.exec_prefix`` for packages that contain extension +modules). Each file name in *files* is interpreted relative to the +:file:`setup.py` script at the top of the package source distribution. No +directory information from *files* is used to determine the final location of +the installed file; only the name of the file is used. + +You can specify the :option:`data_files` options as a simple sequence of files +without specifying a target directory, but this is not recommended, and the +:command:`install` command will print a warning in this case. To install data +files directly in the target directory, an empty string should be given as the +directory. + + +.. _meta-data: + +Additional meta-data +==================== + +The setup script may include additional meta-data beyond the name and version. +This information includes: + ++----------------------+---------------------------+-----------------+--------+ +| Meta-Data | Description | Value | Notes | ++======================+===========================+=================+========+ +| ``name`` | name of the package | short string | \(1) | ++----------------------+---------------------------+-----------------+--------+ +| ``version`` | version of this release | short string | (1)(2) | ++----------------------+---------------------------+-----------------+--------+ +| ``author`` | package author's name | short string | \(3) | ++----------------------+---------------------------+-----------------+--------+ +| ``author_email`` | email address of the | email address | \(3) | +| | package author | | | ++----------------------+---------------------------+-----------------+--------+ +| ``maintainer`` | package maintainer's name | short string | \(3) | ++----------------------+---------------------------+-----------------+--------+ +| ``maintainer_email`` | email address of the | email address | \(3) | +| | package maintainer | | | ++----------------------+---------------------------+-----------------+--------+ +| ``url`` | home page for the package | URL | \(1) | ++----------------------+---------------------------+-----------------+--------+ +| ``description`` | short, summary | short string | | +| | description of the | | | +| | package | | | ++----------------------+---------------------------+-----------------+--------+ +| ``long_description`` | longer description of the | long string | | +| | package | | | ++----------------------+---------------------------+-----------------+--------+ +| ``download_url`` | location where the | URL | \(4) | +| | package may be downloaded | | | ++----------------------+---------------------------+-----------------+--------+ +| ``classifiers`` | a list of classifiers | list of strings | \(4) | ++----------------------+---------------------------+-----------------+--------+ + +Notes: + +(1) + These fields are required. + +(2) + It is recommended that versions take the form *major.minor[.patch[.sub]]*. + +(3) + Either the author or the maintainer must be identified. + +(4) + These fields should not be used if your package is to be compatible with Python + versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website + `_. + +'short string' + A single line of text, not more than 200 characters. + +'long string' + Multiple lines of plain text in reStructuredText format (see + http://docutils.sf.net/). + +'list of strings' + See below. + +None of the string values may be Unicode. + +Encoding the version information is an art in itself. Python packages generally +adhere to the version format *major.minor[.patch][sub]*. The major number is 0 +for initial, experimental releases of software. It is incremented for releases +that represent major milestones in a package. The minor number is incremented +when important new features are added to the package. The patch number +increments when bug-fix releases are made. Additional trailing version +information is sometimes used to indicate sub-releases. These are +"a1,a2,...,aN" (for alpha releases, where functionality and API may change), +"b1,b2,...,bN" (for beta releases, which only fix bugs) and "pr1,pr2,...,prN" +(for final pre-release release testing). Some examples: + +0.1.0 + the first, experimental release of a package + +1.0.1a2 + the second alpha release of the first patch version of 1.0 + +:option:`classifiers` are specified in a python list:: + + setup(... + classifiers=[ + 'Development Status :: 4 - Beta', + 'Environment :: Console', + 'Environment :: Web Environment', + 'Intended Audience :: End Users/Desktop', + 'Intended Audience :: Developers', + 'Intended Audience :: System Administrators', + 'License :: OSI Approved :: Python Software Foundation License', + 'Operating System :: MacOS :: MacOS X', + 'Operating System :: Microsoft :: Windows', + 'Operating System :: POSIX', + 'Programming Language :: Python', + 'Topic :: Communications :: Email', + 'Topic :: Office/Business', + 'Topic :: Software Development :: Bug Tracking', + ], + ) + +If you wish to include classifiers in your :file:`setup.py` file and also wish +to remain backwards-compatible with Python releases prior to 2.2.3, then you can +include the following code fragment in your :file:`setup.py` before the +:func:`setup` call. :: + + # patch distutils if it can't cope with the "classifiers" or + # "download_url" keywords + from sys import version + if version < '2.2.3': + from distutils.dist import DistributionMetadata + DistributionMetadata.classifiers = None + DistributionMetadata.download_url = None + + +Debugging the setup script +========================== + +Sometimes things go wrong, and the setup script doesn't do what the developer +wants. + +Distutils catches any exceptions when running the setup script, and print a +simple error message before the script is terminated. The motivation for this +behaviour is to not confuse administrators who don't know much about Python and +are trying to install a package. If they get a big long traceback from deep +inside the guts of Distutils, they may think the package or the Python +installation is broken because they don't read all the way down to the bottom +and see that it's a permission problem. + +On the other hand, this doesn't help the developer to find the cause of the +failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set +to anything except an empty string, and distutils will now print detailed +information what it is doing, and prints the full traceback in case an exception +occurs. + + diff --git a/sourcedist.rst b/sourcedist.rst new file mode 100644 index 0000000000..9f15870ccd --- /dev/null +++ b/sourcedist.rst @@ -0,0 +1,207 @@ +.. _source-dist: + +****************************** +Creating a Source Distribution +****************************** + +As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command +to create a source distribution. In the simplest case, :: + + python setup.py sdist + +(assuming you haven't specified any :command:`sdist` options in the setup script +or config file), :command:`sdist` creates the archive of the default format for +the current platform. The default format is a gzip'ed tar file +(:file:`.tar.gz`) on Unix, and ZIP file on Windows. + +You can specify as many formats as you like using the :option:`--formats` +option, for example:: + + python setup.py sdist --formats=gztar,zip + +to create a gzipped tarball and a zip file. The available formats are: + ++-----------+-------------------------+---------+ +| Format | Description | Notes | ++===========+=========================+=========+ +| ``zip`` | zip file (:file:`.zip`) | (1),(3) | ++-----------+-------------------------+---------+ +| ``gztar`` | gzip'ed tar file | (2),(4) | +| | (:file:`.tar.gz`) | | ++-----------+-------------------------+---------+ +| ``bztar`` | bzip2'ed tar file | \(4) | +| | (:file:`.tar.bz2`) | | ++-----------+-------------------------+---------+ +| ``ztar`` | compressed tar file | \(4) | +| | (:file:`.tar.Z`) | | ++-----------+-------------------------+---------+ +| ``tar`` | tar file (:file:`.tar`) | \(4) | ++-----------+-------------------------+---------+ + +Notes: + +(1) + default on Windows + +(2) + default on Unix + +(3) + requires either external :program:`zip` utility or :mod:`zipfile` module (part + of the standard Python library since Python 1.6) + +(4) + requires external utilities: :program:`tar` and possibly one of :program:`gzip`, + :program:`bzip2`, or :program:`compress` + + +.. _manifest: + +Specifying the files to distribute +================================== + +If you don't supply an explicit list of files (or instructions on how to +generate one), the :command:`sdist` command puts a minimal default set into the +source distribution: + +* all Python source files implied by the :option:`py_modules` and + :option:`packages` options + +* all C source files mentioned in the :option:`ext_modules` or + :option:`libraries` options ( + + **\*\*** getting C library sources currently broken---no + :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) + +* scripts identified by the :option:`scripts` option + +* anything that looks like a test script: :file:`test/test\*.py` (currently, the + Distutils don't do anything with test scripts except include them in source + distributions, but in the future there will be a standard for testing Python + module distributions) + +* :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever you + called your setup script), and :file:`setup.cfg` + +Sometimes this is enough, but usually you will want to specify additional files +to distribute. The typical way to do this is to write a *manifest template*, +called :file:`MANIFEST.in` by default. The manifest template is just a list of +instructions for how to generate your manifest file, :file:`MANIFEST`, which is +the exact list of files to include in your source distribution. The +:command:`sdist` command processes this template and generates a manifest based +on its instructions and what it finds in the filesystem. + +If you prefer to roll your own manifest file, the format is simple: one filename +per line, regular files (or symlinks to them) only. If you do supply your own +:file:`MANIFEST`, you must specify everything: the default set of files +described above does not apply in this case. + +The manifest template has one command per line, where each command specifies a +set of files to include or exclude from the source distribution. For an +example, again we turn to the Distutils' own manifest template:: + + include *.txt + recursive-include examples *.txt *.py + prune examples/sample?/build + +The meanings should be fairly clear: include all files in the distribution root +matching :file:`\*.txt`, all files anywhere under the :file:`examples` directory +matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching +:file:`examples/sample?/build`. All of this is done *after* the standard +include set, so you can exclude files from the standard set with explicit +instructions in the manifest template. (Or, you can use the +:option:`--no-defaults` option to disable the standard set entirely.) There are +several other commands available in the manifest template mini-language; see +section :ref:`sdist-cmd`. + +The order of commands in the manifest template matters: initially, we have the +list of default files as described above, and each command in the template adds +to or removes from that list of files. Once we have fully processed the +manifest template, we remove files that should not be included in the source +distribution: + +* all files in the Distutils "build" tree (default :file:`build/`) + +* all files in directories named :file:`RCS`, :file:`CVS` or :file:`.svn` + +Now we have our complete list of files, which is written to the manifest for +future reference, and then used to build the source distribution archive(s). + +You can disable the default set of included files with the +:option:`--no-defaults` option, and you can disable the standard exclude set +with :option:`--no-prune`. + +Following the Distutils' own manifest template, let's trace how the +:command:`sdist` command builds the list of files to include in the Distutils +source distribution: + +#. include all Python source files in the :file:`distutils` and + :file:`distutils/command` subdirectories (because packages corresponding to + those two directories were mentioned in the :option:`packages` option in the + setup script---see section :ref:`setup-script`) + +#. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard + files) + +#. include :file:`test/test\*.py` (standard files) + +#. include :file:`\*.txt` in the distribution root (this will find + :file:`README.txt` a second time, but such redundancies are weeded out later) + +#. include anything matching :file:`\*.txt` or :file:`\*.py` in the sub-tree + under :file:`examples`, + +#. exclude all files in the sub-trees starting at directories matching + :file:`examples/sample?/build`\ ---this may exclude files included by the + previous two steps, so it's important that the ``prune`` command in the manifest + template comes after the ``recursive-include`` command + +#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS` and + :file:`.svn` directories + +Just like in the setup script, file and directory names in the manifest template +should always be slash-separated; the Distutils will take care of converting +them to the standard representation on your platform. That way, the manifest +template is portable across operating systems. + + +.. _manifest-options: + +Manifest-related options +======================== + +The normal course of operations for the :command:`sdist` command is as follows: + +* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` + and create the manifest + +* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest + with just the default file set + +* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more + recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading + :file:`MANIFEST.in` + +* use the list of files now in :file:`MANIFEST` (either just generated or read + in) to create the source distribution archive(s) + +There are a couple of options that modify this behaviour. First, use the +:option:`--no-defaults` and :option:`--no-prune` to disable the standard +"include" and "exclude" sets. + +Second, you might want to force the manifest to be regenerated---for example, if +you have added or removed files or directories that match an existing pattern in +the manifest template, you should regenerate the manifest:: + + python setup.py sdist --force-manifest + +Or, you might just want to (re)generate the manifest, but not create a source +distribution:: + + python setup.py sdist --manifest-only + +:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a +shortcut for :option:`--manifest-only`, and :option:`-f` for +:option:`--force-manifest`. + + diff --git a/uploading.rst b/uploading.rst new file mode 100644 index 0000000000..0b82184c48 --- /dev/null +++ b/uploading.rst @@ -0,0 +1,37 @@ +.. _package-upload: + +*************************************** +Uploading Packages to the Package Index +*************************************** + +.. versionadded:: 2.5 + +The Python Package Index (PyPI) not only stores the package info, but also the +package data if the author of the package wishes to. The distutils command +:command:`upload` pushes the distribution files to PyPI. + +The command is invoked immediately after building one or more distribution +files. For example, the command :: + + python setup.py sdist bdist_wininst upload + +will cause the source distribution and the Windows installer to be uploaded to +PyPI. Note that these will be uploaded even if they are built using an earlier +invocation of :file:`setup.py`, but that only distributions named on the command +line for the invocation including the :command:`upload` command are uploaded. + +The :command:`upload` command uses the username, password, and repository URL +from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this +file). + +You can use the :option:`--sign` option to tell :command:`upload` to sign each +uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must +be available for execution on the system :envvar:`PATH`. You can also specify +which key to use for signing using the :option:`--identity=*name*` option. + +Other :command:`upload` options include :option:`--repository=*url*` (which +lets you override the repository setting from :file:`$HOME/.pypirc`), and +:option:`--show-response` (which displays the full response text from the PyPI +server for help in debugging upload problems). + + From a6e3d00688ea151c8a62ff1a3f4916106e706249 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 1 Sep 2007 13:51:09 +0000 Subject: [PATCH 003/330] Get rid of the remaining versionadded/versionchanged directives. --- setupscript.rst | 2 -- uploading.rst | 2 -- 2 files changed, 4 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 26f50e6cd5..3ffcc784df 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -488,8 +488,6 @@ The corresponding call to :func:`setup` might be:: package_data={'mypkg': ['data/*.dat']}, ) -.. versionadded:: 2.4 - Installing Additional Files =========================== diff --git a/uploading.rst b/uploading.rst index 0b82184c48..5be413032c 100644 --- a/uploading.rst +++ b/uploading.rst @@ -4,8 +4,6 @@ Uploading Packages to the Package Index *************************************** -.. versionadded:: 2.5 - The Python Package Index (PyPI) not only stores the package info, but also the package data if the author of the package wishes to. The distutils command :command:`upload` pushes the distribution files to PyPI. From 46ff980e49fd607a6f2ffa9483f483c2bc8922bc Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Oct 2007 10:24:20 +0000 Subject: [PATCH 004/330] Unify "byte code" to "bytecode". Also sprinkle :term: markup for it. --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index b40ddeb369..f6c28d3be8 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -311,7 +311,7 @@ will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`. You have to create a separate installer for every Python version you want to support. -The installer will try to compile pure modules into bytecode after installation +The installer will try to compile pure modules into :term:`bytecode` after installation on the target system in normal and optimizing mode. If you don't want this to happen for some reason, you can run the :command:`bdist_wininst` command with the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` From 09a2cf95606215d0a7fcf2381b36a8ae1f1b14ea Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Oct 2007 10:45:46 +0000 Subject: [PATCH 005/330] Add :term:s for descriptors. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index bc5d2b03d7..e3348816e3 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1199,7 +1199,7 @@ other utility module. If *force* is true, all files are recompiled regardless of timestamps. - The source filename encoded in each bytecode file defaults to the filenames + The source filename encoded in each :term:`bytecode` file defaults to the filenames listed in *py_files*; you can modify these with *prefix* and *basedir*. *prefix* is a string that will be stripped off of each source filename, and *base_dir* is a directory name that will be prepended (after *prefix* is From 34aee2c10a908b2add13a3f41d897008a1d69bb0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 1 Nov 2007 20:32:30 +0000 Subject: [PATCH 006/330] #1370: Finish the merge r58749, log below, by resolving all conflicts in Doc/. Merged revisions 58221-58741 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r58221 | georg.brandl | 2007-09-20 10:57:59 -0700 (Thu, 20 Sep 2007) | 2 lines Patch #1181: add os.environ.clear() method. ........ r58225 | sean.reifschneider | 2007-09-20 23:33:28 -0700 (Thu, 20 Sep 2007) | 3 lines Issue1704287: "make install" fails unless you do "make" first. Make oldsharedmods and sharedmods in "libinstall". ........ r58232 | guido.van.rossum | 2007-09-22 13:18:03 -0700 (Sat, 22 Sep 2007) | 4 lines Patch # 188 by Philip Jenvey. Make tell() mark CRLF as a newline. With unit test. ........ r58242 | georg.brandl | 2007-09-24 10:55:47 -0700 (Mon, 24 Sep 2007) | 2 lines Fix typo and double word. ........ r58245 | georg.brandl | 2007-09-24 10:59:28 -0700 (Mon, 24 Sep 2007) | 2 lines #1196: document default radix for int(). ........ r58247 | georg.brandl | 2007-09-24 11:08:24 -0700 (Mon, 24 Sep 2007) | 2 lines #1177: accept 2xx responses for https too, not only http. ........ r58249 | andrew.kuchling | 2007-09-24 16:45:51 -0700 (Mon, 24 Sep 2007) | 1 line Remove stray odd character; grammar fix ........ r58250 | andrew.kuchling | 2007-09-24 16:46:28 -0700 (Mon, 24 Sep 2007) | 1 line Typo fix ........ r58251 | andrew.kuchling | 2007-09-24 17:09:42 -0700 (Mon, 24 Sep 2007) | 1 line Add various items ........ r58268 | vinay.sajip | 2007-09-26 22:34:45 -0700 (Wed, 26 Sep 2007) | 1 line Change to flush and close logic to fix #1760556. ........ r58269 | vinay.sajip | 2007-09-26 22:38:51 -0700 (Wed, 26 Sep 2007) | 1 line Change to basicConfig() to fix #1021. ........ r58270 | georg.brandl | 2007-09-26 23:26:58 -0700 (Wed, 26 Sep 2007) | 2 lines #1208: document match object's boolean value. ........ r58271 | vinay.sajip | 2007-09-26 23:56:13 -0700 (Wed, 26 Sep 2007) | 1 line Minor date change. ........ r58272 | vinay.sajip | 2007-09-27 00:35:10 -0700 (Thu, 27 Sep 2007) | 1 line Change to LogRecord.__init__() to fix #1206. Note that archaic use of type(x) == types.DictType is because of keeping 1.5.2 compatibility. While this is much less relevant these days, there probably needs to be a separate commit for removing all archaic constructs at the same time. ........ r58288 | brett.cannon | 2007-09-30 12:45:10 -0700 (Sun, 30 Sep 2007) | 9 lines tuple.__repr__ did not consider a reference loop as it is not possible from Python code; but it is possible from C. object.__str__ had the issue of not expecting a type to doing something within it's tp_str implementation that could trigger an infinite recursion, but it could in C code.. Both found thanks to BaseException and how it handles its repr. Closes issue #1686386. Thanks to Thomas Herve for taking an initial stab at coming up with a solution. ........ r58289 | brett.cannon | 2007-09-30 13:37:19 -0700 (Sun, 30 Sep 2007) | 3 lines Fix error introduced by r58288; if a tuple is length 0 return its repr and don't worry about any self-referring tuples. ........ r58294 | facundo.batista | 2007-10-02 10:01:24 -0700 (Tue, 02 Oct 2007) | 11 lines Made the various is_* operations return booleans. This was discussed with Cawlishaw by mail, and he basically confirmed that to these is_* operations, there's no need to return Decimal(0) and Decimal(1) if the language supports the False and True booleans. Also added a few tests for the these functions in extra.decTest, since they are mostly untested (apart from the doctests). Thanks Mark Dickinson ........ r58295 | facundo.batista | 2007-10-02 11:21:18 -0700 (Tue, 02 Oct 2007) | 4 lines Added a class to store the digits of log(10), so that they can be made available when necessary without recomputing. Thanks Mark Dickinson ........ r58299 | mark.summerfield | 2007-10-03 01:53:21 -0700 (Wed, 03 Oct 2007) | 4 lines Added note in footnote about string comparisons about unicodedata.normalize(). ........ r58304 | raymond.hettinger | 2007-10-03 14:18:11 -0700 (Wed, 03 Oct 2007) | 1 line enumerate() is no longer bounded to using sequences shorter than LONG_MAX. The possibility of overflow was sending some newsgroup posters into a tizzy. ........ r58305 | raymond.hettinger | 2007-10-03 17:20:27 -0700 (Wed, 03 Oct 2007) | 1 line itertools.count() no longer limited to sys.maxint. ........ r58306 | kurt.kaiser | 2007-10-03 18:49:54 -0700 (Wed, 03 Oct 2007) | 3 lines Assume that the user knows when he wants to end the line; don't insert something he didn't select or complete. ........ r58307 | kurt.kaiser | 2007-10-03 19:07:50 -0700 (Wed, 03 Oct 2007) | 2 lines Remove unused theme that was causing a fault in p3k. ........ r58308 | kurt.kaiser | 2007-10-03 19:09:17 -0700 (Wed, 03 Oct 2007) | 2 lines Clean up EditorWindow close. ........ r58309 | kurt.kaiser | 2007-10-03 19:53:07 -0700 (Wed, 03 Oct 2007) | 7 lines textView cleanup. Patch 1718043 Tal Einat. M idlelib/EditorWindow.py M idlelib/aboutDialog.py M idlelib/textView.py M idlelib/NEWS.txt ........ r58310 | kurt.kaiser | 2007-10-03 20:11:12 -0700 (Wed, 03 Oct 2007) | 3 lines configDialog cleanup. Patch 1730217 Tal Einat. ........ r58311 | neal.norwitz | 2007-10-03 23:00:48 -0700 (Wed, 03 Oct 2007) | 4 lines Coverity #151: Remove deadcode. All this code already exists above starting at line 653. ........ r58325 | fred.drake | 2007-10-04 19:46:12 -0700 (Thu, 04 Oct 2007) | 1 line wrap lines to <80 characters before fixing errors ........ r58326 | raymond.hettinger | 2007-10-04 19:47:07 -0700 (Thu, 04 Oct 2007) | 6 lines Add __asdict__() to NamedTuple and refine the docs. Add maxlen support to deque() and fixup docs. Partially fix __reduce__(). The None as a third arg was no longer supported. Still needs work on __reduce__() to handle recursive inputs. ........ r58327 | fred.drake | 2007-10-04 19:48:32 -0700 (Thu, 04 Oct 2007) | 3 lines move descriptions of ac_(in|out)_buffer_size to the right place http://bugs.python.org/issue1053 ........ r58329 | neal.norwitz | 2007-10-04 20:39:17 -0700 (Thu, 04 Oct 2007) | 3 lines dict could be NULL, so we need to XDECREF. Fix a compiler warning about passing a PyTypeObject* instead of PyObject*. ........ r58330 | neal.norwitz | 2007-10-04 20:41:19 -0700 (Thu, 04 Oct 2007) | 2 lines Fix Coverity #158: Check the correct variable. ........ r58332 | neal.norwitz | 2007-10-04 22:01:38 -0700 (Thu, 04 Oct 2007) | 7 lines Fix Coverity #159. This code was broken if save() returned a negative number since i contained a boolean value and then we compared i < 0 which should never be true. Will backport (assuming it's necessary) ........ r58334 | neal.norwitz | 2007-10-04 22:29:17 -0700 (Thu, 04 Oct 2007) | 1 line Add a note about fixing some more warnings found by Coverity. ........ r58338 | raymond.hettinger | 2007-10-05 12:07:31 -0700 (Fri, 05 Oct 2007) | 1 line Restore BEGIN/END THREADS macros which were squashed in the previous checkin ........ r58343 | gregory.p.smith | 2007-10-06 00:48:10 -0700 (Sat, 06 Oct 2007) | 3 lines Stab in the dark attempt to fix the test_bsddb3 failure on sparc and S-390 ubuntu buildbots. ........ r58344 | gregory.p.smith | 2007-10-06 00:51:59 -0700 (Sat, 06 Oct 2007) | 2 lines Allows BerkeleyDB 4.6.x >= 4.6.21 for the bsddb module. ........ r58348 | gregory.p.smith | 2007-10-06 08:47:37 -0700 (Sat, 06 Oct 2007) | 3 lines Use the host the author likely meant in the first place. pop.gmail.com is reliable. gmail.org is someones personal domain. ........ r58351 | neal.norwitz | 2007-10-06 12:16:28 -0700 (Sat, 06 Oct 2007) | 3 lines Ensure that this test will pass even if another test left an unwritable TESTFN. Also use the safe unlink in test_support instead of rolling our own here. ........ r58368 | georg.brandl | 2007-10-08 00:50:24 -0700 (Mon, 08 Oct 2007) | 3 lines #1123: fix the docs for the str.split(None, sep) case. Also expand a few other methods' docs, which had more info in the deprecated string module docs. ........ r58369 | georg.brandl | 2007-10-08 01:06:05 -0700 (Mon, 08 Oct 2007) | 2 lines Update docstring of sched, also remove an unused assignment. ........ r58370 | raymond.hettinger | 2007-10-08 02:14:28 -0700 (Mon, 08 Oct 2007) | 5 lines Add comments to NamedTuple code. Let the field spec be either a string or a non-string sequence (suggested by Martin Blais with use cases). Improve the error message in the case of a SyntaxError (caused by a duplicate field name). ........ r58371 | raymond.hettinger | 2007-10-08 02:56:29 -0700 (Mon, 08 Oct 2007) | 1 line Missed a line in the docs ........ r58372 | raymond.hettinger | 2007-10-08 03:11:51 -0700 (Mon, 08 Oct 2007) | 1 line Better variable names ........ r58376 | georg.brandl | 2007-10-08 07:12:47 -0700 (Mon, 08 Oct 2007) | 3 lines #1199: docs for tp_as_{number,sequence,mapping}, by Amaury Forgeot d'Arc. No need to merge this to py3k! ........ r58380 | raymond.hettinger | 2007-10-08 14:26:58 -0700 (Mon, 08 Oct 2007) | 1 line Eliminate camelcase function name ........ r58381 | andrew.kuchling | 2007-10-08 16:23:03 -0700 (Mon, 08 Oct 2007) | 1 line Eliminate camelcase function name ........ r58382 | raymond.hettinger | 2007-10-08 18:36:23 -0700 (Mon, 08 Oct 2007) | 1 line Make the error messages more specific ........ r58384 | gregory.p.smith | 2007-10-08 23:02:21 -0700 (Mon, 08 Oct 2007) | 10 lines Splits Modules/_bsddb.c up into bsddb.h and _bsddb.c and adds a C API object available as bsddb.db.api. This is based on the patch submitted by Duncan Grisby here: http://sourceforge.net/tracker/index.php?func=detail&aid=1551895&group_id=13900&atid=313900 See this thread for additional info: http://sourceforge.net/mailarchive/forum.php?thread_name=E1GAVDK-0002rk-Iw%40apasphere.com&forum_name=pybsddb-users It also cleans up the code a little by removing some ifdef/endifs for python prior to 2.1 and for unsupported Berkeley DB <= 3.2. ........ r58385 | gregory.p.smith | 2007-10-08 23:50:43 -0700 (Mon, 08 Oct 2007) | 5 lines Fix a double free when positioning a database cursor to a non-existant string key (and probably a few other situations with string keys). This was reported with a patch as pybsddb sourceforge bug 1708868 by jjjhhhlll at gmail. ........ r58386 | gregory.p.smith | 2007-10-09 00:19:11 -0700 (Tue, 09 Oct 2007) | 3 lines Use the highest cPickle protocol in bsddb.dbshelve. This comes from sourceforge pybsddb patch 1551443 by w_barnes. ........ r58394 | gregory.p.smith | 2007-10-09 11:26:02 -0700 (Tue, 09 Oct 2007) | 2 lines remove another sleepycat reference ........ r58396 | kurt.kaiser | 2007-10-09 12:31:30 -0700 (Tue, 09 Oct 2007) | 3 lines Allow interrupt only when executing user code in subprocess Patch 1225 Tal Einat modified from IDLE-Spoon. ........ r58399 | brett.cannon | 2007-10-09 17:07:50 -0700 (Tue, 09 Oct 2007) | 5 lines Remove file-level typedefs that were inconsistently used throughout the file. Just move over to the public API names. Closes issue1238. ........ r58401 | raymond.hettinger | 2007-10-09 17:26:46 -0700 (Tue, 09 Oct 2007) | 1 line Accept Jim Jewett's api suggestion to use None instead of -1 to indicate unbounded deques. ........ r58403 | kurt.kaiser | 2007-10-09 17:55:40 -0700 (Tue, 09 Oct 2007) | 2 lines Allow cursor color change w/o restart. Patch 1725576 Tal Einat. ........ r58404 | kurt.kaiser | 2007-10-09 18:06:47 -0700 (Tue, 09 Oct 2007) | 2 lines show paste if > 80 columns. Patch 1659326 Tal Einat. ........ r58415 | thomas.heller | 2007-10-11 12:51:32 -0700 (Thu, 11 Oct 2007) | 5 lines On OS X, use os.uname() instead of gestalt.sysv(...) to get the operating system version. This allows to use ctypes when Python was configured with --disable-toolbox-glue. ........ r58419 | neal.norwitz | 2007-10-11 20:01:01 -0700 (Thu, 11 Oct 2007) | 1 line Get rid of warning about not being able to create an existing directory. ........ r58420 | neal.norwitz | 2007-10-11 20:01:30 -0700 (Thu, 11 Oct 2007) | 1 line Get rid of warnings on a bunch of platforms by using a proper prototype. ........ r58421 | neal.norwitz | 2007-10-11 20:01:54 -0700 (Thu, 11 Oct 2007) | 4 lines Get rid of compiler warning about retval being used (returned) without being initialized. (gcc warning and Coverity 202) ........ r58422 | neal.norwitz | 2007-10-11 20:03:23 -0700 (Thu, 11 Oct 2007) | 1 line Fix Coverity 168: Close the file before returning (exiting). ........ r58423 | neal.norwitz | 2007-10-11 20:04:18 -0700 (Thu, 11 Oct 2007) | 4 lines Fix Coverity 180: Don't overallocate. We don't need structs, but pointers. Also fix a memory leak. ........ r58424 | neal.norwitz | 2007-10-11 20:05:19 -0700 (Thu, 11 Oct 2007) | 5 lines Fix Coverity 185-186: If the passed in FILE is NULL, uninitialized memory would be accessed. Will backport. ........ r58425 | neal.norwitz | 2007-10-11 20:52:34 -0700 (Thu, 11 Oct 2007) | 1 line Get this module to compile with bsddb versions prior to 4.3 ........ r58430 | martin.v.loewis | 2007-10-12 01:56:52 -0700 (Fri, 12 Oct 2007) | 3 lines Bug #1216: Restore support for Visual Studio 2002. Will backport to 2.5. ........ r58433 | raymond.hettinger | 2007-10-12 10:53:11 -0700 (Fri, 12 Oct 2007) | 1 line Fix test of count.__repr__() to ignore the 'L' if the count is a long ........ r58434 | gregory.p.smith | 2007-10-12 11:44:06 -0700 (Fri, 12 Oct 2007) | 4 lines Fixes http://bugs.python.org/issue1233 - bsddb.dbshelve.DBShelf.append was useless due to inverted logic. Also adds a test case for RECNO dbs to test_dbshelve. ........ r58445 | georg.brandl | 2007-10-13 06:20:03 -0700 (Sat, 13 Oct 2007) | 2 lines Fix email example. ........ r58450 | gregory.p.smith | 2007-10-13 16:02:05 -0700 (Sat, 13 Oct 2007) | 2 lines Fix an uncollectable reference leak in bsddb.db.DBShelf.append ........ r58453 | neal.norwitz | 2007-10-13 17:18:40 -0700 (Sat, 13 Oct 2007) | 8 lines Let the O/S supply a port if none of the default ports can be used. This should make the tests more robust at the expense of allowing tests to be sloppier by not requiring them to cleanup after themselves. (It will legitamitely help when running two test suites simultaneously or if another process is already using one of the predefined ports.) Also simplifies (slightLy) the exception handling elsewhere. ........ r58459 | neal.norwitz | 2007-10-14 11:30:21 -0700 (Sun, 14 Oct 2007) | 2 lines Don't raise a string exception, they don't work anymore. ........ r58460 | neal.norwitz | 2007-10-14 11:40:37 -0700 (Sun, 14 Oct 2007) | 1 line Use unittest for assertions ........ r58468 | armin.rigo | 2007-10-15 00:48:35 -0700 (Mon, 15 Oct 2007) | 2 lines test_bigbits was not testing what it seemed to. ........ r58471 | guido.van.rossum | 2007-10-15 08:54:11 -0700 (Mon, 15 Oct 2007) | 3 lines Change a PyErr_Print() into a PyErr_Clear(), per discussion in issue 1031213. ........ r58500 | raymond.hettinger | 2007-10-16 12:18:30 -0700 (Tue, 16 Oct 2007) | 1 line Improve error messages ........ r58506 | raymond.hettinger | 2007-10-16 14:28:32 -0700 (Tue, 16 Oct 2007) | 1 line More docs, error messages, and tests ........ r58507 | andrew.kuchling | 2007-10-16 15:58:03 -0700 (Tue, 16 Oct 2007) | 1 line Add items ........ r58508 | brett.cannon | 2007-10-16 16:24:06 -0700 (Tue, 16 Oct 2007) | 3 lines Remove ``:const:`` notation on None in parameter list. Since the markup is not rendered for parameters it just showed up as ``:const:`None` `` in the output. ........ r58509 | brett.cannon | 2007-10-16 16:26:45 -0700 (Tue, 16 Oct 2007) | 3 lines Re-order some functions whose parameters differ between PyObject and const char * so that they are next to each other. ........ r58522 | armin.rigo | 2007-10-17 11:46:37 -0700 (Wed, 17 Oct 2007) | 5 lines Fix the overflow checking of list_repeat. Introduce overflow checking into list_inplace_repeat. Backport candidate, possibly. ........ r58530 | facundo.batista | 2007-10-17 20:16:03 -0700 (Wed, 17 Oct 2007) | 7 lines Issue #1580738. When HTTPConnection reads the whole stream with read(), it closes itself. When the stream is read in several calls to read(n), it should behave in the same way if HTTPConnection knows where the end of the stream is (through self.length). Added a test case for this behaviour. ........ r58531 | facundo.batista | 2007-10-17 20:44:48 -0700 (Wed, 17 Oct 2007) | 3 lines Issue 1289, just a typo. ........ r58532 | gregory.p.smith | 2007-10-18 00:56:54 -0700 (Thu, 18 Oct 2007) | 4 lines cleanup test_dbtables to use mkdtemp. cleanup dbtables to pass txn as a keyword argument whenever possible to avoid bugs and confusion. (dbtables.py line 447 self.db.get using txn as a non-keyword was an actual bug due to this) ........ r58533 | gregory.p.smith | 2007-10-18 01:34:20 -0700 (Thu, 18 Oct 2007) | 4 lines Fix a weird bug in dbtables: if it chose a random rowid string that contained NULL bytes it would cause the database all sorts of problems in the future leading to very strange random failures and corrupt dbtables.bsdTableDb dbs. ........ r58534 | gregory.p.smith | 2007-10-18 09:32:02 -0700 (Thu, 18 Oct 2007) | 3 lines A cleaner fix than the one committed last night. Generate random rowids that do not contain null bytes. ........ r58537 | gregory.p.smith | 2007-10-18 10:17:57 -0700 (Thu, 18 Oct 2007) | 2 lines mention bsddb fixes. ........ r58538 | raymond.hettinger | 2007-10-18 14:13:06 -0700 (Thu, 18 Oct 2007) | 1 line Remove useless warning ........ r58539 | gregory.p.smith | 2007-10-19 00:31:20 -0700 (Fri, 19 Oct 2007) | 2 lines squelch the warning that this test is supposed to trigger. ........ r58542 | georg.brandl | 2007-10-19 05:32:39 -0700 (Fri, 19 Oct 2007) | 2 lines Clarify wording for apply(). ........ r58544 | mark.summerfield | 2007-10-19 05:48:17 -0700 (Fri, 19 Oct 2007) | 3 lines Added a cross-ref to each other. ........ r58545 | georg.brandl | 2007-10-19 10:38:49 -0700 (Fri, 19 Oct 2007) | 2 lines #1284: "S" means "seen", not unread. ........ r58548 | thomas.heller | 2007-10-19 11:11:41 -0700 (Fri, 19 Oct 2007) | 4 lines Fix ctypes on 32-bit systems when Python is configured --with-system-ffi. See also https://bugs.launchpad.net/bugs/72505. Ported from release25-maint branch. ........ r58550 | facundo.batista | 2007-10-19 12:25:57 -0700 (Fri, 19 Oct 2007) | 8 lines The constructor from tuple was way too permissive: it allowed bad coefficient numbers, floats in the sign, and other details that generated directly the wrong number in the best case, or triggered misfunctionality in the alorithms. Test cases added for these issues. Thanks Mark Dickinson. ........ r58559 | georg.brandl | 2007-10-20 06:22:53 -0700 (Sat, 20 Oct 2007) | 2 lines Fix code being interpreted as a target. ........ r58561 | georg.brandl | 2007-10-20 06:36:24 -0700 (Sat, 20 Oct 2007) | 2 lines Document new "cmdoption" directive. ........ r58562 | georg.brandl | 2007-10-20 08:21:22 -0700 (Sat, 20 Oct 2007) | 2 lines Make a path more Unix-standardy. ........ r58564 | georg.brandl | 2007-10-20 10:51:39 -0700 (Sat, 20 Oct 2007) | 2 lines Document new directive "envvar". ........ r58567 | georg.brandl | 2007-10-20 11:08:14 -0700 (Sat, 20 Oct 2007) | 6 lines * Add new toplevel chapter, "Using Python." (how to install, configure and setup python on different platforms -- at least in theory.) * Move the Python on Mac docs in that chapter. * Add a new chapter about the command line invocation, by stargaming. ........ r58568 | georg.brandl | 2007-10-20 11:33:20 -0700 (Sat, 20 Oct 2007) | 2 lines Change title, for now. ........ r58569 | georg.brandl | 2007-10-20 11:39:25 -0700 (Sat, 20 Oct 2007) | 2 lines Add entry to ACKS. ........ r58570 | georg.brandl | 2007-10-20 12:05:45 -0700 (Sat, 20 Oct 2007) | 2 lines Clarify -E docs. ........ r58571 | georg.brandl | 2007-10-20 12:08:36 -0700 (Sat, 20 Oct 2007) | 2 lines Even more clarification. ........ r58572 | andrew.kuchling | 2007-10-20 12:25:37 -0700 (Sat, 20 Oct 2007) | 1 line Fix protocol name ........ r58573 | andrew.kuchling | 2007-10-20 12:35:18 -0700 (Sat, 20 Oct 2007) | 1 line Various items ........ r58574 | andrew.kuchling | 2007-10-20 12:39:35 -0700 (Sat, 20 Oct 2007) | 1 line Use correct header line ........ r58576 | armin.rigo | 2007-10-21 02:14:15 -0700 (Sun, 21 Oct 2007) | 3 lines Add a crasher for the long-standing issue with closing a file while another thread uses it. ........ r58577 | georg.brandl | 2007-10-21 03:01:56 -0700 (Sun, 21 Oct 2007) | 2 lines Remove duplicate crasher. ........ r58578 | georg.brandl | 2007-10-21 03:24:20 -0700 (Sun, 21 Oct 2007) | 2 lines Unify "byte code" to "bytecode". Also sprinkle :term: markup for it. ........ r58579 | georg.brandl | 2007-10-21 03:32:54 -0700 (Sun, 21 Oct 2007) | 2 lines Add markup to new function descriptions. ........ r58580 | georg.brandl | 2007-10-21 03:45:46 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for descriptors. ........ r58581 | georg.brandl | 2007-10-21 03:46:24 -0700 (Sun, 21 Oct 2007) | 2 lines Unify "file-descriptor" to "file descriptor". ........ r58582 | georg.brandl | 2007-10-21 03:52:38 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term: for generators. ........ r58583 | georg.brandl | 2007-10-21 05:10:28 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for iterator. ........ r58584 | georg.brandl | 2007-10-21 05:15:05 -0700 (Sun, 21 Oct 2007) | 2 lines Add :term:s for "new-style class". ........ r58588 | neal.norwitz | 2007-10-21 21:47:54 -0700 (Sun, 21 Oct 2007) | 1 line Add Chris Monson so he can edit PEPs. ........ r58594 | guido.van.rossum | 2007-10-22 09:27:19 -0700 (Mon, 22 Oct 2007) | 4 lines Issue #1307, patch by Derek Shockey. When "MAIL" is received without args, an exception happens instead of sending a 501 syntax error response. ........ r58598 | travis.oliphant | 2007-10-22 19:40:56 -0700 (Mon, 22 Oct 2007) | 1 line Add phuang patch from Issue 708374 which adds offset parameter to mmap module. ........ r58601 | neal.norwitz | 2007-10-22 22:44:27 -0700 (Mon, 22 Oct 2007) | 2 lines Bug #1313, fix typo (wrong variable name) in example. ........ r58609 | georg.brandl | 2007-10-23 11:21:35 -0700 (Tue, 23 Oct 2007) | 2 lines Update Pygments version from externals. ........ r58618 | guido.van.rossum | 2007-10-23 12:25:41 -0700 (Tue, 23 Oct 2007) | 3 lines Issue 1307 by Derek Shockey, fox the same bug for RCPT. Neal: please backport! ........ r58620 | raymond.hettinger | 2007-10-23 13:37:41 -0700 (Tue, 23 Oct 2007) | 1 line Shorter name for namedtuple() ........ r58621 | andrew.kuchling | 2007-10-23 13:55:47 -0700 (Tue, 23 Oct 2007) | 1 line Update name ........ r58622 | raymond.hettinger | 2007-10-23 14:23:07 -0700 (Tue, 23 Oct 2007) | 1 line Fixup news entry ........ r58623 | raymond.hettinger | 2007-10-23 18:28:33 -0700 (Tue, 23 Oct 2007) | 1 line Optimize sum() for integer and float inputs. ........ r58624 | raymond.hettinger | 2007-10-23 19:05:51 -0700 (Tue, 23 Oct 2007) | 1 line Fixup error return and add support for intermixed ints and floats/ ........ r58628 | vinay.sajip | 2007-10-24 03:47:06 -0700 (Wed, 24 Oct 2007) | 1 line Bug #1321: Fixed logic error in TimedRotatingFileHandler.__init__() ........ r58641 | facundo.batista | 2007-10-24 12:11:08 -0700 (Wed, 24 Oct 2007) | 4 lines Issue 1290. CharacterData.__repr__ was constructing a string in response that keeped having a non-ascii character. ........ r58643 | thomas.heller | 2007-10-24 12:50:45 -0700 (Wed, 24 Oct 2007) | 1 line Added unittest for calling a function with paramflags (backport from py3k branch). ........ r58645 | matthias.klose | 2007-10-24 13:00:44 -0700 (Wed, 24 Oct 2007) | 2 lines - Build using system ffi library on arm*-linux*. ........ r58651 | georg.brandl | 2007-10-24 14:40:38 -0700 (Wed, 24 Oct 2007) | 2 lines Bug #1287: make os.environ.pop() work as expected. ........ r58652 | raymond.hettinger | 2007-10-24 19:26:58 -0700 (Wed, 24 Oct 2007) | 1 line Missing DECREFs ........ r58653 | matthias.klose | 2007-10-24 23:37:24 -0700 (Wed, 24 Oct 2007) | 2 lines - Build using system ffi library on arm*-linux*, pass --with-system-ffi to CONFIG_ARGS ........ r58655 | thomas.heller | 2007-10-25 12:47:32 -0700 (Thu, 25 Oct 2007) | 2 lines ffi_type_longdouble may be already #defined. See issue 1324. ........ r58656 | kurt.kaiser | 2007-10-25 15:43:45 -0700 (Thu, 25 Oct 2007) | 3 lines Correct an ancient bug in an unused path by removing that path: register() is now idempotent. ........ r58660 | kurt.kaiser | 2007-10-25 17:10:09 -0700 (Thu, 25 Oct 2007) | 4 lines 1. Add comments to provide top-level documentation. 2. Refactor to use more descriptive names. 3. Enhance tests in main(). ........ r58675 | georg.brandl | 2007-10-26 11:30:41 -0700 (Fri, 26 Oct 2007) | 2 lines Fix new pop() method on os.environ on ignorecase-platforms. ........ r58696 | neal.norwitz | 2007-10-27 15:32:21 -0700 (Sat, 27 Oct 2007) | 1 line Update URL for Pygments. 0.8.1 is no longer available ........ r58697 | hyeshik.chang | 2007-10-28 04:19:02 -0700 (Sun, 28 Oct 2007) | 3 lines - Add support for FreeBSD 8 which is recently forked from FreeBSD 7. - Regenerate IN module for most recent maintenance tree of FreeBSD 6 and 7. ........ r58698 | hyeshik.chang | 2007-10-28 05:38:09 -0700 (Sun, 28 Oct 2007) | 2 lines Enable platform-specific tweaks for FreeBSD 8 (exactly same to FreeBSD 7's yet) ........ r58700 | kurt.kaiser | 2007-10-28 12:03:59 -0700 (Sun, 28 Oct 2007) | 2 lines Add confirmation dialog before printing. Patch 1717170 Tal Einat. ........ r58706 | guido.van.rossum | 2007-10-29 13:52:45 -0700 (Mon, 29 Oct 2007) | 3 lines Patch 1353 by Jacob Winther. Add mp4 mapping to mimetypes.py. ........ r58709 | guido.van.rossum | 2007-10-29 15:15:05 -0700 (Mon, 29 Oct 2007) | 6 lines Backport fixes for the code that decodes octal escapes (and for PyString also hex escapes) -- this was reaching beyond the end of the input string buffer, even though it is not supposed to be \0-terminated. This has no visible effect but is clearly the correct thing to do. (In 3.0 it had a visible effect after removing ob_sstate from PyString.) ........ r58710 | kurt.kaiser | 2007-10-29 19:38:54 -0700 (Mon, 29 Oct 2007) | 7 lines check in Tal Einat's update to tabpage.py Patch 1612746 M configDialog.py M NEWS.txt AM tabbedpages.py ........ r58715 | georg.brandl | 2007-10-30 10:51:18 -0700 (Tue, 30 Oct 2007) | 2 lines Use correct markup. ........ r58716 | georg.brandl | 2007-10-30 10:57:12 -0700 (Tue, 30 Oct 2007) | 2 lines Make example about hiding None return values at the prompt clearer. ........ r58728 | neal.norwitz | 2007-10-30 23:33:20 -0700 (Tue, 30 Oct 2007) | 1 line Fix some compiler warnings for signed comparisons on Unix and Windows. ........ r58731 | martin.v.loewis | 2007-10-31 10:19:33 -0700 (Wed, 31 Oct 2007) | 2 lines Adding Christian Heimes. ........ r58737 | raymond.hettinger | 2007-10-31 14:57:58 -0700 (Wed, 31 Oct 2007) | 1 line Clarify the reasons why pickle is almost always better than marshal ........ r58739 | raymond.hettinger | 2007-10-31 15:15:49 -0700 (Wed, 31 Oct 2007) | 1 line Sets are marshalable. ........ --- apiref.rst | 2 +- builtdist.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index c8e57fde0b..57e7ea89c1 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1199,7 +1199,7 @@ other utility module. If *force* is true, all files are recompiled regardless of timestamps. - The source filename encoded in each bytecode file defaults to the filenames + The source filename encoded in each :term:`bytecode` file defaults to the filenames listed in *py_files*; you can modify these with *prefix* and *basedir*. *prefix* is a string that will be stripped off of each source filename, and *base_dir* is a directory name that will be prepended (after *prefix* is diff --git a/builtdist.rst b/builtdist.rst index b40ddeb369..f6c28d3be8 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -311,7 +311,7 @@ will reflect this and now has the form :file:`foo-1.0.win32-py2.0.exe`. You have to create a separate installer for every Python version you want to support. -The installer will try to compile pure modules into bytecode after installation +The installer will try to compile pure modules into :term:`bytecode` after installation on the target system in normal and optimizing mode. If you don't want this to happen for some reason, you can run the :command:`bdist_wininst` command with the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` From e7117b7543e8362698c4dd0e63cb1b91f01e0789 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 27 Nov 2007 12:43:08 +0000 Subject: [PATCH 007/330] Futher update docs after unbound method removal. --- apiref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 57e7ea89c1..6c2be3e9f0 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1965,12 +1965,12 @@ Subclasses of :class:`Command` must define the following methods. as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The parent of a family of commands defines *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string -and *predicate* an unbound method, a string or None. *predicate* is a method of +and *predicate* a function, a string or None. *predicate* is a method of the parent command that determines whether the corresponding command is applicable in the current situation. (Eg. we ``install_headers`` is only applicable if we have any C header files to install.) If *predicate* is None, that command is always applicable. *sub_commands* is usually defined at the \*end\* of a class, because predicates -can be unbound methods, so they must already have been defined. The canonical -example is the :command:`install` command. +can be methods of the class, so they must already have been defined. The +canonical example is the :command:`install` command. From 1dbf392d6c28c827e4da6c7c42ec6807924d61e1 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 1 Dec 2007 23:12:45 +0000 Subject: [PATCH 008/330] Add "Using Python on Windows" document, by Robert Lehmann. Written for GHOP. --- extending.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extending.rst b/extending.rst index a2930c77df..972ff02c03 100644 --- a/extending.rst +++ b/extending.rst @@ -1,4 +1,4 @@ -.. _extending: +.. _extending-distutils: ******************* Extending Distutils From 770f40c9ed69ebeb87b1a373f20b34d0c7c59fd9 Mon Sep 17 00:00:00 2001 From: Christian Heimes Date: Sun, 2 Dec 2007 15:22:16 +0000 Subject: [PATCH 009/330] Merged revisions 59259-59274 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59260 | lars.gustaebel | 2007-12-01 22:02:12 +0100 (Sat, 01 Dec 2007) | 5 lines Issue #1531: Read fileobj from the current offset, do not seek to the start. (will backport to 2.5) ........ r59262 | georg.brandl | 2007-12-01 23:24:47 +0100 (Sat, 01 Dec 2007) | 4 lines Document PyEval_* functions from ceval.c. Credits to Michael Sloan from GHOP. ........ r59263 | georg.brandl | 2007-12-01 23:27:56 +0100 (Sat, 01 Dec 2007) | 2 lines Add a few refcount data entries. ........ r59264 | georg.brandl | 2007-12-01 23:38:48 +0100 (Sat, 01 Dec 2007) | 4 lines Add test suite for cmd module. Written by Michael Schneider for GHOP. ........ r59265 | georg.brandl | 2007-12-01 23:42:46 +0100 (Sat, 01 Dec 2007) | 3 lines Add examples to the ElementTree documentation. Written by h4wk.cz for GHOP. ........ r59266 | georg.brandl | 2007-12-02 00:12:45 +0100 (Sun, 02 Dec 2007) | 3 lines Add "Using Python on Windows" document, by Robert Lehmann. Written for GHOP. ........ r59271 | georg.brandl | 2007-12-02 15:34:34 +0100 (Sun, 02 Dec 2007) | 3 lines Add example to mmap docs. Written for GHOP by Rafal Rawicki. ........ r59272 | georg.brandl | 2007-12-02 15:37:29 +0100 (Sun, 02 Dec 2007) | 2 lines Convert bdb.rst line endings to Unix style. ........ r59274 | georg.brandl | 2007-12-02 15:58:50 +0100 (Sun, 02 Dec 2007) | 4 lines Add more entries to the glossary. Written by Jeff Wheeler for GHOP. ........ --- extending.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/extending.rst b/extending.rst index a2930c77df..972ff02c03 100644 --- a/extending.rst +++ b/extending.rst @@ -1,4 +1,4 @@ -.. _extending: +.. _extending-distutils: ******************* Extending Distutils From 3c674561553eb77e7cde26172f0464c50ee41351 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 29 Dec 2007 10:57:00 +0000 Subject: [PATCH 010/330] Some cleanup in the docs. --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index 26f50e6cd5..167265b083 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -137,7 +137,7 @@ the Distutils to go out and find the right files; you have to specify the extension name, source file(s), and any compile/link requirements (include directories, libraries to link with, etc.). -.. % XXX read over this section +.. XXX read over this section All of this is done through another keyword argument to :func:`setup`, the :option:`ext_modules` option. :option:`ext_modules` is just a list of From cb9a4530755a713271f85ab0470b06d9787d0fa2 Mon Sep 17 00:00:00 2001 From: Christian Heimes Date: Mon, 31 Dec 2007 16:14:33 +0000 Subject: [PATCH 011/330] Merged revisions 59605-59624 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r59606 | georg.brandl | 2007-12-29 11:57:00 +0100 (Sat, 29 Dec 2007) | 2 lines Some cleanup in the docs. ........ r59611 | martin.v.loewis | 2007-12-29 19:49:21 +0100 (Sat, 29 Dec 2007) | 2 lines Bug #1699: Define _BSD_SOURCE only on OpenBSD. ........ r59612 | raymond.hettinger | 2007-12-29 23:09:34 +0100 (Sat, 29 Dec 2007) | 1 line Simpler documentation for itertools.tee(). Should be backported. ........ r59613 | raymond.hettinger | 2007-12-29 23:16:24 +0100 (Sat, 29 Dec 2007) | 1 line Improve docs for itertools.groupby(). The use of xrange(0) to create a unique object is less obvious than object(). ........ r59620 | christian.heimes | 2007-12-31 15:47:07 +0100 (Mon, 31 Dec 2007) | 3 lines Added wininst-9.0.exe executable for VS 2008 Integrated bdist_wininst into PCBuild9 directory ........ r59621 | christian.heimes | 2007-12-31 15:51:18 +0100 (Mon, 31 Dec 2007) | 1 line Moved PCbuild directory to PC/VS7.1 ........ r59622 | christian.heimes | 2007-12-31 15:59:26 +0100 (Mon, 31 Dec 2007) | 1 line Fix paths for build bot ........ r59623 | christian.heimes | 2007-12-31 16:02:41 +0100 (Mon, 31 Dec 2007) | 1 line Fix paths for build bot, part 2 ........ r59624 | christian.heimes | 2007-12-31 16:18:55 +0100 (Mon, 31 Dec 2007) | 1 line Renamed PCBuild9 directory to PCBuild ........ --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index 3ffcc784df..8b88b589bd 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -137,7 +137,7 @@ the Distutils to go out and find the right files; you have to specify the extension name, source file(s), and any compile/link requirements (include directories, libraries to link with, etc.). -.. % XXX read over this section +.. XXX read over this section All of this is done through another keyword argument to :func:`setup`, the :option:`ext_modules` option. :option:`ext_modules` is just a list of From 122d159019a971976a95b88f4ff3da0ddd99e801 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 21 Feb 2008 20:38:13 +0000 Subject: [PATCH 012/330] Part of #2154: minimal syntax fixes in doc example snippets. --- setupscript.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 167265b083..0ff347675d 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -185,7 +185,7 @@ If you have a number of extensions all in the same package (or all under the same base package), use the :option:`ext_package` keyword argument to :func:`setup`. For example, :: - setup(... + setup(..., ext_package='pkg', ext_modules=[Extension('foo', ['foo.c']), Extension('subpkg.bar', ['bar.c'])], @@ -214,7 +214,7 @@ extension. This warning notwithstanding, options to SWIG can be currently passed like this:: - setup(... + setup(..., ext_modules=[Extension('_foo', ['foo.i'], swig_opts=['-modern', '-I../include'])], py_modules=['foo'], @@ -443,7 +443,7 @@ option will allow the interpreter path to be explicitly overridden. The :option:`scripts` option simply is a list of files to be handled in this way. From the PyXML setup script:: - setup(... + setup(..., scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] ) @@ -501,7 +501,7 @@ anything which doesn't fit in the previous categories. :option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the following way:: - setup(... + setup(..., data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), ('config', ['cfg/data.cfg']), ('/etc/init.d', ['init-script'])] @@ -613,7 +613,7 @@ information is sometimes used to indicate sub-releases. These are :option:`classifiers` are specified in a python list:: - setup(... + setup(..., classifiers=[ 'Development Status :: 4 - Beta', 'Environment :: Console', From 799570acb1e788507590708e9ede419b5bec7d2f Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 22 Feb 2008 12:31:45 +0000 Subject: [PATCH 013/330] A lot more typo fixes by Ori Avtalion. --- builtdist.rst | 2 +- packageindex.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index f6c28d3be8..2ebc9860f1 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -195,7 +195,7 @@ Distutils configuration files. Various options and sections in the | | or --- & :option:`maintainer` and | | | :option:`maintainer_email` | +------------------------------------------+----------------------------------------------+ -| Copyright | :option:`licence` | +| Copyright | :option:`license` | +------------------------------------------+----------------------------------------------+ | Url | :option:`url` | +------------------------------------------+----------------------------------------------+ diff --git a/packageindex.rst b/packageindex.rst index f0f886bcc9..8242012816 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -53,13 +53,13 @@ the web interface. The .pypirc file ================ -The format of the :file:`.pypirc` file is formated as follows:: +The format of the :file:`.pypirc` file is as follows:: [server-login] repository: username: password: -*repository* can be ommitted and defaults to ``http://www.python.org/pypi``. +*repository* can be omitted and defaults to ``http://www.python.org/pypi``. From c149ceb29aff2d018f9224507d94be6487d88bbd Mon Sep 17 00:00:00 2001 From: Christian Heimes Date: Fri, 22 Feb 2008 16:37:40 +0000 Subject: [PATCH 014/330] Merged revisions 60481,60485,60489-60492,60494-60496,60498-60499,60501-60503,60505-60506,60508-60509,60523-60524,60532,60543,60545,60547-60548,60552,60554,60556-60559,60561-60562,60569,60571-60572,60574,60576-60583,60585-60586,60589,60591,60594-60595,60597-60598,60600-60601,60606-60612,60615,60617,60619-60621,60623-60625,60627-60629,60631,60633,60635,60647,60650,60652,60654,60656,60658-60659,60664-60666,60668-60670,60672,60676,60678,60680-60683,60685-60686,60688,60690,60692-60694,60697-60700,60705-60706,60708,60711,60714,60720,60724-60730,60732,60736,60742,60744,60746,60748,60750-60751,60753,60756-60757,60759-60761,60763-60764,60766,60769-60770,60774-60784,60787-60789,60793,60796,60799-60809,60812-60813,60815-60821,60823-60826,60828-60829,60831-60834,60836,60838-60839,60846-60849,60852-60854,60856-60859,60861-60870,60874-60875,60880-60881,60886,60888-60890,60892,60894-60898,60900-60931,60933-60958 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r60901 | eric.smith | 2008-02-19 14:21:56 +0100 (Tue, 19 Feb 2008) | 1 line Added PEP 3101. ........ r60907 | georg.brandl | 2008-02-20 20:12:36 +0100 (Wed, 20 Feb 2008) | 2 lines Fixes contributed by Ori Avtalion. ........ r60909 | eric.smith | 2008-02-21 00:34:22 +0100 (Thu, 21 Feb 2008) | 1 line Trim leading zeros from a floating point exponent, per C99. See issue 1600. As far as I know, this only affects Windows. Add float type 'n' to PyOS_ascii_formatd (see PEP 3101 for 'n' description). ........ r60910 | eric.smith | 2008-02-21 00:39:28 +0100 (Thu, 21 Feb 2008) | 1 line Now that PyOS_ascii_formatd supports the 'n' format, simplify the float formatting code to just call it. ........ r60918 | andrew.kuchling | 2008-02-21 15:23:38 +0100 (Thu, 21 Feb 2008) | 2 lines Close manifest file. This change doesn't make any difference to CPython, but is a necessary fix for Jython. ........ r60921 | guido.van.rossum | 2008-02-21 18:46:16 +0100 (Thu, 21 Feb 2008) | 2 lines Remove news about float repr() -- issue 1580 is still in limbo. ........ r60923 | guido.van.rossum | 2008-02-21 19:18:37 +0100 (Thu, 21 Feb 2008) | 5 lines Removed uses of dict.has_key() from distutils, and uses of callable() from copy_reg.py, so the interpreter now starts up without warnings when '-3' is given. More work like this needs to be done in the rest of the stdlib. ........ r60924 | thomas.heller | 2008-02-21 19:28:48 +0100 (Thu, 21 Feb 2008) | 4 lines configure.ac: Remove the configure check for _Bool, it is already done in the top-level Python configure script. configure, fficonfig.h.in: regenerated. ........ r60925 | thomas.heller | 2008-02-21 19:52:20 +0100 (Thu, 21 Feb 2008) | 3 lines Replace 'has_key()' with 'in'. Replace 'raise Error, stuff' with 'raise Error(stuff)'. ........ r60927 | raymond.hettinger | 2008-02-21 20:24:53 +0100 (Thu, 21 Feb 2008) | 1 line Update more instances of has_key(). ........ r60928 | guido.van.rossum | 2008-02-21 20:46:35 +0100 (Thu, 21 Feb 2008) | 3 lines Fix a few typos and layout glitches (more work is needed). Move 2.5 news to Misc/HISTORY. ........ r60936 | georg.brandl | 2008-02-21 21:33:38 +0100 (Thu, 21 Feb 2008) | 2 lines #2079: typo in userdict docs. ........ r60938 | georg.brandl | 2008-02-21 21:38:13 +0100 (Thu, 21 Feb 2008) | 2 lines Part of #2154: minimal syntax fixes in doc example snippets. ........ r60942 | raymond.hettinger | 2008-02-22 04:16:42 +0100 (Fri, 22 Feb 2008) | 1 line First draft for itertools.product(). Docs and other updates forthcoming. ........ r60955 | nick.coghlan | 2008-02-22 11:54:06 +0100 (Fri, 22 Feb 2008) | 1 line Try to make command line error messages from runpy easier to understand (and suppress traceback cruft from the implicitly invoked runpy machinery) ........ r60956 | georg.brandl | 2008-02-22 13:31:45 +0100 (Fri, 22 Feb 2008) | 2 lines A lot more typo fixes by Ori Avtalion. ........ r60957 | georg.brandl | 2008-02-22 13:56:34 +0100 (Fri, 22 Feb 2008) | 2 lines Don't reference pyshell. ........ r60958 | georg.brandl | 2008-02-22 13:57:05 +0100 (Fri, 22 Feb 2008) | 2 lines Another fix. ........ --- builtdist.rst | 2 +- packageindex.rst | 4 ++-- setupscript.rst | 10 +++++----- 3 files changed, 8 insertions(+), 8 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index f6c28d3be8..2ebc9860f1 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -195,7 +195,7 @@ Distutils configuration files. Various options and sections in the | | or --- & :option:`maintainer` and | | | :option:`maintainer_email` | +------------------------------------------+----------------------------------------------+ -| Copyright | :option:`licence` | +| Copyright | :option:`license` | +------------------------------------------+----------------------------------------------+ | Url | :option:`url` | +------------------------------------------+----------------------------------------------+ diff --git a/packageindex.rst b/packageindex.rst index f0f886bcc9..8242012816 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -53,13 +53,13 @@ the web interface. The .pypirc file ================ -The format of the :file:`.pypirc` file is formated as follows:: +The format of the :file:`.pypirc` file is as follows:: [server-login] repository: username: password: -*repository* can be ommitted and defaults to ``http://www.python.org/pypi``. +*repository* can be omitted and defaults to ``http://www.python.org/pypi``. diff --git a/setupscript.rst b/setupscript.rst index 8b88b589bd..7c65821d74 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -185,7 +185,7 @@ If you have a number of extensions all in the same package (or all under the same base package), use the :option:`ext_package` keyword argument to :func:`setup`. For example, :: - setup(... + setup(..., ext_package='pkg', ext_modules=[Extension('foo', ['foo.c']), Extension('subpkg.bar', ['bar.c'])], @@ -214,7 +214,7 @@ extension. This warning notwithstanding, options to SWIG can be currently passed like this:: - setup(... + setup(..., ext_modules=[Extension('_foo', ['foo.i'], swig_opts=['-modern', '-I../include'])], py_modules=['foo'], @@ -443,7 +443,7 @@ option will allow the interpreter path to be explicitly overridden. The :option:`scripts` option simply is a list of files to be handled in this way. From the PyXML setup script:: - setup(... + setup(..., scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] ) @@ -499,7 +499,7 @@ anything which doesn't fit in the previous categories. :option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the following way:: - setup(... + setup(..., data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), ('config', ['cfg/data.cfg']), ('/etc/init.d', ['init-script'])] @@ -611,7 +611,7 @@ information is sometimes used to indicate sub-releases. These are :option:`classifiers` are specified in a python list:: - setup(... + setup(..., classifiers=[ 'Development Status :: 4 - Beta', 'Environment :: Console', From 1ed53eb3a1f00b9e08cbc5e871c6579b46f46e3e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 6 Mar 2008 06:47:18 +0000 Subject: [PATCH 015/330] #1725737: ignore other VC directories other than CVS and SVN's too. --- sourcedist.rst | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 9f15870ccd..960cc0ae4d 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -122,7 +122,8 @@ distribution: * all files in the Distutils "build" tree (default :file:`build/`) -* all files in directories named :file:`RCS`, :file:`CVS` or :file:`.svn` +* all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`, + :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs` Now we have our complete list of files, which is written to the manifest for future reference, and then used to build the source distribution archive(s). @@ -156,8 +157,9 @@ source distribution: previous two steps, so it's important that the ``prune`` command in the manifest template comes after the ``recursive-include`` command -#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS` and - :file:`.svn` directories +#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`, + :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs` + directories Just like in the setup script, file and directory names in the manifest template should always be slash-separated; the Distutils will take care of converting From 8ba54417846261a967f8406cad6ac23e013bd0b8 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 15 Mar 2008 00:20:19 +0000 Subject: [PATCH 016/330] Fix lots of broken links in the docs, found by Sphinx' external link checker. --- apiref.rst | 2 +- examples.rst | 2 +- setupscript.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index e3348816e3..f5b49b8910 100644 --- a/apiref.rst +++ b/apiref.rst @@ -73,7 +73,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and +--------------------+--------------------------------+-------------------------------------------------------------+ | *classifiers* | A list of categories for the | The list of available | | | package | categorizations is at | - | | | http://cheeseshop.python.org/pypi?:action=list_classifiers. | + | | | http://pypi.python.org/pypi?:action=list_classifiers. | +--------------------+--------------------------------+-------------------------------------------------------------+ | *distclass* | the :class:`Distribution` | A subclass of | | | class to use | :class:`distutils.core.Distribution` | diff --git a/examples.rst b/examples.rst index 4e4adc56d2..d937b83583 100644 --- a/examples.rst +++ b/examples.rst @@ -11,7 +11,7 @@ Distutils Cookbook. .. seealso:: - `Distutils Cookbook `_ + `Distutils Cookbook `_ Collection of recipes showing how to achieve more control over distutils. diff --git a/setupscript.rst b/setupscript.rst index 0ff347675d..d2be083a66 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -580,7 +580,7 @@ Notes: (4) These fields should not be used if your package is to be compatible with Python versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website - `_. + `_. 'short string' A single line of text, not more than 200 characters. From dc71ea5b678a0662596fd20e371f976ce96421f0 Mon Sep 17 00:00:00 2001 From: Christian Heimes Date: Sun, 16 Mar 2008 00:07:10 +0000 Subject: [PATCH 017/330] Merged revisions 61239-61249,61252-61257,61260-61264,61269-61275,61278-61279,61285-61286,61288-61290,61298,61303-61305,61312-61314,61317,61329,61332,61344,61350-61351,61363-61376,61378-61379,61382-61383,61387-61388,61392,61395-61396,61402-61403 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r61239 | andrew.kuchling | 2008-03-05 01:44:41 +0100 (Wed, 05 Mar 2008) | 1 line Add more items; add fragmentary notes ........ r61240 | amaury.forgeotdarc | 2008-03-05 02:50:33 +0100 (Wed, 05 Mar 2008) | 13 lines Issue#2238: some syntax errors from *args or **kwargs expressions would give bogus error messages, because of untested exceptions:: >>> f(**g(1=2)) XXX undetected error Traceback (most recent call last): File "", line 1, in TypeError: 'int' object is not iterable instead of the expected SyntaxError: keyword can't be an expression Will backport. ........ r61241 | neal.norwitz | 2008-03-05 06:10:48 +0100 (Wed, 05 Mar 2008) | 3 lines Remove the files/dirs after closing the DB so the tests work on Windows. Patch from Trent Nelson. Also simplified removing a file by using test_support. ........ r61242 | neal.norwitz | 2008-03-05 06:14:18 +0100 (Wed, 05 Mar 2008) | 3 lines Get this test to pass even when there is no sound card in the system. Patch from Trent Nelson. (I can't test this.) ........ r61243 | neal.norwitz | 2008-03-05 06:20:44 +0100 (Wed, 05 Mar 2008) | 3 lines Catch OSError when trying to remove a file in case removal fails. This should prevent a failure in tearDown masking any real test failure. ........ r61244 | neal.norwitz | 2008-03-05 06:38:06 +0100 (Wed, 05 Mar 2008) | 5 lines Make the timeout longer to give slow machines a chance to pass the test before timing out. This doesn't change the duration of the test under normal circumstances. This is targetted at fixing the spurious failures on the FreeBSD buildbot primarily. ........ r61245 | neal.norwitz | 2008-03-05 06:49:03 +0100 (Wed, 05 Mar 2008) | 1 line Tabs -> spaces ........ r61246 | neal.norwitz | 2008-03-05 06:50:20 +0100 (Wed, 05 Mar 2008) | 1 line Use -u urlfetch to run more tests ........ r61247 | neal.norwitz | 2008-03-05 06:51:20 +0100 (Wed, 05 Mar 2008) | 1 line test_smtplib sometimes reports leaks too, suppress it ........ r61248 | jeffrey.yasskin | 2008-03-05 07:19:56 +0100 (Wed, 05 Mar 2008) | 5 lines Fix test_socketserver on Windows after r61099 added several signal.alarm() calls (which don't exist on non-Unix platforms). Thanks to Trent Nelson for the report and patch. ........ r61249 | georg.brandl | 2008-03-05 08:10:35 +0100 (Wed, 05 Mar 2008) | 2 lines Fix some rst. ........ r61252 | thomas.heller | 2008-03-05 15:53:39 +0100 (Wed, 05 Mar 2008) | 2 lines News entry for yesterdays commit. ........ r61253 | thomas.heller | 2008-03-05 16:34:29 +0100 (Wed, 05 Mar 2008) | 3 lines Issue 1872: Changed the struct module typecode from 't' to '?', for compatibility with PEP3118. ........ r61254 | skip.montanaro | 2008-03-05 17:41:09 +0100 (Wed, 05 Mar 2008) | 4 lines Elaborate on the role of the altinstall target when installing multiple versions. ........ r61255 | georg.brandl | 2008-03-05 20:31:44 +0100 (Wed, 05 Mar 2008) | 2 lines #2239: PYTHONPATH delimiter is os.pathsep. ........ r61256 | raymond.hettinger | 2008-03-05 21:59:58 +0100 (Wed, 05 Mar 2008) | 1 line C implementation of itertools.permutations(). ........ r61257 | raymond.hettinger | 2008-03-05 22:04:32 +0100 (Wed, 05 Mar 2008) | 1 line Small code cleanup. ........ r61260 | martin.v.loewis | 2008-03-05 23:24:31 +0100 (Wed, 05 Mar 2008) | 2 lines cd PCbuild only after deleting all pyc files. ........ r61261 | raymond.hettinger | 2008-03-06 02:15:52 +0100 (Thu, 06 Mar 2008) | 1 line Add examples. ........ r61262 | andrew.kuchling | 2008-03-06 02:36:27 +0100 (Thu, 06 Mar 2008) | 1 line Add two items ........ r61263 | georg.brandl | 2008-03-06 07:47:18 +0100 (Thu, 06 Mar 2008) | 2 lines #1725737: ignore other VC directories other than CVS and SVN's too. ........ r61264 | martin.v.loewis | 2008-03-06 07:55:22 +0100 (Thu, 06 Mar 2008) | 4 lines Patch #2232: os.tmpfile might fail on Windows if the user has no permission to create files in the root directory. Will backport to 2.5. ........ r61269 | georg.brandl | 2008-03-06 08:19:15 +0100 (Thu, 06 Mar 2008) | 2 lines Expand on re.split behavior with captured expressions. ........ r61270 | georg.brandl | 2008-03-06 08:22:09 +0100 (Thu, 06 Mar 2008) | 2 lines Little clarification of assignments. ........ r61271 | georg.brandl | 2008-03-06 08:31:34 +0100 (Thu, 06 Mar 2008) | 2 lines Add isinstance/issubclass to tutorial. ........ r61272 | georg.brandl | 2008-03-06 08:34:52 +0100 (Thu, 06 Mar 2008) | 2 lines Add missing NEWS entry for r61263. ........ r61273 | georg.brandl | 2008-03-06 08:41:16 +0100 (Thu, 06 Mar 2008) | 2 lines #2225: return nonzero status code from py_compile if not all files could be compiled. ........ r61274 | georg.brandl | 2008-03-06 08:43:02 +0100 (Thu, 06 Mar 2008) | 2 lines #2220: handle matching failure more gracefully. ........ r61275 | georg.brandl | 2008-03-06 08:45:52 +0100 (Thu, 06 Mar 2008) | 2 lines Bug #2220: handle rlcompleter attribute match failure more gracefully. ........ r61278 | martin.v.loewis | 2008-03-06 14:49:47 +0100 (Thu, 06 Mar 2008) | 1 line Rely on x64 platform configuration when building _bsddb on AMD64. ........ r61279 | martin.v.loewis | 2008-03-06 14:50:28 +0100 (Thu, 06 Mar 2008) | 1 line Update db-4.4.20 build procedure. ........ r61285 | raymond.hettinger | 2008-03-06 21:52:01 +0100 (Thu, 06 Mar 2008) | 1 line More tests. ........ r61286 | raymond.hettinger | 2008-03-06 23:51:36 +0100 (Thu, 06 Mar 2008) | 1 line Issue 2246: itertools grouper object did not participate in GC (should be backported). ........ r61288 | raymond.hettinger | 2008-03-07 02:33:20 +0100 (Fri, 07 Mar 2008) | 1 line Tweak recipes and tests ........ r61289 | jeffrey.yasskin | 2008-03-07 07:22:15 +0100 (Fri, 07 Mar 2008) | 5 lines Progress on issue #1193577 by adding a polling .shutdown() method to SocketServers. The core of the patch was written by Pedro Werneck, but any bugs are mine. I've also rearranged the code for timeouts in order to avoid interfering with the shutdown poll. ........ r61290 | nick.coghlan | 2008-03-07 15:13:28 +0100 (Fri, 07 Mar 2008) | 1 line Speed up with statements by storing the __exit__ method on the stack instead of in a temp variable (bumps the magic number for pyc files) ........ r61298 | andrew.kuchling | 2008-03-07 22:09:23 +0100 (Fri, 07 Mar 2008) | 1 line Grammar fix ........ r61303 | georg.brandl | 2008-03-08 10:54:06 +0100 (Sat, 08 Mar 2008) | 2 lines #2253: fix continue vs. finally docs. ........ r61304 | marc-andre.lemburg | 2008-03-08 11:01:43 +0100 (Sat, 08 Mar 2008) | 3 lines Add new name for Mandrake: Mandriva. ........ r61305 | georg.brandl | 2008-03-08 11:05:24 +0100 (Sat, 08 Mar 2008) | 2 lines #1533486: fix types in refcount intro. ........ r61312 | facundo.batista | 2008-03-08 17:50:27 +0100 (Sat, 08 Mar 2008) | 5 lines Issue 1106316. post_mortem()'s parameter, traceback, is now optional: it defaults to the traceback of the exception that is currently being handled. ........ r61313 | jeffrey.yasskin | 2008-03-08 19:26:54 +0100 (Sat, 08 Mar 2008) | 2 lines Add tests for with and finally performance to pybench. ........ r61314 | jeffrey.yasskin | 2008-03-08 21:08:21 +0100 (Sat, 08 Mar 2008) | 2 lines Fix pybench for pythons < 2.6, tested back to 2.3. ........ r61317 | jeffrey.yasskin | 2008-03-08 22:35:15 +0100 (Sat, 08 Mar 2008) | 3 lines Well that was dumb. platform.python_implementation returns a function, not a string. ........ r61329 | georg.brandl | 2008-03-09 16:11:39 +0100 (Sun, 09 Mar 2008) | 2 lines #2249: document assertTrue and assertFalse. ........ r61332 | neal.norwitz | 2008-03-09 20:03:42 +0100 (Sun, 09 Mar 2008) | 4 lines Introduce a lock to fix a race condition which caused an exception in the test. Some buildbots were consistently failing (e.g., amd64). Also remove a couple of semi-colons. ........ r61344 | raymond.hettinger | 2008-03-11 01:19:07 +0100 (Tue, 11 Mar 2008) | 1 line Add recipe to docs. ........ r61350 | guido.van.rossum | 2008-03-11 22:18:06 +0100 (Tue, 11 Mar 2008) | 3 lines Fix the overflows in expandtabs(). "This time for sure!" (Exploit at request.) ........ r61351 | raymond.hettinger | 2008-03-11 22:37:46 +0100 (Tue, 11 Mar 2008) | 1 line Improve docs for itemgetter(). Show that it works with slices. ........ r61363 | georg.brandl | 2008-03-13 08:15:56 +0100 (Thu, 13 Mar 2008) | 2 lines #2265: fix example. ........ r61364 | georg.brandl | 2008-03-13 08:17:14 +0100 (Thu, 13 Mar 2008) | 2 lines #2270: fix typo. ........ r61365 | georg.brandl | 2008-03-13 08:21:41 +0100 (Thu, 13 Mar 2008) | 2 lines #1720705: add docs about import/threading interaction, wording by Nick. ........ r61366 | andrew.kuchling | 2008-03-13 12:07:35 +0100 (Thu, 13 Mar 2008) | 1 line Add class decorators ........ r61367 | raymond.hettinger | 2008-03-13 17:43:17 +0100 (Thu, 13 Mar 2008) | 1 line Add 2-to-3 support for the itertools moved to builtins or renamed. ........ r61368 | raymond.hettinger | 2008-03-13 17:43:59 +0100 (Thu, 13 Mar 2008) | 1 line Consistent tense. ........ r61369 | raymond.hettinger | 2008-03-13 20:03:51 +0100 (Thu, 13 Mar 2008) | 1 line Issue 2274: Add heapq.heappushpop(). ........ r61370 | raymond.hettinger | 2008-03-13 20:33:34 +0100 (Thu, 13 Mar 2008) | 1 line Simplify the nlargest() code using heappushpop(). ........ r61371 | brett.cannon | 2008-03-13 21:27:00 +0100 (Thu, 13 Mar 2008) | 4 lines Move test_thread over to unittest. Commits GHOP 237. Thanks Benjamin Peterson for the patch. ........ r61372 | brett.cannon | 2008-03-13 21:33:10 +0100 (Thu, 13 Mar 2008) | 4 lines Move test_tokenize to doctest. Done as GHOP 238 by Josip Dzolonga. ........ r61373 | brett.cannon | 2008-03-13 21:47:41 +0100 (Thu, 13 Mar 2008) | 4 lines Convert test_contains, test_crypt, and test_select to unittest. Patch from GHOP 294 by David Marek. ........ r61374 | brett.cannon | 2008-03-13 22:02:16 +0100 (Thu, 13 Mar 2008) | 4 lines Move test_gdbm to use unittest. Closes issue #1960. Thanks Giampaolo Rodola. ........ r61375 | brett.cannon | 2008-03-13 22:09:28 +0100 (Thu, 13 Mar 2008) | 4 lines Convert test_fcntl to unittest. Closes issue #2055. Thanks Giampaolo Rodola. ........ r61376 | raymond.hettinger | 2008-03-14 06:03:44 +0100 (Fri, 14 Mar 2008) | 1 line Leave heapreplace() unchanged. ........ r61378 | martin.v.loewis | 2008-03-14 14:56:09 +0100 (Fri, 14 Mar 2008) | 2 lines Patch #2284: add -x64 option to rt.bat. ........ r61379 | martin.v.loewis | 2008-03-14 14:57:59 +0100 (Fri, 14 Mar 2008) | 2 lines Use -x64 flag. ........ r61382 | brett.cannon | 2008-03-14 15:03:10 +0100 (Fri, 14 Mar 2008) | 2 lines Remove a bad test. ........ r61383 | mark.dickinson | 2008-03-14 15:23:37 +0100 (Fri, 14 Mar 2008) | 9 lines Issue 705836: Fix struct.pack(">f", 1e40) to behave consistently across platforms: it should now raise OverflowError on all platforms. (Previously it raised OverflowError only on non IEEE 754 platforms.) Also fix the (already existing) test for this behaviour so that it actually raises TestFailed instead of just referencing it. ........ r61387 | thomas.heller | 2008-03-14 22:06:21 +0100 (Fri, 14 Mar 2008) | 1 line Remove unneeded initializer. ........ r61388 | martin.v.loewis | 2008-03-14 22:19:28 +0100 (Fri, 14 Mar 2008) | 2 lines Run debug version, cd to PCbuild. ........ r61392 | georg.brandl | 2008-03-15 00:10:34 +0100 (Sat, 15 Mar 2008) | 2 lines Remove obsolete paragraph. #2288. ........ r61395 | georg.brandl | 2008-03-15 01:20:19 +0100 (Sat, 15 Mar 2008) | 2 lines Fix lots of broken links in the docs, found by Sphinx' external link checker. ........ r61396 | skip.montanaro | 2008-03-15 03:32:49 +0100 (Sat, 15 Mar 2008) | 1 line note that fork and forkpty raise OSError on failure ........ r61402 | skip.montanaro | 2008-03-15 17:04:45 +0100 (Sat, 15 Mar 2008) | 1 line add %f format to datetime - issue 1158 ........ r61403 | skip.montanaro | 2008-03-15 17:07:11 +0100 (Sat, 15 Mar 2008) | 2 lines . ........ --- apiref.rst | 2 +- examples.rst | 2 +- setupscript.rst | 2 +- sourcedist.rst | 8 +++++--- 4 files changed, 8 insertions(+), 6 deletions(-) diff --git a/apiref.rst b/apiref.rst index 6c2be3e9f0..36684e2255 100644 --- a/apiref.rst +++ b/apiref.rst @@ -73,7 +73,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and +--------------------+--------------------------------+-------------------------------------------------------------+ | *classifiers* | A list of categories for the | The list of available | | | package | categorizations is at | - | | | http://cheeseshop.python.org/pypi?:action=list_classifiers. | + | | | http://pypi.python.org/pypi?:action=list_classifiers. | +--------------------+--------------------------------+-------------------------------------------------------------+ | *distclass* | the :class:`Distribution` | A subclass of | | | class to use | :class:`distutils.core.Distribution` | diff --git a/examples.rst b/examples.rst index 4e4adc56d2..d937b83583 100644 --- a/examples.rst +++ b/examples.rst @@ -11,7 +11,7 @@ Distutils Cookbook. .. seealso:: - `Distutils Cookbook `_ + `Distutils Cookbook `_ Collection of recipes showing how to achieve more control over distutils. diff --git a/setupscript.rst b/setupscript.rst index 7c65821d74..3cc1da92e9 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -578,7 +578,7 @@ Notes: (4) These fields should not be used if your package is to be compatible with Python versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website - `_. + `_. 'short string' A single line of text, not more than 200 characters. diff --git a/sourcedist.rst b/sourcedist.rst index 9f15870ccd..960cc0ae4d 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -122,7 +122,8 @@ distribution: * all files in the Distutils "build" tree (default :file:`build/`) -* all files in directories named :file:`RCS`, :file:`CVS` or :file:`.svn` +* all files in directories named :file:`RCS`, :file:`CVS`, :file:`.svn`, + :file:`.hg`, :file:`.git`, :file:`.bzr` or :file:`_darcs` Now we have our complete list of files, which is written to the manifest for future reference, and then used to build the source distribution archive(s). @@ -156,8 +157,9 @@ source distribution: previous two steps, so it's important that the ``prune`` command in the manifest template comes after the ``recursive-include`` command -#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS` and - :file:`.svn` directories +#. exclude the entire :file:`build` tree, and any :file:`RCS`, :file:`CVS`, + :file:`.svn`, :file:`.hg`, :file:`.git`, :file:`.bzr` and :file:`_darcs` + directories Just like in the setup script, file and directory names in the manifest template should always be slash-separated; the Distutils will take care of converting From afdc93911ec0168c3ae1b1777e5b9280fcce2dbf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20v=2E=20L=C3=B6wis?= Date: Sat, 22 Mar 2008 00:35:10 +0000 Subject: [PATCH 018/330] Add build_py_2to3. --- apiref.rst | 20 +++++++++++++++++++- 1 file changed, 19 insertions(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 36684e2255..6616f83661 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1820,7 +1820,25 @@ This module supplies the abstract base class :class:`Command`. :synopsis: Build the .py/.pyc files of a package -.. % todo +.. class:: build_py(Command) + +.. class:: build_py_2to3(build_py) + + Alternative implementation of build_py which also runs the + 2to3 conversion library on each .py file that is going to be + installed. To use this in a setup.py file for a distribution + that is designed to run with both Python 2.x and 3.x, add:: + + try: + from distutils.command.build_py import build_py_2to3 as build_py + except ImportError: + from distutils.command.build_py import build_py + + to your setup.py, and later:: + + cmdclass = {'build_py':build_py} + + to the invocation of setup(). :mod:`distutils.command.build_scripts` --- Build the scripts of a package From 5a899df791ed0cf231606ebf81909d6bb35b8e5c Mon Sep 17 00:00:00 2001 From: Mark Hammond Date: Mon, 7 Apr 2008 01:53:39 +0000 Subject: [PATCH 019/330] Issue #2513: enable 64bit cross compilation on windows. --- builtdist.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/builtdist.rst b/builtdist.rst index 2ebc9860f1..f009bbb928 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -329,6 +329,42 @@ version number. This can be changed to another text by using the The installer file will be written to the "distribution directory" --- normally :file:`dist/`, but customizable with the :option:`--dist-dir` option. +.. _cross-compile-windows: + +Cross-compiling on Windows +===================== + +Starting with Python 2.6, distutils is capable of cross-compiling between +Windows platforms. In practice, this means that with the correct tools +installed, you can use a 32bit version of Windows to create 64bit extensions +and vice-versa. + +To build for an alternate platform, specify the :option:`--plat-name` option +to the build command. Valid values are currently 'win32', 'win-amd64' and +'win-ia64'. For example, on a 32bit version of Windows, you could execute:: + + python setup.py build --plat-name=win-amd64 + +to build a 64bit version of your extension. The Windows Installers also +support this option, so the command:: + + python setup.py build --plat-name=win-amd64 bdist_wininst + +would create a 64bit installation executable on your 32bit version of Windows. + +To cross-compile, you must download the Python source code and cross-compile +Python itself for the platform you are targetting - it is not possible from a +binary installtion of Python (as the .lib etc file for other platforms are +not included.) In practice, this means the user of a 32 bit operating +system will need to use Visual Studio 2008 to open the +:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the +"x64" configuration of the 'pythoncore' project before cross-compiling +extensions is possible. + +Note that by default, Visual Studio 2008 does not install 64bit compilers or +tools. You may need to reexecute the Visual Studio setup process and select +these tools (using Control Panel->[Add/Remove] Programs is a convenient way to +check or modify your existing install.) .. _postinstallation-script: From 965efecf0a6dff120005799f4e3f4a4ce3b860cd Mon Sep 17 00:00:00 2001 From: Mark Hammond Date: Mon, 7 Apr 2008 01:59:40 +0000 Subject: [PATCH 020/330] correct heading underline for new "Cross-compiling on Windows" section --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index f009bbb928..cd2bd817b4 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -332,7 +332,7 @@ The installer file will be written to the "distribution directory" --- normally .. _cross-compile-windows: Cross-compiling on Windows -===================== +========================== Starting with Python 2.6, distutils is capable of cross-compiling between Windows platforms. In practice, this means that with the correct tools From 29277620a1d1528464e9459cf8f36578f940ab6d Mon Sep 17 00:00:00 2001 From: Christian Heimes Date: Wed, 9 Apr 2008 08:37:03 +0000 Subject: [PATCH 021/330] Merged revisions 62194,62197-62198,62204-62205,62214,62219-62221,62227,62229-62231,62233-62235,62237-62239 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62194 | jeffrey.yasskin | 2008-04-07 01:04:28 +0200 (Mon, 07 Apr 2008) | 7 lines Add enough debugging information to diagnose failures where the HandlerBException is ignored, and fix one such problem, where it was thrown during the __del__ method of the previous Popen object. We may want to find a better way of printing verbose information so it's not spammy when the test passes. ........ r62197 | mark.hammond | 2008-04-07 03:53:39 +0200 (Mon, 07 Apr 2008) | 2 lines Issue #2513: enable 64bit cross compilation on windows. ........ r62198 | mark.hammond | 2008-04-07 03:59:40 +0200 (Mon, 07 Apr 2008) | 2 lines correct heading underline for new "Cross-compiling on Windows" section ........ r62204 | gregory.p.smith | 2008-04-07 08:33:21 +0200 (Mon, 07 Apr 2008) | 4 lines Use the new PyFile_IncUseCount & PyFile_DecUseCount calls appropriatly within the standard library. These modules use PyFile_AsFile and later release the GIL while operating on the previously returned FILE*. ........ r62205 | mark.summerfield | 2008-04-07 09:39:23 +0200 (Mon, 07 Apr 2008) | 4 lines changed "2500 components" to "several thousand" since the number keeps growning:-) ........ r62214 | georg.brandl | 2008-04-07 20:51:59 +0200 (Mon, 07 Apr 2008) | 2 lines #2525: update timezone info examples in the docs. ........ r62219 | andrew.kuchling | 2008-04-08 01:57:07 +0200 (Tue, 08 Apr 2008) | 1 line Write PEP 3127 section; add items ........ r62220 | andrew.kuchling | 2008-04-08 01:57:21 +0200 (Tue, 08 Apr 2008) | 1 line Typo fix ........ r62221 | andrew.kuchling | 2008-04-08 03:33:10 +0200 (Tue, 08 Apr 2008) | 1 line Typographical fix: 32bit -> 32-bit, 64bit -> 64-bit ........ r62227 | andrew.kuchling | 2008-04-08 23:22:53 +0200 (Tue, 08 Apr 2008) | 1 line Add items ........ r62229 | amaury.forgeotdarc | 2008-04-08 23:27:42 +0200 (Tue, 08 Apr 2008) | 7 lines Issue2564: Prevent a hang in "import test.autotest", which runs the entire test suite as a side-effect of importing the module. - in test_capi, a thread tried to import other modules - re.compile() imported sre_parse again on every call. ........ r62230 | amaury.forgeotdarc | 2008-04-08 23:51:57 +0200 (Tue, 08 Apr 2008) | 2 lines Prevent an error when inspect.isabstract() is called with something else than a new-style class. ........ r62231 | amaury.forgeotdarc | 2008-04-09 00:07:05 +0200 (Wed, 09 Apr 2008) | 8 lines Issue 2408: remove the _types module It was only used as a helper in types.py to access types (GetSetDescriptorType and MemberDescriptorType), when they can easily be obtained with python code. These expressions even work with Jython. I don't know what the future of the types module is; (cf. discussion in http://bugs.python.org/issue1605 ) at least this change makes it simpler. ........ r62233 | amaury.forgeotdarc | 2008-04-09 01:10:07 +0200 (Wed, 09 Apr 2008) | 2 lines Add a NEWS entry for previous checkin ........ r62234 | trent.nelson | 2008-04-09 01:47:30 +0200 (Wed, 09 Apr 2008) | 37 lines - Issue #2550: The approach used by client/server code for obtaining ports to listen on in network-oriented tests has been refined in an effort to facilitate running multiple instances of the entire regression test suite in parallel without issue. test_support.bind_port() has been fixed such that it will always return a unique port -- which wasn't always the case with the previous implementation, especially if socket options had been set that affected address reuse (i.e. SO_REUSEADDR, SO_REUSEPORT). The new implementation of bind_port() will actually raise an exception if it is passed an AF_INET/SOCK_STREAM socket with either the SO_REUSEADDR or SO_REUSEPORT socket option set. Furthermore, if available, bind_port() will set the SO_EXCLUSIVEADDRUSE option on the socket it's been passed. This currently only applies to Windows. This option prevents any other sockets from binding to the host/port we've bound to, thus removing the possibility of the 'non-deterministic' behaviour, as Microsoft puts it, that occurs when a second SOCK_STREAM socket binds and accepts to a host/port that's already been bound by another socket. The optional preferred port parameter to bind_port() has been removed. Under no circumstances should tests be hard coding ports! test_support.find_unused_port() has also been introduced, which will pass a temporary socket object to bind_port() in order to obtain an unused port. The temporary socket object is then closed and deleted, and the port is returned. This method should only be used for obtaining an unused port in order to pass to an external program (i.e. the -accept [port] argument to openssl's s_server mode) or as a parameter to a server-oriented class that doesn't give you direct access to the underlying socket used. Finally, test_support.HOST has been introduced, which should be used for the host argument of any relevant socket calls (i.e. bind and connect). The following tests were updated to following the new conventions: test_socket, test_smtplib, test_asyncore, test_ssl, test_httplib, test_poplib, test_ftplib, test_telnetlib, test_socketserver, test_asynchat and test_socket_ssl. It is now possible for multiple instances of the regression test suite to run in parallel without issue. ........ r62235 | gregory.p.smith | 2008-04-09 02:25:17 +0200 (Wed, 09 Apr 2008) | 3 lines Fix zlib crash from zlib.decompressobj().flush(val) when val was not positive. It tried to allocate negative or zero memory. That fails. ........ r62237 | trent.nelson | 2008-04-09 02:34:53 +0200 (Wed, 09 Apr 2008) | 1 line Fix typo with regards to self.PORT shadowing class variables with the same name. ........ r62238 | andrew.kuchling | 2008-04-09 03:08:32 +0200 (Wed, 09 Apr 2008) | 1 line Add items ........ r62239 | jerry.seutter | 2008-04-09 07:07:58 +0200 (Wed, 09 Apr 2008) | 1 line Changed test so it no longer runs as a side effect of importing. ........ --- builtdist.rst | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/builtdist.rst b/builtdist.rst index 2ebc9860f1..cd2bd817b4 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -329,6 +329,42 @@ version number. This can be changed to another text by using the The installer file will be written to the "distribution directory" --- normally :file:`dist/`, but customizable with the :option:`--dist-dir` option. +.. _cross-compile-windows: + +Cross-compiling on Windows +========================== + +Starting with Python 2.6, distutils is capable of cross-compiling between +Windows platforms. In practice, this means that with the correct tools +installed, you can use a 32bit version of Windows to create 64bit extensions +and vice-versa. + +To build for an alternate platform, specify the :option:`--plat-name` option +to the build command. Valid values are currently 'win32', 'win-amd64' and +'win-ia64'. For example, on a 32bit version of Windows, you could execute:: + + python setup.py build --plat-name=win-amd64 + +to build a 64bit version of your extension. The Windows Installers also +support this option, so the command:: + + python setup.py build --plat-name=win-amd64 bdist_wininst + +would create a 64bit installation executable on your 32bit version of Windows. + +To cross-compile, you must download the Python source code and cross-compile +Python itself for the platform you are targetting - it is not possible from a +binary installtion of Python (as the .lib etc file for other platforms are +not included.) In practice, this means the user of a 32 bit operating +system will need to use Visual Studio 2008 to open the +:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the +"x64" configuration of the 'pythoncore' project before cross-compiling +extensions is possible. + +Note that by default, Visual Studio 2008 does not install 64bit compilers or +tools. You may need to reexecute the Visual Studio setup process and select +these tools (using Control Panel->[Add/Remove] Programs is a convenient way to +check or modify your existing install.) .. _postinstallation-script: From c265f6b8a075e070c8c91c1f25ffc4e1eee4b35d Mon Sep 17 00:00:00 2001 From: Mark Hammond Date: Fri, 2 May 2008 12:48:15 +0000 Subject: [PATCH 022/330] #2581: Vista UAC/elevation support for bdist_wininst --- builtdist.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index cd2bd817b4..c4b8dbf3f4 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -426,6 +426,13 @@ built-in functions in the installation script. also the configuration. For details refer to Microsoft's documentation of the :cfunc:`SHGetSpecialFolderPath` function. +Vista User Access Control (UAC) +=============================== + +Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` +option. The default is 'none' (meaning no UAC handling is done), and other +valid values are 'auto' (meaning prompt for UAC elevation if Python was +installed for all users) and 'force' (meaning always prompt for elevation) .. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) @@ -437,5 +444,3 @@ built-in functions in the installation script. and *iconindex* is the index of the icon in the file *iconpath*. Again, for details consult the Microsoft documentation for the :class:`IShellLink` interface. - - From e444bee055d583b6947ad456eefb5bce498c4f9d Mon Sep 17 00:00:00 2001 From: Christian Heimes Date: Sun, 4 May 2008 22:42:01 +0000 Subject: [PATCH 023/330] Merged revisions 62425-62429,62434-62436,62441,62444,62446-62448,62450-62455,62463,62465-62466,62469,62474,62476-62478,62480,62485,62492,62497-62498,62500,62507,62513-62514,62516,62521,62531,62535,62545-62546,62548-62551,62553-62559,62569,62574,62577,62593,62595,62604-62606,62608,62616,62626-62627,62636,62638,62644-62645,62647-62648,62651-62653,62656,62661,62663,62680,62686-62687,62696,62699-62703,62711 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ................ r62425 | andrew.kuchling | 2008-04-21 03:45:57 +0200 (Mon, 21 Apr 2008) | 1 line Comment typo ................ r62426 | mark.dickinson | 2008-04-21 03:55:50 +0200 (Mon, 21 Apr 2008) | 2 lines Silence 'r may be used uninitialized' compiler warning. ................ r62427 | andrew.kuchling | 2008-04-21 04:08:00 +0200 (Mon, 21 Apr 2008) | 1 line Markup fix ................ r62428 | andrew.kuchling | 2008-04-21 04:08:13 +0200 (Mon, 21 Apr 2008) | 1 line Wording changes ................ r62429 | andrew.kuchling | 2008-04-21 04:14:24 +0200 (Mon, 21 Apr 2008) | 1 line Add various items ................ r62434 | thomas.heller | 2008-04-21 15:46:55 +0200 (Mon, 21 Apr 2008) | 1 line Fix typo. ................ r62435 | david.goodger | 2008-04-21 16:40:22 +0200 (Mon, 21 Apr 2008) | 1 line corrections ("reStructuredText" is one word) ................ r62436 | david.goodger | 2008-04-21 16:43:33 +0200 (Mon, 21 Apr 2008) | 1 line capitalization ................ r62441 | gregory.p.smith | 2008-04-21 19:46:40 +0200 (Mon, 21 Apr 2008) | 2 lines explicitly flush after the ... since there wasn't a newline ................ r62444 | jeroen.ruigrok | 2008-04-21 22:15:39 +0200 (Mon, 21 Apr 2008) | 2 lines Windows x64 also falls under VER_PLATFORM_WIN32_NT. ................ r62446 | gregory.p.smith | 2008-04-21 23:31:08 +0200 (Mon, 21 Apr 2008) | 3 lines If sys.stdin is not a tty, fall back to default_getpass after printing a warning instead of failing with a termios.error. ................ r62447 | mark.dickinson | 2008-04-22 00:32:24 +0200 (Tue, 22 Apr 2008) | 8 lines test_math and test_cmath are failing on the FreeBSD 6.2 trunk buildbot, apparently because tanh(-0.) loses the sign of zero on that platform. If true, this is a bug in FreeBSD. Added a configure test to verify this. I still need to figure out how best to deal with this failure. ................ r62448 | amaury.forgeotdarc | 2008-04-22 00:35:30 +0200 (Tue, 22 Apr 2008) | 7 lines Issue 2665: On Windows, sys.stderr does not contain a valid file when running without a console. It seems to work, but will fail at the first flush. This causes IDLE to crash when too many warnings are printed. Will backport. ................ r62450 | benjamin.peterson | 2008-04-22 00:57:00 +0200 (Tue, 22 Apr 2008) | 2 lines Fix Sphinx warnings ................ r62451 | mark.dickinson | 2008-04-22 02:54:27 +0200 (Tue, 22 Apr 2008) | 3 lines Make configure test for tanh(-0.) == -0. committed in r62447 actually work. (The test wasn't properly linked with libm. Sigh.) ................ r62452 | benjamin.peterson | 2008-04-22 04:16:03 +0200 (Tue, 22 Apr 2008) | 2 lines Various io doc updates ................ r62453 | neal.norwitz | 2008-04-22 07:07:47 +0200 (Tue, 22 Apr 2008) | 1 line Add Thomas Lee ................ r62454 | gregory.p.smith | 2008-04-22 10:08:41 +0200 (Tue, 22 Apr 2008) | 8 lines Major improvements: * Default to using /dev/tty for the password prompt and input before falling back to sys.stdin and sys.stderr. * Use sys.stderr instead of sys.stdout. * print the 'password may be echoed' warning to stream used to display the prompt rather than always sys.stderr. * warn() with GetPassWarning when input may be echoed. ................ r62455 | gregory.p.smith | 2008-04-22 10:11:33 +0200 (Tue, 22 Apr 2008) | 2 lines update the getpass entry ................ r62463 | amaury.forgeotdarc | 2008-04-22 23:14:41 +0200 (Tue, 22 Apr 2008) | 5 lines Issue #2670: urllib2.build_opener() failed when two handlers derive the same default base class. Will backport. ................ r62465 | skip.montanaro | 2008-04-23 00:45:09 +0200 (Wed, 23 Apr 2008) | 3 lines Factor in documentation changes from issue 1753732. ................ r62466 | gregory.p.smith | 2008-04-23 03:06:42 +0200 (Wed, 23 Apr 2008) | 2 lines syntax fixup ................ r62469 | benjamin.peterson | 2008-04-23 22:38:06 +0200 (Wed, 23 Apr 2008) | 2 lines #2673 Fix example typo in optparse docs ................ r62474 | martin.v.loewis | 2008-04-24 11:50:50 +0200 (Thu, 24 Apr 2008) | 2 lines Add Guilherme Polo. ................ r62476 | martin.v.loewis | 2008-04-24 15:16:36 +0200 (Thu, 24 Apr 2008) | 3 lines Remove Py_Refcnt, Py_Type, Py_Size, as they were added only for backwards compatibility, yet 2.5 did not have them at all. ................ r62477 | martin.v.loewis | 2008-04-24 15:17:24 +0200 (Thu, 24 Apr 2008) | 2 lines Fix typo. ................ r62478 | martin.v.loewis | 2008-04-24 15:18:03 +0200 (Thu, 24 Apr 2008) | 2 lines Add Jesus Cea. ................ r62480 | amaury.forgeotdarc | 2008-04-24 20:07:05 +0200 (Thu, 24 Apr 2008) | 4 lines Issue2681: the literal 0o8 was wrongly accepted, and evaluated as float(0.0). This happened only when 8 is the first digit. Credits go to Lukas Meuser. ................ r62485 | amaury.forgeotdarc | 2008-04-24 22:10:26 +0200 (Thu, 24 Apr 2008) | 5 lines Disable gc when running test_trace, or we may record the __del__ of collected objects. See http://mail.python.org/pipermail/python-checkins/2008-April/068633.html the extra events perfectly match several calls to socket._fileobject.__del__() ................ r62492 | neal.norwitz | 2008-04-25 05:40:17 +0200 (Fri, 25 Apr 2008) | 1 line Fix typo (now -> no) ................ r62497 | armin.rigo | 2008-04-25 11:35:18 +0200 (Fri, 25 Apr 2008) | 2 lines A new crasher. ................ r62498 | thomas.heller | 2008-04-25 17:44:16 +0200 (Fri, 25 Apr 2008) | 1 line Add from_buffer and from_buffer_copy class methods to ctypes types. ................ r62500 | mark.dickinson | 2008-04-25 18:59:09 +0200 (Fri, 25 Apr 2008) | 3 lines Issue 2635: fix bug in the fix_sentence_endings option to textwrap.fill. ................ r62507 | benjamin.peterson | 2008-04-25 23:43:56 +0200 (Fri, 25 Apr 2008) | 2 lines Allow test_import to work when it is invoked directly ................ r62513 | georg.brandl | 2008-04-26 20:31:07 +0200 (Sat, 26 Apr 2008) | 2 lines #2691: document PyLong (s)size_t APIs, patch by Alexander Belopolsky. ................ r62514 | georg.brandl | 2008-04-26 20:32:17 +0200 (Sat, 26 Apr 2008) | 2 lines Add missing return type to dealloc. ................ r62516 | alexandre.vassalotti | 2008-04-27 02:52:24 +0200 (Sun, 27 Apr 2008) | 2 lines Fixed URL of PEP 205 in weakref's module docstring. ................ r62521 | georg.brandl | 2008-04-27 11:39:59 +0200 (Sun, 27 Apr 2008) | 2 lines #2677: add note that not all functions may accept keyword args. ................ r62531 | georg.brandl | 2008-04-27 19:38:55 +0200 (Sun, 27 Apr 2008) | 2 lines Use correct XHTML tags. ................ r62535 | benjamin.peterson | 2008-04-27 20:14:39 +0200 (Sun, 27 Apr 2008) | 2 lines #2700 Document PyNumber_ToBase ................ r62545 | skip.montanaro | 2008-04-27 22:53:57 +0200 (Sun, 27 Apr 2008) | 1 line minor wording changes, rewrap a few lines ................ r62546 | kurt.kaiser | 2008-04-27 23:07:41 +0200 (Sun, 27 Apr 2008) | 7 lines Home / Control-A toggles between left margin and end of leading white space. Patch 1196903 Jeff Shute. M idlelib/PyShell.py M idlelib/EditorWindow.py M idlelib/NEWS.txt ................ r62548 | kurt.kaiser | 2008-04-27 23:38:05 +0200 (Sun, 27 Apr 2008) | 2 lines Improved AutoCompleteWindow logic. Patch 2062 Tal Einat. ................ r62549 | kurt.kaiser | 2008-04-27 23:52:19 +0200 (Sun, 27 Apr 2008) | 4 lines Autocompletion of filenames now support alternate separators, e.g. the '/' char on Windows. Patch 2061 Tal Einat. ................ r62550 | skip.montanaro | 2008-04-28 00:49:56 +0200 (Mon, 28 Apr 2008) | 6 lines A few small changes: * The only exception we should catch when trying to import cStringIO is an ImportError. * Delete the function signatures embedded in the mk*temp docstrings. * The tempdir global variable was initialized twice. ................ r62551 | skip.montanaro | 2008-04-28 00:52:02 +0200 (Mon, 28 Apr 2008) | 4 lines Wrap some long paragraphs and include the default values for optional function parameters. ................ r62553 | skip.montanaro | 2008-04-28 04:57:23 +0200 (Mon, 28 Apr 2008) | 7 lines Minor cleanups: * Avoid creating unused local variables where we can. Where we can't prefix the unused variables with '_'. * Avoid shadowing builtins where it won't change the external interface of a function. * Use None as default path arg to readmodule and readmodule_ex. ................ r62554 | skip.montanaro | 2008-04-28 04:59:45 +0200 (Mon, 28 Apr 2008) | 6 lines Correct documentation to match implementation: "Class" instead of "class_descriptor", "Function" instead of "function_descriptor". Note default path value for readmodule*. Wrap some long paragraphs. Don't mention 'inpackage' which isn't part of the public API. ................ r62555 | brett.cannon | 2008-04-28 05:23:50 +0200 (Mon, 28 Apr 2008) | 5 lines Fix a bug introduced by the warnings rewrite where tracebacks were being improperly indented. Closes issue #2699. ................ r62556 | skip.montanaro | 2008-04-28 05:25:37 +0200 (Mon, 28 Apr 2008) | 2 lines Wrap some long lines. ................ r62557 | skip.montanaro | 2008-04-28 05:27:53 +0200 (Mon, 28 Apr 2008) | 6 lines Get rid of _test(), _main(), _debug() and _check(). Tests are no longer needed (better set available in Lib/test/test_robotparser.py). Clean up a few PEP 8 nits (compound statements on a single line, whitespace around operators). ................ r62558 | brett.cannon | 2008-04-28 06:50:06 +0200 (Mon, 28 Apr 2008) | 3 lines Rename the test_traceback_print() function to traceback_print() to prevent test_capi from automatically calling the function. ................ r62559 | georg.brandl | 2008-04-28 07:16:30 +0200 (Mon, 28 Apr 2008) | 2 lines Fix markup. ................ r62569 | amaury.forgeotdarc | 2008-04-28 23:07:06 +0200 (Mon, 28 Apr 2008) | 5 lines test_sundry performs minimal tests (a simple import...) on modules that are not tested otherwise. Some of them now have tests and can be removed. Only 70 to go... ................ r62574 | andrew.kuchling | 2008-04-29 04:03:54 +0200 (Tue, 29 Apr 2008) | 1 line Strip down SSL docs; I'm not managing to get test programs working, so I'll just give a minimal description ................ r62577 | martin.v.loewis | 2008-04-29 08:10:53 +0200 (Tue, 29 Apr 2008) | 2 lines Add Rodrigo and Heiko. ................ r62593 | nick.coghlan | 2008-04-30 16:23:36 +0200 (Wed, 30 Apr 2008) | 1 line Update command line usage documentation to reflect 2.6 changes (also includes some minor cleanups). Addresses TODO list issue 2258 ................ r62595 | andrew.kuchling | 2008-04-30 18:19:55 +0200 (Wed, 30 Apr 2008) | 1 line Typo fix ................ r62604 | benjamin.peterson | 2008-04-30 23:03:58 +0200 (Wed, 30 Apr 2008) | 2 lines make test_support's captured_output a bit more robust when exceptions happen ................ r62605 | georg.brandl | 2008-04-30 23:08:42 +0200 (Wed, 30 Apr 2008) | 2 lines #1748: use functools.wraps instead of rolling own metadata update. ................ r62606 | benjamin.peterson | 2008-04-30 23:25:55 +0200 (Wed, 30 Apr 2008) | 2 lines Remove some from __future__ import with_statements ................ r62608 | benjamin.peterson | 2008-05-01 00:03:36 +0200 (Thu, 01 May 2008) | 2 lines Fix typo in whatsnew ................ r62616 | georg.brandl | 2008-05-01 20:24:32 +0200 (Thu, 01 May 2008) | 2 lines Fix synopsis. ................ r62626 | brett.cannon | 2008-05-02 04:25:09 +0200 (Fri, 02 May 2008) | 6 lines Fix a backwards-compatibility mistake where a new optional argument for warnings.showwarning() was being used. This broke pre-existing replacements for the function since they didn't support the extra argument. Closes issue 2705. ................ r62627 | gregory.p.smith | 2008-05-02 09:26:52 +0200 (Fri, 02 May 2008) | 20 lines This should fix issue2632. A long description of the two competing problems is in the bug report (one old, one recently introduced trying to fix the old one). In short: buffer data during socket._fileobject.read() and readlines() within a cStringIO object instead of a [] of str()s returned from the recv() call. This prevents excessive memory use due to the size parameter being passed to recv() being grossly larger than the actual size of the data returned *and* prevents excessive cpu usage due to looping in python calling recv() with a very tiny size value if min() is used as the previous memory-use bug "fix" did. It also documents what the socket._fileobject._rbufsize member is actually used for. This is a candidate for back porting to 2.5. ................ r62636 | mark.hammond | 2008-05-02 14:48:15 +0200 (Fri, 02 May 2008) | 2 lines #2581: Vista UAC/elevation support for bdist_wininst ................ r62638 | facundo.batista | 2008-05-02 19:39:00 +0200 (Fri, 02 May 2008) | 3 lines Fixed some test structures. Thanks Mark Dickinson. ................ r62644 | ronald.oussoren | 2008-05-02 21:45:11 +0200 (Fri, 02 May 2008) | 7 lines Fix for issue #2573: Can't change the framework name on OS X builds This introduces a new configure option: --with-framework-name=NAME (defaulting to 'Python'). This allows you to install several copies of the Python framework with different names (such as a normal build and a debug build). ................ r62645 | ronald.oussoren | 2008-05-02 21:58:56 +0200 (Fri, 02 May 2008) | 2 lines Finish fix for issue2573, previous patch was incomplete. ................ r62647 | martin.v.loewis | 2008-05-02 23:30:20 +0200 (Fri, 02 May 2008) | 13 lines Merged revisions 62263-62646 via svnmerge from svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3 ........ r62470 | david.wolever | 2008-04-24 02:11:07 +0200 (Do, 24 Apr 2008) | 3 lines Fixed up and applied the patch for #2431 -- speeding up 2to3 with a lookup table. ........ r62646 | martin.v.loewis | 2008-05-02 23:29:27 +0200 (Fr, 02 Mai 2008) | 2 lines Fix whitespace. ........ ................ r62648 | ronald.oussoren | 2008-05-02 23:42:35 +0200 (Fri, 02 May 2008) | 4 lines Fix for #1905: PythonLauncher not working correctly on OSX 10.5/Leopard This fixes both Python Launchar and the terminalcommand module. ................ r62651 | ronald.oussoren | 2008-05-02 23:54:56 +0200 (Fri, 02 May 2008) | 2 lines Fix for issue #2520 (cannot import macerrors) ................ r62652 | benjamin.peterson | 2008-05-03 00:12:58 +0200 (Sat, 03 May 2008) | 2 lines capitalization nit for reStructuredText ................ r62653 | brett.cannon | 2008-05-03 03:02:41 +0200 (Sat, 03 May 2008) | 2 lines Fix some indentation errors. ................ r62656 | brett.cannon | 2008-05-03 05:19:39 +0200 (Sat, 03 May 2008) | 6 lines Fix the C implementation of 'warnings' to infer the filename of the module that raised an exception properly when __file__ is not set, __name__ == '__main__', and sys.argv[0] is a false value. Closes issue2743. ................ r62661 | amaury.forgeotdarc | 2008-05-03 14:21:13 +0200 (Sat, 03 May 2008) | 8 lines In test_io, StatefulIncrementalDecoderTest was not part of the test suite. And of course, the test failed: a bytearray was used without reason in io.TextIOWrapper.tell(). The difference is that iterating over bytes (i.e. str in python2.6) returns 1-char bytes, whereas bytearrays yield integers. This code should still work with python3.0 ................ r62663 | benjamin.peterson | 2008-05-03 17:56:42 +0200 (Sat, 03 May 2008) | 2 lines The compiling struct is now passed around to all AST helpers (see issue 2720) ................ r62680 | benjamin.peterson | 2008-05-03 23:35:18 +0200 (Sat, 03 May 2008) | 2 lines Moved testing of builtin types out of test_builtin and into type specific modules ................ r62686 | mark.dickinson | 2008-05-04 04:25:46 +0200 (Sun, 04 May 2008) | 4 lines Make sure that Context traps and flags dictionaries have values 0 and 1 (as documented) rather than True and False. ................ r62687 | benjamin.peterson | 2008-05-04 05:05:49 +0200 (Sun, 04 May 2008) | 2 lines Fix typo in whatsnew ................ r62696 | georg.brandl | 2008-05-04 11:15:04 +0200 (Sun, 04 May 2008) | 2 lines #2752: wrong meaning of '' for socket host. ................ r62699 | christian.heimes | 2008-05-04 13:50:53 +0200 (Sun, 04 May 2008) | 1 line Added note that Python requires at least Win2k SP4 ................ r62700 | gerhard.haering | 2008-05-04 14:59:57 +0200 (Sun, 04 May 2008) | 3 lines SQLite requires 64-bit integers in order to build. So the whole HAVE_LONG_LONG #ifdefing was useless. ................ r62701 | gerhard.haering | 2008-05-04 15:15:12 +0200 (Sun, 04 May 2008) | 3 lines Applied sqliterow-richcmp.diff patch from Thomas Heller in Issue2152. The sqlite3.Row type is now correctly hashable. ................ r62702 | gerhard.haering | 2008-05-04 15:42:44 +0200 (Sun, 04 May 2008) | 5 lines Implemented feature request 2157: Converter names are cut off at '(' characters. This avoids the common case of something like 'NUMBER(10)' not being parsed as 'NUMBER', like expected. Also corrected the docs about converter names being case-sensitive. They aren't any longer. ................ r62703 | georg.brandl | 2008-05-04 17:45:05 +0200 (Sun, 04 May 2008) | 2 lines #2757: Remove spare newline. ................ r62711 | benjamin.peterson | 2008-05-04 21:10:02 +0200 (Sun, 04 May 2008) | 2 lines Fix typo in bugs.rst ................ --- builtdist.rst | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index cd2bd817b4..c4b8dbf3f4 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -426,6 +426,13 @@ built-in functions in the installation script. also the configuration. For details refer to Microsoft's documentation of the :cfunc:`SHGetSpecialFolderPath` function. +Vista User Access Control (UAC) +=============================== + +Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` +option. The default is 'none' (meaning no UAC handling is done), and other +valid values are 'auto' (meaning prompt for UAC elevation if Python was +installed for all users) and 'force' (meaning always prompt for elevation) .. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) @@ -437,5 +444,3 @@ built-in functions in the installation script. and *iconindex* is the index of the icon in the file *iconpath*. Again, for details consult the Microsoft documentation for the :class:`IShellLink` interface. - - From c7e570dcce34e861bc19fdaa9eff0cf9adf249e9 Mon Sep 17 00:00:00 2001 From: "Andrew M. Kuchling" Date: Sat, 10 May 2008 19:51:55 +0000 Subject: [PATCH 024/330] #1858 from Tarek Ziade: Allow multiple repositories in .pypirc; see http://wiki.python.org/moin/EnhancedPyPI for discussion. The patch is slightly revised from Tarek's last patch: I've simplified the PyPIRCCommand.finalize_options() method to not look at sys.argv. Tests still pass. --- packageindex.rst | 31 ++++++++++++++++++++++++++++++- uploading.rst | 12 +++++++++--- 2 files changed, 39 insertions(+), 4 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index 8242012816..ef81d6465a 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -55,11 +55,40 @@ The .pypirc file The format of the :file:`.pypirc` file is as follows:: - [server-login] + [distutils] + index-servers = + pypi + + [pypi] repository: username: password: *repository* can be omitted and defaults to ``http://www.python.org/pypi``. +If you want to define another server a new section can be created:: + + [distutils] + index-servers = + pypi + other + + [pypi] + repository: + username: + password: + + [other] + repository: http://example.com/pypi + username: + password: + +The command can then be called with the -r option:: + + python setup.py register -r http://example.com/pypi + +Or even with the section name:: + + python setup.py register -r other + diff --git a/uploading.rst b/uploading.rst index 0b82184c48..52d6d5b7c7 100644 --- a/uploading.rst +++ b/uploading.rst @@ -24,14 +24,20 @@ The :command:`upload` command uses the username, password, and repository URL from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this file). +You can specify another PyPI server with the :option:`--repository=*url*` option:: + + python setup.py sdist bdist_wininst upload -r http://example.com/pypi + +See section :ref:`pypirc` for more on defining several servers. + You can use the :option:`--sign` option to tell :command:`upload` to sign each uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must be available for execution on the system :envvar:`PATH`. You can also specify which key to use for signing using the :option:`--identity=*name*` option. -Other :command:`upload` options include :option:`--repository=*url*` (which -lets you override the repository setting from :file:`$HOME/.pypirc`), and +Other :command:`upload` options include :option:`--repository=*url*` +or :option:`--repository=*section*` where `url` is the url of the server +and `section` the name of the section in :file:`$HOME/.pypirc`, and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). - From 99fdc1342493866363cca1176e8a74ec264e8603 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Sat, 10 May 2008 20:52:01 +0000 Subject: [PATCH 025/330] Revert r62998 as it broke the build (seems distutils.config is missing). --- packageindex.rst | 31 +------------------------------ uploading.rst | 12 +++--------- 2 files changed, 4 insertions(+), 39 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index ef81d6465a..8242012816 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -55,40 +55,11 @@ The .pypirc file The format of the :file:`.pypirc` file is as follows:: - [distutils] - index-servers = - pypi - - [pypi] + [server-login] repository: username: password: *repository* can be omitted and defaults to ``http://www.python.org/pypi``. -If you want to define another server a new section can be created:: - - [distutils] - index-servers = - pypi - other - - [pypi] - repository: - username: - password: - - [other] - repository: http://example.com/pypi - username: - password: - -The command can then be called with the -r option:: - - python setup.py register -r http://example.com/pypi - -Or even with the section name:: - - python setup.py register -r other - diff --git a/uploading.rst b/uploading.rst index 52d6d5b7c7..0b82184c48 100644 --- a/uploading.rst +++ b/uploading.rst @@ -24,20 +24,14 @@ The :command:`upload` command uses the username, password, and repository URL from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this file). -You can specify another PyPI server with the :option:`--repository=*url*` option:: - - python setup.py sdist bdist_wininst upload -r http://example.com/pypi - -See section :ref:`pypirc` for more on defining several servers. - You can use the :option:`--sign` option to tell :command:`upload` to sign each uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must be available for execution on the system :envvar:`PATH`. You can also specify which key to use for signing using the :option:`--identity=*name*` option. -Other :command:`upload` options include :option:`--repository=*url*` -or :option:`--repository=*section*` where `url` is the url of the server -and `section` the name of the section in :file:`$HOME/.pypirc`, and +Other :command:`upload` options include :option:`--repository=*url*` (which +lets you override the repository setting from :file:`$HOME/.pypirc`), and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). + From ff695c6e307ee2147a6d7f0d8e5dfd30216d820a Mon Sep 17 00:00:00 2001 From: "Andrew M. Kuchling" Date: Sun, 11 May 2008 14:00:00 +0000 Subject: [PATCH 026/330] #1858: re-apply patch for this, adding the missing files --- packageindex.rst | 31 ++++++++++++++++++++++++++++++- uploading.rst | 12 +++++++++--- 2 files changed, 39 insertions(+), 4 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index 8242012816..ef81d6465a 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -55,11 +55,40 @@ The .pypirc file The format of the :file:`.pypirc` file is as follows:: - [server-login] + [distutils] + index-servers = + pypi + + [pypi] repository: username: password: *repository* can be omitted and defaults to ``http://www.python.org/pypi``. +If you want to define another server a new section can be created:: + + [distutils] + index-servers = + pypi + other + + [pypi] + repository: + username: + password: + + [other] + repository: http://example.com/pypi + username: + password: + +The command can then be called with the -r option:: + + python setup.py register -r http://example.com/pypi + +Or even with the section name:: + + python setup.py register -r other + diff --git a/uploading.rst b/uploading.rst index 0b82184c48..52d6d5b7c7 100644 --- a/uploading.rst +++ b/uploading.rst @@ -24,14 +24,20 @@ The :command:`upload` command uses the username, password, and repository URL from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this file). +You can specify another PyPI server with the :option:`--repository=*url*` option:: + + python setup.py sdist bdist_wininst upload -r http://example.com/pypi + +See section :ref:`pypirc` for more on defining several servers. + You can use the :option:`--sign` option to tell :command:`upload` to sign each uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must be available for execution on the system :envvar:`PATH`. You can also specify which key to use for signing using the :option:`--identity=*name*` option. -Other :command:`upload` options include :option:`--repository=*url*` (which -lets you override the repository setting from :file:`$HOME/.pypirc`), and +Other :command:`upload` options include :option:`--repository=*url*` +or :option:`--repository=*section*` where `url` is the url of the server +and `section` the name of the section in :file:`$HOME/.pypirc`, and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). - From 9f3e56e5f23df7de81f4ce47dcb9193ff5010029 Mon Sep 17 00:00:00 2001 From: Alexandre Vassalotti Date: Fri, 16 May 2008 00:03:33 +0000 Subject: [PATCH 027/330] Merged revisions 62998-63003,63005-63006,63009-63012,63014-63017,63019-63020,63022-63024,63026-63029,63031-63041,63043-63045,63047-63054,63056-63062 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r62998 | andrew.kuchling | 2008-05-10 15:51:55 -0400 (Sat, 10 May 2008) | 7 lines #1858 from Tarek Ziade: Allow multiple repositories in .pypirc; see http://wiki.python.org/moin/EnhancedPyPI for discussion. The patch is slightly revised from Tarek's last patch: I've simplified the PyPIRCCommand.finalize_options() method to not look at sys.argv. Tests still pass. ........ r63000 | alexandre.vassalotti | 2008-05-10 15:59:16 -0400 (Sat, 10 May 2008) | 5 lines Cleaned up io._BytesIO.write(). I am amazed that the old code, for inserting null-bytes, actually worked. Who wrote that thing? Oh, it is me... doh. ........ r63002 | brett.cannon | 2008-05-10 16:52:01 -0400 (Sat, 10 May 2008) | 2 lines Revert r62998 as it broke the build (seems distutils.config is missing). ........ r63014 | andrew.kuchling | 2008-05-10 18:12:38 -0400 (Sat, 10 May 2008) | 1 line #1858: add distutils.config module ........ r63027 | brett.cannon | 2008-05-10 21:09:32 -0400 (Sat, 10 May 2008) | 2 lines Flesh out the 3.0 deprecation to suggest using the ctypes module. ........ r63028 | skip.montanaro | 2008-05-10 22:59:30 -0400 (Sat, 10 May 2008) | 4 lines Copied two versions of the example from the interactive session. Delete one. ........ r63037 | georg.brandl | 2008-05-11 03:02:17 -0400 (Sun, 11 May 2008) | 2 lines reload() takes the module itself. ........ r63038 | alexandre.vassalotti | 2008-05-11 03:06:04 -0400 (Sun, 11 May 2008) | 4 lines Added test framework for handling module renames. Factored the import guard in test_py3kwarn.TestStdlibRemovals into a context manager, namely test_support.CleanImport. ........ r63039 | georg.brandl | 2008-05-11 03:06:05 -0400 (Sun, 11 May 2008) | 2 lines #2742: ``''`` is not converted to NULL in getaddrinfo. ........ r63040 | alexandre.vassalotti | 2008-05-11 03:08:12 -0400 (Sun, 11 May 2008) | 2 lines Fixed typo in a comment of test_support.CleanImport. ........ r63041 | alexandre.vassalotti | 2008-05-11 03:10:25 -0400 (Sun, 11 May 2008) | 2 lines Removed a dead line of code. ........ r63043 | georg.brandl | 2008-05-11 04:47:53 -0400 (Sun, 11 May 2008) | 2 lines #2812: document property.getter/setter/deleter. ........ r63049 | georg.brandl | 2008-05-11 05:06:30 -0400 (Sun, 11 May 2008) | 2 lines #1153769: document PEP 237 changes to string formatting. ........ r63050 | georg.brandl | 2008-05-11 05:11:40 -0400 (Sun, 11 May 2008) | 2 lines #2809: elaborate str.split docstring a bit. ........ r63051 | georg.brandl | 2008-05-11 06:13:59 -0400 (Sun, 11 May 2008) | 2 lines Fix typo. ........ r63052 | georg.brandl | 2008-05-11 06:33:27 -0400 (Sun, 11 May 2008) | 2 lines #2709: clarification. ........ r63053 | georg.brandl | 2008-05-11 06:42:28 -0400 (Sun, 11 May 2008) | 2 lines #2659: add ``break_on_hyphens`` to TextWrapper. ........ r63057 | georg.brandl | 2008-05-11 06:59:39 -0400 (Sun, 11 May 2008) | 2 lines #2741: clarification of value range for address_family. ........ r63058 | georg.brandl | 2008-05-11 07:09:35 -0400 (Sun, 11 May 2008) | 2 lines #2452: timeout is used for all blocking operations. ........ r63059 | andrew.kuchling | 2008-05-11 09:33:56 -0400 (Sun, 11 May 2008) | 2 lines #1792: Improve performance of marshal.dumps() on large objects by increasing the size of the buffer more quickly. ........ r63060 | andrew.kuchling | 2008-05-11 10:00:00 -0400 (Sun, 11 May 2008) | 1 line #1858: re-apply patch for this, adding the missing files ........ r63061 | benjamin.peterson | 2008-05-11 10:13:25 -0400 (Sun, 11 May 2008) | 2 lines Add the "until" command to pdb ........ r63062 | georg.brandl | 2008-05-11 10:17:13 -0400 (Sun, 11 May 2008) | 2 lines Add some sentence endings. ........ --- packageindex.rst | 31 ++++++++++++++++++++++++++++++- uploading.rst | 12 +++++++++--- 2 files changed, 39 insertions(+), 4 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index 8242012816..ef81d6465a 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -55,11 +55,40 @@ The .pypirc file The format of the :file:`.pypirc` file is as follows:: - [server-login] + [distutils] + index-servers = + pypi + + [pypi] repository: username: password: *repository* can be omitted and defaults to ``http://www.python.org/pypi``. +If you want to define another server a new section can be created:: + + [distutils] + index-servers = + pypi + other + + [pypi] + repository: + username: + password: + + [other] + repository: http://example.com/pypi + username: + password: + +The command can then be called with the -r option:: + + python setup.py register -r http://example.com/pypi + +Or even with the section name:: + + python setup.py register -r other + diff --git a/uploading.rst b/uploading.rst index 5be413032c..d960656515 100644 --- a/uploading.rst +++ b/uploading.rst @@ -22,14 +22,20 @@ The :command:`upload` command uses the username, password, and repository URL from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this file). +You can specify another PyPI server with the :option:`--repository=*url*` option:: + + python setup.py sdist bdist_wininst upload -r http://example.com/pypi + +See section :ref:`pypirc` for more on defining several servers. + You can use the :option:`--sign` option to tell :command:`upload` to sign each uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must be available for execution on the system :envvar:`PATH`. You can also specify which key to use for signing using the :option:`--identity=*name*` option. -Other :command:`upload` options include :option:`--repository=*url*` (which -lets you override the repository setting from :file:`$HOME/.pypirc`), and +Other :command:`upload` options include :option:`--repository=*url*` +or :option:`--repository=*section*` where `url` is the url of the server +and `section` the name of the section in :file:`$HOME/.pypirc`, and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). - From 2b7075c442a9595e396c879a981c42ecfdfda1a3 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 26 May 2008 10:29:35 +0000 Subject: [PATCH 028/330] Create the dbm package from PEP 3108. #2881. --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index 3cc1da92e9..616b99cd09 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -316,7 +316,7 @@ For example, if you need to link against libraries known to be in the standard library search path on target systems :: Extension(..., - libraries=['gdbm', 'readline']) + libraries=['_gdbm', 'readline']) If you need to link with libraries in a non-standard location, you'll have to include the location in ``library_dirs``:: From 9d4fafe27fe8cc0ac142fbfb8d93edbae939b5e0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 26 May 2008 17:55:52 +0000 Subject: [PATCH 029/330] Fix old-style octal literals in the docs. --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 6616f83661..be1eb0fd18 100644 --- a/apiref.rst +++ b/apiref.rst @@ -961,7 +961,7 @@ This module provides functions for operating on directories and trees of directories. -.. function:: mkpath(name[, mode=0777, verbose=0, dry_run=0]) +.. function:: mkpath(name[, mode=0o777, verbose=0, dry_run=0]) Create a directory and any missing ancestor directories. If the directory already exists (or if *name* is the empty string, which means the current @@ -972,7 +972,7 @@ directories. directories actually created. -.. function:: create_tree(base_dir, files[, mode=0777, verbose=0, dry_run=0]) +.. function:: create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0]) Create all the empty directories under *base_dir* needed to put *files* there. *base_dir* is just the a name of a directory which doesn't necessarily exist From f3f19e6f70c581f5d7bf10c70ee0346222c8b7c7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 13 Sep 2008 17:41:16 +0000 Subject: [PATCH 030/330] Remove things specific to the old Macintosh, and spell "Mac OS X" consistently. --- apiref.rst | 2 +- builtdist.rst | 4 ++-- commandref.rst | 2 +- setupscript.rst | 4 +--- 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/apiref.rst b/apiref.rst index f5b49b8910..a8f74616ab 100644 --- a/apiref.rst +++ b/apiref.rst @@ -326,7 +326,7 @@ This module provides the following functions. ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the default compilers are "traditional Unix interface" (:class:`UnixCCompiler` - class) and Visual C++(:class:`MSVCCompiler` class). Note that it's perfectly + class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly possible to ask for a Unix compiler object under Windows, and a Microsoft compiler object under Unix---if you supply a value for *compiler*, *plat* is ignored. diff --git a/builtdist.rst b/builtdist.rst index c4b8dbf3f4..58b62f834e 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -302,8 +302,8 @@ or the :command:`bdist` command with the :option:`--formats` option:: If you have a pure module distribution (only containing pure Python modules and packages), the resulting installer will be version independent and have a name -like :file:`foo-1.0.win32.exe`. These installers can even be created on Unix or -Mac OS platforms. +like :file:`foo-1.0.win32.exe`. These installers can even be created on Unix +platforms or Mac OS X. If you have a non-pure distribution, the extensions can only be created on a Windows platform, and will be Python version dependent. The installer filename diff --git a/commandref.rst b/commandref.rst index f5f02204c5..fbe40de6c2 100644 --- a/commandref.rst +++ b/commandref.rst @@ -88,7 +88,7 @@ regular filename characters, ``?`` matches any single regular filename character, and ``[range]`` matches any of the characters in *range* (e.g., ``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename character" is platform-specific: on Unix it is anything except slash; on Windows -anything except backslash or colon; on Mac OS 9 anything except colon. +anything except backslash or colon. **\*\*** Windows support not there yet **\*\*** diff --git a/setupscript.rst b/setupscript.rst index d2be083a66..1e540edb25 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -46,9 +46,7 @@ Distutils will take care of converting this platform-neutral representation into whatever is appropriate on your current platform before actually using the pathname. This makes your setup script portable across operating systems, which of course is one of the major goals of the Distutils. In this spirit, all -pathnames in this document are slash-separated. (Mac OS 9 programmers should -keep in mind that the *absence* of a leading slash indicates a relative path, -the opposite of the Mac OS convention with colons.) +pathnames in this document are slash-separated. This, of course, only applies to pathnames given to Distutils functions. If you, for example, use standard Python functions such as :func:`glob.glob` or From 8e5a6db3689266a82aa0dea50c8b7a904193c604 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 13 Sep 2008 17:46:05 +0000 Subject: [PATCH 031/330] Merged revisions 66452 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r66452 | georg.brandl | 2008-09-13 19:41:16 +0200 (Sat, 13 Sep 2008) | 2 lines Remove things specific to the old Macintosh, and spell "Mac OS X" consistently. ........ --- apiref.rst | 2 +- builtdist.rst | 4 ++-- commandref.rst | 2 +- setupscript.rst | 4 +--- 4 files changed, 5 insertions(+), 7 deletions(-) diff --git a/apiref.rst b/apiref.rst index be1eb0fd18..f2d863c79c 100644 --- a/apiref.rst +++ b/apiref.rst @@ -326,7 +326,7 @@ This module provides the following functions. ``'posix'``, ``'nt'``), and *compiler* defaults to the default compiler for that platform. Currently only ``'posix'`` and ``'nt'`` are supported, and the default compilers are "traditional Unix interface" (:class:`UnixCCompiler` - class) and Visual C++(:class:`MSVCCompiler` class). Note that it's perfectly + class) and Visual C++ (:class:`MSVCCompiler` class). Note that it's perfectly possible to ask for a Unix compiler object under Windows, and a Microsoft compiler object under Unix---if you supply a value for *compiler*, *plat* is ignored. diff --git a/builtdist.rst b/builtdist.rst index c4b8dbf3f4..58b62f834e 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -302,8 +302,8 @@ or the :command:`bdist` command with the :option:`--formats` option:: If you have a pure module distribution (only containing pure Python modules and packages), the resulting installer will be version independent and have a name -like :file:`foo-1.0.win32.exe`. These installers can even be created on Unix or -Mac OS platforms. +like :file:`foo-1.0.win32.exe`. These installers can even be created on Unix +platforms or Mac OS X. If you have a non-pure distribution, the extensions can only be created on a Windows platform, and will be Python version dependent. The installer filename diff --git a/commandref.rst b/commandref.rst index f5f02204c5..fbe40de6c2 100644 --- a/commandref.rst +++ b/commandref.rst @@ -88,7 +88,7 @@ regular filename characters, ``?`` matches any single regular filename character, and ``[range]`` matches any of the characters in *range* (e.g., ``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename character" is platform-specific: on Unix it is anything except slash; on Windows -anything except backslash or colon; on Mac OS 9 anything except colon. +anything except backslash or colon. **\*\*** Windows support not there yet **\*\*** diff --git a/setupscript.rst b/setupscript.rst index 616b99cd09..8bbcb29746 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -46,9 +46,7 @@ Distutils will take care of converting this platform-neutral representation into whatever is appropriate on your current platform before actually using the pathname. This makes your setup script portable across operating systems, which of course is one of the major goals of the Distutils. In this spirit, all -pathnames in this document are slash-separated. (Mac OS 9 programmers should -keep in mind that the *absence* of a leading slash indicates a relative path, -the opposite of the Mac OS convention with colons.) +pathnames in this document are slash-separated. This, of course, only applies to pathnames given to Distutils functions. If you, for example, use standard Python functions such as :func:`glob.glob` or From 801cb3c54c2330eceddb36a930c7aa0f7d25f5cf Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20v=2E=20L=C3=B6wis?= Date: Mon, 17 Nov 2008 16:04:09 +0000 Subject: [PATCH 032/330] Issue #4312: Remove claim that distutils parameters must not be Unicode. The opposite is true. --- setupscript.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 8bbcb29746..6e3fd3826e 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -588,8 +588,6 @@ Notes: 'list of strings' See below. -None of the string values may be Unicode. - Encoding the version information is an art in itself. Python packages generally adhere to the version format *major.minor[.patch][sub]*. The major number is 0 for initial, experimental releases of software. It is incremented for releases From c399e01cf9817d1a8ae62521ae48530953a1ed73 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 15 Dec 2008 08:33:58 +0000 Subject: [PATCH 033/330] #4446: document "platforms" argument for setup(). --- setupscript.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 1e540edb25..7971878bba 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -563,6 +563,8 @@ This information includes: +----------------------+---------------------------+-----------------+--------+ | ``classifiers`` | a list of classifiers | list of strings | \(4) | +----------------------+---------------------------+-----------------+--------+ +| ``platforms`` | a list of platforms | list of strings | | ++----------------------+---------------------------+-----------------+--------+ Notes: From fa3bd7d8e8bb453c8e06daa3b747d8a15faa5796 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sun, 21 Dec 2008 00:06:59 +0000 Subject: [PATCH 034/330] Merged revisions 67654,67676-67677,67681,67692,67725,67761,67784-67785,67787-67788,67802,67848-67850,67862-67864,67880,67882 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67654 | georg.brandl | 2008-12-07 16:42:09 -0600 (Sun, 07 Dec 2008) | 2 lines #4457: rewrite __import__() documentation. ........ r67676 | benjamin.peterson | 2008-12-08 20:03:03 -0600 (Mon, 08 Dec 2008) | 1 line specify how things are copied ........ r67677 | benjamin.peterson | 2008-12-08 20:05:11 -0600 (Mon, 08 Dec 2008) | 1 line revert unrelated change to installer script ........ r67681 | jeremy.hylton | 2008-12-09 15:03:10 -0600 (Tue, 09 Dec 2008) | 2 lines Add simple unittests for Request ........ r67692 | amaury.forgeotdarc | 2008-12-10 18:03:42 -0600 (Wed, 10 Dec 2008) | 2 lines #1030250: correctly pass the dry_run option to the mkpath() function. ........ r67725 | benjamin.peterson | 2008-12-12 22:02:20 -0600 (Fri, 12 Dec 2008) | 1 line fix incorrect example ........ r67761 | benjamin.peterson | 2008-12-14 11:26:04 -0600 (Sun, 14 Dec 2008) | 1 line fix missing bracket ........ r67784 | georg.brandl | 2008-12-15 02:33:58 -0600 (Mon, 15 Dec 2008) | 2 lines #4446: document "platforms" argument for setup(). ........ r67785 | georg.brandl | 2008-12-15 02:36:11 -0600 (Mon, 15 Dec 2008) | 2 lines #4611: fix typo. ........ r67787 | georg.brandl | 2008-12-15 02:58:59 -0600 (Mon, 15 Dec 2008) | 2 lines #4578: fix has_key() usage in compiler package. ........ r67788 | georg.brandl | 2008-12-15 03:07:39 -0600 (Mon, 15 Dec 2008) | 2 lines #4568: remove limitation in varargs callback example. ........ r67802 | amaury.forgeotdarc | 2008-12-15 16:29:14 -0600 (Mon, 15 Dec 2008) | 4 lines #3632: the "pyo" macro from gdbinit can now run when the GIL is released. Patch by haypo. ........ r67848 | benjamin.peterson | 2008-12-18 20:28:56 -0600 (Thu, 18 Dec 2008) | 1 line fix typo ........ r67849 | benjamin.peterson | 2008-12-18 20:31:35 -0600 (Thu, 18 Dec 2008) | 1 line _call_method -> _callmethod and _get_value to _getvalue ........ r67850 | raymond.hettinger | 2008-12-19 03:06:07 -0600 (Fri, 19 Dec 2008) | 9 lines Fix-up and clean-up docs for int.bit_length(). * Replace dramatic footnote with in-line comment about possible round-off errors in logarithms of large numbers. * Add comments to the pure python code equivalent. * replace floor() with int() in the mathematical equivalent so the type is correct (should be an int, not a float). * add abs() to the mathematical equivalent so that it matches the previous line that it is supposed to be equivalent to. * make one combined example with a negative input. ........ r67862 | benjamin.peterson | 2008-12-19 20:48:02 -0600 (Fri, 19 Dec 2008) | 1 line copy sentence from docstring ........ r67863 | benjamin.peterson | 2008-12-19 20:51:26 -0600 (Fri, 19 Dec 2008) | 1 line add headings ........ r67864 | benjamin.peterson | 2008-12-19 20:57:19 -0600 (Fri, 19 Dec 2008) | 1 line beef up docstring ........ r67880 | benjamin.peterson | 2008-12-20 16:49:24 -0600 (Sat, 20 Dec 2008) | 1 line remove redundant sentence ........ r67882 | benjamin.peterson | 2008-12-20 16:59:49 -0600 (Sat, 20 Dec 2008) | 1 line add some recent releases to the list ........ --- setupscript.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 6e3fd3826e..7a6be8b270 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -561,6 +561,8 @@ This information includes: +----------------------+---------------------------+-----------------+--------+ | ``classifiers`` | a list of classifiers | list of strings | \(4) | +----------------------+---------------------------+-----------------+--------+ +| ``platforms`` | a list of platforms | list of strings | | ++----------------------+---------------------------+-----------------+--------+ Notes: From 8ea52a369c8eab44d7ad7c39aa82f1440d03377b Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sun, 21 Dec 2008 17:01:26 +0000 Subject: [PATCH 035/330] Merged revisions 67654,67676-67677,67681,67692,67725,67746,67748,67761,67784-67785,67787-67788,67802,67832,67848-67849,67859,67862-67864,67880,67882,67885,67889-67892,67895 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ................ r67654 | georg.brandl | 2008-12-07 16:42:09 -0600 (Sun, 07 Dec 2008) | 2 lines #4457: rewrite __import__() documentation. ................ r67676 | benjamin.peterson | 2008-12-08 20:03:03 -0600 (Mon, 08 Dec 2008) | 1 line specify how things are copied ................ r67677 | benjamin.peterson | 2008-12-08 20:05:11 -0600 (Mon, 08 Dec 2008) | 1 line revert unrelated change to installer script ................ r67681 | jeremy.hylton | 2008-12-09 15:03:10 -0600 (Tue, 09 Dec 2008) | 2 lines Add simple unittests for Request ................ r67692 | amaury.forgeotdarc | 2008-12-10 18:03:42 -0600 (Wed, 10 Dec 2008) | 2 lines #1030250: correctly pass the dry_run option to the mkpath() function. ................ r67725 | benjamin.peterson | 2008-12-12 22:02:20 -0600 (Fri, 12 Dec 2008) | 1 line fix incorrect example ................ r67746 | antoine.pitrou | 2008-12-13 17:12:30 -0600 (Sat, 13 Dec 2008) | 3 lines Issue #4163: Use unicode-friendly word splitting in the textwrap functions when given an unicode string. ................ r67748 | benjamin.peterson | 2008-12-13 19:46:11 -0600 (Sat, 13 Dec 2008) | 1 line remove has_key usage ................ r67761 | benjamin.peterson | 2008-12-14 11:26:04 -0600 (Sun, 14 Dec 2008) | 1 line fix missing bracket ................ r67784 | georg.brandl | 2008-12-15 02:33:58 -0600 (Mon, 15 Dec 2008) | 2 lines #4446: document "platforms" argument for setup(). ................ r67785 | georg.brandl | 2008-12-15 02:36:11 -0600 (Mon, 15 Dec 2008) | 2 lines #4611: fix typo. ................ r67787 | georg.brandl | 2008-12-15 02:58:59 -0600 (Mon, 15 Dec 2008) | 2 lines #4578: fix has_key() usage in compiler package. ................ r67788 | georg.brandl | 2008-12-15 03:07:39 -0600 (Mon, 15 Dec 2008) | 2 lines #4568: remove limitation in varargs callback example. ................ r67802 | amaury.forgeotdarc | 2008-12-15 16:29:14 -0600 (Mon, 15 Dec 2008) | 4 lines #3632: the "pyo" macro from gdbinit can now run when the GIL is released. Patch by haypo. ................ r67832 | antoine.pitrou | 2008-12-17 16:46:54 -0600 (Wed, 17 Dec 2008) | 4 lines Issue #2467: gc.DEBUG_STATS reports invalid elapsed times. Patch by Neil Schemenauer, very slightly modified. ................ r67848 | benjamin.peterson | 2008-12-18 20:28:56 -0600 (Thu, 18 Dec 2008) | 1 line fix typo ................ r67849 | benjamin.peterson | 2008-12-18 20:31:35 -0600 (Thu, 18 Dec 2008) | 1 line _call_method -> _callmethod and _get_value to _getvalue ................ r67859 | amaury.forgeotdarc | 2008-12-19 16:56:48 -0600 (Fri, 19 Dec 2008) | 4 lines #4700: crtlicense.txt is displayed by the license() command and should be kept ascii-only. Will port to 3.0 ................ r67862 | benjamin.peterson | 2008-12-19 20:48:02 -0600 (Fri, 19 Dec 2008) | 1 line copy sentence from docstring ................ r67863 | benjamin.peterson | 2008-12-19 20:51:26 -0600 (Fri, 19 Dec 2008) | 1 line add headings ................ r67864 | benjamin.peterson | 2008-12-19 20:57:19 -0600 (Fri, 19 Dec 2008) | 1 line beef up docstring ................ r67880 | benjamin.peterson | 2008-12-20 16:49:24 -0600 (Sat, 20 Dec 2008) | 1 line remove redundant sentence ................ r67882 | benjamin.peterson | 2008-12-20 16:59:49 -0600 (Sat, 20 Dec 2008) | 1 line add some recent releases to the list ................ r67885 | benjamin.peterson | 2008-12-20 17:48:54 -0600 (Sat, 20 Dec 2008) | 1 line silence annoying DeprecationWarning ................ r67889 | benjamin.peterson | 2008-12-20 19:04:32 -0600 (Sat, 20 Dec 2008) | 1 line sphinx.web is long gone ................ r67890 | benjamin.peterson | 2008-12-20 19:12:26 -0600 (Sat, 20 Dec 2008) | 1 line update readme ................ r67891 | benjamin.peterson | 2008-12-20 19:14:47 -0600 (Sat, 20 Dec 2008) | 1 line there are way too many places which need to have the current version added ................ r67892 | benjamin.peterson | 2008-12-20 19:29:32 -0600 (Sat, 20 Dec 2008) | 9 lines Merged revisions 67809 via svnmerge from svn+ssh://pythondev@svn.python.org/sandbox/trunk/2to3/lib2to3 ........ r67809 | benjamin.peterson | 2008-12-15 21:54:45 -0600 (Mon, 15 Dec 2008) | 1 line fix logic error ........ ................ r67895 | neal.norwitz | 2008-12-21 08:28:32 -0600 (Sun, 21 Dec 2008) | 2 lines Add Tarek for work on distutils. ................ --- setupscript.rst | 2 ++ 1 file changed, 2 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 1e540edb25..7971878bba 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -563,6 +563,8 @@ This information includes: +----------------------+---------------------------+-----------------+--------+ | ``classifiers`` | a list of classifiers | list of strings | \(4) | +----------------------+---------------------------+-----------------+--------+ +| ``platforms`` | a list of platforms | list of strings | | ++----------------------+---------------------------+-----------------+--------+ Notes: From 8925b86f030f66d6cd7fddd68700ae216164f524 Mon Sep 17 00:00:00 2001 From: Ronald Oussoren Date: Sun, 28 Dec 2008 19:40:56 +0000 Subject: [PATCH 036/330] Issue4064: architecture string for universal builds on OSX --- apiref.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/apiref.rst b/apiref.rst index a8f74616ab..a932fbd387 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1100,6 +1100,23 @@ other utility module. For non-POSIX platforms, currently just returns ``sys.platform``. + For MacOS X systems the OS version reflects the minimal version on which + binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` + during the build of Python), not the OS version of the current system. + + For universal binary builds on MacOS X the architecture value reflects + the univeral binary status instead of the architecture of the current + processor. For 32-bit universal binaries the architecture is ``fat``, + for 4-way universal binaries the architecture is ``universal``. + + Examples of returned values on MacOS X: + + * ``macosx-10.3-ppc`` + + * ``macosx-10.3-fat`` + + * ``macosx-10.5-universal`` + .. % XXX isn't this also provided by some other non-distutils module? From 31afdff6c8393395586f79fcc63768233b867502 Mon Sep 17 00:00:00 2001 From: Ronald Oussoren Date: Sun, 28 Dec 2008 19:50:40 +0000 Subject: [PATCH 037/330] Update the fix for issue4064 to deal correctly with all three variants of universal builds that are presented by the configure script. --- apiref.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/apiref.rst b/apiref.rst index a932fbd387..65f175f6be 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1107,6 +1107,7 @@ other utility module. For universal binary builds on MacOS X the architecture value reflects the univeral binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is ``fat``, + for 64-bit universal binaries the architecture is ``fat64``, and for 4-way universal binaries the architecture is ``universal``. Examples of returned values on MacOS X: From 7f133f8f1c8b577769654f7b8358b42186a50cba Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Tue, 30 Dec 2008 17:56:45 +0000 Subject: [PATCH 038/330] Merged revisions 67982,67988,67990 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67982 | benjamin.peterson | 2008-12-28 09:37:31 -0600 (Sun, 28 Dec 2008) | 1 line fix WORD_BIGEDIAN declaration in Universal builds; fixes #4060 and #4728 ........ r67988 | ronald.oussoren | 2008-12-28 13:40:56 -0600 (Sun, 28 Dec 2008) | 1 line Issue4064: architecture string for universal builds on OSX ........ r67990 | ronald.oussoren | 2008-12-28 13:50:40 -0600 (Sun, 28 Dec 2008) | 3 lines Update the fix for issue4064 to deal correctly with all three variants of universal builds that are presented by the configure script. ........ --- apiref.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/apiref.rst b/apiref.rst index f2d863c79c..c3148a647c 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1100,6 +1100,24 @@ other utility module. For non-POSIX platforms, currently just returns ``sys.platform``. + For MacOS X systems the OS version reflects the minimal version on which + binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` + during the build of Python), not the OS version of the current system. + + For universal binary builds on MacOS X the architecture value reflects + the univeral binary status instead of the architecture of the current + processor. For 32-bit universal binaries the architecture is ``fat``, + for 64-bit universal binaries the architecture is ``fat64``, and + for 4-way universal binaries the architecture is ``universal``. + + Examples of returned values on MacOS X: + + * ``macosx-10.3-ppc`` + + * ``macosx-10.3-fat`` + + * ``macosx-10.5-universal`` + .. % XXX isn't this also provided by some other non-distutils module? From ab60e089572247e8954d0468d02fbe5976d5104c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 1 Jan 2009 13:02:09 +0000 Subject: [PATCH 039/330] #4776: add data_files and package_dir arguments. --- apiref.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 65f175f6be..4a0d354547 100644 --- a/apiref.rst +++ b/apiref.rst @@ -88,9 +88,9 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *options* | default options for the setup | a string | | | script | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *license* | The license for the package | | + | *license* | The license for the package | a string | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *keywords* | Descriptive meta-data. See | | + | *keywords* | Descriptive meta-data, see | | | | :pep:`314` | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *platforms* | | | @@ -98,6 +98,13 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *cmdclass* | A mapping of command names to | a dictionary | | | :class:`Command` subclasses | | +--------------------+--------------------------------+-------------------------------------------------------------+ + | *data_files* | A list of data files to | a list | + | | install | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *package_dir* | A mapping of package to | a dictionary | + | | directory names | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + .. function:: run_setup(script_name[, script_args=None, stop_after='run']) From 52397084319e075770a4b5d82a1605150a763e60 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Thu, 1 Jan 2009 15:05:06 +0000 Subject: [PATCH 040/330] Merged revisions 68116-68119,68121,68123-68127 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68116 | georg.brandl | 2009-01-01 05:46:51 -0600 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 05:53:55 -0600 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 06:00:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68119 | georg.brandl | 2009-01-01 06:09:40 -0600 (Thu, 01 Jan 2009) | 3 lines #4222: document dis.findlabels() and dis.findlinestarts() and put them into dis.__all__. ........ r68121 | georg.brandl | 2009-01-01 06:43:33 -0600 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 06:52:29 -0600 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 06:53:19 -0600 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 07:02:09 -0600 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 07:05:13 -0600 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 07:14:49 -0600 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........ --- apiref.rst | 11 +++++++++-- 1 file changed, 9 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index c3148a647c..aec68c083e 100644 --- a/apiref.rst +++ b/apiref.rst @@ -88,9 +88,9 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *options* | default options for the setup | a string | | | script | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *license* | The license for the package | | + | *license* | The license for the package | a string | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *keywords* | Descriptive meta-data. See | | + | *keywords* | Descriptive meta-data, see | | | | :pep:`314` | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *platforms* | | | @@ -98,6 +98,13 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *cmdclass* | A mapping of command names to | a dictionary | | | :class:`Command` subclasses | | +--------------------+--------------------------------+-------------------------------------------------------------+ + | *data_files* | A list of data files to | a list | + | | install | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *package_dir* | A mapping of package to | a dictionary | + | | directory names | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + .. function:: run_setup(script_name[, script_args=None, stop_after='run']) From cdde5a1fcba1db781692d39b91b3b6c9d32149f8 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 1 Jan 2009 15:46:10 +0000 Subject: [PATCH 041/330] Merged revisions 67952-67953,67955,67957-67958,67960-67961,67963,67965,67967,67970-67971,67973,67982,67988,67990,67995,68014,68016,68030,68057,68061,68112,68115-68118,68120-68121,68123-68128 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r67952 | georg.brandl | 2008-12-27 18:42:40 +0100 (Sat, 27 Dec 2008) | 2 lines #4752: actually use custom handler in example. ........ r67953 | georg.brandl | 2008-12-27 19:20:04 +0100 (Sat, 27 Dec 2008) | 3 lines Patch #4739 by David Laban: add symbols to pydoc help topics, so that ``help('@')`` works as expected. ........ r67955 | georg.brandl | 2008-12-27 19:27:53 +0100 (Sat, 27 Dec 2008) | 3 lines Follow-up to r67746 in order to restore backwards-compatibility for those who (monkey-)patch TextWrapper.wordsep_re with a custom RE. ........ r67957 | georg.brandl | 2008-12-27 19:49:19 +0100 (Sat, 27 Dec 2008) | 2 lines #4754: improve winsound documentation. ........ r67958 | georg.brandl | 2008-12-27 20:02:59 +0100 (Sat, 27 Dec 2008) | 2 lines #4682: 'b' is actually unsigned char. ........ r67960 | georg.brandl | 2008-12-27 20:04:44 +0100 (Sat, 27 Dec 2008) | 2 lines #4695: fix backslashery. ........ r67961 | georg.brandl | 2008-12-27 20:06:04 +0100 (Sat, 27 Dec 2008) | 2 lines Use :samp: role. ........ r67963 | georg.brandl | 2008-12-27 20:11:15 +0100 (Sat, 27 Dec 2008) | 2 lines #4671: document that pydoc imports modules. ........ r67965 | antoine.pitrou | 2008-12-27 21:34:52 +0100 (Sat, 27 Dec 2008) | 3 lines Issue #4677: add two list comprehension tests to pybench. ........ r67967 | benjamin.peterson | 2008-12-27 23:18:58 +0100 (Sat, 27 Dec 2008) | 1 line fix markup ........ r67970 | alexandre.vassalotti | 2008-12-28 02:52:58 +0100 (Sun, 28 Dec 2008) | 2 lines Fix name mangling of PyUnicode_ClearFreeList. ........ r67971 | alexandre.vassalotti | 2008-12-28 03:10:35 +0100 (Sun, 28 Dec 2008) | 2 lines Sort UCS-2/UCS-4 name mangling list. ........ r67973 | alexandre.vassalotti | 2008-12-28 03:58:22 +0100 (Sun, 28 Dec 2008) | 2 lines Document Py_VaBuildValue. ........ r67982 | benjamin.peterson | 2008-12-28 16:37:31 +0100 (Sun, 28 Dec 2008) | 1 line fix WORD_BIGEDIAN declaration in Universal builds; fixes #4060 and #4728 ........ r67988 | ronald.oussoren | 2008-12-28 20:40:56 +0100 (Sun, 28 Dec 2008) | 1 line Issue4064: architecture string for universal builds on OSX ........ r67990 | ronald.oussoren | 2008-12-28 20:50:40 +0100 (Sun, 28 Dec 2008) | 3 lines Update the fix for issue4064 to deal correctly with all three variants of universal builds that are presented by the configure script. ........ r67995 | benjamin.peterson | 2008-12-28 22:16:07 +0100 (Sun, 28 Dec 2008) | 1 line #4763 PyErr_ExceptionMatches won't blow up with NULL arguments ........ r68014 | benjamin.peterson | 2008-12-29 18:47:42 +0100 (Mon, 29 Dec 2008) | 1 line #4764 set IOError.filename when trying to open a directory on POSIX platforms ........ r68016 | benjamin.peterson | 2008-12-29 18:56:58 +0100 (Mon, 29 Dec 2008) | 1 line #4764 in io.open, set IOError.filename when trying to open a directory on POSIX platforms ........ r68030 | benjamin.peterson | 2008-12-29 22:38:14 +0100 (Mon, 29 Dec 2008) | 1 line fix French ........ r68057 | vinay.sajip | 2008-12-30 08:01:25 +0100 (Tue, 30 Dec 2008) | 1 line Minor documentation change relating to NullHandler. ........ r68061 | georg.brandl | 2008-12-30 11:15:49 +0100 (Tue, 30 Dec 2008) | 2 lines #4778: attributes can't be called. ........ r68112 | benjamin.peterson | 2009-01-01 00:48:39 +0100 (Thu, 01 Jan 2009) | 1 line #4795 inspect.isgeneratorfunction() should return False instead of None ........ r68115 | benjamin.peterson | 2009-01-01 05:04:41 +0100 (Thu, 01 Jan 2009) | 1 line simplfy code ........ r68116 | georg.brandl | 2009-01-01 12:46:51 +0100 (Thu, 01 Jan 2009) | 2 lines #4100: note that element children are not necessarily present on "start" events. ........ r68117 | georg.brandl | 2009-01-01 12:53:55 +0100 (Thu, 01 Jan 2009) | 2 lines #4156: make clear that "protocol" is to be replaced with the protocol name. ........ r68118 | georg.brandl | 2009-01-01 13:00:19 +0100 (Thu, 01 Jan 2009) | 2 lines #4185: clarify escape behavior of replacement strings. ........ r68120 | georg.brandl | 2009-01-01 13:15:31 +0100 (Thu, 01 Jan 2009) | 4 lines #4228: Pack negative values the same way as 2.4 in struct's L format. ........ r68121 | georg.brandl | 2009-01-01 13:43:33 +0100 (Thu, 01 Jan 2009) | 2 lines Point to types module in new module deprecation notice. ........ r68123 | georg.brandl | 2009-01-01 13:52:29 +0100 (Thu, 01 Jan 2009) | 2 lines #4784: ... on three counts ... ........ r68124 | georg.brandl | 2009-01-01 13:53:19 +0100 (Thu, 01 Jan 2009) | 2 lines #4782: Fix markup error that hid load() and loads(). ........ r68125 | georg.brandl | 2009-01-01 14:02:09 +0100 (Thu, 01 Jan 2009) | 2 lines #4776: add data_files and package_dir arguments. ........ r68126 | georg.brandl | 2009-01-01 14:05:13 +0100 (Thu, 01 Jan 2009) | 2 lines Handlers are in the `logging.handlers` module. ........ r68127 | georg.brandl | 2009-01-01 14:14:49 +0100 (Thu, 01 Jan 2009) | 2 lines #4767: Use correct submodules for all MIME classes. ........ r68128 | antoine.pitrou | 2009-01-01 15:11:22 +0100 (Thu, 01 Jan 2009) | 3 lines Issue #3680: Reference cycles created through a dict, set or deque iterator did not get collected. ........ --- apiref.rst | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index a8f74616ab..4a0d354547 100644 --- a/apiref.rst +++ b/apiref.rst @@ -88,9 +88,9 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *options* | default options for the setup | a string | | | script | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *license* | The license for the package | | + | *license* | The license for the package | a string | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *keywords* | Descriptive meta-data. See | | + | *keywords* | Descriptive meta-data, see | | | | :pep:`314` | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *platforms* | | | @@ -98,6 +98,13 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *cmdclass* | A mapping of command names to | a dictionary | | | :class:`Command` subclasses | | +--------------------+--------------------------------+-------------------------------------------------------------+ + | *data_files* | A list of data files to | a list | + | | install | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + | *package_dir* | A mapping of package to | a dictionary | + | | directory names | | + +--------------------+--------------------------------+-------------------------------------------------------------+ + .. function:: run_setup(script_name[, script_args=None, stop_after='run']) @@ -1100,6 +1107,24 @@ other utility module. For non-POSIX platforms, currently just returns ``sys.platform``. + For MacOS X systems the OS version reflects the minimal version on which + binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` + during the build of Python), not the OS version of the current system. + + For universal binary builds on MacOS X the architecture value reflects + the univeral binary status instead of the architecture of the current + processor. For 32-bit universal binaries the architecture is ``fat``, + for 64-bit universal binaries the architecture is ``fat64``, and + for 4-way universal binaries the architecture is ``universal``. + + Examples of returned values on MacOS X: + + * ``macosx-10.3-ppc`` + + * ``macosx-10.3-fat`` + + * ``macosx-10.5-universal`` + .. % XXX isn't this also provided by some other non-distutils module? From 4843c1b99c2001706bfd70909789db9ca32d98bd Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 2 Jan 2009 20:25:14 +0000 Subject: [PATCH 042/330] #4811: fix markup glitches (mostly remains of the conversion), found by Gabriel Genellina. --- apiref.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 4a0d354547..f9222ece68 100644 --- a/apiref.rst +++ b/apiref.rst @@ -188,9 +188,10 @@ the full reference. | | for C/C++ header files (in | | | | Unix form for portability) | | +------------------------+--------------------------------+---------------------------+ - | *define_macros* | list of macros to define; each | (string,string) tuple or | - | | macro is defined using a | (name,``None``) | - | | 2-tuple, where 'value' is | | + | *define_macros* | list of macros to define; each | (string, string) tuple or | + | | macro is defined using a | (name, ``None``) | + | | 2-tuple ``(name, value)``, | | + | | where *value* is | | | | either the string to define it | | | | to or ``None`` to define it | | | | without a particular value | | From 7ff371e8d3f5a9db5ca7353521fe9196a54d0ad2 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 3 Jan 2009 20:47:01 +0000 Subject: [PATCH 043/330] Fix uses of the default role. --- uploading.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/uploading.rst b/uploading.rst index 52d6d5b7c7..66f712b758 100644 --- a/uploading.rst +++ b/uploading.rst @@ -35,9 +35,9 @@ uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must be available for execution on the system :envvar:`PATH`. You can also specify which key to use for signing using the :option:`--identity=*name*` option. -Other :command:`upload` options include :option:`--repository=*url*` -or :option:`--repository=*section*` where `url` is the url of the server -and `section` the name of the section in :file:`$HOME/.pypirc`, and +Other :command:`upload` options include :option:`--repository=` or +:option:`--repository=
` where *url* is the url of the server and +*section* the name of the section in :file:`$HOME/.pypirc`, and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). From ead198e5f880823a3cc3c3b6407ebef102b51a31 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 3 Jan 2009 20:55:06 +0000 Subject: [PATCH 044/330] Remove trailing whitespace. --- apiref.rst | 16 ++++++++-------- builtdist.rst | 24 ++++++++++++------------ configfile.rst | 2 +- packageindex.rst | 4 ++-- setupscript.rst | 2 +- 5 files changed, 24 insertions(+), 24 deletions(-) diff --git a/apiref.rst b/apiref.rst index f9222ece68..4d65de0394 100644 --- a/apiref.rst +++ b/apiref.rst @@ -104,7 +104,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *package_dir* | A mapping of package to | a dictionary | | | directory names | | +--------------------+--------------------------------+-------------------------------------------------------------+ - + .. function:: run_setup(script_name[, script_args=None, stop_after='run']) @@ -755,7 +755,7 @@ This module provides the following functions. standard output, otherwise do nothing. .. % \subsection{Compiler-specific modules} -.. % +.. % .. % The following modules implement concrete subclasses of the abstract .. % \class{CCompiler} class. They should not be instantiated directly, but should .. % be created using \function{distutils.ccompiler.new_compiler()} factory @@ -859,7 +859,7 @@ Contains :class:`MWerksCompiler`, an implementation of the abstract Macintosh. Needs work to support CW on Windows or Mac OS X. .. % \subsection{Utility modules} -.. % +.. % .. % The following modules all provide general utility functions. They haven't .. % all been documented yet. @@ -1110,13 +1110,13 @@ other utility module. For MacOS X systems the OS version reflects the minimal version on which binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` - during the build of Python), not the OS version of the current system. + during the build of Python), not the OS version of the current system. For universal binary builds on MacOS X the architecture value reflects the univeral binary status instead of the architecture of the current - processor. For 32-bit universal binaries the architecture is ``fat``, - for 64-bit universal binaries the architecture is ``fat64``, and - for 4-way universal binaries the architecture is ``universal``. + processor. For 32-bit universal binaries the architecture is ``fat``, + for 64-bit universal binaries the architecture is ``fat64``, and + for 4-way universal binaries the architecture is ``universal``. Examples of returned values on MacOS X: @@ -1693,7 +1693,7 @@ lines, and joining lines with backslashes. .. % todo .. % \section{Distutils Commands} -.. % +.. % .. % This part of Distutils implements the various Distutils commands, such .. % as \code{build}, \code{install} \&c. Each command is implemented as a .. % separate module, with the command name as the name of the module. diff --git a/builtdist.rst b/builtdist.rst index 58b62f834e..672faee34c 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -268,13 +268,13 @@ file winds up deep in the "build tree," in a temporary directory created by .. % \longprogramopt{spec-file} option; used in conjunction with .. % \longprogramopt{spec-only}, this gives you an opportunity to customize .. % the \file{.spec} file manually: -.. % +.. % .. % \ begin{verbatim} .. % > python setup.py bdist_rpm --spec-only .. % # ...edit dist/FooBar-1.0.spec .. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec .. % \ end{verbatim} -.. % +.. % .. % (Although a better way to do this is probably to override the standard .. % \command{bdist\_rpm} command with one that writes whatever else you want .. % to the \file{.spec} file.) @@ -334,31 +334,31 @@ The installer file will be written to the "distribution directory" --- normally Cross-compiling on Windows ========================== -Starting with Python 2.6, distutils is capable of cross-compiling between -Windows platforms. In practice, this means that with the correct tools +Starting with Python 2.6, distutils is capable of cross-compiling between +Windows platforms. In practice, this means that with the correct tools installed, you can use a 32bit version of Windows to create 64bit extensions and vice-versa. -To build for an alternate platform, specify the :option:`--plat-name` option -to the build command. Valid values are currently 'win32', 'win-amd64' and +To build for an alternate platform, specify the :option:`--plat-name` option +to the build command. Valid values are currently 'win32', 'win-amd64' and 'win-ia64'. For example, on a 32bit version of Windows, you could execute:: python setup.py build --plat-name=win-amd64 -to build a 64bit version of your extension. The Windows Installers also +to build a 64bit version of your extension. The Windows Installers also support this option, so the command:: python setup.py build --plat-name=win-amd64 bdist_wininst would create a 64bit installation executable on your 32bit version of Windows. -To cross-compile, you must download the Python source code and cross-compile +To cross-compile, you must download the Python source code and cross-compile Python itself for the platform you are targetting - it is not possible from a binary installtion of Python (as the .lib etc file for other platforms are -not included.) In practice, this means the user of a 32 bit operating -system will need to use Visual Studio 2008 to open the -:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the -"x64" configuration of the 'pythoncore' project before cross-compiling +not included.) In practice, this means the user of a 32 bit operating +system will need to use Visual Studio 2008 to open the +:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the +"x64" configuration of the 'pythoncore' project before cross-compiling extensions is possible. Note that by default, Visual Studio 2008 does not install 64bit compilers or diff --git a/configfile.rst b/configfile.rst index 0ccd5fd3e8..890047c08e 100644 --- a/configfile.rst +++ b/configfile.rst @@ -63,7 +63,7 @@ universal :option:`--help` option, e.g. :: --include-dirs (-I) list of directories to search for header files --define (-D) C preprocessor macros to define --undef (-U) C preprocessor macros to undefine - --swig-opts list of SWIG command line options + --swig-opts list of SWIG command line options [...] Note that an option spelled :option:`--foo-bar` on the command-line is spelled diff --git a/packageindex.rst b/packageindex.rst index ef81d6465a..3715c82480 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -72,7 +72,7 @@ If you want to define another server a new section can be created:: index-servers = pypi other - + [pypi] repository: username: @@ -91,4 +91,4 @@ Or even with the section name:: python setup.py register -r other - + diff --git a/setupscript.rst b/setupscript.rst index 7971878bba..997dab7fb3 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -213,7 +213,7 @@ This warning notwithstanding, options to SWIG can be currently passed like this:: setup(..., - ext_modules=[Extension('_foo', ['foo.i'], + ext_modules=[Extension('_foo', ['foo.i'], swig_opts=['-modern', '-I../include'])], py_modules=['foo'], ) From 393d418790e72f2714b0253eda9f86286c9d9c1e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 3 Jan 2009 21:17:04 +0000 Subject: [PATCH 045/330] Merged revisions 68219 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68219 | georg.brandl | 2009-01-03 21:47:01 +0100 (Sat, 03 Jan 2009) | 2 lines Fix uses of the default role. ........ --- uploading.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/uploading.rst b/uploading.rst index d960656515..e3aa7c3f51 100644 --- a/uploading.rst +++ b/uploading.rst @@ -33,9 +33,9 @@ uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must be available for execution on the system :envvar:`PATH`. You can also specify which key to use for signing using the :option:`--identity=*name*` option. -Other :command:`upload` options include :option:`--repository=*url*` -or :option:`--repository=*section*` where `url` is the url of the server -and `section` the name of the section in :file:`$HOME/.pypirc`, and +Other :command:`upload` options include :option:`--repository=` or +:option:`--repository=
` where *url* is the url of the server and +*section* the name of the section in :file:`$HOME/.pypirc`, and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). From 1e792c83fd243fa8af51bfb446055dc9c93d4280 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 3 Jan 2009 21:18:54 +0000 Subject: [PATCH 046/330] Remove trailing whitespace. --- apiref.rst | 16 ++++++++-------- builtdist.rst | 24 ++++++++++++------------ configfile.rst | 2 +- packageindex.rst | 4 ++-- setupscript.rst | 2 +- 5 files changed, 24 insertions(+), 24 deletions(-) diff --git a/apiref.rst b/apiref.rst index aec68c083e..868099ba5f 100644 --- a/apiref.rst +++ b/apiref.rst @@ -104,7 +104,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *package_dir* | A mapping of package to | a dictionary | | | directory names | | +--------------------+--------------------------------+-------------------------------------------------------------+ - + .. function:: run_setup(script_name[, script_args=None, stop_after='run']) @@ -754,7 +754,7 @@ This module provides the following functions. standard output, otherwise do nothing. .. % \subsection{Compiler-specific modules} -.. % +.. % .. % The following modules implement concrete subclasses of the abstract .. % \class{CCompiler} class. They should not be instantiated directly, but should .. % be created using \function{distutils.ccompiler.new_compiler()} factory @@ -858,7 +858,7 @@ Contains :class:`MWerksCompiler`, an implementation of the abstract Macintosh. Needs work to support CW on Windows or Mac OS X. .. % \subsection{Utility modules} -.. % +.. % .. % The following modules all provide general utility functions. They haven't .. % all been documented yet. @@ -1109,13 +1109,13 @@ other utility module. For MacOS X systems the OS version reflects the minimal version on which binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` - during the build of Python), not the OS version of the current system. + during the build of Python), not the OS version of the current system. For universal binary builds on MacOS X the architecture value reflects the univeral binary status instead of the architecture of the current - processor. For 32-bit universal binaries the architecture is ``fat``, - for 64-bit universal binaries the architecture is ``fat64``, and - for 4-way universal binaries the architecture is ``universal``. + processor. For 32-bit universal binaries the architecture is ``fat``, + for 64-bit universal binaries the architecture is ``fat64``, and + for 4-way universal binaries the architecture is ``universal``. Examples of returned values on MacOS X: @@ -1692,7 +1692,7 @@ lines, and joining lines with backslashes. .. % todo .. % \section{Distutils Commands} -.. % +.. % .. % This part of Distutils implements the various Distutils commands, such .. % as \code{build}, \code{install} \&c. Each command is implemented as a .. % separate module, with the command name as the name of the module. diff --git a/builtdist.rst b/builtdist.rst index 58b62f834e..672faee34c 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -268,13 +268,13 @@ file winds up deep in the "build tree," in a temporary directory created by .. % \longprogramopt{spec-file} option; used in conjunction with .. % \longprogramopt{spec-only}, this gives you an opportunity to customize .. % the \file{.spec} file manually: -.. % +.. % .. % \ begin{verbatim} .. % > python setup.py bdist_rpm --spec-only .. % # ...edit dist/FooBar-1.0.spec .. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec .. % \ end{verbatim} -.. % +.. % .. % (Although a better way to do this is probably to override the standard .. % \command{bdist\_rpm} command with one that writes whatever else you want .. % to the \file{.spec} file.) @@ -334,31 +334,31 @@ The installer file will be written to the "distribution directory" --- normally Cross-compiling on Windows ========================== -Starting with Python 2.6, distutils is capable of cross-compiling between -Windows platforms. In practice, this means that with the correct tools +Starting with Python 2.6, distutils is capable of cross-compiling between +Windows platforms. In practice, this means that with the correct tools installed, you can use a 32bit version of Windows to create 64bit extensions and vice-versa. -To build for an alternate platform, specify the :option:`--plat-name` option -to the build command. Valid values are currently 'win32', 'win-amd64' and +To build for an alternate platform, specify the :option:`--plat-name` option +to the build command. Valid values are currently 'win32', 'win-amd64' and 'win-ia64'. For example, on a 32bit version of Windows, you could execute:: python setup.py build --plat-name=win-amd64 -to build a 64bit version of your extension. The Windows Installers also +to build a 64bit version of your extension. The Windows Installers also support this option, so the command:: python setup.py build --plat-name=win-amd64 bdist_wininst would create a 64bit installation executable on your 32bit version of Windows. -To cross-compile, you must download the Python source code and cross-compile +To cross-compile, you must download the Python source code and cross-compile Python itself for the platform you are targetting - it is not possible from a binary installtion of Python (as the .lib etc file for other platforms are -not included.) In practice, this means the user of a 32 bit operating -system will need to use Visual Studio 2008 to open the -:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the -"x64" configuration of the 'pythoncore' project before cross-compiling +not included.) In practice, this means the user of a 32 bit operating +system will need to use Visual Studio 2008 to open the +:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the +"x64" configuration of the 'pythoncore' project before cross-compiling extensions is possible. Note that by default, Visual Studio 2008 does not install 64bit compilers or diff --git a/configfile.rst b/configfile.rst index 0ccd5fd3e8..890047c08e 100644 --- a/configfile.rst +++ b/configfile.rst @@ -63,7 +63,7 @@ universal :option:`--help` option, e.g. :: --include-dirs (-I) list of directories to search for header files --define (-D) C preprocessor macros to define --undef (-U) C preprocessor macros to undefine - --swig-opts list of SWIG command line options + --swig-opts list of SWIG command line options [...] Note that an option spelled :option:`--foo-bar` on the command-line is spelled diff --git a/packageindex.rst b/packageindex.rst index ef81d6465a..3715c82480 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -72,7 +72,7 @@ If you want to define another server a new section can be created:: index-servers = pypi other - + [pypi] repository: username: @@ -91,4 +91,4 @@ Or even with the section name:: python setup.py register -r other - + diff --git a/setupscript.rst b/setupscript.rst index 7a6be8b270..666b7d6274 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -213,7 +213,7 @@ This warning notwithstanding, options to SWIG can be currently passed like this:: setup(..., - ext_modules=[Extension('_foo', ['foo.i'], + ext_modules=[Extension('_foo', ['foo.i'], swig_opts=['-modern', '-I../include'])], py_modules=['foo'], ) From 345c0b3a2dad1742e1998bba043c843f5d7d3644 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 3 Jan 2009 21:55:17 +0000 Subject: [PATCH 047/330] Merged revisions 68133-68134,68141-68142,68145-68146,68148-68149,68159-68162,68166,68171-68174,68179,68195-68196,68210,68214-68215,68217-68222 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68133 | antoine.pitrou | 2009-01-01 16:38:03 +0100 (Thu, 01 Jan 2009) | 1 line fill in actual issue number in tests ........ r68134 | hirokazu.yamamoto | 2009-01-01 16:45:39 +0100 (Thu, 01 Jan 2009) | 2 lines Issue #4797: IOError.filename was not set when _fileio.FileIO failed to open file with `str' filename on Windows. ........ r68141 | benjamin.peterson | 2009-01-01 17:43:12 +0100 (Thu, 01 Jan 2009) | 1 line fix highlighting ........ r68142 | benjamin.peterson | 2009-01-01 18:29:49 +0100 (Thu, 01 Jan 2009) | 2 lines welcome to 2009, Python! ........ r68145 | amaury.forgeotdarc | 2009-01-02 01:03:54 +0100 (Fri, 02 Jan 2009) | 5 lines #4801 _collections module fails to build on cygwin. _PyObject_GC_TRACK is the macro version of PyObject_GC_Track, and according to documentation it should not be used for extension modules. ........ r68146 | ronald.oussoren | 2009-01-02 11:44:46 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue4472: "configure --enable-shared doesn't work on OSX" ........ r68148 | ronald.oussoren | 2009-01-02 11:48:31 +0100 (Fri, 02 Jan 2009) | 2 lines Forgot to add a NEWS item in my previous checkin ........ r68149 | ronald.oussoren | 2009-01-02 11:50:48 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue4780 ........ r68159 | ronald.oussoren | 2009-01-02 15:48:17 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue 1627952 ........ r68160 | ronald.oussoren | 2009-01-02 15:52:09 +0100 (Fri, 02 Jan 2009) | 2 lines Fix for issue r1737832 ........ r68161 | ronald.oussoren | 2009-01-02 16:00:05 +0100 (Fri, 02 Jan 2009) | 3 lines Fix for issue 1149804 ........ r68162 | ronald.oussoren | 2009-01-02 16:06:00 +0100 (Fri, 02 Jan 2009) | 3 lines Fix for issue 4472 is incompatible with Cygwin, this patch should fix that. ........ r68166 | benjamin.peterson | 2009-01-02 19:26:23 +0100 (Fri, 02 Jan 2009) | 1 line document PyMemberDef ........ r68171 | georg.brandl | 2009-01-02 21:25:14 +0100 (Fri, 02 Jan 2009) | 3 lines #4811: fix markup glitches (mostly remains of the conversion), found by Gabriel Genellina. ........ r68172 | martin.v.loewis | 2009-01-02 21:32:55 +0100 (Fri, 02 Jan 2009) | 2 lines Issue #4075: Use OutputDebugStringW in Py_FatalError. ........ r68173 | martin.v.loewis | 2009-01-02 21:40:14 +0100 (Fri, 02 Jan 2009) | 2 lines Issue #4051: Prevent conflict of UNICODE macros in cPickle. ........ r68174 | benjamin.peterson | 2009-01-02 21:47:27 +0100 (Fri, 02 Jan 2009) | 1 line fix compilation on non-Windows platforms ........ r68179 | raymond.hettinger | 2009-01-02 22:26:45 +0100 (Fri, 02 Jan 2009) | 1 line Issue #4615. Document how to use itertools for de-duping. ........ r68195 | georg.brandl | 2009-01-03 14:45:15 +0100 (Sat, 03 Jan 2009) | 2 lines Remove useless string literal. ........ r68196 | georg.brandl | 2009-01-03 15:29:53 +0100 (Sat, 03 Jan 2009) | 2 lines Fix indentation. ........ r68210 | georg.brandl | 2009-01-03 20:10:12 +0100 (Sat, 03 Jan 2009) | 2 lines Set eol-style correctly for mp_distributing.py. ........ r68214 | georg.brandl | 2009-01-03 20:44:48 +0100 (Sat, 03 Jan 2009) | 2 lines Make indentation consistent. ........ r68215 | georg.brandl | 2009-01-03 21:15:14 +0100 (Sat, 03 Jan 2009) | 2 lines Fix role name. ........ r68217 | georg.brandl | 2009-01-03 21:30:15 +0100 (Sat, 03 Jan 2009) | 2 lines Add rstlint, a little tool to find subtle markup problems and inconsistencies in the Doc sources. ........ r68218 | georg.brandl | 2009-01-03 21:38:59 +0100 (Sat, 03 Jan 2009) | 2 lines Recognize usage of the default role. ........ r68219 | georg.brandl | 2009-01-03 21:47:01 +0100 (Sat, 03 Jan 2009) | 2 lines Fix uses of the default role. ........ r68220 | georg.brandl | 2009-01-03 21:55:06 +0100 (Sat, 03 Jan 2009) | 2 lines Remove trailing whitespace. ........ r68221 | georg.brandl | 2009-01-03 22:04:55 +0100 (Sat, 03 Jan 2009) | 2 lines Remove tabs from the documentation. ........ r68222 | georg.brandl | 2009-01-03 22:11:58 +0100 (Sat, 03 Jan 2009) | 2 lines Disable the line length checker by default. ........ --- apiref.rst | 23 ++++++++++++----------- builtdist.rst | 24 ++++++++++++------------ configfile.rst | 2 +- packageindex.rst | 4 ++-- setupscript.rst | 2 +- uploading.rst | 6 +++--- 6 files changed, 31 insertions(+), 30 deletions(-) diff --git a/apiref.rst b/apiref.rst index 4a0d354547..4d65de0394 100644 --- a/apiref.rst +++ b/apiref.rst @@ -104,7 +104,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *package_dir* | A mapping of package to | a dictionary | | | directory names | | +--------------------+--------------------------------+-------------------------------------------------------------+ - + .. function:: run_setup(script_name[, script_args=None, stop_after='run']) @@ -188,9 +188,10 @@ the full reference. | | for C/C++ header files (in | | | | Unix form for portability) | | +------------------------+--------------------------------+---------------------------+ - | *define_macros* | list of macros to define; each | (string,string) tuple or | - | | macro is defined using a | (name,``None``) | - | | 2-tuple, where 'value' is | | + | *define_macros* | list of macros to define; each | (string, string) tuple or | + | | macro is defined using a | (name, ``None``) | + | | 2-tuple ``(name, value)``, | | + | | where *value* is | | | | either the string to define it | | | | to or ``None`` to define it | | | | without a particular value | | @@ -754,7 +755,7 @@ This module provides the following functions. standard output, otherwise do nothing. .. % \subsection{Compiler-specific modules} -.. % +.. % .. % The following modules implement concrete subclasses of the abstract .. % \class{CCompiler} class. They should not be instantiated directly, but should .. % be created using \function{distutils.ccompiler.new_compiler()} factory @@ -858,7 +859,7 @@ Contains :class:`MWerksCompiler`, an implementation of the abstract Macintosh. Needs work to support CW on Windows or Mac OS X. .. % \subsection{Utility modules} -.. % +.. % .. % The following modules all provide general utility functions. They haven't .. % all been documented yet. @@ -1109,13 +1110,13 @@ other utility module. For MacOS X systems the OS version reflects the minimal version on which binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` - during the build of Python), not the OS version of the current system. + during the build of Python), not the OS version of the current system. For universal binary builds on MacOS X the architecture value reflects the univeral binary status instead of the architecture of the current - processor. For 32-bit universal binaries the architecture is ``fat``, - for 64-bit universal binaries the architecture is ``fat64``, and - for 4-way universal binaries the architecture is ``universal``. + processor. For 32-bit universal binaries the architecture is ``fat``, + for 64-bit universal binaries the architecture is ``fat64``, and + for 4-way universal binaries the architecture is ``universal``. Examples of returned values on MacOS X: @@ -1692,7 +1693,7 @@ lines, and joining lines with backslashes. .. % todo .. % \section{Distutils Commands} -.. % +.. % .. % This part of Distutils implements the various Distutils commands, such .. % as \code{build}, \code{install} \&c. Each command is implemented as a .. % separate module, with the command name as the name of the module. diff --git a/builtdist.rst b/builtdist.rst index 58b62f834e..672faee34c 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -268,13 +268,13 @@ file winds up deep in the "build tree," in a temporary directory created by .. % \longprogramopt{spec-file} option; used in conjunction with .. % \longprogramopt{spec-only}, this gives you an opportunity to customize .. % the \file{.spec} file manually: -.. % +.. % .. % \ begin{verbatim} .. % > python setup.py bdist_rpm --spec-only .. % # ...edit dist/FooBar-1.0.spec .. % > python setup.py bdist_rpm --spec-file=dist/FooBar-1.0.spec .. % \ end{verbatim} -.. % +.. % .. % (Although a better way to do this is probably to override the standard .. % \command{bdist\_rpm} command with one that writes whatever else you want .. % to the \file{.spec} file.) @@ -334,31 +334,31 @@ The installer file will be written to the "distribution directory" --- normally Cross-compiling on Windows ========================== -Starting with Python 2.6, distutils is capable of cross-compiling between -Windows platforms. In practice, this means that with the correct tools +Starting with Python 2.6, distutils is capable of cross-compiling between +Windows platforms. In practice, this means that with the correct tools installed, you can use a 32bit version of Windows to create 64bit extensions and vice-versa. -To build for an alternate platform, specify the :option:`--plat-name` option -to the build command. Valid values are currently 'win32', 'win-amd64' and +To build for an alternate platform, specify the :option:`--plat-name` option +to the build command. Valid values are currently 'win32', 'win-amd64' and 'win-ia64'. For example, on a 32bit version of Windows, you could execute:: python setup.py build --plat-name=win-amd64 -to build a 64bit version of your extension. The Windows Installers also +to build a 64bit version of your extension. The Windows Installers also support this option, so the command:: python setup.py build --plat-name=win-amd64 bdist_wininst would create a 64bit installation executable on your 32bit version of Windows. -To cross-compile, you must download the Python source code and cross-compile +To cross-compile, you must download the Python source code and cross-compile Python itself for the platform you are targetting - it is not possible from a binary installtion of Python (as the .lib etc file for other platforms are -not included.) In practice, this means the user of a 32 bit operating -system will need to use Visual Studio 2008 to open the -:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the -"x64" configuration of the 'pythoncore' project before cross-compiling +not included.) In practice, this means the user of a 32 bit operating +system will need to use Visual Studio 2008 to open the +:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the +"x64" configuration of the 'pythoncore' project before cross-compiling extensions is possible. Note that by default, Visual Studio 2008 does not install 64bit compilers or diff --git a/configfile.rst b/configfile.rst index 0ccd5fd3e8..890047c08e 100644 --- a/configfile.rst +++ b/configfile.rst @@ -63,7 +63,7 @@ universal :option:`--help` option, e.g. :: --include-dirs (-I) list of directories to search for header files --define (-D) C preprocessor macros to define --undef (-U) C preprocessor macros to undefine - --swig-opts list of SWIG command line options + --swig-opts list of SWIG command line options [...] Note that an option spelled :option:`--foo-bar` on the command-line is spelled diff --git a/packageindex.rst b/packageindex.rst index ef81d6465a..3715c82480 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -72,7 +72,7 @@ If you want to define another server a new section can be created:: index-servers = pypi other - + [pypi] repository: username: @@ -91,4 +91,4 @@ Or even with the section name:: python setup.py register -r other - + diff --git a/setupscript.rst b/setupscript.rst index 7971878bba..997dab7fb3 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -213,7 +213,7 @@ This warning notwithstanding, options to SWIG can be currently passed like this:: setup(..., - ext_modules=[Extension('_foo', ['foo.i'], + ext_modules=[Extension('_foo', ['foo.i'], swig_opts=['-modern', '-I../include'])], py_modules=['foo'], ) diff --git a/uploading.rst b/uploading.rst index 52d6d5b7c7..66f712b758 100644 --- a/uploading.rst +++ b/uploading.rst @@ -35,9 +35,9 @@ uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must be available for execution on the system :envvar:`PATH`. You can also specify which key to use for signing using the :option:`--identity=*name*` option. -Other :command:`upload` options include :option:`--repository=*url*` -or :option:`--repository=*section*` where `url` is the url of the server -and `section` the name of the section in :file:`$HOME/.pypirc`, and +Other :command:`upload` options include :option:`--repository=` or +:option:`--repository=
` where *url* is the url of the server and +*section* the name of the section in :file:`$HOME/.pypirc`, and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). From 66095fdd97f8751184f4ad8ff08346d84386ca63 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 3 Jan 2009 22:47:39 +0000 Subject: [PATCH 048/330] Merged revisions 68162,68166,68171,68176,68195-68196,68210,68232 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68162 | ronald.oussoren | 2009-01-02 16:06:00 +0100 (Fri, 02 Jan 2009) | 3 lines Fix for issue 4472 is incompatible with Cygwin, this patch should fix that. ........ r68166 | benjamin.peterson | 2009-01-02 19:26:23 +0100 (Fri, 02 Jan 2009) | 1 line document PyMemberDef ........ r68171 | georg.brandl | 2009-01-02 21:25:14 +0100 (Fri, 02 Jan 2009) | 3 lines #4811: fix markup glitches (mostly remains of the conversion), found by Gabriel Genellina. ........ r68176 | andrew.kuchling | 2009-01-02 22:00:35 +0100 (Fri, 02 Jan 2009) | 1 line Add various items ........ r68195 | georg.brandl | 2009-01-03 14:45:15 +0100 (Sat, 03 Jan 2009) | 2 lines Remove useless string literal. ........ r68196 | georg.brandl | 2009-01-03 15:29:53 +0100 (Sat, 03 Jan 2009) | 2 lines Fix indentation. ........ r68210 | georg.brandl | 2009-01-03 20:10:12 +0100 (Sat, 03 Jan 2009) | 2 lines Set eol-style correctly for mp_distributing.py. ........ r68232 | georg.brandl | 2009-01-03 22:52:16 +0100 (Sat, 03 Jan 2009) | 2 lines Grammar fix. ........ --- apiref.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 868099ba5f..612993414d 100644 --- a/apiref.rst +++ b/apiref.rst @@ -188,9 +188,10 @@ the full reference. | | for C/C++ header files (in | | | | Unix form for portability) | | +------------------------+--------------------------------+---------------------------+ - | *define_macros* | list of macros to define; each | (string,string) tuple or | - | | macro is defined using a | (name,``None``) | - | | 2-tuple, where 'value' is | | + | *define_macros* | list of macros to define; each | (string, string) tuple or | + | | macro is defined using a | (name, ``None``) | + | | 2-tuple ``(name, value)``, | | + | | where *value* is | | | | either the string to define it | | | | to or ``None`` to define it | | | | without a particular value | | From ac02ae87fa5adaf775baab8e4eb5d6a42684a858 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Thu, 8 Jan 2009 23:56:31 +0000 Subject: [PATCH 049/330] fixed #4394 make the storage of the password optional in .pypirc --- packageindex.rst | 76 +++++++++++++++++++++++++++--------------------- uploading.rst | 10 ++++--- 2 files changed, 49 insertions(+), 37 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index 3715c82480..c4cbf88616 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -8,17 +8,17 @@ The Python Package Index (PyPI) holds meta-data describing distributions packaged with distutils. The distutils command :command:`register` is used to submit your distribution's meta-data to the index. It is invoked as follows:: - python setup.py register + python setup.py register Distutils will respond with the following prompt:: - running register - We need to know who you are, so please choose either: - 1. use your existing login, - 2. register as a new user, - 3. have the server generate a new password for you (and email it to you), or - 4. quit - Your selection [default 1]: + running register + We need to know who you are, so please choose either: + 1. use your existing login, + 2. register as a new user, + 3. have the server generate a new password for you (and email it to you), or + 4. quit + Your selection [default 1]: Note: if your username and password are saved locally, you will not see this menu. @@ -55,40 +55,50 @@ The .pypirc file The format of the :file:`.pypirc` file is as follows:: - [distutils] - index-servers = - pypi + [distutils] + index-servers = + pypi - [pypi] - repository: - username: - password: + [pypi] + repository: + username: + password: -*repository* can be omitted and defaults to ``http://www.python.org/pypi``. +The *distutils* section defines a *index-servers* variable that lists the +name of all sections describing a repository. -If you want to define another server a new section can be created:: +Each section describing a repository defines three variables: - [distutils] - index-servers = - pypi - other +- *repository*, that defines the url of the PyPI server. Defaults to + ``http://www.python.org/pypi``. +- *username*, which is the registered username on the PyPI server. +- *password*, that will be used to authenticate. If omitted the user + will be prompt to type it when needed. - [pypi] - repository: - username: - password: +If you want to define another server a new section can be created and +listed in the *index-servers* variable:: - [other] - repository: http://example.com/pypi - username: - password: + [distutils] + index-servers = + pypi + other -The command can then be called with the -r option:: + [pypi] + repository: + username: + password: - python setup.py register -r http://example.com/pypi + [other] + repository: http://example.com/pypi + username: + password: -Or even with the section name:: +:command:`register` can then be called with the -r option to point the +repository to work with:: - python setup.py register -r other + python setup.py register -r http://example.com/pypi +The name of the section that describes the repository may also be used +for conveniency:: + python setup.py register -r other diff --git a/uploading.rst b/uploading.rst index 66f712b758..71b3ca1e14 100644 --- a/uploading.rst +++ b/uploading.rst @@ -13,7 +13,7 @@ package data if the author of the package wishes to. The distutils command The command is invoked immediately after building one or more distribution files. For example, the command :: - python setup.py sdist bdist_wininst upload + python setup.py sdist bdist_wininst upload will cause the source distribution and the Windows installer to be uploaded to PyPI. Note that these will be uploaded even if they are built using an earlier @@ -22,11 +22,14 @@ line for the invocation including the :command:`upload` command are uploaded. The :command:`upload` command uses the username, password, and repository URL from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this -file). +file). If a :command:`register` command was previously called in the same command, +and if the password was entered in the prompt, :command:`upload` will reuse the +entered password. This is useful if you do not want to store a clear text +password in the :file:`$HOME/.pypirc` file. You can specify another PyPI server with the :option:`--repository=*url*` option:: - python setup.py sdist bdist_wininst upload -r http://example.com/pypi + python setup.py sdist bdist_wininst upload -r http://example.com/pypi See section :ref:`pypirc` for more on defining several servers. @@ -40,4 +43,3 @@ Other :command:`upload` options include :option:`--repository=` or *section* the name of the section in :file:`$HOME/.pypirc`, and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). - From 0743bbb5a4e9a8e7972878026ccb104cf667be50 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Fri, 9 Jan 2009 00:15:45 +0000 Subject: [PATCH 050/330] Merged revisions 68415 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68415 | tarek.ziade | 2009-01-09 00:56:31 +0100 (Fri, 09 Jan 2009) | 1 line fixed #4394 make the storage of the password optional in .pypirc ........ --- packageindex.rst | 76 +++++++++++++++++++++++++++--------------------- uploading.rst | 10 ++++--- 2 files changed, 49 insertions(+), 37 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index 3715c82480..c4cbf88616 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -8,17 +8,17 @@ The Python Package Index (PyPI) holds meta-data describing distributions packaged with distutils. The distutils command :command:`register` is used to submit your distribution's meta-data to the index. It is invoked as follows:: - python setup.py register + python setup.py register Distutils will respond with the following prompt:: - running register - We need to know who you are, so please choose either: - 1. use your existing login, - 2. register as a new user, - 3. have the server generate a new password for you (and email it to you), or - 4. quit - Your selection [default 1]: + running register + We need to know who you are, so please choose either: + 1. use your existing login, + 2. register as a new user, + 3. have the server generate a new password for you (and email it to you), or + 4. quit + Your selection [default 1]: Note: if your username and password are saved locally, you will not see this menu. @@ -55,40 +55,50 @@ The .pypirc file The format of the :file:`.pypirc` file is as follows:: - [distutils] - index-servers = - pypi + [distutils] + index-servers = + pypi - [pypi] - repository: - username: - password: + [pypi] + repository: + username: + password: -*repository* can be omitted and defaults to ``http://www.python.org/pypi``. +The *distutils* section defines a *index-servers* variable that lists the +name of all sections describing a repository. -If you want to define another server a new section can be created:: +Each section describing a repository defines three variables: - [distutils] - index-servers = - pypi - other +- *repository*, that defines the url of the PyPI server. Defaults to + ``http://www.python.org/pypi``. +- *username*, which is the registered username on the PyPI server. +- *password*, that will be used to authenticate. If omitted the user + will be prompt to type it when needed. - [pypi] - repository: - username: - password: +If you want to define another server a new section can be created and +listed in the *index-servers* variable:: - [other] - repository: http://example.com/pypi - username: - password: + [distutils] + index-servers = + pypi + other -The command can then be called with the -r option:: + [pypi] + repository: + username: + password: - python setup.py register -r http://example.com/pypi + [other] + repository: http://example.com/pypi + username: + password: -Or even with the section name:: +:command:`register` can then be called with the -r option to point the +repository to work with:: - python setup.py register -r other + python setup.py register -r http://example.com/pypi +The name of the section that describes the repository may also be used +for conveniency:: + python setup.py register -r other diff --git a/uploading.rst b/uploading.rst index e3aa7c3f51..36e7b8f325 100644 --- a/uploading.rst +++ b/uploading.rst @@ -11,7 +11,7 @@ package data if the author of the package wishes to. The distutils command The command is invoked immediately after building one or more distribution files. For example, the command :: - python setup.py sdist bdist_wininst upload + python setup.py sdist bdist_wininst upload will cause the source distribution and the Windows installer to be uploaded to PyPI. Note that these will be uploaded even if they are built using an earlier @@ -20,11 +20,14 @@ line for the invocation including the :command:`upload` command are uploaded. The :command:`upload` command uses the username, password, and repository URL from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this -file). +file). If a :command:`register` command was previously called in the same command, +and if the password was entered in the prompt, :command:`upload` will reuse the +entered password. This is useful if you do not want to store a clear text +password in the :file:`$HOME/.pypirc` file. You can specify another PyPI server with the :option:`--repository=*url*` option:: - python setup.py sdist bdist_wininst upload -r http://example.com/pypi + python setup.py sdist bdist_wininst upload -r http://example.com/pypi See section :ref:`pypirc` for more on defining several servers. @@ -38,4 +41,3 @@ Other :command:`upload` options include :option:`--repository=` or *section* the name of the section in :file:`$HOME/.pypirc`, and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). - From 64961aed4336dd4b4ff2b818e057d74a0634346d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 25 Jan 2009 19:29:10 +0000 Subject: [PATCH 051/330] Issue #4863, removing remaining bits --- apiref.rst | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/apiref.rst b/apiref.rst index 4d65de0394..b53c94a5d7 100644 --- a/apiref.rst +++ b/apiref.rst @@ -847,23 +847,6 @@ This module provides the EMXCCompiler class, a subclass of :class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2. -:mod:`distutils.mwerkscompiler` --- Metrowerks CodeWarrior support -================================================================== - -.. module:: distutils.mwerkscompiler - :synopsis: Metrowerks CodeWarrior support - - -Contains :class:`MWerksCompiler`, an implementation of the abstract -:class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X -Macintosh. Needs work to support CW on Windows or Mac OS X. - -.. % \subsection{Utility modules} -.. % -.. % The following modules all provide general utility functions. They haven't -.. % all been documented yet. - - :mod:`distutils.archive_util` --- Archiving utilities ====================================================== From 3f18b2ea9ee98d45c3bd50ea660d624f3b554321 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 25 Jan 2009 19:31:22 +0000 Subject: [PATCH 052/330] Merged revisions 68933 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r68933 | tarek.ziade | 2009-01-25 20:29:10 +0100 (Sun, 25 Jan 2009) | 1 line Issue #4863, removing remaining bits ........ --- apiref.rst | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/apiref.rst b/apiref.rst index 612993414d..9b075483a0 100644 --- a/apiref.rst +++ b/apiref.rst @@ -847,23 +847,6 @@ This module provides the EMXCCompiler class, a subclass of :class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2. -:mod:`distutils.mwerkscompiler` --- Metrowerks CodeWarrior support -================================================================== - -.. module:: distutils.mwerkscompiler - :synopsis: Metrowerks CodeWarrior support - - -Contains :class:`MWerksCompiler`, an implementation of the abstract -:class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X -Macintosh. Needs work to support CW on Windows or Mac OS X. - -.. % \subsection{Utility modules} -.. % -.. % The following modules all provide general utility functions. They haven't -.. % all been documented yet. - - :mod:`distutils.archive_util` --- Archiving utilities ====================================================== From 69885802eeeb40237e170df3a0f8134529a0307d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Fri, 13 Feb 2009 09:12:33 +0000 Subject: [PATCH 053/330] #5158: added documentation on the depends option in distutils extensions --- setupscript.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 997dab7fb3..9308288e13 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -347,6 +347,10 @@ symbols (functions or variables) to be exported. This option is not needed when building compiled extensions: Distutils will automatically add ``initmodule`` to the list of exported symbols. +The :option:`depends` option is a list of files that the extension depends on +(for example header files). The build command will call the compiler on the +sources to rebuild extension if any on this files has been modified since the +previous build. Relationships between Distributions and Packages ================================================ From 5ce707a778ac8945305341210744df3134900d78 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Fri, 13 Feb 2009 09:15:20 +0000 Subject: [PATCH 054/330] Merged revisions 69566 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r69566 | tarek.ziade | 2009-02-13 10:12:33 +0100 (Fri, 13 Feb 2009) | 1 line #5158: added documentation on the depends option in distutils extensions ........ --- setupscript.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 666b7d6274..9ae2e4d244 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -347,6 +347,10 @@ symbols (functions or variables) to be exported. This option is not needed when building compiled extensions: Distutils will automatically add ``initmodule`` to the list of exported symbols. +The :option:`depends` option is a list of files that the extension depends on +(for example header files). The build command will call the compiler on the +sources to rebuild extension if any on this files has been modified since the +previous build. Relationships between Distributions and Packages ================================================ From 500d759ad1a7ee24a9bfa8eb938826487739ea07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Mon, 16 Feb 2009 21:38:01 +0000 Subject: [PATCH 055/330] Fixed #2279: distutils.sdist.add_defaults now add files listed in package_data and data_files --- setupscript.rst | 18 ++++++++++++++++++ sourcedist.rst | 12 ++++++++++++ 2 files changed, 30 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 9308288e13..81790315af 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -427,6 +427,7 @@ The versions identified by the qualifiers are those that are obsoleted by the distribution being described. If no qualifiers are given, all versions of the named module or package are understood to be obsoleted. +.. _distutils-installing-scripts: Installing Scripts ================== @@ -449,6 +450,12 @@ way. From the PyXML setup script:: scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] ) +All the scripts will also be added to the ``MANIFEST`` +file if no template is provided. See :ref:`manifest`. + +.. versionadded:: 2.7 + +.. _distutils-installing-package-data: Installing Package Data ======================= @@ -492,6 +499,12 @@ The corresponding call to :func:`setup` might be:: .. versionadded:: 2.4 +All the files that match ``package_data`` will be added to the ``MANIFEST`` +file if no template is provided. See :ref:`manifest`. + +.. versionadded:: 2.7 + +.. _distutils-additional-files: Installing Additional Files =========================== @@ -527,6 +540,11 @@ without specifying a target directory, but this is not recommended, and the files directly in the target directory, an empty string should be given as the directory. +All the files that match ``data_files`` will be added to the ``MANIFEST`` +file if no template is provided. See :ref:`manifest`. + +.. versionadded:: 2.7 + .. _meta-data: diff --git a/sourcedist.rst b/sourcedist.rst index 960cc0ae4d..5c0e5d0423 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -74,6 +74,7 @@ source distribution: :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) * scripts identified by the :option:`scripts` option + See :ref:`distutils-installing-scripts`. * anything that looks like a test script: :file:`test/test\*.py` (currently, the Distutils don't do anything with test scripts except include them in source @@ -83,6 +84,17 @@ source distribution: * :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever you called your setup script), and :file:`setup.cfg` +* all files that matches the ``package_data`` metadata. + See :ref:`distutils-installing-package-data`. + + .. versionadded:: 2.7 + +* all files that matches the ``data_files`` metadata. + See :ref:`distutils-additional-files`. + + .. versionadded:: 2.7 + + Sometimes this is enough, but usually you will want to specify additional files to distribute. The typical way to do this is to write a *manifest template*, called :file:`MANIFEST.in` by default. The manifest template is just a list of From 7671a8bceaa3b3de537cf3efb48eeee7eb593a68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Mon, 16 Feb 2009 21:49:12 +0000 Subject: [PATCH 056/330] Merged revisions 69692 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r69692 | tarek.ziade | 2009-02-16 22:38:01 +0100 (Mon, 16 Feb 2009) | 1 line Fixed #2279: distutils.sdist.add_defaults now add files listed in package_data and data_files ........ --- setupscript.rst | 19 +++++++++++++++++++ sourcedist.rst | 12 ++++++++++++ 2 files changed, 31 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 9ae2e4d244..6fed2fabbc 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -427,6 +427,7 @@ The versions identified by the qualifiers are those that are obsoleted by the distribution being described. If no qualifiers are given, all versions of the named module or package are understood to be obsoleted. +.. _distutils-installing-scripts: Installing Scripts ================== @@ -449,6 +450,12 @@ way. From the PyXML setup script:: scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] ) +All the scripts will also be added to the ``MANIFEST`` +file if no template is provided. See :ref:`manifest`. + +.. versionadded:: 2.7 + +.. _distutils-installing-package-data: Installing Package Data ======================= @@ -491,6 +498,13 @@ The corresponding call to :func:`setup` might be:: ) +All the files that match ``package_data`` will be added to the ``MANIFEST`` +file if no template is provided. See :ref:`manifest`. + +.. versionadded:: 2.7 + +.. _distutils-additional-files: + Installing Additional Files =========================== @@ -525,6 +539,11 @@ without specifying a target directory, but this is not recommended, and the files directly in the target directory, an empty string should be given as the directory. +All the files that match ``data_files`` will be added to the ``MANIFEST`` +file if no template is provided. See :ref:`manifest`. + +.. versionadded:: 2.7 + .. _meta-data: diff --git a/sourcedist.rst b/sourcedist.rst index 960cc0ae4d..5c0e5d0423 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -74,6 +74,7 @@ source distribution: :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) * scripts identified by the :option:`scripts` option + See :ref:`distutils-installing-scripts`. * anything that looks like a test script: :file:`test/test\*.py` (currently, the Distutils don't do anything with test scripts except include them in source @@ -83,6 +84,17 @@ source distribution: * :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever you called your setup script), and :file:`setup.cfg` +* all files that matches the ``package_data`` metadata. + See :ref:`distutils-installing-package-data`. + + .. versionadded:: 2.7 + +* all files that matches the ``data_files`` metadata. + See :ref:`distutils-additional-files`. + + .. versionadded:: 2.7 + + Sometimes this is enough, but usually you will want to specify additional files to distribute. The typical way to do this is to write a *manifest template*, called :file:`MANIFEST.in` by default. The manifest template is just a list of From c2200ee9ee7d65563df0ef3802c6635dce17d909 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 22 Feb 2009 00:07:45 +0000 Subject: [PATCH 057/330] using versionchanged instead of versionadded for distutils doc on sdist default files --- setupscript.rst | 19 +++++++++---------- sourcedist.rst | 5 ----- 2 files changed, 9 insertions(+), 15 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 81790315af..d575b8b860 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -450,10 +450,9 @@ way. From the PyXML setup script:: scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] ) -All the scripts will also be added to the ``MANIFEST`` -file if no template is provided. See :ref:`manifest`. - -.. versionadded:: 2.7 +.. versionchanged:: 2.7 + All the scripts will also be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. .. _distutils-installing-package-data: @@ -499,10 +498,10 @@ The corresponding call to :func:`setup` might be:: .. versionadded:: 2.4 -All the files that match ``package_data`` will be added to the ``MANIFEST`` -file if no template is provided. See :ref:`manifest`. +.. versionchanged:: 2.7 + All the files that match ``package_data`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. -.. versionadded:: 2.7 .. _distutils-additional-files: @@ -540,10 +539,10 @@ without specifying a target directory, but this is not recommended, and the files directly in the target directory, an empty string should be given as the directory. -All the files that match ``data_files`` will be added to the ``MANIFEST`` -file if no template is provided. See :ref:`manifest`. +.. versionchanged:: 2.7 + All the files that match ``data_files`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. -.. versionadded:: 2.7 .. _meta-data: diff --git a/sourcedist.rst b/sourcedist.rst index 5c0e5d0423..0c786c5a0a 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -87,14 +87,9 @@ source distribution: * all files that matches the ``package_data`` metadata. See :ref:`distutils-installing-package-data`. - .. versionadded:: 2.7 - * all files that matches the ``data_files`` metadata. See :ref:`distutils-additional-files`. - .. versionadded:: 2.7 - - Sometimes this is enough, but usually you will want to specify additional files to distribute. The typical way to do this is to write a *manifest template*, called :file:`MANIFEST.in` by default. The manifest template is just a list of From 01cabe5261e19aa1ef275adef262711a8676e8c3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 22 Feb 2009 00:10:58 +0000 Subject: [PATCH 058/330] Merged revisions 69861 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r69861 | tarek.ziade | 2009-02-22 01:07:45 +0100 (Sun, 22 Feb 2009) | 1 line using versionchanged instead of versionadded for distutils doc on sdist default files ........ --- setupscript.rst | 19 +++++++++---------- sourcedist.rst | 5 ----- 2 files changed, 9 insertions(+), 15 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 6fed2fabbc..97ac5be540 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -450,10 +450,9 @@ way. From the PyXML setup script:: scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] ) -All the scripts will also be added to the ``MANIFEST`` -file if no template is provided. See :ref:`manifest`. - -.. versionadded:: 2.7 +.. versionchanged:: 2.7 + All the scripts will also be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. .. _distutils-installing-package-data: @@ -498,10 +497,10 @@ The corresponding call to :func:`setup` might be:: ) -All the files that match ``package_data`` will be added to the ``MANIFEST`` -file if no template is provided. See :ref:`manifest`. +.. versionchanged:: 2.7 + All the files that match ``package_data`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. -.. versionadded:: 2.7 .. _distutils-additional-files: @@ -539,10 +538,10 @@ without specifying a target directory, but this is not recommended, and the files directly in the target directory, an empty string should be given as the directory. -All the files that match ``data_files`` will be added to the ``MANIFEST`` -file if no template is provided. See :ref:`manifest`. +.. versionchanged:: 2.7 + All the files that match ``data_files`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. -.. versionadded:: 2.7 .. _meta-data: diff --git a/sourcedist.rst b/sourcedist.rst index 5c0e5d0423..0c786c5a0a 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -87,14 +87,9 @@ source distribution: * all files that matches the ``package_data`` metadata. See :ref:`distutils-installing-package-data`. - .. versionadded:: 2.7 - * all files that matches the ``data_files`` metadata. See :ref:`distutils-additional-files`. - .. versionadded:: 2.7 - - Sometimes this is enough, but usually you will want to specify additional files to distribute. The typical way to do this is to write a *manifest template*, called :file:`MANIFEST.in` by default. The manifest template is just a list of From e7f0f3f33b6d9c8b1a57240b0c90fed7421b375c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Fri, 27 Feb 2009 02:14:35 +0000 Subject: [PATCH 059/330] more info on long_description --- setupscript.rst | 254 ++++++++++++++++++++++++------------------------ uploading.rst | 29 ++++++ 2 files changed, 157 insertions(+), 126 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index d575b8b860..efdc51abe3 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -19,18 +19,18 @@ existence so that Python 1.5.2 users can use them to install other module distributions. The Distutils' own setup script, shown here, is used to install the package into Python 1.5.2.) :: - #!/usr/bin/env python + #!/usr/bin/env python - from distutils.core import setup + from distutils.core import setup - setup(name='Distutils', - version='1.0', - description='Python Distribution Utilities', - author='Greg Ward', - author_email='gward@python.net', - url='http://www.python.org/sigs/distutils-sig/', - packages=['distutils', 'distutils.command'], - ) + setup(name='Distutils', + version='1.0', + description='Python Distribution Utilities', + author='Greg Ward', + author_email='gward@python.net', + url='http://www.python.org/sigs/distutils-sig/', + packages=['distutils', 'distutils.command'], + ) There are only two differences between this and the trivial one-file distribution presented in section :ref:`distutils-simple-example`: more metadata, and the @@ -53,8 +53,8 @@ you, for example, use standard Python functions such as :func:`glob.glob` or :func:`os.listdir` to specify files, you should be careful to write portable code instead of hardcoding path separators:: - glob.glob(os.path.join('mydir', 'subdir', '*.html')) - os.listdir(os.path.join('mydir', 'subdir')) + glob.glob(os.path.join('mydir', 'subdir', '*.html')) + os.listdir(os.path.join('mydir', 'subdir')) .. _listing-packages: @@ -81,7 +81,7 @@ under :file:`lib`, so that modules in the "root package" (i.e., not in any package at all) are in :file:`lib`, modules in the :mod:`foo` package are in :file:`lib/foo`, and so forth. Then you would put :: - package_dir = {'': 'lib'} + package_dir = {'': 'lib'} in your setup script. The keys to this dictionary are package names, and an empty package name stands for the root package. The values are directory names @@ -92,7 +92,7 @@ Another possible convention is to put the :mod:`foo` package right in :file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be written in the setup script as :: - package_dir = {'foo': 'lib'} + package_dir = {'foo': 'lib'} A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly applies to all packages below *package*, so the :mod:`foo.bar` case is @@ -114,7 +114,7 @@ than listing packages---especially the case of a single module that goes in the "root package" (i.e., no package at all). This simplest case was shown in section :ref:`distutils-simple-example`; here is a slightly more involved example:: - py_modules = ['mod1', 'pkg.mod2'] + py_modules = ['mod1', 'pkg.mod2'] This describes two modules, one of them in the "root" package, the other in the :mod:`pkg` package. Again, the default package/directory layout implies that @@ -144,17 +144,17 @@ Suppose your distribution includes a single extension, called :mod:`foo` and implemented by :file:`foo.c`. If no additional instructions to the compiler/linker are needed, describing this extension is quite simple:: - Extension('foo', ['foo.c']) + Extension('foo', ['foo.c']) The :class:`Extension` class can be imported from :mod:`distutils.core` along with :func:`setup`. Thus, the setup script for a module distribution that contains only this one extension and nothing else might be:: - from distutils.core import setup, Extension - setup(name='foo', - version='1.0', - ext_modules=[Extension('foo', ['foo.c'])], - ) + from distutils.core import setup, Extension + setup(name='foo', + version='1.0', + ext_modules=[Extension('foo', ['foo.c'])], + ) The :class:`Extension` class (actually, the underlying extension-building machinery implemented by the :command:`build_ext` command) supports a great deal @@ -168,11 +168,11 @@ Extension names and packages The first argument to the :class:`Extension` constructor is always the name of the extension, including any package names. For example, :: - Extension('foo', ['src/foo1.c', 'src/foo2.c']) + Extension('foo', ['src/foo1.c', 'src/foo2.c']) describes an extension that lives in the root package, while :: - Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) + Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) describes the same extension in the :mod:`pkg` package. The source files and resulting object code are identical in both cases; the only difference is where @@ -183,11 +183,11 @@ If you have a number of extensions all in the same package (or all under the same base package), use the :option:`ext_package` keyword argument to :func:`setup`. For example, :: - setup(..., - ext_package='pkg', - ext_modules=[Extension('foo', ['foo.c']), - Extension('subpkg.bar', ['bar.c'])], - ) + setup(..., + ext_package='pkg', + ext_modules=[Extension('foo', ['foo.c']), + Extension('subpkg.bar', ['bar.c'])], + ) will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to :mod:`pkg.subpkg.bar`. @@ -212,15 +212,15 @@ extension. This warning notwithstanding, options to SWIG can be currently passed like this:: - setup(..., - ext_modules=[Extension('_foo', ['foo.i'], - swig_opts=['-modern', '-I../include'])], - py_modules=['foo'], - ) + setup(..., + ext_modules=[Extension('_foo', ['foo.i'], + swig_opts=['-modern', '-I../include'])], + py_modules=['foo'], + ) Or on the commandline like this:: - > python setup.py build_ext --swig-opts="-modern -I../include" + > python setup.py build_ext --swig-opts="-modern -I../include" On some platforms, you can include non-source files that are processed by the compiler and included in your extension. Currently, this just means Windows @@ -239,18 +239,18 @@ include directories to search or preprocessor macros to define/undefine: For example, if your extension requires header files in the :file:`include` directory under your distribution root, use the ``include_dirs`` option:: - Extension('foo', ['foo.c'], include_dirs=['include']) + Extension('foo', ['foo.c'], include_dirs=['include']) You can specify absolute directories there; if you know that your extension will only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get away with :: - Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11']) + Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11']) You should avoid this sort of non-portable usage if you plan to distribute your code: it's probably better to write C code like :: - #include + #include If you need to include header files from some other Python extension, you can take advantage of the fact that header files are installed in a consistent way @@ -262,17 +262,17 @@ directory---\ :file:`/usr/local/include/python1.5` in this case---is always included in the search path when building Python extensions, the best approach is to write C code like :: - #include + #include If you must put the :file:`Numerical` include directory right into your header search path, though, you can find that directory using the Distutils :mod:`distutils.sysconfig` module:: - from distutils.sysconfig import get_python_inc - incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical') - setup(..., - Extension(..., include_dirs=[incdir]), - ) + from distutils.sysconfig import get_python_inc + incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical') + setup(..., + Extension(..., include_dirs=[incdir]), + ) Even though this is quite portable---it will work on any Python installation, regardless of platform---it's probably easier to just write your C code in the @@ -288,17 +288,17 @@ just a list of macros to undefine. For example:: - Extension(..., - define_macros=[('NDEBUG', '1'), - ('HAVE_STRFTIME', None)], - undef_macros=['HAVE_FOO', 'HAVE_BAR']) + Extension(..., + define_macros=[('NDEBUG', '1'), + ('HAVE_STRFTIME', None)], + undef_macros=['HAVE_FOO', 'HAVE_BAR']) is the equivalent of having this at the top of every C source file:: - #define NDEBUG 1 - #define HAVE_STRFTIME - #undef HAVE_FOO - #undef HAVE_BAR + #define NDEBUG 1 + #define HAVE_STRFTIME + #undef HAVE_FOO + #undef HAVE_BAR Library options @@ -313,15 +313,15 @@ directories to search for shared (dynamically loaded) libraries at run-time. For example, if you need to link against libraries known to be in the standard library search path on target systems :: - Extension(..., - libraries=['gdbm', 'readline']) + Extension(..., + libraries=['gdbm', 'readline']) If you need to link with libraries in a non-standard location, you'll have to include the location in ``library_dirs``:: - Extension(..., - library_dirs=['/usr/X11R6/lib'], - libraries=['X11', 'Xt']) + Extension(..., + library_dirs=['/usr/X11R6/lib'], + libraries=['X11', 'Xt']) (Again, this sort of non-portable construct should be avoided if you intend to distribute your code.) @@ -379,8 +379,8 @@ If specific versions are required, a sequence of qualifiers can be supplied in parentheses. Each qualifier may consist of a comparison operator and a version number. The accepted comparison operators are:: - < > == - <= >= != + < > == + <= >= != These can be combined by using multiple qualifiers separated by commas (and optional whitespace). In this case, all of the qualifiers must be matched; a @@ -446,13 +446,13 @@ option will allow the interpreter path to be explicitly overridden. The :option:`scripts` option simply is a list of files to be handled in this way. From the PyXML setup script:: - setup(..., - scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] - ) + setup(..., + scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] + ) .. versionchanged:: 2.7 - All the scripts will also be added to the ``MANIFEST`` - file if no template is provided. See :ref:`manifest`. + All the scripts will also be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. .. _distutils-installing-package-data: @@ -478,29 +478,29 @@ created in the installation. For example, if a package should contain a subdirectory with several data files, the files can be arranged like this in the source tree:: - setup.py - src/ - mypkg/ - __init__.py - module.py - data/ - tables.dat - spoons.dat - forks.dat + setup.py + src/ + mypkg/ + __init__.py + module.py + data/ + tables.dat + spoons.dat + forks.dat The corresponding call to :func:`setup` might be:: - setup(..., - packages=['mypkg'], - package_dir={'mypkg': 'src/mypkg'}, - package_data={'mypkg': ['data/*.dat']}, - ) + setup(..., + packages=['mypkg'], + package_dir={'mypkg': 'src/mypkg'}, + package_data={'mypkg': ['data/*.dat']}, + ) .. versionadded:: 2.4 .. versionchanged:: 2.7 - All the files that match ``package_data`` will be added to the ``MANIFEST`` - file if no template is provided. See :ref:`manifest`. + All the files that match ``package_data`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. .. _distutils-additional-files: @@ -515,11 +515,11 @@ anything which doesn't fit in the previous categories. :option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the following way:: - setup(..., - data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), - ('config', ['cfg/data.cfg']), - ('/etc/init.d', ['init-script'])] - ) + setup(..., + data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), + ('config', ['cfg/data.cfg']), + ('/etc/init.d', ['init-script'])] + ) Note that you can specify the directory names where the data files will be installed, but you cannot rename the data files themselves. @@ -540,8 +540,8 @@ files directly in the target directory, an empty string should be given as the directory. .. versionchanged:: 2.7 - All the files that match ``data_files`` will be added to the ``MANIFEST`` - file if no template is provided. See :ref:`manifest`. + All the files that match ``data_files`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. @@ -576,7 +576,7 @@ This information includes: | | description of the | | | | | package | | | +----------------------+---------------------------+-----------------+--------+ -| ``long_description`` | longer description of the | long string | | +| ``long_description`` | longer description of the | long string | \(5) | | | package | | | +----------------------+---------------------------+-----------------+--------+ | ``download_url`` | location where the | URL | \(4) | @@ -590,28 +590,32 @@ This information includes: Notes: (1) - These fields are required. + These fields are required. (2) - It is recommended that versions take the form *major.minor[.patch[.sub]]*. + It is recommended that versions take the form *major.minor[.patch[.sub]]*. (3) - Either the author or the maintainer must be identified. + Either the author or the maintainer must be identified. (4) - These fields should not be used if your package is to be compatible with Python - versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website - `_. + These fields should not be used if your package is to be compatible with Python + versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website + `_. + +(5) + The ``long_description`` field is used by PyPI when you are registering a + package, to build its home page. 'short string' - A single line of text, not more than 200 characters. + A single line of text, not more than 200 characters. 'long string' - Multiple lines of plain text in reStructuredText format (see - http://docutils.sf.net/). + Multiple lines of plain text in reStructuredText format (see + http://docutils.sf.net/). 'list of strings' - See below. + See below. None of the string values may be Unicode. @@ -627,44 +631,44 @@ information is sometimes used to indicate sub-releases. These are (for final pre-release release testing). Some examples: 0.1.0 - the first, experimental release of a package + the first, experimental release of a package 1.0.1a2 - the second alpha release of the first patch version of 1.0 + the second alpha release of the first patch version of 1.0 :option:`classifiers` are specified in a python list:: - setup(..., - classifiers=[ - 'Development Status :: 4 - Beta', - 'Environment :: Console', - 'Environment :: Web Environment', - 'Intended Audience :: End Users/Desktop', - 'Intended Audience :: Developers', - 'Intended Audience :: System Administrators', - 'License :: OSI Approved :: Python Software Foundation License', - 'Operating System :: MacOS :: MacOS X', - 'Operating System :: Microsoft :: Windows', - 'Operating System :: POSIX', - 'Programming Language :: Python', - 'Topic :: Communications :: Email', - 'Topic :: Office/Business', - 'Topic :: Software Development :: Bug Tracking', - ], - ) + setup(..., + classifiers=[ + 'Development Status :: 4 - Beta', + 'Environment :: Console', + 'Environment :: Web Environment', + 'Intended Audience :: End Users/Desktop', + 'Intended Audience :: Developers', + 'Intended Audience :: System Administrators', + 'License :: OSI Approved :: Python Software Foundation License', + 'Operating System :: MacOS :: MacOS X', + 'Operating System :: Microsoft :: Windows', + 'Operating System :: POSIX', + 'Programming Language :: Python', + 'Topic :: Communications :: Email', + 'Topic :: Office/Business', + 'Topic :: Software Development :: Bug Tracking', + ], + ) If you wish to include classifiers in your :file:`setup.py` file and also wish to remain backwards-compatible with Python releases prior to 2.2.3, then you can include the following code fragment in your :file:`setup.py` before the :func:`setup` call. :: - # patch distutils if it can't cope with the "classifiers" or - # "download_url" keywords - from sys import version - if version < '2.2.3': - from distutils.dist import DistributionMetadata - DistributionMetadata.classifiers = None - DistributionMetadata.download_url = None + # patch distutils if it can't cope with the "classifiers" or + # "download_url" keywords + from sys import version + if version < '2.2.3': + from distutils.dist import DistributionMetadata + DistributionMetadata.classifiers = None + DistributionMetadata.download_url = None Debugging the setup script @@ -686,5 +690,3 @@ failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set to anything except an empty string, and distutils will now print detailed information what it is doing, and prints the full traceback in case an exception occurs. - - diff --git a/uploading.rst b/uploading.rst index 71b3ca1e14..84388c2124 100644 --- a/uploading.rst +++ b/uploading.rst @@ -43,3 +43,32 @@ Other :command:`upload` options include :option:`--repository=` or *section* the name of the section in :file:`$HOME/.pypirc`, and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). + +PyPI package display +==================== + +The ``long_description`` field plays a special role at PyPI. It is used by +the server to display a home page for the registered package. + +If you use the `reStructuredText `_ +syntax for this field, PyPI will parse it and display an HTML output for +the package home page. + +The ``long_description`` field can be attached to a text file located +in the package:: + + from distutils.core import setup + + setup(name='Distutils', + long_description=open('README.txt')) + +In that case, `README.txt` is a regular reStructuredText text file located +in the root of the package besides `setup.py`. + +To prevent registering broken reStructuredText content, you can use the +:program:`rst2html` program that is provided by the `docutils` package +and check the ``long_description`` from the command line:: + + $ python setup.py --long-description | rst2html.py > output.html + +`docutils` will display a warning if there's something wrong with your syntax. From 9278ebb08f08784ac2f4a503ba150e26a0eab944 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Fri, 27 Feb 2009 02:22:25 +0000 Subject: [PATCH 060/330] Merged revisions 70007 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r70007 | tarek.ziade | 2009-02-27 03:14:35 +0100 (Fri, 27 Feb 2009) | 1 line more info on long_description ........ --- setupscript.rst | 254 ++++++++++++++++++++++++------------------------ uploading.rst | 29 ++++++ 2 files changed, 157 insertions(+), 126 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 97ac5be540..2e5d8c17a7 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -19,18 +19,18 @@ existence so that Python 1.5.2 users can use them to install other module distributions. The Distutils' own setup script, shown here, is used to install the package into Python 1.5.2.) :: - #!/usr/bin/env python + #!/usr/bin/env python - from distutils.core import setup + from distutils.core import setup - setup(name='Distutils', - version='1.0', - description='Python Distribution Utilities', - author='Greg Ward', - author_email='gward@python.net', - url='http://www.python.org/sigs/distutils-sig/', - packages=['distutils', 'distutils.command'], - ) + setup(name='Distutils', + version='1.0', + description='Python Distribution Utilities', + author='Greg Ward', + author_email='gward@python.net', + url='http://www.python.org/sigs/distutils-sig/', + packages=['distutils', 'distutils.command'], + ) There are only two differences between this and the trivial one-file distribution presented in section :ref:`distutils-simple-example`: more metadata, and the @@ -53,8 +53,8 @@ you, for example, use standard Python functions such as :func:`glob.glob` or :func:`os.listdir` to specify files, you should be careful to write portable code instead of hardcoding path separators:: - glob.glob(os.path.join('mydir', 'subdir', '*.html')) - os.listdir(os.path.join('mydir', 'subdir')) + glob.glob(os.path.join('mydir', 'subdir', '*.html')) + os.listdir(os.path.join('mydir', 'subdir')) .. _listing-packages: @@ -81,7 +81,7 @@ under :file:`lib`, so that modules in the "root package" (i.e., not in any package at all) are in :file:`lib`, modules in the :mod:`foo` package are in :file:`lib/foo`, and so forth. Then you would put :: - package_dir = {'': 'lib'} + package_dir = {'': 'lib'} in your setup script. The keys to this dictionary are package names, and an empty package name stands for the root package. The values are directory names @@ -92,7 +92,7 @@ Another possible convention is to put the :mod:`foo` package right in :file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be written in the setup script as :: - package_dir = {'foo': 'lib'} + package_dir = {'foo': 'lib'} A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly applies to all packages below *package*, so the :mod:`foo.bar` case is @@ -114,7 +114,7 @@ than listing packages---especially the case of a single module that goes in the "root package" (i.e., no package at all). This simplest case was shown in section :ref:`distutils-simple-example`; here is a slightly more involved example:: - py_modules = ['mod1', 'pkg.mod2'] + py_modules = ['mod1', 'pkg.mod2'] This describes two modules, one of them in the "root" package, the other in the :mod:`pkg` package. Again, the default package/directory layout implies that @@ -144,17 +144,17 @@ Suppose your distribution includes a single extension, called :mod:`foo` and implemented by :file:`foo.c`. If no additional instructions to the compiler/linker are needed, describing this extension is quite simple:: - Extension('foo', ['foo.c']) + Extension('foo', ['foo.c']) The :class:`Extension` class can be imported from :mod:`distutils.core` along with :func:`setup`. Thus, the setup script for a module distribution that contains only this one extension and nothing else might be:: - from distutils.core import setup, Extension - setup(name='foo', - version='1.0', - ext_modules=[Extension('foo', ['foo.c'])], - ) + from distutils.core import setup, Extension + setup(name='foo', + version='1.0', + ext_modules=[Extension('foo', ['foo.c'])], + ) The :class:`Extension` class (actually, the underlying extension-building machinery implemented by the :command:`build_ext` command) supports a great deal @@ -168,11 +168,11 @@ Extension names and packages The first argument to the :class:`Extension` constructor is always the name of the extension, including any package names. For example, :: - Extension('foo', ['src/foo1.c', 'src/foo2.c']) + Extension('foo', ['src/foo1.c', 'src/foo2.c']) describes an extension that lives in the root package, while :: - Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) + Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) describes the same extension in the :mod:`pkg` package. The source files and resulting object code are identical in both cases; the only difference is where @@ -183,11 +183,11 @@ If you have a number of extensions all in the same package (or all under the same base package), use the :option:`ext_package` keyword argument to :func:`setup`. For example, :: - setup(..., - ext_package='pkg', - ext_modules=[Extension('foo', ['foo.c']), - Extension('subpkg.bar', ['bar.c'])], - ) + setup(..., + ext_package='pkg', + ext_modules=[Extension('foo', ['foo.c']), + Extension('subpkg.bar', ['bar.c'])], + ) will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to :mod:`pkg.subpkg.bar`. @@ -212,15 +212,15 @@ extension. This warning notwithstanding, options to SWIG can be currently passed like this:: - setup(..., - ext_modules=[Extension('_foo', ['foo.i'], - swig_opts=['-modern', '-I../include'])], - py_modules=['foo'], - ) + setup(..., + ext_modules=[Extension('_foo', ['foo.i'], + swig_opts=['-modern', '-I../include'])], + py_modules=['foo'], + ) Or on the commandline like this:: - > python setup.py build_ext --swig-opts="-modern -I../include" + > python setup.py build_ext --swig-opts="-modern -I../include" On some platforms, you can include non-source files that are processed by the compiler and included in your extension. Currently, this just means Windows @@ -239,18 +239,18 @@ include directories to search or preprocessor macros to define/undefine: For example, if your extension requires header files in the :file:`include` directory under your distribution root, use the ``include_dirs`` option:: - Extension('foo', ['foo.c'], include_dirs=['include']) + Extension('foo', ['foo.c'], include_dirs=['include']) You can specify absolute directories there; if you know that your extension will only be built on Unix systems with X11R6 installed to :file:`/usr`, you can get away with :: - Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11']) + Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11']) You should avoid this sort of non-portable usage if you plan to distribute your code: it's probably better to write C code like :: - #include + #include If you need to include header files from some other Python extension, you can take advantage of the fact that header files are installed in a consistent way @@ -262,17 +262,17 @@ directory---\ :file:`/usr/local/include/python1.5` in this case---is always included in the search path when building Python extensions, the best approach is to write C code like :: - #include + #include If you must put the :file:`Numerical` include directory right into your header search path, though, you can find that directory using the Distutils :mod:`distutils.sysconfig` module:: - from distutils.sysconfig import get_python_inc - incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical') - setup(..., - Extension(..., include_dirs=[incdir]), - ) + from distutils.sysconfig import get_python_inc + incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical') + setup(..., + Extension(..., include_dirs=[incdir]), + ) Even though this is quite portable---it will work on any Python installation, regardless of platform---it's probably easier to just write your C code in the @@ -288,17 +288,17 @@ just a list of macros to undefine. For example:: - Extension(..., - define_macros=[('NDEBUG', '1'), - ('HAVE_STRFTIME', None)], - undef_macros=['HAVE_FOO', 'HAVE_BAR']) + Extension(..., + define_macros=[('NDEBUG', '1'), + ('HAVE_STRFTIME', None)], + undef_macros=['HAVE_FOO', 'HAVE_BAR']) is the equivalent of having this at the top of every C source file:: - #define NDEBUG 1 - #define HAVE_STRFTIME - #undef HAVE_FOO - #undef HAVE_BAR + #define NDEBUG 1 + #define HAVE_STRFTIME + #undef HAVE_FOO + #undef HAVE_BAR Library options @@ -313,15 +313,15 @@ directories to search for shared (dynamically loaded) libraries at run-time. For example, if you need to link against libraries known to be in the standard library search path on target systems :: - Extension(..., - libraries=['_gdbm', 'readline']) + Extension(..., + libraries=['gdbm', 'readline']) If you need to link with libraries in a non-standard location, you'll have to include the location in ``library_dirs``:: - Extension(..., - library_dirs=['/usr/X11R6/lib'], - libraries=['X11', 'Xt']) + Extension(..., + library_dirs=['/usr/X11R6/lib'], + libraries=['X11', 'Xt']) (Again, this sort of non-portable construct should be avoided if you intend to distribute your code.) @@ -379,8 +379,8 @@ If specific versions are required, a sequence of qualifiers can be supplied in parentheses. Each qualifier may consist of a comparison operator and a version number. The accepted comparison operators are:: - < > == - <= >= != + < > == + <= >= != These can be combined by using multiple qualifiers separated by commas (and optional whitespace). In this case, all of the qualifiers must be matched; a @@ -446,13 +446,13 @@ option will allow the interpreter path to be explicitly overridden. The :option:`scripts` option simply is a list of files to be handled in this way. From the PyXML setup script:: - setup(..., - scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] - ) + setup(..., + scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] + ) .. versionchanged:: 2.7 - All the scripts will also be added to the ``MANIFEST`` - file if no template is provided. See :ref:`manifest`. + All the scripts will also be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. .. _distutils-installing-package-data: @@ -478,28 +478,28 @@ created in the installation. For example, if a package should contain a subdirectory with several data files, the files can be arranged like this in the source tree:: - setup.py - src/ - mypkg/ - __init__.py - module.py - data/ - tables.dat - spoons.dat - forks.dat + setup.py + src/ + mypkg/ + __init__.py + module.py + data/ + tables.dat + spoons.dat + forks.dat The corresponding call to :func:`setup` might be:: - setup(..., - packages=['mypkg'], - package_dir={'mypkg': 'src/mypkg'}, - package_data={'mypkg': ['data/*.dat']}, - ) + setup(..., + packages=['mypkg'], + package_dir={'mypkg': 'src/mypkg'}, + package_data={'mypkg': ['data/*.dat']}, + ) .. versionchanged:: 2.7 - All the files that match ``package_data`` will be added to the ``MANIFEST`` - file if no template is provided. See :ref:`manifest`. + All the files that match ``package_data`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. .. _distutils-additional-files: @@ -514,11 +514,11 @@ anything which doesn't fit in the previous categories. :option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the following way:: - setup(..., - data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), - ('config', ['cfg/data.cfg']), - ('/etc/init.d', ['init-script'])] - ) + setup(..., + data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), + ('config', ['cfg/data.cfg']), + ('/etc/init.d', ['init-script'])] + ) Note that you can specify the directory names where the data files will be installed, but you cannot rename the data files themselves. @@ -539,8 +539,8 @@ files directly in the target directory, an empty string should be given as the directory. .. versionchanged:: 2.7 - All the files that match ``data_files`` will be added to the ``MANIFEST`` - file if no template is provided. See :ref:`manifest`. + All the files that match ``data_files`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. @@ -575,7 +575,7 @@ This information includes: | | description of the | | | | | package | | | +----------------------+---------------------------+-----------------+--------+ -| ``long_description`` | longer description of the | long string | | +| ``long_description`` | longer description of the | long string | \(5) | | | package | | | +----------------------+---------------------------+-----------------+--------+ | ``download_url`` | location where the | URL | \(4) | @@ -589,28 +589,32 @@ This information includes: Notes: (1) - These fields are required. + These fields are required. (2) - It is recommended that versions take the form *major.minor[.patch[.sub]]*. + It is recommended that versions take the form *major.minor[.patch[.sub]]*. (3) - Either the author or the maintainer must be identified. + Either the author or the maintainer must be identified. (4) - These fields should not be used if your package is to be compatible with Python - versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website - `_. + These fields should not be used if your package is to be compatible with Python + versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website + `_. + +(5) + The ``long_description`` field is used by PyPI when you are registering a + package, to build its home page. 'short string' - A single line of text, not more than 200 characters. + A single line of text, not more than 200 characters. 'long string' - Multiple lines of plain text in reStructuredText format (see - http://docutils.sf.net/). + Multiple lines of plain text in reStructuredText format (see + http://docutils.sf.net/). 'list of strings' - See below. + See below. Encoding the version information is an art in itself. Python packages generally adhere to the version format *major.minor[.patch][sub]*. The major number is 0 @@ -624,44 +628,44 @@ information is sometimes used to indicate sub-releases. These are (for final pre-release release testing). Some examples: 0.1.0 - the first, experimental release of a package + the first, experimental release of a package 1.0.1a2 - the second alpha release of the first patch version of 1.0 + the second alpha release of the first patch version of 1.0 :option:`classifiers` are specified in a python list:: - setup(..., - classifiers=[ - 'Development Status :: 4 - Beta', - 'Environment :: Console', - 'Environment :: Web Environment', - 'Intended Audience :: End Users/Desktop', - 'Intended Audience :: Developers', - 'Intended Audience :: System Administrators', - 'License :: OSI Approved :: Python Software Foundation License', - 'Operating System :: MacOS :: MacOS X', - 'Operating System :: Microsoft :: Windows', - 'Operating System :: POSIX', - 'Programming Language :: Python', - 'Topic :: Communications :: Email', - 'Topic :: Office/Business', - 'Topic :: Software Development :: Bug Tracking', - ], - ) + setup(..., + classifiers=[ + 'Development Status :: 4 - Beta', + 'Environment :: Console', + 'Environment :: Web Environment', + 'Intended Audience :: End Users/Desktop', + 'Intended Audience :: Developers', + 'Intended Audience :: System Administrators', + 'License :: OSI Approved :: Python Software Foundation License', + 'Operating System :: MacOS :: MacOS X', + 'Operating System :: Microsoft :: Windows', + 'Operating System :: POSIX', + 'Programming Language :: Python', + 'Topic :: Communications :: Email', + 'Topic :: Office/Business', + 'Topic :: Software Development :: Bug Tracking', + ], + ) If you wish to include classifiers in your :file:`setup.py` file and also wish to remain backwards-compatible with Python releases prior to 2.2.3, then you can include the following code fragment in your :file:`setup.py` before the :func:`setup` call. :: - # patch distutils if it can't cope with the "classifiers" or - # "download_url" keywords - from sys import version - if version < '2.2.3': - from distutils.dist import DistributionMetadata - DistributionMetadata.classifiers = None - DistributionMetadata.download_url = None + # patch distutils if it can't cope with the "classifiers" or + # "download_url" keywords + from sys import version + if version < '2.2.3': + from distutils.dist import DistributionMetadata + DistributionMetadata.classifiers = None + DistributionMetadata.download_url = None Debugging the setup script @@ -683,5 +687,3 @@ failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set to anything except an empty string, and distutils will now print detailed information what it is doing, and prints the full traceback in case an exception occurs. - - diff --git a/uploading.rst b/uploading.rst index 36e7b8f325..e9472453d3 100644 --- a/uploading.rst +++ b/uploading.rst @@ -41,3 +41,32 @@ Other :command:`upload` options include :option:`--repository=` or *section* the name of the section in :file:`$HOME/.pypirc`, and :option:`--show-response` (which displays the full response text from the PyPI server for help in debugging upload problems). + +PyPI package display +==================== + +The ``long_description`` field plays a special role at PyPI. It is used by +the server to display a home page for the registered package. + +If you use the `reStructuredText `_ +syntax for this field, PyPI will parse it and display an HTML output for +the package home page. + +The ``long_description`` field can be attached to a text file located +in the package:: + + from distutils.core import setup + + setup(name='Distutils', + long_description=open('README.txt')) + +In that case, `README.txt` is a regular reStructuredText text file located +in the root of the package besides `setup.py`. + +To prevent registering broken reStructuredText content, you can use the +:program:`rst2html` program that is provided by the `docutils` package +and check the ``long_description`` from the command line:: + + $ python setup.py --long-description | rst2html.py > output.html + +`docutils` will display a warning if there's something wrong with your syntax. From c6e6e6ecd03571581e0f22639f4ca82bfd725f43 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 13 Mar 2009 19:03:58 +0000 Subject: [PATCH 061/330] #5486: typos. --- packageindex.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index c4cbf88616..1498394481 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -98,7 +98,7 @@ repository to work with:: python setup.py register -r http://example.com/pypi -The name of the section that describes the repository may also be used -for conveniency:: +For convenience, the name of the section that describes the repository +may also be used:: python setup.py register -r other From 00f4691e7d10576b694609654b6cef50385d4f2b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 13 Mar 2009 19:04:40 +0000 Subject: [PATCH 062/330] #5486: typos. --- packageindex.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index c4cbf88616..1498394481 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -98,7 +98,7 @@ repository to work with:: python setup.py register -r http://example.com/pypi -The name of the section that describes the repository may also be used -for conveniency:: +For convenience, the name of the section that describes the repository +may also be used:: python setup.py register -r other From c9817606fd8a19a66bab22aa2aa1178f4867b237 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 28 Mar 2009 19:57:36 +0000 Subject: [PATCH 063/330] Add section numbering to some of the larger subdocuments. --- index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/index.rst b/index.rst index 6d82c847bb..ace8280894 100644 --- a/index.rst +++ b/index.rst @@ -16,6 +16,7 @@ very little overhead for build/release/install mechanics. .. toctree:: :maxdepth: 2 + :numbered: introduction.rst setupscript.rst From 483ef30c5d11c996012bb21d917316ce6aaea968 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Mon, 30 Mar 2009 14:51:56 +0000 Subject: [PATCH 064/330] Merged revisions 70578,70599,70641-70642,70650,70660-70661,70674,70691,70697-70698,70700,70704 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r70578 | benjamin.peterson | 2009-03-23 22:24:56 -0500 (Mon, 23 Mar 2009) | 1 line this is better written using assertRaises ........ r70599 | benjamin.peterson | 2009-03-25 16:42:51 -0500 (Wed, 25 Mar 2009) | 1 line this can be slightly less ugly ........ r70641 | guilherme.polo | 2009-03-27 16:43:08 -0500 (Fri, 27 Mar 2009) | 3 lines Adjusted _tkinter to compile without warnings when WITH_THREAD is not defined (part of issue #5035) ........ r70642 | georg.brandl | 2009-03-27 19:48:48 -0500 (Fri, 27 Mar 2009) | 1 line Fix typo. ........ r70650 | benjamin.peterson | 2009-03-28 14:16:10 -0500 (Sat, 28 Mar 2009) | 1 line give os.symlink and os.link() better parameter names #5564 ........ r70660 | georg.brandl | 2009-03-28 14:52:58 -0500 (Sat, 28 Mar 2009) | 1 line Switch to fixed Sphinx version. ........ r70661 | georg.brandl | 2009-03-28 14:57:36 -0500 (Sat, 28 Mar 2009) | 2 lines Add section numbering to some of the larger subdocuments. ........ r70674 | guilherme.polo | 2009-03-29 05:19:05 -0500 (Sun, 29 Mar 2009) | 1 line Typo fix. ........ r70691 | raymond.hettinger | 2009-03-29 13:51:11 -0500 (Sun, 29 Mar 2009) | 1 line Make life easier for non-CPython implementations. ........ r70697 | benjamin.peterson | 2009-03-29 16:22:35 -0500 (Sun, 29 Mar 2009) | 1 line this has been fixed since 2.6 (I love removing these) ........ r70698 | benjamin.peterson | 2009-03-29 16:31:05 -0500 (Sun, 29 Mar 2009) | 1 line thanks to guido's bytecode verifier, this is fixed ........ r70700 | benjamin.peterson | 2009-03-29 16:50:14 -0500 (Sun, 29 Mar 2009) | 1 line use the awesome new status iterator ........ r70704 | benjamin.peterson | 2009-03-29 21:49:32 -0500 (Sun, 29 Mar 2009) | 1 line there's actually three methods here #5600 ........ --- index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/index.rst b/index.rst index 6d82c847bb..ace8280894 100644 --- a/index.rst +++ b/index.rst @@ -16,6 +16,7 @@ very little overhead for build/release/install mechanics. .. toctree:: :maxdepth: 2 + :numbered: introduction.rst setupscript.rst From 614a2aa6f089b3dd0a79d89313699746648e71f1 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 31 Mar 2009 22:03:40 +0000 Subject: [PATCH 065/330] #5563: more documentation for bdist_msi. --- apiref.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index b53c94a5d7..e3608fbb6d 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1758,8 +1758,16 @@ This module supplies the abstract base class :class:`Command`. .. module:: distutils.command.bdist_msi :synopsis: Build a binary distribution as a Windows MSI file +.. class:: bdist_msi(Command) -.. % todo + Builds a `Windows Installer`_ (.msi) binary package. + + .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx + + In most cases, the ``bdist_msi`` installer is a better choice than the + ``bdist_wininst`` installer, because it provides better support for + Win64 platforms, allows administrators to perform non-interactive + installations, and allows installation through group policies. :mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM From bca3aaf020992b64f8e98a00f5d10a94686a9e6f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Tue, 31 Mar 2009 22:27:23 +0000 Subject: [PATCH 066/330] #5583 Added optional Extensions in Distutils --- setupscript.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index efdc51abe3..61f57aa37b 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -334,6 +334,10 @@ Other options There are still some other options which can be used to handle special cases. +The :option:`optional` option is a boolean; if it is true, that specifies that +a build failure in the extension should not abort the build process, but simply +not install the failing extension. + The :option:`extra_objects` option is a list of object files to be passed to the linker. These files must not have extensions, as the default extension for the compiler is used. From 3e7f1f464cef0b81fff0f380e47538449e2f18b0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Tue, 31 Mar 2009 22:37:55 +0000 Subject: [PATCH 067/330] Merged revisions 70910 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r70910 | tarek.ziade | 2009-03-31 17:27:23 -0500 (Tue, 31 Mar 2009) | 1 line #5583 Added optional Extensions in Distutils ........ --- setupscript.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 2e5d8c17a7..85089d092d 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -334,6 +334,10 @@ Other options There are still some other options which can be used to handle special cases. +The :option:`optional` option is a boolean; if it is true, that specifies that +a build failure in the extension should not abort the build process, but simply +not install the failing extension. + The :option:`extra_objects` option is a list of object files to be passed to the linker. These files must not have extensions, as the default extension for the compiler is used. From bcfa48fe639ebac1869ba19fdcca85096faca3b6 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 5 Apr 2009 10:29:57 +0000 Subject: [PATCH 068/330] Normalize spelling of Mac OS X. --- apiref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index e3608fbb6d..a3b464afec 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1091,17 +1091,17 @@ other utility module. For non-POSIX platforms, currently just returns ``sys.platform``. - For MacOS X systems the OS version reflects the minimal version on which + For Mac OS X systems the OS version reflects the minimal version on which binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` during the build of Python), not the OS version of the current system. - For universal binary builds on MacOS X the architecture value reflects + For universal binary builds on Mac OS X the architecture value reflects the univeral binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is ``fat``, for 64-bit universal binaries the architecture is ``fat64``, and for 4-way universal binaries the architecture is ``universal``. - Examples of returned values on MacOS X: + Examples of returned values on Mac OS X: * ``macosx-10.3-ppc`` From b6454ff406757e3cc8d4c74ab9a7f478fe59d336 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 5 Apr 2009 10:32:26 +0000 Subject: [PATCH 069/330] Avoid sure signs of a diseased mind. --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index a3b464afec..4ee9fcc81c 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1050,8 +1050,8 @@ This module contains some utility functions for operating on individual files. .. warning:: - Handles cross-device moves on Unix using :func:`copy_file`. What about other - systems??? + Handles cross-device moves on Unix using :func:`copy_file`. What about + other systems? .. function:: write_file(filename, contents) From 826f6ceacecb5929468b236fe49e5ab5f9687b54 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sun, 5 Apr 2009 19:13:16 +0000 Subject: [PATCH 070/330] Merged revisions 70712,70714,70764-70765,70769-70771,70773,70776-70777,70788-70789,70824,70828,70832,70836,70842,70851,70855,70857,70866-70872,70883,70885,70893-70894,70896-70897,70903,70905-70907,70915,70927,70933,70951,70960,70962-70964,70998,71001,71006,71008,71010-71011,71019,71037,71056,71094,71101-71103,71106,71119,71123,71149-71150,71203,71212,71214-71217,71221,71240 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r70712 | benjamin.peterson | 2009-03-30 10:15:38 -0500 (Mon, 30 Mar 2009) | 1 line don't rely on the order dict repr #5605 ........ r70714 | brett.cannon | 2009-03-30 10:20:53 -0500 (Mon, 30 Mar 2009) | 1 line Add an entry to developers.txt. ........ r70764 | martin.v.loewis | 2009-03-30 17:06:33 -0500 (Mon, 30 Mar 2009) | 2 lines Add several VM developers. ........ r70765 | georg.brandl | 2009-03-30 17:09:34 -0500 (Mon, 30 Mar 2009) | 1 line #5199: make warning about vars() assignment more visible. ........ r70769 | andrew.kuchling | 2009-03-30 17:29:53 -0500 (Mon, 30 Mar 2009) | 1 line Remove comment ........ r70770 | andrew.kuchling | 2009-03-30 17:30:20 -0500 (Mon, 30 Mar 2009) | 1 line Add several items and placeholders ........ r70771 | andrew.kuchling | 2009-03-30 17:31:11 -0500 (Mon, 30 Mar 2009) | 1 line Many edits ........ r70773 | georg.brandl | 2009-03-30 17:43:00 -0500 (Mon, 30 Mar 2009) | 1 line #5039: make it clear that the impl. note refers to CPython. ........ r70776 | andrew.kuchling | 2009-03-30 18:08:24 -0500 (Mon, 30 Mar 2009) | 1 line typo fix ........ r70777 | andrew.kuchling | 2009-03-30 18:09:46 -0500 (Mon, 30 Mar 2009) | 1 line Add more items ........ r70788 | andrew.kuchling | 2009-03-30 20:21:01 -0500 (Mon, 30 Mar 2009) | 1 line Add various items ........ r70789 | georg.brandl | 2009-03-30 20:25:15 -0500 (Mon, 30 Mar 2009) | 1 line Fix a wrong struct field assignment (docstring as closure). ........ r70824 | georg.brandl | 2009-03-31 10:43:20 -0500 (Tue, 31 Mar 2009) | 1 line #5519: remove reference to Kodos, which seems dead. ........ r70828 | georg.brandl | 2009-03-31 10:50:16 -0500 (Tue, 31 Mar 2009) | 1 line #5581: fget argument of abstractproperty is optional as well. ........ r70832 | georg.brandl | 2009-03-31 11:31:11 -0500 (Tue, 31 Mar 2009) | 1 line #1386675: specify WindowsError as the exception, because it has a winerror attribute that EnvironmentError doesnt have. ........ r70836 | georg.brandl | 2009-03-31 11:50:25 -0500 (Tue, 31 Mar 2009) | 1 line #5417: replace references to undocumented functions by ones to documented functions. ........ r70842 | georg.brandl | 2009-03-31 12:13:06 -0500 (Tue, 31 Mar 2009) | 1 line #970783: document PyObject_Generic[GS]etAttr. ........ r70851 | georg.brandl | 2009-03-31 13:26:55 -0500 (Tue, 31 Mar 2009) | 1 line #837577: note cryptic return value of spawn*e on invalid env dicts. ........ r70855 | georg.brandl | 2009-03-31 13:30:37 -0500 (Tue, 31 Mar 2009) | 1 line #5245: note that PyRun_SimpleString doesnt return on SystemExit. ........ r70857 | georg.brandl | 2009-03-31 13:33:10 -0500 (Tue, 31 Mar 2009) | 1 line #5227: note that Py_Main doesnt return on SystemExit. ........ r70866 | georg.brandl | 2009-03-31 14:06:57 -0500 (Tue, 31 Mar 2009) | 1 line #4882: document named group behavior a bit better. ........ r70867 | georg.brandl | 2009-03-31 14:10:35 -0500 (Tue, 31 Mar 2009) | 1 line #1096310: document usage of sys.__std*__ a bit better. ........ r70868 | georg.brandl | 2009-03-31 14:12:17 -0500 (Tue, 31 Mar 2009) | 1 line #5190: export make_option in __all__. ........ r70869 | georg.brandl | 2009-03-31 14:14:42 -0500 (Tue, 31 Mar 2009) | 1 line Fix-up unwanted change. ........ r70870 | georg.brandl | 2009-03-31 14:26:24 -0500 (Tue, 31 Mar 2009) | 1 line #4411: document mro() and __mro__. (I hope I got it right.) ........ r70871 | georg.brandl | 2009-03-31 14:30:56 -0500 (Tue, 31 Mar 2009) | 1 line #5618: fix typo. ........ r70872 | r.david.murray | 2009-03-31 14:31:17 -0500 (Tue, 31 Mar 2009) | 3 lines Delete out-of-date and little-known README from the test directory by consensus of devs at pycon sprint. ........ r70883 | georg.brandl | 2009-03-31 15:41:08 -0500 (Tue, 31 Mar 2009) | 1 line #1674032: return value of flag from Event.wait(). OKed by Guido. ........ r70885 | tarek.ziade | 2009-03-31 15:48:31 -0500 (Tue, 31 Mar 2009) | 1 line using log.warn for sys.stderr ........ r70893 | georg.brandl | 2009-03-31 15:56:32 -0500 (Tue, 31 Mar 2009) | 1 line #1530012: move TQS section before raw strings. ........ r70894 | benjamin.peterson | 2009-03-31 16:06:30 -0500 (Tue, 31 Mar 2009) | 1 line take the usual lock precautions around _active_limbo_lock ........ r70896 | georg.brandl | 2009-03-31 16:15:33 -0500 (Tue, 31 Mar 2009) | 1 line #5598: document DocFileSuite *args argument. ........ r70897 | benjamin.peterson | 2009-03-31 16:34:42 -0500 (Tue, 31 Mar 2009) | 1 line fix Thread.ident when it is the main thread or a dummy thread #5632 ........ r70903 | georg.brandl | 2009-03-31 16:45:18 -0500 (Tue, 31 Mar 2009) | 1 line #1676135: remove trailing slashes from --prefix argument. ........ r70905 | georg.brandl | 2009-03-31 17:03:40 -0500 (Tue, 31 Mar 2009) | 1 line #5563: more documentation for bdist_msi. ........ r70906 | georg.brandl | 2009-03-31 17:11:53 -0500 (Tue, 31 Mar 2009) | 1 line #1651995: fix _convert_ref for non-ASCII characters. ........ r70907 | georg.brandl | 2009-03-31 17:18:19 -0500 (Tue, 31 Mar 2009) | 1 line #3427: document correct return type for urlopen().info(). ........ r70915 | georg.brandl | 2009-03-31 17:40:16 -0500 (Tue, 31 Mar 2009) | 1 line #5018: remove confusing paragraph. ........ r70927 | georg.brandl | 2009-03-31 18:01:27 -0500 (Tue, 31 Mar 2009) | 1 line Dont shout to users. ........ r70933 | georg.brandl | 2009-03-31 19:04:33 -0500 (Tue, 31 Mar 2009) | 2 lines Issue #5635: Fix running test_sys with tracing enabled. ........ r70951 | georg.brandl | 2009-04-01 09:02:27 -0500 (Wed, 01 Apr 2009) | 1 line Add Maksim, who worked on several issues at the sprint. ........ r70960 | jesse.noller | 2009-04-01 11:42:19 -0500 (Wed, 01 Apr 2009) | 1 line Issue 3270: document Listener address restrictions on windows ........ r70962 | brett.cannon | 2009-04-01 12:07:16 -0500 (Wed, 01 Apr 2009) | 2 lines Ron DuPlain was given commit privileges at PyCon 2009 to work on 3to2. ........ r70963 | georg.brandl | 2009-04-01 12:46:01 -0500 (Wed, 01 Apr 2009) | 1 line #5655: fix docstring oversight. ........ r70964 | brett.cannon | 2009-04-01 12:52:13 -0500 (Wed, 01 Apr 2009) | 2 lines Paul Kippes was given commit privileges to work on 3to2. ........ r70998 | georg.brandl | 2009-04-01 16:54:21 -0500 (Wed, 01 Apr 2009) | 1 line In Pdb, stop assigning values to __builtin__._ which interferes with the one commonly installed by gettext. ........ r71001 | brett.cannon | 2009-04-01 18:01:12 -0500 (Wed, 01 Apr 2009) | 3 lines Add my initials to Misc/developers.txt. Names are now sorted by number of characters in the person's name. ........ r71006 | georg.brandl | 2009-04-01 18:32:17 -0500 (Wed, 01 Apr 2009) | 1 line Cache the f_locals dict of the current frame, since every access to frame.f_locals overrides its contents with the real locals which undoes modifications made by the debugging user. ........ r71008 | andrew.kuchling | 2009-04-01 19:02:14 -0500 (Wed, 01 Apr 2009) | 1 line Typo fix ........ r71010 | benjamin.peterson | 2009-04-01 19:11:52 -0500 (Wed, 01 Apr 2009) | 1 line fix markup ........ r71011 | benjamin.peterson | 2009-04-01 19:12:47 -0500 (Wed, 01 Apr 2009) | 1 line this should be :noindex: ........ r71019 | georg.brandl | 2009-04-01 21:00:01 -0500 (Wed, 01 Apr 2009) | 1 line Fix test_doctest, missed two assignments to curframe. ........ r71037 | r.david.murray | 2009-04-01 23:34:04 -0500 (Wed, 01 Apr 2009) | 6 lines Clarify that datetime strftime does not produce leap seconds and datetime strptime does not accept it in the strftime behavior section of the datetime docs. Closes issue 2568. ........ r71056 | georg.brandl | 2009-04-02 12:43:07 -0500 (Thu, 02 Apr 2009) | 2 lines Actually the displayhook should print the repr. ........ r71094 | vinay.sajip | 2009-04-03 05:23:18 -0500 (Fri, 03 Apr 2009) | 1 line Added warning about logging use from asynchronous signal handlers. ........ r71101 | andrew.kuchling | 2009-04-03 16:43:00 -0500 (Fri, 03 Apr 2009) | 1 line Add some items ........ r71102 | andrew.kuchling | 2009-04-03 16:44:49 -0500 (Fri, 03 Apr 2009) | 1 line Fix 'the the'; grammar fix ........ r71103 | andrew.kuchling | 2009-04-03 16:45:29 -0500 (Fri, 03 Apr 2009) | 1 line Fix 'the the' duplication ........ r71106 | vinay.sajip | 2009-04-03 16:58:16 -0500 (Fri, 03 Apr 2009) | 1 line Clarified warning about logging use from asynchronous signal handlers. ........ r71119 | raymond.hettinger | 2009-04-04 00:37:47 -0500 (Sat, 04 Apr 2009) | 1 line Add helpful link. ........ r71123 | r.david.murray | 2009-04-04 01:39:56 -0500 (Sat, 04 Apr 2009) | 2 lines Fix error in description of 'oct' (issue 5678). ........ r71149 | georg.brandl | 2009-04-04 08:42:39 -0500 (Sat, 04 Apr 2009) | 1 line #5642: clarify map() compatibility to the builtin. ........ r71150 | georg.brandl | 2009-04-04 08:45:49 -0500 (Sat, 04 Apr 2009) | 1 line #5601: clarify that webbrowser is not meant for file names. ........ r71203 | benjamin.peterson | 2009-04-04 18:46:34 -0500 (Sat, 04 Apr 2009) | 1 line note how using iter* are unsafe while mutating and document iter(dict) ........ r71212 | georg.brandl | 2009-04-05 05:24:20 -0500 (Sun, 05 Apr 2009) | 1 line #1742837: expand HTTP server docs, and fix SocketServer ones to document methods as methods, not functions. ........ r71214 | georg.brandl | 2009-04-05 05:29:57 -0500 (Sun, 05 Apr 2009) | 1 line Normalize spelling of Mac OS X. ........ r71215 | georg.brandl | 2009-04-05 05:32:26 -0500 (Sun, 05 Apr 2009) | 1 line Avoid sure signs of a diseased mind. ........ r71216 | georg.brandl | 2009-04-05 05:41:02 -0500 (Sun, 05 Apr 2009) | 1 line #1718017: document the relation of os.path and the posixpath, ntpath etc. modules better. ........ r71217 | georg.brandl | 2009-04-05 05:48:47 -0500 (Sun, 05 Apr 2009) | 1 line #1726172: dont raise an unexpected IndexError if a voidresp() call has an empty response. ........ r71221 | vinay.sajip | 2009-04-05 06:06:24 -0500 (Sun, 05 Apr 2009) | 1 line Issue #5695: Moved logging.captureWarnings() call inside with statement in WarningsTest.test_warnings. ........ r71240 | georg.brandl | 2009-04-05 09:40:06 -0500 (Sun, 05 Apr 2009) | 1 line #5370: doc update about unpickling objects with custom __getattr__ etc. methods. ........ --- apiref.rst | 20 ++++++++++++++------ 1 file changed, 14 insertions(+), 6 deletions(-) diff --git a/apiref.rst b/apiref.rst index 9b075483a0..ce260d9b80 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1050,8 +1050,8 @@ This module contains some utility functions for operating on individual files. .. warning:: - Handles cross-device moves on Unix using :func:`copy_file`. What about other - systems??? + Handles cross-device moves on Unix using :func:`copy_file`. What about + other systems? .. function:: write_file(filename, contents) @@ -1091,17 +1091,17 @@ other utility module. For non-POSIX platforms, currently just returns ``sys.platform``. - For MacOS X systems the OS version reflects the minimal version on which + For Mac OS X systems the OS version reflects the minimal version on which binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` during the build of Python), not the OS version of the current system. - For universal binary builds on MacOS X the architecture value reflects + For universal binary builds on Mac OS X the architecture value reflects the univeral binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is ``fat``, for 64-bit universal binaries the architecture is ``fat64``, and for 4-way universal binaries the architecture is ``universal``. - Examples of returned values on MacOS X: + Examples of returned values on Mac OS X: * ``macosx-10.3-ppc`` @@ -1758,8 +1758,16 @@ This module supplies the abstract base class :class:`Command`. .. module:: distutils.command.bdist_msi :synopsis: Build a binary distribution as a Windows MSI file +.. class:: bdist_msi(Command) -.. % todo + Builds a `Windows Installer`_ (.msi) binary package. + + .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx + + In most cases, the ``bdist_msi`` installer is a better choice than the + ``bdist_wininst`` installer, because it provides better support for + Win64 platforms, allows administrators to perform non-interactive + installations, and allows installation through group policies. :mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM From 70ab1f95dcc86e72b6b499434b6155fbb317ba76 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 5 Apr 2009 21:11:43 +0000 Subject: [PATCH 071/330] Merged revisions 70642,70648,70656,70661,70765,70773,70789,70824-70825,70828,70830,70832,70836,70838,70842,70851,70855,70857-70858 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r70642 | georg.brandl | 2009-03-28 01:48:48 +0100 (Sa, 28 Mär 2009) | 1 line Fix typo. ........ r70648 | georg.brandl | 2009-03-28 20:10:37 +0100 (Sa, 28 Mär 2009) | 1 line #5324: document __subclasses__(). ........ r70656 | georg.brandl | 2009-03-28 20:33:33 +0100 (Sa, 28 Mär 2009) | 2 lines Add a script to fixup rst files if the pre-commit hook rejects them. ........ r70661 | georg.brandl | 2009-03-28 20:57:36 +0100 (Sa, 28 Mär 2009) | 2 lines Add section numbering to some of the larger subdocuments. ........ r70765 | georg.brandl | 2009-03-31 00:09:34 +0200 (Di, 31 Mär 2009) | 1 line #5199: make warning about vars() assignment more visible. ........ r70773 | georg.brandl | 2009-03-31 00:43:00 +0200 (Di, 31 Mär 2009) | 1 line #5039: make it clear that the impl. note refers to CPython. ........ r70789 | georg.brandl | 2009-03-31 03:25:15 +0200 (Di, 31 Mär 2009) | 1 line Fix a wrong struct field assignment (docstring as closure). ........ r70824 | georg.brandl | 2009-03-31 17:43:20 +0200 (Di, 31 Mär 2009) | 1 line #5519: remove reference to Kodos, which seems dead. ........ r70825 | georg.brandl | 2009-03-31 17:46:30 +0200 (Di, 31 Mär 2009) | 1 line #5566: fix versionadded from PyLong ssize_t functions. ........ r70828 | georg.brandl | 2009-03-31 17:50:16 +0200 (Di, 31 Mär 2009) | 1 line #5581: fget argument of abstractproperty is optional as well. ........ r70830 | georg.brandl | 2009-03-31 18:11:45 +0200 (Di, 31 Mär 2009) | 1 line #5529: backport new docs of import semantics written by Brett to 2.x. ........ r70832 | georg.brandl | 2009-03-31 18:31:11 +0200 (Di, 31 Mär 2009) | 1 line #1386675: specify WindowsError as the exception, because it has a winerror attribute that EnvironmentError doesnt have. ........ r70836 | georg.brandl | 2009-03-31 18:50:25 +0200 (Di, 31 Mär 2009) | 1 line #5417: replace references to undocumented functions by ones to documented functions. ........ r70838 | georg.brandl | 2009-03-31 18:54:38 +0200 (Di, 31 Mär 2009) | 1 line #992207: document that the parser only accepts \\n newlines. ........ r70842 | georg.brandl | 2009-03-31 19:13:06 +0200 (Di, 31 Mär 2009) | 1 line #970783: document PyObject_Generic[GS]etAttr. ........ r70851 | georg.brandl | 2009-03-31 20:26:55 +0200 (Di, 31 Mär 2009) | 1 line #837577: note cryptic return value of spawn*e on invalid env dicts. ........ r70855 | georg.brandl | 2009-03-31 20:30:37 +0200 (Di, 31 Mär 2009) | 1 line #5245: note that PyRun_SimpleString doesnt return on SystemExit. ........ r70857 | georg.brandl | 2009-03-31 20:33:10 +0200 (Di, 31 Mär 2009) | 1 line #5227: note that Py_Main doesnt return on SystemExit. ........ r70858 | georg.brandl | 2009-03-31 20:38:56 +0200 (Di, 31 Mär 2009) | 1 line #5241: document missing U in regex howto. ........ --- index.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/index.rst b/index.rst index 6d82c847bb..ace8280894 100644 --- a/index.rst +++ b/index.rst @@ -16,6 +16,7 @@ very little overhead for build/release/install mechanics. .. toctree:: :maxdepth: 2 + :numbered: introduction.rst setupscript.rst From ff88e202f41e3aad51c76de16850b2cda424655b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 5 Apr 2009 21:21:05 +0000 Subject: [PATCH 072/330] Merged revisions 70866-70868,70870-70871,70893,70896,70902,70905,70907,70912,70915,70927,70933,70940,70944,70954,70963,70998,71056 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r70866 | georg.brandl | 2009-03-31 21:06:57 +0200 (Di, 31 Mär 2009) | 1 line #4882: document named group behavior a bit better. ........ r70867 | georg.brandl | 2009-03-31 21:10:35 +0200 (Di, 31 Mär 2009) | 1 line #1096310: document usage of sys.__std*__ a bit better. ........ r70868 | georg.brandl | 2009-03-31 21:12:17 +0200 (Di, 31 Mär 2009) | 1 line #5190: export make_option in __all__. ........ r70870 | georg.brandl | 2009-03-31 21:26:24 +0200 (Di, 31 Mär 2009) | 1 line #4411: document mro() and __mro__. (I hope I got it right.) ........ r70871 | georg.brandl | 2009-03-31 21:30:56 +0200 (Di, 31 Mär 2009) | 1 line #5618: fix typo. ........ r70893 | georg.brandl | 2009-03-31 22:56:32 +0200 (Di, 31 Mär 2009) | 1 line #1530012: move TQS section before raw strings. ........ r70896 | georg.brandl | 2009-03-31 23:15:33 +0200 (Di, 31 Mär 2009) | 1 line #5598: document DocFileSuite *args argument. ........ r70902 | georg.brandl | 2009-03-31 23:43:03 +0200 (Di, 31 Mär 2009) | 1 line #1675026: add a note about a strange Windows problem, and remove notes about AtheOS. ........ r70905 | georg.brandl | 2009-04-01 00:03:40 +0200 (Mi, 01 Apr 2009) | 1 line #5563: more documentation for bdist_msi. ........ r70907 | georg.brandl | 2009-04-01 00:18:19 +0200 (Mi, 01 Apr 2009) | 1 line #3427: document correct return type for urlopen().info(). ........ r70912 | georg.brandl | 2009-04-01 00:35:46 +0200 (Mi, 01 Apr 2009) | 1 line #5617: add a handy function to print a unicode string to gdbinit. ........ r70915 | georg.brandl | 2009-04-01 00:40:16 +0200 (Mi, 01 Apr 2009) | 1 line #5018: remove confusing paragraph. ........ r70927 | georg.brandl | 2009-04-01 01:01:27 +0200 (Mi, 01 Apr 2009) | 1 line Dont shout to users. ........ r70933 | georg.brandl | 2009-04-01 02:04:33 +0200 (Mi, 01 Apr 2009) | 2 lines Issue #5635: Fix running test_sys with tracing enabled. ........ r70940 | georg.brandl | 2009-04-01 06:21:14 +0200 (Mi, 01 Apr 2009) | 2 lines The SimpleXMLRPCServer's CGI handler now runs like a pony. ........ r70944 | georg.brandl | 2009-04-01 06:32:39 +0200 (Mi, 01 Apr 2009) | 1 line #5631: add upload to list of possible commands, which is presented in --help-commands. ........ r70954 | georg.brandl | 2009-04-01 17:23:43 +0200 (Mi, 01 Apr 2009) | 1 line Fix test_xmlrpc and make the CGI handler work with no CONTENT_LENGTH. ........ r70963 | georg.brandl | 2009-04-01 19:46:01 +0200 (Mi, 01 Apr 2009) | 1 line #5655: fix docstring oversight. ........ r70998 | georg.brandl | 2009-04-01 23:54:21 +0200 (Mi, 01 Apr 2009) | 1 line In Pdb, stop assigning values to __builtin__._ which interferes with the one commonly installed by gettext. ........ r71056 | georg.brandl | 2009-04-02 19:43:07 +0200 (Do, 02 Apr 2009) | 2 lines Actually the displayhook should print the repr. ........ --- apiref.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 4d65de0394..b4887cf826 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1775,8 +1775,16 @@ This module supplies the abstract base class :class:`Command`. .. module:: distutils.command.bdist_msi :synopsis: Build a binary distribution as a Windows MSI file +.. class:: bdist_msi(Command) -.. % todo + Builds a `Windows Installer`_ (.msi) binary package. + + .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx + + In most cases, the ``bdist_msi`` installer is a better choice than the + ``bdist_wininst`` installer, because it provides better support for + Win64 platforms, allows administrators to perform non-interactive + installations, and allows installation through group policies. :mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM From 54f9f96b8434ba9883bf30c37037ae48e14d9ee4 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 5 Apr 2009 21:26:31 +0000 Subject: [PATCH 073/330] Merged revisions 71058,71149-71150,71212,71214-71216,71222,71225,71234,71237-71238,71240-71241,71243,71249,71251 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71058 | georg.brandl | 2009-04-02 20:09:04 +0200 (Do, 02 Apr 2009) | 3 lines PyErr_NormalizeException may not set an error, so convert the PyErr_SetObject call on hitting the recursion limit into just assigning it to the arguments provided. ........ r71149 | georg.brandl | 2009-04-04 15:42:39 +0200 (Sa, 04 Apr 2009) | 1 line #5642: clarify map() compatibility to the builtin. ........ r71150 | georg.brandl | 2009-04-04 15:45:49 +0200 (Sa, 04 Apr 2009) | 1 line #5601: clarify that webbrowser is not meant for file names. ........ r71212 | georg.brandl | 2009-04-05 12:24:20 +0200 (So, 05 Apr 2009) | 1 line #1742837: expand HTTP server docs, and fix SocketServer ones to document methods as methods, not functions. ........ r71214 | georg.brandl | 2009-04-05 12:29:57 +0200 (So, 05 Apr 2009) | 1 line Normalize spelling of Mac OS X. ........ r71215 | georg.brandl | 2009-04-05 12:32:26 +0200 (So, 05 Apr 2009) | 1 line Avoid sure signs of a diseased mind. ........ r71216 | georg.brandl | 2009-04-05 12:41:02 +0200 (So, 05 Apr 2009) | 1 line #1718017: document the relation of os.path and the posixpath, ntpath etc. modules better. ........ r71222 | georg.brandl | 2009-04-05 13:07:14 +0200 (So, 05 Apr 2009) | 1 line #5615: make it possible to configure --without-threads again. ........ r71225 | georg.brandl | 2009-04-05 13:54:07 +0200 (So, 05 Apr 2009) | 1 line #5580: no need to use parentheses when converterr() argument is actually a type description. ........ r71234 | georg.brandl | 2009-04-05 15:16:35 +0200 (So, 05 Apr 2009) | 1 line Whitespace normalization. ........ r71237 | georg.brandl | 2009-04-05 16:24:52 +0200 (So, 05 Apr 2009) | 1 line #1326077: fix traceback formatting of SyntaxErrors. This fixes two differences with formatting coming from Python: a) the reproduction of location details in the error message if no line text is given, b) the prefixing of the last line by one space. ........ r71238 | georg.brandl | 2009-04-05 16:25:41 +0200 (So, 05 Apr 2009) | 1 line Add NEWS entry for r71237. ........ r71240 | georg.brandl | 2009-04-05 16:40:06 +0200 (So, 05 Apr 2009) | 1 line #5370: doc update about unpickling objects with custom __getattr__ etc. methods. ........ r71241 | georg.brandl | 2009-04-05 16:48:49 +0200 (So, 05 Apr 2009) | 1 line #5471: fix expanduser() for $HOME set to "/". ........ r71243 | georg.brandl | 2009-04-05 17:14:29 +0200 (So, 05 Apr 2009) | 1 line #5432: make plistlib docstring a raw string, since it contains examples with backslash escapes. ........ r71249 | georg.brandl | 2009-04-05 18:30:43 +0200 (So, 05 Apr 2009) | 1 line #5444: adapt make.bat to new htmlhelp output file name. ........ r71251 | georg.brandl | 2009-04-05 19:17:42 +0200 (So, 05 Apr 2009) | 1 line #5298: clarify docs about GIL by using more consistent wording. ........ --- apiref.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/apiref.rst b/apiref.rst index b4887cf826..20bb31a106 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1067,8 +1067,8 @@ This module contains some utility functions for operating on individual files. .. warning:: - Handles cross-device moves on Unix using :func:`copy_file`. What about other - systems??? + Handles cross-device moves on Unix using :func:`copy_file`. What about + other systems? .. function:: write_file(filename, contents) @@ -1108,17 +1108,17 @@ other utility module. For non-POSIX platforms, currently just returns ``sys.platform``. - For MacOS X systems the OS version reflects the minimal version on which + For Mac OS X systems the OS version reflects the minimal version on which binaries will run (that is, the value of ``MACOSX_DEPLOYMENT_TARGET`` during the build of Python), not the OS version of the current system. - For universal binary builds on MacOS X the architecture value reflects + For universal binary builds on Mac OS X the architecture value reflects the univeral binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is ``fat``, for 64-bit universal binaries the architecture is ``fat64``, and for 4-way universal binaries the architecture is ``universal``. - Examples of returned values on MacOS X: + Examples of returned values on Mac OS X: * ``macosx-10.3-ppc`` From 00c6dd1331de0a3e6014a806aa6b36c7b8de49d0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 5 Apr 2009 21:48:06 +0000 Subject: [PATCH 074/330] Merged revisions 69578-69580,69901,69907,69994,70022-70023,70025-70026,70166,70273,70275,70342,70386-70387,70389-70390,70392-70393,70395,70397,70400,70418 via svnmerge MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r69578 | georg.brandl | 2009-02-13 12:03:59 +0100 (Fr, 13 Feb 2009) | 1 line #3694: add test for fix committed in r66693. ........ r69579 | georg.brandl | 2009-02-13 12:06:59 +0100 (Fr, 13 Feb 2009) | 2 lines Fix warnings GCC emits where the argument of PyErr_Format is a single variable. ........ r69580 | georg.brandl | 2009-02-13 12:10:04 +0100 (Fr, 13 Feb 2009) | 2 lines Fix warnings GCC emits where the argument of PyErr_Format is a single variable. ........ r69901 | georg.brandl | 2009-02-23 12:24:46 +0100 (Mo, 23 Feb 2009) | 2 lines #5349: C++ pure virtuals can also have an implementation. ........ r69907 | georg.brandl | 2009-02-23 19:33:48 +0100 (Mo, 23 Feb 2009) | 1 line Fix grammar. ........ r69994 | georg.brandl | 2009-02-26 18:36:26 +0100 (Do, 26 Feb 2009) | 1 line Document that setting sys.py3kwarning wont do anything. ........ r70022 | georg.brandl | 2009-02-27 17:23:18 +0100 (Fr, 27 Feb 2009) | 1 line #5361: fix typo. ........ r70023 | georg.brandl | 2009-02-27 17:39:26 +0100 (Fr, 27 Feb 2009) | 1 line #5363: fix cmpfiles() docs. Another instance where a prose description is twice as long as the code. ........ r70025 | georg.brandl | 2009-02-27 17:52:55 +0100 (Fr, 27 Feb 2009) | 1 line #5344: fix punctuation. ........ r70026 | georg.brandl | 2009-02-27 17:59:03 +0100 (Fr, 27 Feb 2009) | 1 line #5365: add quick look conversion table for different time representations. ........ r70166 | georg.brandl | 2009-03-04 19:24:41 +0100 (Mi, 04 Mär 2009) | 2 lines Remove obsolete stuff from string module docs. ........ r70273 | georg.brandl | 2009-03-09 15:25:07 +0100 (Mo, 09 Mär 2009) | 2 lines #5458: add a note when we started to raise RuntimeErrors. ........ r70275 | georg.brandl | 2009-03-09 17:35:48 +0100 (Mo, 09 Mär 2009) | 2 lines Add missing space. ........ r70342 | georg.brandl | 2009-03-13 20:03:58 +0100 (Fr, 13 Mär 2009) | 1 line #5486: typos. ........ r70386 | georg.brandl | 2009-03-15 22:32:06 +0100 (So, 15 Mär 2009) | 1 line #5496: fix docstring of lookup(). ........ r70387 | georg.brandl | 2009-03-15 22:37:16 +0100 (So, 15 Mär 2009) | 1 line #5493: clarify __nonzero__ docs. ........ r70389 | georg.brandl | 2009-03-15 22:43:38 +0100 (So, 15 Mär 2009) | 1 line Fix a small nit in the error message if bool() falls back on __len__ and it returns the wrong type: it would tell the user that __nonzero__ should return bool or int. ........ r70390 | georg.brandl | 2009-03-15 22:44:43 +0100 (So, 15 Mär 2009) | 1 line #5491: clarify nested() semantics. ........ r70392 | georg.brandl | 2009-03-15 22:46:00 +0100 (So, 15 Mär 2009) | 1 line #5488: add missing struct member. ........ r70393 | georg.brandl | 2009-03-15 22:47:42 +0100 (So, 15 Mär 2009) | 1 line #5478: fix copy-paste oversight in function signature. ........ r70395 | georg.brandl | 2009-03-15 22:51:48 +0100 (So, 15 Mär 2009) | 1 line #5276: document IDLESTARTUP and .Idle.py. ........ r70397 | georg.brandl | 2009-03-15 22:53:56 +0100 (So, 15 Mär 2009) | 1 line #5469: add with statement to list of name-binding constructs. ........ r70400 | georg.brandl | 2009-03-15 22:59:37 +0100 (So, 15 Mär 2009) | 3 lines Fix markup in re docs and give a mail address in regex howto, so that the recommendation to send suggestions to the author can be followed. ........ r70418 | georg.brandl | 2009-03-16 20:42:03 +0100 (Mo, 16 Mär 2009) | 1 line Add token markup. ........ --- packageindex.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/packageindex.rst b/packageindex.rst index 3715c82480..912248ec7b 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -91,4 +91,3 @@ Or even with the section name:: python setup.py register -r other - From 60bec36e6e5e0b57621aa66d2a2d9a9eabc2ddd7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 5 Apr 2009 22:51:09 +0000 Subject: [PATCH 075/330] Fixed #5095: msi missing from Distutils bdist formats --- builtdist.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 672faee34c..6e7e51c04e 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -80,7 +80,7 @@ The available formats for built distributions are: +-------------+------------------------------+---------+ | ``tar`` | tar file (:file:`.tar`) | \(3) | +-------------+------------------------------+---------+ -| ``zip`` | zip file (:file:`.zip`) | \(4) | +| ``zip`` | zip file (:file:`.zip`) | (2),(4) | +-------------+------------------------------+---------+ | ``rpm`` | RPM | \(5) | +-------------+------------------------------+---------+ @@ -90,9 +90,12 @@ The available formats for built distributions are: +-------------+------------------------------+---------+ | ``rpm`` | RPM | \(5) | +-------------+------------------------------+---------+ -| ``wininst`` | self-extracting ZIP file for | (2),(4) | +| ``wininst`` | self-extracting ZIP file for | \(4) | | | Windows | | +-------------+------------------------------+---------+ +| ``msi`` | Microsoft Installer. | | ++-------------+------------------------------+---------+ + Notes: @@ -102,8 +105,6 @@ Notes: (2) default on Windows - **\*\*** to-do! **\*\*** - (3) requires external utilities: :program:`tar` and possibly one of :program:`gzip`, :program:`bzip2`, or :program:`compress` @@ -133,6 +134,8 @@ generates all the "dumb" archive formats (``tar``, ``ztar``, ``gztar``, and +--------------------------+-----------------------+ | :command:`bdist_wininst` | wininst | +--------------------------+-----------------------+ +| :command:`bdist_msi` | msi | ++--------------------------+-----------------------+ The following sections give details on the individual :command:`bdist_\*` commands. From 844d7645e938b064fd8969ac492148d3fe85c132 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 5 Apr 2009 22:57:21 +0000 Subject: [PATCH 076/330] Merged revisions 71291 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71291 | tarek.ziade | 2009-04-06 00:51:09 +0200 (Mon, 06 Apr 2009) | 1 line Fixed #5095: msi missing from Distutils bdist formats ........ --- builtdist.rst | 11 +++++++---- 1 file changed, 7 insertions(+), 4 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 672faee34c..6e7e51c04e 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -80,7 +80,7 @@ The available formats for built distributions are: +-------------+------------------------------+---------+ | ``tar`` | tar file (:file:`.tar`) | \(3) | +-------------+------------------------------+---------+ -| ``zip`` | zip file (:file:`.zip`) | \(4) | +| ``zip`` | zip file (:file:`.zip`) | (2),(4) | +-------------+------------------------------+---------+ | ``rpm`` | RPM | \(5) | +-------------+------------------------------+---------+ @@ -90,9 +90,12 @@ The available formats for built distributions are: +-------------+------------------------------+---------+ | ``rpm`` | RPM | \(5) | +-------------+------------------------------+---------+ -| ``wininst`` | self-extracting ZIP file for | (2),(4) | +| ``wininst`` | self-extracting ZIP file for | \(4) | | | Windows | | +-------------+------------------------------+---------+ +| ``msi`` | Microsoft Installer. | | ++-------------+------------------------------+---------+ + Notes: @@ -102,8 +105,6 @@ Notes: (2) default on Windows - **\*\*** to-do! **\*\*** - (3) requires external utilities: :program:`tar` and possibly one of :program:`gzip`, :program:`bzip2`, or :program:`compress` @@ -133,6 +134,8 @@ generates all the "dumb" archive formats (``tar``, ``ztar``, ``gztar``, and +--------------------------+-----------------------+ | :command:`bdist_wininst` | wininst | +--------------------------+-----------------------+ +| :command:`bdist_msi` | msi | ++--------------------------+-----------------------+ The following sections give details on the individual :command:`bdist_\*` commands. From 72dcd7a597f58424656f507b76665be35f3faa44 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sat, 11 Apr 2009 13:59:05 +0000 Subject: [PATCH 077/330] fixed link --- examples.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples.rst b/examples.rst index d937b83583..b495928657 100644 --- a/examples.rst +++ b/examples.rst @@ -11,7 +11,7 @@ Distutils Cookbook. .. seealso:: - `Distutils Cookbook `_ + `Distutils Cookbook `_ Collection of recipes showing how to achieve more control over distutils. From 77f79cb9742ad126289e9d24e63c57cba13f22d3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sat, 11 Apr 2009 14:31:24 +0000 Subject: [PATCH 078/330] Merged revisions 71467 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71467 | tarek.ziade | 2009-04-11 15:59:05 +0200 (Sat, 11 Apr 2009) | 1 line fixed link ........ --- examples.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples.rst b/examples.rst index d937b83583..b495928657 100644 --- a/examples.rst +++ b/examples.rst @@ -11,7 +11,7 @@ Distutils Cookbook. .. seealso:: - `Distutils Cookbook `_ + `Distutils Cookbook `_ Collection of recipes showing how to achieve more control over distutils. From 9aec8ce27f70734e0147653ac4b3965363c5ac8d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sat, 11 Apr 2009 14:32:37 +0000 Subject: [PATCH 079/330] Merged revisions 71467 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71467 | tarek.ziade | 2009-04-11 15:59:05 +0200 (Sat, 11 Apr 2009) | 1 line fixed link ........ --- examples.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples.rst b/examples.rst index d937b83583..b495928657 100644 --- a/examples.rst +++ b/examples.rst @@ -11,7 +11,7 @@ Distutils Cookbook. .. seealso:: - `Distutils Cookbook `_ + `Distutils Cookbook `_ Collection of recipes showing how to achieve more control over distutils. From bba34bc44fc791879aa14170b8078cfd02b5c283 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sat, 11 Apr 2009 14:55:07 +0000 Subject: [PATCH 080/330] #5732: added the check command into Distutils --- apiref.rst | 13 +++++++++++++ examples.rst | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) diff --git a/apiref.rst b/apiref.rst index 4ee9fcc81c..79e13c1810 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1932,6 +1932,19 @@ This is described in more detail in :pep:`301`. .. % todo +:mod:`distutils.command.check` --- Check the meta-data of a package +=================================================================== + +.. module:: distutils.command.check + :synopsis: Check the metadata of a package + + +The ``check`` command performs some tests on the meta-data of a package. +It makes sure for example that all required meta-data are provided through +the arguments passed to the :func:`setup` function. + +.. % todo + Creating a new Distutils command ================================ diff --git a/examples.rst b/examples.rst index b495928657..d5918a5eb2 100644 --- a/examples.rst +++ b/examples.rst @@ -233,6 +233,58 @@ With exactly the same source tree layout, this extension can be put in the ext_modules=[Extension('foopkg.foo', ['foo.c'])], ) +Checking a package +================== + +The ``check`` command allows you to verify if your package meta-data are +meeting the minimum requirements to build a distribution. + +To run it, just call it over your :file:`setup.py` script. If something is +missing, ``check`` will display a warning. + +Let's take an example with a simple script:: + + from distutils.core import setup + + setup(name='foobar') + +Running the ``check`` command will display some warnings:: + + $ python setup.py check + running check + warning: check: missing required meta-data: version ,url + warning: check: missing meta-data: either (author and author_email) or + (maintainer and maintainer_email) must be supplied + + +If you use the reStructuredText syntax in the `long_description` field and +`docutils `_ is installed you can check if +the syntax is fine with the ``check`` command, using the `restructuredtext` +option. + +For example, if the :file:`setup.py` script is changed like this:: + + from distutils.core import setup + + desc = """\ + My description + ============= + + This is the description of the ``foobar`` package. + """ + + setup(name='foobar', version='1', author='tarek', + author_email='tarek@ziade.org', + url='http://example.com', long_description=desc) + +Where the long description is broken, ``check`` will be able to detect it +by using the `docutils` parser:: + + $ pythontrunk setup.py check --restructuredtext + running check + warning: check: Title underline too short. (line 2) + warning: check: Could not finish the parsing. + .. % \section{Multiple extension modules} .. % \label{multiple-ext} From 4d8ec3cf94447d2fe0dc2d949d1a9491050b1d89 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sat, 11 Apr 2009 15:00:43 +0000 Subject: [PATCH 081/330] Merged revisions 71473 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r71473 | tarek.ziade | 2009-04-11 16:55:07 +0200 (Sat, 11 Apr 2009) | 1 line #5732: added the check command into Distutils ........ --- apiref.rst | 13 +++++++++++++ examples.rst | 52 ++++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 65 insertions(+) diff --git a/apiref.rst b/apiref.rst index ce260d9b80..490e7f3560 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1950,6 +1950,19 @@ This is described in more detail in :pep:`301`. .. % todo +:mod:`distutils.command.check` --- Check the meta-data of a package +=================================================================== + +.. module:: distutils.command.check + :synopsis: Check the metadata of a package + + +The ``check`` command performs some tests on the meta-data of a package. +It makes sure for example that all required meta-data are provided through +the arguments passed to the :func:`setup` function. + +.. % todo + Creating a new Distutils command ================================ diff --git a/examples.rst b/examples.rst index b495928657..d5918a5eb2 100644 --- a/examples.rst +++ b/examples.rst @@ -233,6 +233,58 @@ With exactly the same source tree layout, this extension can be put in the ext_modules=[Extension('foopkg.foo', ['foo.c'])], ) +Checking a package +================== + +The ``check`` command allows you to verify if your package meta-data are +meeting the minimum requirements to build a distribution. + +To run it, just call it over your :file:`setup.py` script. If something is +missing, ``check`` will display a warning. + +Let's take an example with a simple script:: + + from distutils.core import setup + + setup(name='foobar') + +Running the ``check`` command will display some warnings:: + + $ python setup.py check + running check + warning: check: missing required meta-data: version ,url + warning: check: missing meta-data: either (author and author_email) or + (maintainer and maintainer_email) must be supplied + + +If you use the reStructuredText syntax in the `long_description` field and +`docutils `_ is installed you can check if +the syntax is fine with the ``check`` command, using the `restructuredtext` +option. + +For example, if the :file:`setup.py` script is changed like this:: + + from distutils.core import setup + + desc = """\ + My description + ============= + + This is the description of the ``foobar`` package. + """ + + setup(name='foobar', version='1', author='tarek', + author_email='tarek@ziade.org', + url='http://example.com', long_description=desc) + +Where the long description is broken, ``check`` will be able to detect it +by using the `docutils` parser:: + + $ pythontrunk setup.py check --restructuredtext + running check + warning: check: Title underline too short. (line 2) + warning: check: Could not finish the parsing. + .. % \section{Multiple extension modules} .. % \label{multiple-ext} From b794b4ed1544bea05f6cd33e015c56a168d130c8 Mon Sep 17 00:00:00 2001 From: "Andrew M. Kuchling" Date: Sat, 11 Apr 2009 16:18:14 +0000 Subject: [PATCH 082/330] Re-word --- setupscript.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 61f57aa37b..851c904848 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -334,9 +334,9 @@ Other options There are still some other options which can be used to handle special cases. -The :option:`optional` option is a boolean; if it is true, that specifies that -a build failure in the extension should not abort the build process, but simply -not install the failing extension. +The :option:`optional` option is a boolean; if it is true, +a build failure in the extension will not abort the build process, but +instead simply not install the failing extension. The :option:`extra_objects` option is a list of object files to be passed to the linker. These files must not have extensions, as the default extension for the From f318228b69d023f51bfe068422c286f4936f8c14 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sat, 11 Apr 2009 19:48:14 +0000 Subject: [PATCH 083/330] Merged revisions 70980,71059,71225,71234,71241,71243,71249,71251,71255,71266,71299,71329,71397-71398,71486 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r70980 | jack.diederich | 2009-04-01 15:26:13 -0500 (Wed, 01 Apr 2009) | 3 lines bounds check arguments to mmap.move(). All of them. Really. fixes crasher on OS X 10.5 ........ r71059 | mark.dickinson | 2009-04-02 13:39:37 -0500 (Thu, 02 Apr 2009) | 2 lines sys.long_info attributes should be ints, not longs ........ r71225 | georg.brandl | 2009-04-05 06:54:07 -0500 (Sun, 05 Apr 2009) | 1 line #5580: no need to use parentheses when converterr() argument is actually a type description. ........ r71234 | georg.brandl | 2009-04-05 08:16:35 -0500 (Sun, 05 Apr 2009) | 1 line Whitespace normalization. ........ r71241 | georg.brandl | 2009-04-05 09:48:49 -0500 (Sun, 05 Apr 2009) | 1 line #5471: fix expanduser() for $HOME set to "/". ........ r71243 | georg.brandl | 2009-04-05 10:14:29 -0500 (Sun, 05 Apr 2009) | 1 line #5432: make plistlib docstring a raw string, since it contains examples with backslash escapes. ........ r71249 | georg.brandl | 2009-04-05 11:30:43 -0500 (Sun, 05 Apr 2009) | 1 line #5444: adapt make.bat to new htmlhelp output file name. ........ r71251 | georg.brandl | 2009-04-05 12:17:42 -0500 (Sun, 05 Apr 2009) | 1 line #5298: clarify docs about GIL by using more consistent wording. ........ r71255 | georg.brandl | 2009-04-05 13:34:58 -0500 (Sun, 05 Apr 2009) | 1 line #602893: add indicator for current line in cgitb that doesnt rely on styling alone. ........ r71266 | georg.brandl | 2009-04-05 15:23:13 -0500 (Sun, 05 Apr 2009) | 1 line Normalize issue referencing style. ........ r71299 | gregory.p.smith | 2009-04-05 18:43:58 -0500 (Sun, 05 Apr 2009) | 3 lines Fixes issue5705: os.setuid() and friends did not accept the same range of values that pwd.getpwnam() returns. ........ r71329 | benjamin.peterson | 2009-04-06 16:53:33 -0500 (Mon, 06 Apr 2009) | 1 line add create_connection to __all__ #5711 ........ r71397 | georg.brandl | 2009-04-08 11:36:39 -0500 (Wed, 08 Apr 2009) | 1 line Remove redundant backtick. ........ r71398 | georg.brandl | 2009-04-08 11:39:04 -0500 (Wed, 08 Apr 2009) | 1 line Update ignore file for suspicious builder. ........ r71486 | andrew.kuchling | 2009-04-11 11:18:14 -0500 (Sat, 11 Apr 2009) | 1 line Re-word ........ --- setupscript.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 85089d092d..29854377e4 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -334,9 +334,9 @@ Other options There are still some other options which can be used to handle special cases. -The :option:`optional` option is a boolean; if it is true, that specifies that -a build failure in the extension should not abort the build process, but simply -not install the failing extension. +The :option:`optional` option is a boolean; if it is true, +a build failure in the extension will not abort the build process, but +instead simply not install the failing extension. The :option:`extra_objects` option is a list of object files to be passed to the linker. These files must not have extensions, as the default extension for the From a0355b672acf424bba00a4d3ff7b8ad905a8584b Mon Sep 17 00:00:00 2001 From: Jeroen Ruigrok van der Werven Date: Mon, 27 Apr 2009 08:07:12 +0000 Subject: [PATCH 084/330] After discussing some more with Georg, do no migrate versionchanged:: 2.5 to this branch. While I am here, also get rid of other versionchanged:: 2.x constructs, as discussed. --- setupscript.rst | 13 ------------- 1 file changed, 13 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 29854377e4..bbc349897d 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -454,9 +454,6 @@ way. From the PyXML setup script:: scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] ) -.. versionchanged:: 2.7 - All the scripts will also be added to the ``MANIFEST`` - file if no template is provided. See :ref:`manifest`. .. _distutils-installing-package-data: @@ -501,11 +498,6 @@ The corresponding call to :func:`setup` might be:: ) -.. versionchanged:: 2.7 - All the files that match ``package_data`` will be added to the ``MANIFEST`` - file if no template is provided. See :ref:`manifest`. - - .. _distutils-additional-files: Installing Additional Files @@ -542,11 +534,6 @@ without specifying a target directory, but this is not recommended, and the files directly in the target directory, an empty string should be given as the directory. -.. versionchanged:: 2.7 - All the files that match ``data_files`` will be added to the ``MANIFEST`` - file if no template is provided. See :ref:`manifest`. - - .. _meta-data: From 61ef5ce9feadf8a9d0c71430bf356ba1896377d7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 27 Apr 2009 08:58:15 +0000 Subject: [PATCH 085/330] Reintroduce versionchanged tags, but with correct version. --- setupscript.rst | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index bbc349897d..13c42b6b41 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -454,6 +454,10 @@ way. From the PyXML setup script:: scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val'] ) +.. versionchanged:: 3.1 + All the scripts will also be added to the ``MANIFEST`` file if no template is + provided. See :ref:`manifest`. + .. _distutils-installing-package-data: @@ -498,6 +502,11 @@ The corresponding call to :func:`setup` might be:: ) +.. versionchanged:: 3.1 + All the files that match ``package_data`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. + + .. _distutils-additional-files: Installing Additional Files @@ -534,6 +543,10 @@ without specifying a target directory, but this is not recommended, and the files directly in the target directory, an empty string should be given as the directory. +.. versionchanged:: 3.1 + All the files that match ``data_files`` will be added to the ``MANIFEST`` + file if no template is provided. See :ref:`manifest`. + .. _meta-data: From 2591f871564dd86a8eabf06b91c88462b0a4dc72 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 27 Apr 2009 15:10:44 +0000 Subject: [PATCH 086/330] Remove ".. warning::" markup that doesnt contain warnings for users, rather todo items. --- apiref.rst | 25 +++++++------------------ 1 file changed, 7 insertions(+), 18 deletions(-) diff --git a/apiref.rst b/apiref.rst index 79e13c1810..fa28516167 100644 --- a/apiref.rst +++ b/apiref.rst @@ -869,9 +869,7 @@ tarballs or zipfiles. prefix of all files and directories in the archive. *root_dir* and *base_dir* both default to the current directory. Returns the name of the archive file. - .. warning:: - - This should be changed to support bz2 files + .. XXX This should be changed to support bz2 files. .. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) @@ -884,9 +882,7 @@ tarballs or zipfiles. possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2` or :file:`.Z`). Return the output filename. - .. warning:: - - This should be replaced with calls to the :mod:`tarfile` module. + .. XXX This should be replaced with calls to the :mod:`tarfile` module. .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) @@ -1329,10 +1325,8 @@ provides the following additional features: Wraps *text* to less than *width* wide. - .. warning:: - - Should be replaced with :mod:`textwrap` (which is available in Python 2.3 and - later). + .. XXX Should be replaced with :mod:`textwrap` (which is available in Python + 2.3 and later). .. class:: FancyGetopt([option_table=None]) @@ -1381,8 +1375,8 @@ The :class:`FancyGetopt` class provides the following methods: ================================================ .. module:: distutils.filelist - :synopsis: The FileList class, used for poking about the file system and building lists of - files. + :synopsis: The FileList class, used for poking about the file system and + building lists of files. This module provides the :class:`FileList` class, used for poking about the @@ -1396,13 +1390,8 @@ filesystem and building lists of files. :synopsis: A simple logging mechanism, 282-style -.. warning:: - - Should be replaced with standard :mod:`logging` module. +.. XXX Should be replaced with standard :mod:`logging` module. -.. % \subsubsection{\module{} --- } -.. % \declaremodule{standard}{distutils.magic} -.. % \modulesynopsis{ } :mod:`distutils.spawn` --- Spawn a sub-process From f39ff6c5f650d0b4a90b492ccd354971bbd66a6a Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 27 Apr 2009 16:23:47 +0000 Subject: [PATCH 087/330] Merged revisions 72008 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r72008 | georg.brandl | 2009-04-27 17:10:44 +0200 (Mo, 27 Apr 2009) | 1 line Remove ".. warning::" markup that doesnt contain warnings for users, rather todo items. ........ --- apiref.rst | 25 +++++++------------------ 1 file changed, 7 insertions(+), 18 deletions(-) diff --git a/apiref.rst b/apiref.rst index 490e7f3560..8abd0e37cb 100644 --- a/apiref.rst +++ b/apiref.rst @@ -869,9 +869,7 @@ tarballs or zipfiles. prefix of all files and directories in the archive. *root_dir* and *base_dir* both default to the current directory. Returns the name of the archive file. - .. warning:: - - This should be changed to support bz2 files + .. XXX This should be changed to support bz2 files. .. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) @@ -884,9 +882,7 @@ tarballs or zipfiles. possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2` or :file:`.Z`). Return the output filename. - .. warning:: - - This should be replaced with calls to the :mod:`tarfile` module. + .. XXX This should be replaced with calls to the :mod:`tarfile` module. .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) @@ -1329,10 +1325,8 @@ provides the following additional features: Wraps *text* to less than *width* wide. - .. warning:: - - Should be replaced with :mod:`textwrap` (which is available in Python 2.3 and - later). + .. XXX Should be replaced with :mod:`textwrap` (which is available in Python + 2.3 and later). .. class:: FancyGetopt([option_table=None]) @@ -1381,8 +1375,8 @@ The :class:`FancyGetopt` class provides the following methods: ================================================ .. module:: distutils.filelist - :synopsis: The FileList class, used for poking about the file system and building lists of - files. + :synopsis: The FileList class, used for poking about the file system and + building lists of files. This module provides the :class:`FileList` class, used for poking about the @@ -1396,13 +1390,8 @@ filesystem and building lists of files. :synopsis: A simple logging mechanism, 282-style -.. warning:: - - Should be replaced with standard :mod:`logging` module. +.. XXX Should be replaced with standard :mod:`logging` module. -.. % \subsubsection{\module{} --- } -.. % \declaremodule{standard}{distutils.magic} -.. % \modulesynopsis{ } :mod:`distutils.spawn` --- Spawn a sub-process From 7f56aed31a4f22b34df9907d65875131133461bd Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 28 Apr 2009 18:23:28 +0000 Subject: [PATCH 088/330] Merged revisions 72007-72010,72036-72037 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r72007 | georg.brandl | 2009-04-27 17:09:25 +0200 (Mo, 27 Apr 2009) | 1 line #5856: fix typo s in traceback example. ........ r72008 | georg.brandl | 2009-04-27 17:10:44 +0200 (Mo, 27 Apr 2009) | 1 line Remove ".. warning::" markup that doesnt contain warnings for users, rather todo items. ........ r72009 | georg.brandl | 2009-04-27 17:29:09 +0200 (Mo, 27 Apr 2009) | 3 lines Demote warnings to notices where appropriate, following the goal that as few "red box" warnings should clutter the docs as possible. Part 1: stuff that gets merged to Py3k. ........ r72010 | georg.brandl | 2009-04-27 17:29:26 +0200 (Mo, 27 Apr 2009) | 2 lines Demote warnings to notices, part 2: stuff that is 2.x-only. ........ r72036 | georg.brandl | 2009-04-27 19:04:23 +0200 (Mo, 27 Apr 2009) | 1 line #5848: small unittest doc patch. ........ r72037 | georg.brandl | 2009-04-27 19:09:53 +0200 (Mo, 27 Apr 2009) | 1 line #5840: dont claim we dont support TLS. ........ --- apiref.rst | 25 +++++++------------------ 1 file changed, 7 insertions(+), 18 deletions(-) diff --git a/apiref.rst b/apiref.rst index 20bb31a106..a7db455d68 100644 --- a/apiref.rst +++ b/apiref.rst @@ -886,9 +886,7 @@ tarballs or zipfiles. prefix of all files and directories in the archive. *root_dir* and *base_dir* both default to the current directory. Returns the name of the archive file. - .. warning:: - - This should be changed to support bz2 files + .. XXX This should be changed to support bz2 files. .. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) @@ -901,9 +899,7 @@ tarballs or zipfiles. possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2` or :file:`.Z`). Return the output filename. - .. warning:: - - This should be replaced with calls to the :mod:`tarfile` module. + .. XXX This should be replaced with calls to the :mod:`tarfile` module. .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) @@ -1346,10 +1342,8 @@ provides the following additional features: Wraps *text* to less than *width* wide. - .. warning:: - - Should be replaced with :mod:`textwrap` (which is available in Python 2.3 and - later). + .. XXX Should be replaced with :mod:`textwrap` (which is available in Python + 2.3 and later). .. class:: FancyGetopt([option_table=None]) @@ -1398,8 +1392,8 @@ The :class:`FancyGetopt` class provides the following methods: ================================================ .. module:: distutils.filelist - :synopsis: The FileList class, used for poking about the file system and building lists of - files. + :synopsis: The FileList class, used for poking about the file system and + building lists of files. This module provides the :class:`FileList` class, used for poking about the @@ -1413,13 +1407,8 @@ filesystem and building lists of files. :synopsis: A simple logging mechanism, 282-style -.. warning:: - - Should be replaced with standard :mod:`logging` module. +.. XXX Should be replaced with standard :mod:`logging` module. -.. % \subsubsection{\module{} --- } -.. % \declaremodule{standard}{distutils.magic} -.. % \modulesynopsis{ } :mod:`distutils.spawn` --- Spawn a sub-process From 6ba6564829099dfbad7133f4c0e8a0d70fe5c419 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Tue, 16 Jun 2009 07:29:52 +0000 Subject: [PATCH 089/330] Fixed #6287: documentation for the license field in distutils --- setupscript.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 851c904848..bf4eeeb89a 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -590,6 +590,8 @@ This information includes: +----------------------+---------------------------+-----------------+--------+ | ``platforms`` | a list of platforms | list of strings | | +----------------------+---------------------------+-----------------+--------+ +| ``license`` | license for the package | short string | \(6) | ++----------------------+---------------------------+-----------------+--------+ Notes: @@ -611,6 +613,13 @@ Notes: The ``long_description`` field is used by PyPI when you are registering a package, to build its home page. +(6) + The ``license`` field is a text indicating the license covering the + package where the license is not a selection from the "License" Trove + classifiers. See the ``Classifier`` field. Notice that + there's a ``licence`` distribution option which is deprecated but still + acts as an alias for ``license``. + 'short string' A single line of text, not more than 200 characters. From 19fc0a23317644641ef58e43ebec00aed16d0827 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Tue, 16 Jun 2009 07:41:29 +0000 Subject: [PATCH 090/330] Merged revisions 73441 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r73441 | tarek.ziade | 2009-06-16 09:29:52 +0200 (Tue, 16 Jun 2009) | 1 line Fixed #6287: documentation for the license field in distutils ........ --- setupscript.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 997dab7fb3..a258e28bc8 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -565,6 +565,8 @@ This information includes: +----------------------+---------------------------+-----------------+--------+ | ``platforms`` | a list of platforms | list of strings | | +----------------------+---------------------------+-----------------+--------+ +| ``license`` | license for the package | short string | \(6) | ++----------------------+---------------------------+-----------------+--------+ Notes: @@ -582,6 +584,13 @@ Notes: versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website `_. +(6) + The ``license`` field is a text indicating the license covering the + package where the license is not a selection from the "License" Trove + classifiers. See the ``Classifier`` field. Notice that + there's a ``licence`` distribution option which is deprecated but still + acts as an alias for ``license``. + 'short string' A single line of text, not more than 200 characters. From 77eeb2615de9748a9088d06efc16fbabeb7853f8 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Tue, 16 Jun 2009 07:43:42 +0000 Subject: [PATCH 091/330] Merged revisions 73441 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r73441 | tarek.ziade | 2009-06-16 09:29:52 +0200 (Tue, 16 Jun 2009) | 1 line Fixed #6287: documentation for the license field in distutils ........ --- setupscript.rst | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/setupscript.rst b/setupscript.rst index 13c42b6b41..e7c630054a 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -589,6 +589,8 @@ This information includes: +----------------------+---------------------------+-----------------+--------+ | ``platforms`` | a list of platforms | list of strings | | +----------------------+---------------------------+-----------------+--------+ +| ``license`` | license for the package | short string | \(6) | ++----------------------+---------------------------+-----------------+--------+ Notes: @@ -610,6 +612,13 @@ Notes: The ``long_description`` field is used by PyPI when you are registering a package, to build its home page. +(6) + The ``license`` field is a text indicating the license covering the + package where the license is not a selection from the "License" Trove + classifiers. See the ``Classifier`` field. Notice that + there's a ``licence`` distribution option which is deprecated but still + acts as an alias for ``license``. + 'short string' A single line of text, not more than 200 characters. From 0731522b559cb14c88e62963743141581b76f73e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 26 Jul 2009 14:37:28 +0000 Subject: [PATCH 092/330] builtin -> built-in. --- apiref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index fa28516167..f0408e8ab1 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1601,7 +1601,7 @@ lines, and joining lines with backslashes. +------------------+--------------------------------+---------+ Note that since *rstrip_ws* can strip the trailing newline, the semantics of - :meth:`readline` must differ from those of the builtin file object's + :meth:`readline` must differ from those of the built-in file object's :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for end-of-file: an empty string might just be a blank line (or an all-whitespace line), if *rstrip_ws* is true but *skip_blanks* is not. @@ -1609,8 +1609,8 @@ lines, and joining lines with backslashes. .. method:: TextFile.open(filename) - Open a new file *filename*. This overrides any *file* or *filename* constructor - arguments. + Open a new file *filename*. This overrides any *file* or *filename* + constructor arguments. .. method:: TextFile.close() From 7e84020a8fd5c745c6dcb893e122b4cd8485f640 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 26 Jul 2009 14:54:51 +0000 Subject: [PATCH 093/330] Merged revisions 74209 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74209 | georg.brandl | 2009-07-26 16:37:28 +0200 (So, 26 Jul 2009) | 1 line builtin -> built-in. ........ --- apiref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 8abd0e37cb..643825766a 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1601,7 +1601,7 @@ lines, and joining lines with backslashes. +------------------+--------------------------------+---------+ Note that since *rstrip_ws* can strip the trailing newline, the semantics of - :meth:`readline` must differ from those of the builtin file object's + :meth:`readline` must differ from those of the built-in file object's :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for end-of-file: an empty string might just be a blank line (or an all-whitespace line), if *rstrip_ws* is true but *skip_blanks* is not. @@ -1609,8 +1609,8 @@ lines, and joining lines with backslashes. .. method:: TextFile.open(filename) - Open a new file *filename*. This overrides any *file* or *filename* constructor - arguments. + Open a new file *filename*. This overrides any *file* or *filename* + constructor arguments. .. method:: TextFile.close() From ff4f4df6959c9117677e83bc8047dcf8d03f218b Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 13 Aug 2009 08:26:44 +0000 Subject: [PATCH 094/330] Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ................ r73941 | georg.brandl | 2009-07-11 12:39:00 +0200 (Sa, 11 Jul 2009) | 9 lines Merged revisions 73940 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r73940 | georg.brandl | 2009-07-11 12:37:38 +0200 (Sa, 11 Jul 2009) | 1 line #6430: add note about size of "u" type. ........ ................ r73942 | georg.brandl | 2009-07-11 12:39:23 +0200 (Sa, 11 Jul 2009) | 1 line #6430: remove mention of "w" array typecode. ................ r73943 | georg.brandl | 2009-07-11 12:43:08 +0200 (Sa, 11 Jul 2009) | 1 line #6421: The self argument of module-level PyCFunctions is now a reference to the module object. ................ r74076 | georg.brandl | 2009-07-18 11:07:48 +0200 (Sa, 18 Jul 2009) | 1 line #6502: add missing comma in docstring. ................ r74094 | georg.brandl | 2009-07-19 09:25:56 +0200 (So, 19 Jul 2009) | 10 lines Recorded merge of revisions 74089 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74089 | senthil.kumaran | 2009-07-19 04:43:43 +0200 (So, 19 Jul 2009) | 3 lines Fix for issue5102, timeout value propages between redirects, proxy, digest and auth handlers. Fixed tests to reflect the same. ........ ................ r74186 | georg.brandl | 2009-07-23 11:19:09 +0200 (Do, 23 Jul 2009) | 9 lines Recorded merge of revisions 74185 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74185 | georg.brandl | 2009-07-23 11:17:09 +0200 (Do, 23 Jul 2009) | 1 line Fix the "pylocals" gdb command. ........ ................ r74211 | georg.brandl | 2009-07-26 16:48:09 +0200 (So, 26 Jul 2009) | 9 lines Recorded merge of revisions 74210 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74210 | georg.brandl | 2009-07-26 16:44:23 +0200 (So, 26 Jul 2009) | 1 line Move member descriptions inside the classes. ........ ................ r74212 | georg.brandl | 2009-07-26 16:54:51 +0200 (So, 26 Jul 2009) | 9 lines Merged revisions 74209 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74209 | georg.brandl | 2009-07-26 16:37:28 +0200 (So, 26 Jul 2009) | 1 line builtin -> built-in. ........ ................ r74213 | georg.brandl | 2009-07-26 17:02:41 +0200 (So, 26 Jul 2009) | 9 lines Merged revisions 74207 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74207 | georg.brandl | 2009-07-26 16:19:57 +0200 (So, 26 Jul 2009) | 1 line #6577: fix (hopefully) all links to builtin instead of module/class-specific objects. ........ ................ r74214 | georg.brandl | 2009-07-26 17:03:49 +0200 (So, 26 Jul 2009) | 9 lines Merged revisions 74205 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74205 | georg.brandl | 2009-07-26 15:36:39 +0200 (So, 26 Jul 2009) | 1 line #6576: fix cross-refs in re docs. ........ ................ r74247 | georg.brandl | 2009-07-29 09:27:08 +0200 (Mi, 29 Jul 2009) | 9 lines Merged revisions 74239 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74239 | georg.brandl | 2009-07-28 18:55:32 +0000 (Di, 28 Jul 2009) | 1 line Clarify quote_plus() usage. ........ ................ r74254 | georg.brandl | 2009-07-29 18:14:16 +0200 (Mi, 29 Jul 2009) | 1 line #6586: fix return/argument type doc for os.read() and os.write(). ................ r74262 | alexandre.vassalotti | 2009-07-29 21:54:39 +0200 (Mi, 29 Jul 2009) | 57 lines Merged revisions 74074,74077,74111,74188,74192-74193,74200,74252-74253,74258-74261 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74074 | georg.brandl | 2009-07-18 05:03:10 -0400 (Sat, 18 Jul 2009) | 1 line #6513: fix example code: warning categories are classes, not instances. ........ r74077 | georg.brandl | 2009-07-18 05:43:40 -0400 (Sat, 18 Jul 2009) | 1 line #6489: fix an ambiguity in getiterator() documentation. ........ r74111 | benjamin.peterson | 2009-07-20 09:30:10 -0400 (Mon, 20 Jul 2009) | 1 line remove docs for deprecated -p option ........ r74188 | benjamin.peterson | 2009-07-23 10:25:31 -0400 (Thu, 23 Jul 2009) | 1 line use bools ........ r74192 | georg.brandl | 2009-07-24 12:28:38 -0400 (Fri, 24 Jul 2009) | 1 line Fix arg types of et#. ........ r74193 | georg.brandl | 2009-07-24 12:46:38 -0400 (Fri, 24 Jul 2009) | 1 line Dont put "void" in signature for nullary functions. ........ r74200 | georg.brandl | 2009-07-25 09:02:15 -0400 (Sat, 25 Jul 2009) | 1 line #6571: add index entries for more operators. ........ r74252 | georg.brandl | 2009-07-29 12:06:31 -0400 (Wed, 29 Jul 2009) | 1 line #6593: fix link targets. ........ r74253 | georg.brandl | 2009-07-29 12:09:17 -0400 (Wed, 29 Jul 2009) | 1 line #6591: add reference to ioctl in fcntl module for platforms other than Windows. ........ r74258 | georg.brandl | 2009-07-29 12:57:05 -0400 (Wed, 29 Jul 2009) | 1 line Add a link to readline, and mention IPython and bpython. ........ r74259 | georg.brandl | 2009-07-29 13:07:21 -0400 (Wed, 29 Jul 2009) | 1 line Fix some markup and small factual glitches found by M. Markert. ........ r74260 | georg.brandl | 2009-07-29 13:15:20 -0400 (Wed, 29 Jul 2009) | 1 line Fix a few markup glitches. ........ r74261 | georg.brandl | 2009-07-29 13:50:25 -0400 (Wed, 29 Jul 2009) | 1 line Rewrite the section about classes a bit; mostly tidbits, and a larger update to the section about "private" variables to reflect the Pythonic consensus better. ........ ................ r74311 | georg.brandl | 2009-08-04 22:29:27 +0200 (Di, 04 Aug 2009) | 1 line Slightly improve buffer-related error message. ................ r74334 | georg.brandl | 2009-08-06 19:51:03 +0200 (Do, 06 Aug 2009) | 1 line #6648: mention surrogateescape handler where all standard handlers are listed. ................ r74368 | georg.brandl | 2009-08-13 09:56:35 +0200 (Do, 13 Aug 2009) | 21 lines Merged revisions 74328,74332-74333,74365 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74328 | georg.brandl | 2009-08-06 17:06:25 +0200 (Do, 06 Aug 2009) | 1 line Fix base keyword arg name for int() and long(). ........ r74332 | georg.brandl | 2009-08-06 19:23:21 +0200 (Do, 06 Aug 2009) | 1 line Fix punctuation and one copy-paste error. ........ r74333 | georg.brandl | 2009-08-06 19:43:55 +0200 (Do, 06 Aug 2009) | 1 line #6658: fix two typos. ........ r74365 | georg.brandl | 2009-08-13 09:48:05 +0200 (Do, 13 Aug 2009) | 1 line #6679: Remove mention that sub supports no flags. ........ ................ --- apiref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 8abd0e37cb..643825766a 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1601,7 +1601,7 @@ lines, and joining lines with backslashes. +------------------+--------------------------------+---------+ Note that since *rstrip_ws* can strip the trailing newline, the semantics of - :meth:`readline` must differ from those of the builtin file object's + :meth:`readline` must differ from those of the built-in file object's :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for end-of-file: an empty string might just be a blank line (or an all-whitespace line), if *rstrip_ws* is true but *skip_blanks* is not. @@ -1609,8 +1609,8 @@ lines, and joining lines with backslashes. .. method:: TextFile.open(filename) - Open a new file *filename*. This overrides any *file* or *filename* constructor - arguments. + Open a new file *filename*. This overrides any *file* or *filename* + constructor arguments. .. method:: TextFile.close() From 896be188802d495d7479dfe5b3a738948afbcf26 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 11 Sep 2009 07:55:20 +0000 Subject: [PATCH 095/330] Move function back to its section. --- builtdist.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 6e7e51c04e..e58937d200 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -429,13 +429,6 @@ built-in functions in the installation script. also the configuration. For details refer to Microsoft's documentation of the :cfunc:`SHGetSpecialFolderPath` function. -Vista User Access Control (UAC) -=============================== - -Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` -option. The default is 'none' (meaning no UAC handling is done), and other -valid values are 'auto' (meaning prompt for UAC elevation if Python was -installed for all users) and 'force' (meaning always prompt for elevation) .. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) @@ -447,3 +440,12 @@ installed for all users) and 'force' (meaning always prompt for elevation) and *iconindex* is the index of the icon in the file *iconpath*. Again, for details consult the Microsoft documentation for the :class:`IShellLink` interface. + + +Vista User Access Control (UAC) +=============================== + +Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` +option. The default is 'none' (meaning no UAC handling is done), and other +valid values are 'auto' (meaning prompt for UAC elevation if Python was +installed for all users) and 'force' (meaning always prompt for elevation). From 9782dfb1b86de4adb58e2997f0c0f1e961513b03 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Fri, 11 Sep 2009 22:24:02 +0000 Subject: [PATCH 096/330] Merged revisions 74277,74321,74323,74326,74355,74465,74467,74488,74492,74513,74531,74549,74553,74625,74632,74643-74644,74647,74652,74666,74671,74727,74739 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74277 | sean.reifschneider | 2009-08-01 18:54:55 -0500 (Sat, 01 Aug 2009) | 3 lines - Issue #6624: yArg_ParseTuple with "s" format when parsing argument with NUL: Bogus TypeError detail string. ........ r74321 | guilherme.polo | 2009-08-05 11:51:41 -0500 (Wed, 05 Aug 2009) | 1 line Easier reference to find (at least while svn continues being used). ........ r74323 | guilherme.polo | 2009-08-05 18:48:26 -0500 (Wed, 05 Aug 2009) | 1 line Typo. ........ r74326 | jesse.noller | 2009-08-05 21:05:56 -0500 (Wed, 05 Aug 2009) | 1 line Fix issue 4660: spurious task_done errors in multiprocessing, remove doc note for from_address ........ r74355 | gregory.p.smith | 2009-08-12 12:02:37 -0500 (Wed, 12 Aug 2009) | 2 lines comment typo fix ........ r74465 | vinay.sajip | 2009-08-15 18:23:12 -0500 (Sat, 15 Aug 2009) | 1 line Added section on logging to one file from multiple processes. ........ r74467 | vinay.sajip | 2009-08-15 18:34:47 -0500 (Sat, 15 Aug 2009) | 1 line Refined section on logging to one file from multiple processes. ........ r74488 | vinay.sajip | 2009-08-17 08:14:37 -0500 (Mon, 17 Aug 2009) | 1 line Further refined section on logging to one file from multiple processes. ........ r74492 | r.david.murray | 2009-08-17 14:26:49 -0500 (Mon, 17 Aug 2009) | 2 lines Issue 6685: 'toupper' -> 'upper' in cgi doc example explanation. ........ r74513 | skip.montanaro | 2009-08-18 09:37:52 -0500 (Tue, 18 Aug 2009) | 1 line missing module ref (issue6723) ........ r74531 | vinay.sajip | 2009-08-20 17:04:32 -0500 (Thu, 20 Aug 2009) | 1 line Added section on exceptions raised during logging. ........ r74549 | benjamin.peterson | 2009-08-24 12:42:36 -0500 (Mon, 24 Aug 2009) | 1 line fix pdf building by teaching latex the right encoding package ........ r74553 | r.david.murray | 2009-08-26 20:04:59 -0500 (Wed, 26 Aug 2009) | 2 lines Remove leftover text from end of sentence. ........ r74625 | benjamin.peterson | 2009-09-01 17:27:57 -0500 (Tue, 01 Sep 2009) | 1 line remove the check that classmethod's argument is a callable ........ r74632 | georg.brandl | 2009-09-03 02:27:26 -0500 (Thu, 03 Sep 2009) | 1 line #6828: fix wrongly highlighted blocks. ........ r74643 | georg.brandl | 2009-09-04 01:59:20 -0500 (Fri, 04 Sep 2009) | 2 lines Issue #2666: Handle BROWSER environment variable properly for unknown browser names in the webbrowser module. ........ r74644 | georg.brandl | 2009-09-04 02:55:14 -0500 (Fri, 04 Sep 2009) | 1 line #5047: remove Monterey support from configure. ........ r74647 | georg.brandl | 2009-09-04 03:17:04 -0500 (Fri, 04 Sep 2009) | 2 lines Issue #5275: In Cookie's Cookie.load(), properly handle non-string arguments as documented. ........ r74652 | georg.brandl | 2009-09-04 06:25:37 -0500 (Fri, 04 Sep 2009) | 1 line #6756: add some info about the "acct" parameter. ........ r74666 | georg.brandl | 2009-09-05 04:04:09 -0500 (Sat, 05 Sep 2009) | 1 line #6841: remove duplicated word. ........ r74671 | georg.brandl | 2009-09-05 11:47:17 -0500 (Sat, 05 Sep 2009) | 1 line #6843: add link from filterwarnings to where the meaning of the arguments is covered. ........ r74727 | benjamin.peterson | 2009-09-08 18:04:22 -0500 (Tue, 08 Sep 2009) | 1 line #6865 fix ref counting in initialization of pwd module ........ r74739 | georg.brandl | 2009-09-11 02:55:20 -0500 (Fri, 11 Sep 2009) | 1 line Move function back to its section. ........ --- builtdist.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 6e7e51c04e..e58937d200 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -429,13 +429,6 @@ built-in functions in the installation script. also the configuration. For details refer to Microsoft's documentation of the :cfunc:`SHGetSpecialFolderPath` function. -Vista User Access Control (UAC) -=============================== - -Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` -option. The default is 'none' (meaning no UAC handling is done), and other -valid values are 'auto' (meaning prompt for UAC elevation if Python was -installed for all users) and 'force' (meaning always prompt for elevation) .. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) @@ -447,3 +440,12 @@ installed for all users) and 'force' (meaning always prompt for elevation) and *iconindex* is the index of the icon in the file *iconpath*. Again, for details consult the Microsoft documentation for the :class:`IShellLink` interface. + + +Vista User Access Control (UAC) +=============================== + +Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` +option. The default is 'none' (meaning no UAC handling is done), and other +valid values are 'auto' (meaning prompt for UAC elevation if Python was +installed for all users) and 'force' (meaning always prompt for elevation). From 8944d66672cfbe24e3ec7639bacbebbbf6ddb57f Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Fri, 11 Sep 2009 22:36:27 +0000 Subject: [PATCH 097/330] Merged revisions 74745 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ................ r74745 | benjamin.peterson | 2009-09-11 17:24:02 -0500 (Fri, 11 Sep 2009) | 98 lines Merged revisions 74277,74321,74323,74326,74355,74465,74467,74488,74492,74513,74531,74549,74553,74625,74632,74643-74644,74647,74652,74666,74671,74727,74739 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74277 | sean.reifschneider | 2009-08-01 18:54:55 -0500 (Sat, 01 Aug 2009) | 3 lines - Issue #6624: yArg_ParseTuple with "s" format when parsing argument with NUL: Bogus TypeError detail string. ........ r74321 | guilherme.polo | 2009-08-05 11:51:41 -0500 (Wed, 05 Aug 2009) | 1 line Easier reference to find (at least while svn continues being used). ........ r74323 | guilherme.polo | 2009-08-05 18:48:26 -0500 (Wed, 05 Aug 2009) | 1 line Typo. ........ r74326 | jesse.noller | 2009-08-05 21:05:56 -0500 (Wed, 05 Aug 2009) | 1 line Fix issue 4660: spurious task_done errors in multiprocessing, remove doc note for from_address ........ r74355 | gregory.p.smith | 2009-08-12 12:02:37 -0500 (Wed, 12 Aug 2009) | 2 lines comment typo fix ........ r74465 | vinay.sajip | 2009-08-15 18:23:12 -0500 (Sat, 15 Aug 2009) | 1 line Added section on logging to one file from multiple processes. ........ r74467 | vinay.sajip | 2009-08-15 18:34:47 -0500 (Sat, 15 Aug 2009) | 1 line Refined section on logging to one file from multiple processes. ........ r74488 | vinay.sajip | 2009-08-17 08:14:37 -0500 (Mon, 17 Aug 2009) | 1 line Further refined section on logging to one file from multiple processes. ........ r74492 | r.david.murray | 2009-08-17 14:26:49 -0500 (Mon, 17 Aug 2009) | 2 lines Issue 6685: 'toupper' -> 'upper' in cgi doc example explanation. ........ r74513 | skip.montanaro | 2009-08-18 09:37:52 -0500 (Tue, 18 Aug 2009) | 1 line missing module ref (issue6723) ........ r74531 | vinay.sajip | 2009-08-20 17:04:32 -0500 (Thu, 20 Aug 2009) | 1 line Added section on exceptions raised during logging. ........ r74549 | benjamin.peterson | 2009-08-24 12:42:36 -0500 (Mon, 24 Aug 2009) | 1 line fix pdf building by teaching latex the right encoding package ........ r74553 | r.david.murray | 2009-08-26 20:04:59 -0500 (Wed, 26 Aug 2009) | 2 lines Remove leftover text from end of sentence. ........ r74625 | benjamin.peterson | 2009-09-01 17:27:57 -0500 (Tue, 01 Sep 2009) | 1 line remove the check that classmethod's argument is a callable ........ r74632 | georg.brandl | 2009-09-03 02:27:26 -0500 (Thu, 03 Sep 2009) | 1 line #6828: fix wrongly highlighted blocks. ........ r74643 | georg.brandl | 2009-09-04 01:59:20 -0500 (Fri, 04 Sep 2009) | 2 lines Issue #2666: Handle BROWSER environment variable properly for unknown browser names in the webbrowser module. ........ r74644 | georg.brandl | 2009-09-04 02:55:14 -0500 (Fri, 04 Sep 2009) | 1 line #5047: remove Monterey support from configure. ........ r74647 | georg.brandl | 2009-09-04 03:17:04 -0500 (Fri, 04 Sep 2009) | 2 lines Issue #5275: In Cookie's Cookie.load(), properly handle non-string arguments as documented. ........ r74652 | georg.brandl | 2009-09-04 06:25:37 -0500 (Fri, 04 Sep 2009) | 1 line #6756: add some info about the "acct" parameter. ........ r74666 | georg.brandl | 2009-09-05 04:04:09 -0500 (Sat, 05 Sep 2009) | 1 line #6841: remove duplicated word. ........ r74671 | georg.brandl | 2009-09-05 11:47:17 -0500 (Sat, 05 Sep 2009) | 1 line #6843: add link from filterwarnings to where the meaning of the arguments is covered. ........ r74727 | benjamin.peterson | 2009-09-08 18:04:22 -0500 (Tue, 08 Sep 2009) | 1 line #6865 fix ref counting in initialization of pwd module ........ r74739 | georg.brandl | 2009-09-11 02:55:20 -0500 (Fri, 11 Sep 2009) | 1 line Move function back to its section. ........ ................ --- builtdist.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 6e7e51c04e..e58937d200 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -429,13 +429,6 @@ built-in functions in the installation script. also the configuration. For details refer to Microsoft's documentation of the :cfunc:`SHGetSpecialFolderPath` function. -Vista User Access Control (UAC) -=============================== - -Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` -option. The default is 'none' (meaning no UAC handling is done), and other -valid values are 'auto' (meaning prompt for UAC elevation if Python was -installed for all users) and 'force' (meaning always prompt for elevation) .. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) @@ -447,3 +440,12 @@ installed for all users) and 'force' (meaning always prompt for elevation) and *iconindex* is the index of the icon in the file *iconpath*. Again, for details consult the Microsoft documentation for the :class:`IShellLink` interface. + + +Vista User Access Control (UAC) +=============================== + +Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` +option. The default is 'none' (meaning no UAC handling is done), and other +valid values are 'auto' (meaning prompt for UAC elevation if Python was +installed for all users) and 'force' (meaning always prompt for elevation). From 1756fda07d5e6eda3d310a127bfce7b29c63cec2 Mon Sep 17 00:00:00 2001 From: Ronald Oussoren Date: Tue, 15 Sep 2009 19:13:15 +0000 Subject: [PATCH 098/330] Finish support for --with-universal-archs=intel and --with-universal-archs=3-way (issue6245) --- apiref.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index f0408e8ab1..e227833ea4 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1095,7 +1095,10 @@ other utility module. the univeral binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is ``fat``, for 64-bit universal binaries the architecture is ``fat64``, and - for 4-way universal binaries the architecture is ``universal``. + for 4-way universal binaries the architecture is ``universal``. Starting + from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for + a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for + a univeral build with the i386 and x86_64 architectures Examples of returned values on Mac OS X: @@ -1105,6 +1108,8 @@ other utility module. * ``macosx-10.5-universal`` + * ``macosx-10.6-intel`` + .. % XXX isn't this also provided by some other non-distutils module? From 3ae812086ec12d053cd01f094c13f0b2c056f669 Mon Sep 17 00:00:00 2001 From: Ronald Oussoren Date: Tue, 15 Sep 2009 19:14:37 +0000 Subject: [PATCH 099/330] Merged revisions 74806 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74806 | ronald.oussoren | 2009-09-15 21:13:15 +0200 (Tue, 15 Sep 2009) | 3 lines Finish support for --with-universal-archs=intel and --with-universal-archs=3-way (issue6245) ........ --- apiref.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index a7db455d68..995b76748e 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1112,7 +1112,10 @@ other utility module. the univeral binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is ``fat``, for 64-bit universal binaries the architecture is ``fat64``, and - for 4-way universal binaries the architecture is ``universal``. + for 4-way universal binaries the architecture is ``universal``. Starting + from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for + a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for + a univeral build with the i386 and x86_64 architectures Examples of returned values on Mac OS X: @@ -1122,6 +1125,8 @@ other utility module. * ``macosx-10.5-universal`` + * ``macosx-10.6-intel`` + .. % XXX isn't this also provided by some other non-distutils module? From 7360d223f111956da9481344da040fb4efc6839a Mon Sep 17 00:00:00 2001 From: Ronald Oussoren Date: Tue, 15 Sep 2009 19:16:02 +0000 Subject: [PATCH 100/330] Merged revisions 74806 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74806 | ronald.oussoren | 2009-09-15 21:13:15 +0200 (Tue, 15 Sep 2009) | 3 lines Finish support for --with-universal-archs=intel and --with-universal-archs=3-way (issue6245) ........ --- apiref.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 643825766a..af19111dfb 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1095,7 +1095,10 @@ other utility module. the univeral binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is ``fat``, for 64-bit universal binaries the architecture is ``fat64``, and - for 4-way universal binaries the architecture is ``universal``. + for 4-way universal binaries the architecture is ``universal``. Starting + from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for + a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for + a univeral build with the i386 and x86_64 architectures Examples of returned values on Mac OS X: @@ -1105,6 +1108,8 @@ other utility module. * ``macosx-10.5-universal`` + * ``macosx-10.6-intel`` + .. % XXX isn't this also provided by some other non-distutils module? From 10de28c13343eeb0cb9d0b79b8ebac972b612565 Mon Sep 17 00:00:00 2001 From: Ronald Oussoren Date: Tue, 15 Sep 2009 19:16:40 +0000 Subject: [PATCH 101/330] Merged revisions 74808 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ................ r74808 | ronald.oussoren | 2009-09-15 21:16:02 +0200 (Tue, 15 Sep 2009) | 10 lines Merged revisions 74806 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74806 | ronald.oussoren | 2009-09-15 21:13:15 +0200 (Tue, 15 Sep 2009) | 3 lines Finish support for --with-universal-archs=intel and --with-universal-archs=3-way (issue6245) ........ ................ --- apiref.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 643825766a..af19111dfb 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1095,7 +1095,10 @@ other utility module. the univeral binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is ``fat``, for 64-bit universal binaries the architecture is ``fat64``, and - for 4-way universal binaries the architecture is ``universal``. + for 4-way universal binaries the architecture is ``universal``. Starting + from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for + a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for + a univeral build with the i386 and x86_64 architectures Examples of returned values on Mac OS X: @@ -1105,6 +1108,8 @@ other utility module. * ``macosx-10.5-universal`` + * ``macosx-10.6-intel`` + .. % XXX isn't this also provided by some other non-distutils module? From 2c2910e7155c1dff8d6b15a6c13c4aee8752df12 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Fri, 2 Oct 2009 23:49:48 +0000 Subject: [PATCH 102/330] #6516 added owner/group support for tarfiles in Distutils --- sourcedist.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 0c786c5a0a..94fa338c19 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -26,16 +26,16 @@ to create a gzipped tarball and a zip file. The available formats are: +===========+=========================+=========+ | ``zip`` | zip file (:file:`.zip`) | (1),(3) | +-----------+-------------------------+---------+ -| ``gztar`` | gzip'ed tar file | (2),(4) | +| ``gztar`` | gzip'ed tar file | \(2) | | | (:file:`.tar.gz`) | | +-----------+-------------------------+---------+ -| ``bztar`` | bzip2'ed tar file | \(4) | +| ``bztar`` | bzip2'ed tar file | | | | (:file:`.tar.bz2`) | | +-----------+-------------------------+---------+ | ``ztar`` | compressed tar file | \(4) | | | (:file:`.tar.Z`) | | +-----------+-------------------------+---------+ -| ``tar`` | tar file (:file:`.tar`) | \(4) | +| ``tar`` | tar file (:file:`.tar`) | | +-----------+-------------------------+---------+ Notes: @@ -51,8 +51,16 @@ Notes: of the standard Python library since Python 1.6) (4) - requires external utilities: :program:`tar` and possibly one of :program:`gzip`, - :program:`bzip2`, or :program:`compress` + requires the :program:`compress` program. Notice that this format is now + pending for deprecation and will be removed in the future versions of Python. + +When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or ``tar``), you +can specify under Unix the ``owner`` and ``group`` names that will be set for +each member of the archive. + +For example, if you want all files of the archive to be owned by root:: + + python setup.py sdist --owner=root --group=root .. _manifest: From d35f4c2282ca9fb6c9303845fc7c6c2b21ce4cc3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Fri, 2 Oct 2009 23:56:02 +0000 Subject: [PATCH 103/330] Merged revisions 75192 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r75192 | tarek.ziade | 2009-10-03 01:49:48 +0200 (Sat, 03 Oct 2009) | 1 line #6516 added owner/group support for tarfiles in Distutils ........ --- sourcedist.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 0c786c5a0a..94fa338c19 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -26,16 +26,16 @@ to create a gzipped tarball and a zip file. The available formats are: +===========+=========================+=========+ | ``zip`` | zip file (:file:`.zip`) | (1),(3) | +-----------+-------------------------+---------+ -| ``gztar`` | gzip'ed tar file | (2),(4) | +| ``gztar`` | gzip'ed tar file | \(2) | | | (:file:`.tar.gz`) | | +-----------+-------------------------+---------+ -| ``bztar`` | bzip2'ed tar file | \(4) | +| ``bztar`` | bzip2'ed tar file | | | | (:file:`.tar.bz2`) | | +-----------+-------------------------+---------+ | ``ztar`` | compressed tar file | \(4) | | | (:file:`.tar.Z`) | | +-----------+-------------------------+---------+ -| ``tar`` | tar file (:file:`.tar`) | \(4) | +| ``tar`` | tar file (:file:`.tar`) | | +-----------+-------------------------+---------+ Notes: @@ -51,8 +51,16 @@ Notes: of the standard Python library since Python 1.6) (4) - requires external utilities: :program:`tar` and possibly one of :program:`gzip`, - :program:`bzip2`, or :program:`compress` + requires the :program:`compress` program. Notice that this format is now + pending for deprecation and will be removed in the future versions of Python. + +When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or ``tar``), you +can specify under Unix the ``owner`` and ``group`` names that will be set for +each member of the archive. + +For example, if you want all files of the archive to be owned by root:: + + python setup.py sdist --owner=root --group=root .. _manifest: From ec1defd66761d4f1959fc5738733c1b0c08919ad Mon Sep 17 00:00:00 2001 From: "Andrew M. Kuchling" Date: Mon, 5 Oct 2009 22:31:11 +0000 Subject: [PATCH 104/330] Reword sentence --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index e227833ea4..6a640d832f 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1934,7 +1934,7 @@ This is described in more detail in :pep:`301`. The ``check`` command performs some tests on the meta-data of a package. -It makes sure for example that all required meta-data are provided through +For example, it verifies that all required meta-data are provided as the arguments passed to the :func:`setup` function. .. % todo From 7cbbb61db7c44d79825285f747f3e24bee2fae13 Mon Sep 17 00:00:00 2001 From: "Andrew M. Kuchling" Date: Mon, 5 Oct 2009 22:32:48 +0000 Subject: [PATCH 105/330] Use standard comma punctuation; reword some sentences in the docs --- examples.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples.rst b/examples.rst index d5918a5eb2..648063b217 100644 --- a/examples.rst +++ b/examples.rst @@ -236,10 +236,10 @@ With exactly the same source tree layout, this extension can be put in the Checking a package ================== -The ``check`` command allows you to verify if your package meta-data are -meeting the minimum requirements to build a distribution. +The ``check`` command allows you to verify if your package meta-data +meet the minimum requirements to build a distribution. -To run it, just call it over your :file:`setup.py` script. If something is +To run it, just call it using your :file:`setup.py` script. If something is missing, ``check`` will display a warning. Let's take an example with a simple script:: @@ -252,7 +252,7 @@ Running the ``check`` command will display some warnings:: $ python setup.py check running check - warning: check: missing required meta-data: version ,url + warning: check: missing required meta-data: version, url warning: check: missing meta-data: either (author and author_email) or (maintainer and maintainer_email) must be supplied From 04d16588e223e5878ddd548646535274310da468 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 27 Oct 2009 14:37:48 +0000 Subject: [PATCH 106/330] Merged revisions 74209 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74209 | georg.brandl | 2009-07-26 16:37:28 +0200 (So, 26 Jul 2009) | 1 line builtin -> built-in. ........ --- apiref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 995b76748e..0a51b7c005 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1623,7 +1623,7 @@ lines, and joining lines with backslashes. +------------------+--------------------------------+---------+ Note that since *rstrip_ws* can strip the trailing newline, the semantics of - :meth:`readline` must differ from those of the builtin file object's + :meth:`readline` must differ from those of the built-in file object's :meth:`readline` method! In particular, :meth:`readline` returns ``None`` for end-of-file: an empty string might just be a blank line (or an all-whitespace line), if *rstrip_ws* is true but *skip_blanks* is not. @@ -1631,8 +1631,8 @@ lines, and joining lines with backslashes. .. method:: TextFile.open(filename) - Open a new file *filename*. This overrides any *file* or *filename* constructor - arguments. + Open a new file *filename*. This overrides any *file* or *filename* + constructor arguments. .. method:: TextFile.close() From c78c38992860a35e5753b8f5afdfbbab3100b0b7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 27 Oct 2009 14:50:20 +0000 Subject: [PATCH 107/330] Merged revisions 74492,74531,74545-74550,74553-74555,74588,74603,74608,74614,74616-74618,74631-74633,74652-74653,74666,74671,74737,74739,74779,74781-74782,74784,74791,74793,74818-74820,74822,74832 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r74492 | r.david.murray | 2009-08-17 21:26:49 +0200 (Mo, 17 Aug 2009) | 2 lines Issue 6685: 'toupper' -> 'upper' in cgi doc example explanation. ........ r74531 | vinay.sajip | 2009-08-21 00:04:32 +0200 (Fr, 21 Aug 2009) | 1 line Added section on exceptions raised during logging. ........ r74545 | georg.brandl | 2009-08-24 19:14:29 +0200 (Mo, 24 Aug 2009) | 1 line #6772: mention utf-8 as utf8 alias. ........ r74546 | georg.brandl | 2009-08-24 19:20:40 +0200 (Mo, 24 Aug 2009) | 1 line #6725: spell "namespace" consistently. ........ r74547 | georg.brandl | 2009-08-24 19:22:05 +0200 (Mo, 24 Aug 2009) | 1 line #6718: fix example. ........ r74548 | georg.brandl | 2009-08-24 19:24:27 +0200 (Mo, 24 Aug 2009) | 1 line #6677: mention "deleting" as an alias for removing files. ........ r74549 | benjamin.peterson | 2009-08-24 19:42:36 +0200 (Mo, 24 Aug 2009) | 1 line fix pdf building by teaching latex the right encoding package ........ r74550 | georg.brandl | 2009-08-24 19:48:40 +0200 (Mo, 24 Aug 2009) | 1 line #6677: note that rmdir only removes empty directories. ........ r74553 | r.david.murray | 2009-08-27 03:04:59 +0200 (Do, 27 Aug 2009) | 2 lines Remove leftover text from end of sentence. ........ r74554 | georg.brandl | 2009-08-27 20:59:02 +0200 (Do, 27 Aug 2009) | 1 line Typo fix. ........ r74555 | georg.brandl | 2009-08-27 21:02:43 +0200 (Do, 27 Aug 2009) | 1 line #6787: reference fix. ........ r74588 | georg.brandl | 2009-08-30 10:35:01 +0200 (So, 30 Aug 2009) | 1 line #6803: fix old name. ........ r74603 | georg.brandl | 2009-08-31 08:38:29 +0200 (Mo, 31 Aug 2009) | 1 line other -> others where multiple arguments are accepted. ........ r74608 | senthil.kumaran | 2009-08-31 18:40:27 +0200 (Mo, 31 Aug 2009) | 3 lines Doc fix for the issue2637. ........ r74614 | georg.brandl | 2009-09-01 09:40:54 +0200 (Di, 01 Sep 2009) | 1 line #6813: better documentation for numberless string formats. ........ r74616 | georg.brandl | 2009-09-01 09:46:26 +0200 (Di, 01 Sep 2009) | 1 line #6808: clarification. ........ r74617 | georg.brandl | 2009-09-01 09:53:37 +0200 (Di, 01 Sep 2009) | 1 line #6765: hint that log(x, base) is not very sophisticated. ........ r74618 | georg.brandl | 2009-09-01 10:00:47 +0200 (Di, 01 Sep 2009) | 1 line #6810: add a link to the section about frame objects instead of just a description where to find it. ........ r74631 | georg.brandl | 2009-09-02 22:37:16 +0200 (Mi, 02 Sep 2009) | 1 line #6821: fix signature of PyBuffer_Release(). ........ r74632 | georg.brandl | 2009-09-03 09:27:26 +0200 (Do, 03 Sep 2009) | 1 line #6828: fix wrongly highlighted blocks. ........ r74633 | georg.brandl | 2009-09-03 14:31:39 +0200 (Do, 03 Sep 2009) | 1 line #6757: complete the list of types that marshal can serialize. ........ r74652 | georg.brandl | 2009-09-04 13:25:37 +0200 (Fr, 04 Sep 2009) | 1 line #6756: add some info about the "acct" parameter. ........ r74653 | georg.brandl | 2009-09-04 13:32:18 +0200 (Fr, 04 Sep 2009) | 1 line #6777: dont discourage usage of Exception.args or promote usage of Exception.message. ........ r74666 | georg.brandl | 2009-09-05 11:04:09 +0200 (Sa, 05 Sep 2009) | 1 line #6841: remove duplicated word. ........ r74671 | georg.brandl | 2009-09-05 18:47:17 +0200 (Sa, 05 Sep 2009) | 1 line #6843: add link from filterwarnings to where the meaning of the arguments is covered. ........ r74737 | georg.brandl | 2009-09-09 18:49:13 +0200 (Mi, 09 Sep 2009) | 1 line Properly document copy and deepcopy as functions. ........ r74739 | georg.brandl | 2009-09-11 09:55:20 +0200 (Fr, 11 Sep 2009) | 1 line Move function back to its section. ........ r74779 | michael.foord | 2009-09-13 18:13:36 +0200 (So, 13 Sep 2009) | 1 line Change to tutorial wording for reading text / binary files on Windows. Issue #6301. ........ r74781 | michael.foord | 2009-09-13 18:46:19 +0200 (So, 13 Sep 2009) | 1 line Note that sys._getframe is not guaranteed to exist in all implementations of Python, and a corresponding note in inspect.currentframe. Issue 6712. ........ r74782 | michael.foord | 2009-09-13 19:07:46 +0200 (So, 13 Sep 2009) | 1 line Tutorial tweaks. Issue 6849. ........ r74784 | georg.brandl | 2009-09-13 20:15:07 +0200 (So, 13 Sep 2009) | 1 line Typo fix. ........ r74791 | georg.brandl | 2009-09-14 16:08:54 +0200 (Mo, 14 Sep 2009) | 1 line #6574: list the future features in a table. ........ r74793 | georg.brandl | 2009-09-14 16:50:47 +0200 (Mo, 14 Sep 2009) | 1 line #6908: fix association of hashlib hash attributes. ........ r74818 | georg.brandl | 2009-09-16 11:23:04 +0200 (Mi, 16 Sep 2009) | 1 line #6880: add reference to classes section in exceptions section, which comes earlier. ........ r74819 | georg.brandl | 2009-09-16 11:24:57 +0200 (Mi, 16 Sep 2009) | 1 line #6876: fix base class constructor invocation in example. ........ r74820 | georg.brandl | 2009-09-16 11:30:48 +0200 (Mi, 16 Sep 2009) | 1 line #6891: comment out dead link to Unicode article. ........ r74822 | georg.brandl | 2009-09-16 12:12:06 +0200 (Mi, 16 Sep 2009) | 1 line #5621: refactor description of how class/instance attributes interact on a.x=a.x+1 or augassign. ........ r74832 | georg.brandl | 2009-09-16 17:57:46 +0200 (Mi, 16 Sep 2009) | 1 line Rewrap long lines. ........ --- builtdist.rst | 16 +++++++++------- 1 file changed, 9 insertions(+), 7 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 672faee34c..25d392348b 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -426,13 +426,6 @@ built-in functions in the installation script. also the configuration. For details refer to Microsoft's documentation of the :cfunc:`SHGetSpecialFolderPath` function. -Vista User Access Control (UAC) -=============================== - -Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` -option. The default is 'none' (meaning no UAC handling is done), and other -valid values are 'auto' (meaning prompt for UAC elevation if Python was -installed for all users) and 'force' (meaning always prompt for elevation) .. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) @@ -444,3 +437,12 @@ installed for all users) and 'force' (meaning always prompt for elevation) and *iconindex* is the index of the icon in the file *iconpath*. Again, for details consult the Microsoft documentation for the :class:`IShellLink` interface. + + +Vista User Access Control (UAC) +=============================== + +Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` +option. The default is 'none' (meaning no UAC handling is done), and other +valid values are 'auto' (meaning prompt for UAC elevation if Python was +installed for all users) and 'force' (meaning always prompt for elevation). From 701fd84e2821cabaa8bf8e78e1ec77dd48e3b02a Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 27 Oct 2009 15:10:22 +0000 Subject: [PATCH 108/330] Fix a strange mis-edit. --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 6a640d832f..a70c8071f1 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1958,9 +1958,9 @@ it so that it's implementing the class :class:`peel_banana`, a subclass of Subclasses of :class:`Command` must define the following methods. -.. method:: Command.initialize_options()(S) +.. method:: Command.initialize_options() - et default values for all the options that this command supports. Note that + Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, :meth:`initialize_options` From 1afd08730141928a37f5f91e9750793e5ba68c5e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 27 Oct 2009 15:10:48 +0000 Subject: [PATCH 109/330] Merged revisions 75795 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r75795 | georg.brandl | 2009-10-27 16:10:22 +0100 (Di, 27 Okt 2009) | 1 line Fix a strange mis-edit. ........ --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 0a51b7c005..71116e6d87 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1962,9 +1962,9 @@ it so that it's implementing the class :class:`peel_banana`, a subclass of Subclasses of :class:`Command` must define the following methods. -.. method:: Command.initialize_options()(S) +.. method:: Command.initialize_options() - et default values for all the options that this command supports. Note that + Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, :meth:`initialize_options` From 49f74affbb3ab8183c4f74ad04bb269157e3a216 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 27 Oct 2009 15:28:25 +0000 Subject: [PATCH 110/330] Merged revisions 75365,75394,75402-75403,75418,75459,75484,75592-75596,75600,75602-75607,75610-75613,75616-75617,75623,75627,75640,75647,75696,75795 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r75365 | georg.brandl | 2009-10-11 22:16:16 +0200 (So, 11 Okt 2009) | 1 line Fix broken links found by "make linkcheck". scipy.org seems to be done right now, so I could not verify links going there. ........ r75394 | georg.brandl | 2009-10-13 20:10:59 +0200 (Di, 13 Okt 2009) | 1 line Fix markup. ........ r75402 | georg.brandl | 2009-10-14 17:51:48 +0200 (Mi, 14 Okt 2009) | 1 line #7125: fix typo. ........ r75403 | georg.brandl | 2009-10-14 17:57:46 +0200 (Mi, 14 Okt 2009) | 1 line #7126: os.environ changes *do* take effect in subprocesses started with os.system(). ........ r75418 | georg.brandl | 2009-10-14 20:48:32 +0200 (Mi, 14 Okt 2009) | 1 line #7116: str.join() takes an iterable. ........ r75459 | georg.brandl | 2009-10-17 10:57:43 +0200 (Sa, 17 Okt 2009) | 1 line Fix refleaks in _ctypes PyCSimpleType_New, which fixes the refleak seen in test___all__. ........ r75484 | georg.brandl | 2009-10-18 09:58:12 +0200 (So, 18 Okt 2009) | 1 line Fix missing word. ........ r75592 | georg.brandl | 2009-10-22 09:05:48 +0200 (Do, 22 Okt 2009) | 1 line Fix punctuation. ........ r75593 | georg.brandl | 2009-10-22 09:06:49 +0200 (Do, 22 Okt 2009) | 1 line Revert unintended change. ........ r75594 | georg.brandl | 2009-10-22 09:56:02 +0200 (Do, 22 Okt 2009) | 1 line Fix markup. ........ r75595 | georg.brandl | 2009-10-22 09:56:56 +0200 (Do, 22 Okt 2009) | 1 line Fix duplicate target. ........ r75596 | georg.brandl | 2009-10-22 10:05:04 +0200 (Do, 22 Okt 2009) | 1 line Add a new directive marking up implementation details and start using it. ........ r75600 | georg.brandl | 2009-10-22 13:01:46 +0200 (Do, 22 Okt 2009) | 1 line Make it more robust. ........ r75602 | georg.brandl | 2009-10-22 13:28:06 +0200 (Do, 22 Okt 2009) | 1 line Document new directive. ........ r75603 | georg.brandl | 2009-10-22 13:28:23 +0200 (Do, 22 Okt 2009) | 1 line Allow short form with text as argument. ........ r75604 | georg.brandl | 2009-10-22 13:36:50 +0200 (Do, 22 Okt 2009) | 1 line Fix stylesheet for multi-paragraph impl-details. ........ r75605 | georg.brandl | 2009-10-22 13:48:10 +0200 (Do, 22 Okt 2009) | 1 line Use "impl-detail" directive where applicable. ........ r75606 | georg.brandl | 2009-10-22 17:00:06 +0200 (Do, 22 Okt 2009) | 1 line #6324: membership test tries iteration via __iter__. ........ r75607 | georg.brandl | 2009-10-22 17:04:09 +0200 (Do, 22 Okt 2009) | 1 line #7088: document new functions in signal as Unix-only. ........ r75610 | georg.brandl | 2009-10-22 17:27:24 +0200 (Do, 22 Okt 2009) | 1 line Reorder __slots__ fine print and add a clarification. ........ r75611 | georg.brandl | 2009-10-22 17:42:32 +0200 (Do, 22 Okt 2009) | 1 line #7035: improve docs of the various _errors() functions, and give them docstrings. ........ r75612 | georg.brandl | 2009-10-22 17:52:15 +0200 (Do, 22 Okt 2009) | 1 line #7156: document curses as Unix-only. ........ r75613 | georg.brandl | 2009-10-22 17:54:35 +0200 (Do, 22 Okt 2009) | 1 line #6977: getopt does not support optional option arguments. ........ r75616 | georg.brandl | 2009-10-22 18:17:05 +0200 (Do, 22 Okt 2009) | 1 line Add proper references. ........ r75617 | georg.brandl | 2009-10-22 18:20:55 +0200 (Do, 22 Okt 2009) | 1 line Make printout margin important. ........ r75623 | georg.brandl | 2009-10-23 10:14:44 +0200 (Fr, 23 Okt 2009) | 1 line #7188: fix optionxform() docs. ........ r75627 | fred.drake | 2009-10-23 15:04:51 +0200 (Fr, 23 Okt 2009) | 2 lines add further note about what's passed to optionxform ........ r75640 | neil.schemenauer | 2009-10-23 21:58:17 +0200 (Fr, 23 Okt 2009) | 2 lines Improve some docstrings in the 'warnings' module. ........ r75647 | georg.brandl | 2009-10-24 12:04:19 +0200 (Sa, 24 Okt 2009) | 1 line Fix markup. ........ r75696 | georg.brandl | 2009-10-25 21:25:43 +0100 (So, 25 Okt 2009) | 1 line Fix a demo. ........ r75795 | georg.brandl | 2009-10-27 16:10:22 +0100 (Di, 27 Okt 2009) | 1 line Fix a strange mis-edit. ........ --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index af19111dfb..cdb32d3eac 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1976,9 +1976,9 @@ it so that it's implementing the class :class:`peel_banana`, a subclass of Subclasses of :class:`Command` must define the following methods. -.. method:: Command.initialize_options()(S) +.. method:: Command.initialize_options() - et default values for all the options that this command supports. Note that + Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, :meth:`initialize_options` From 0b1a62bfa712e884aeaa741756cdedaf6aadf93d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 27 Oct 2009 20:24:45 +0000 Subject: [PATCH 111/330] Merged revisions 75797 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ................ r75797 | georg.brandl | 2009-10-27 16:28:25 +0100 (Di, 27 Okt 2009) | 129 lines Merged revisions 75365,75394,75402-75403,75418,75459,75484,75592-75596,75600,75602-75607,75610-75613,75616-75617,75623,75627,75640,75647,75696,75795 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r75365 | georg.brandl | 2009-10-11 22:16:16 +0200 (So, 11 Okt 2009) | 1 line Fix broken links found by "make linkcheck". scipy.org seems to be done right now, so I could not verify links going there. ........ r75394 | georg.brandl | 2009-10-13 20:10:59 +0200 (Di, 13 Okt 2009) | 1 line Fix markup. ........ r75402 | georg.brandl | 2009-10-14 17:51:48 +0200 (Mi, 14 Okt 2009) | 1 line #7125: fix typo. ........ r75403 | georg.brandl | 2009-10-14 17:57:46 +0200 (Mi, 14 Okt 2009) | 1 line #7126: os.environ changes *do* take effect in subprocesses started with os.system(). ........ r75418 | georg.brandl | 2009-10-14 20:48:32 +0200 (Mi, 14 Okt 2009) | 1 line #7116: str.join() takes an iterable. ........ r75459 | georg.brandl | 2009-10-17 10:57:43 +0200 (Sa, 17 Okt 2009) | 1 line Fix refleaks in _ctypes PyCSimpleType_New, which fixes the refleak seen in test___all__. ........ r75484 | georg.brandl | 2009-10-18 09:58:12 +0200 (So, 18 Okt 2009) | 1 line Fix missing word. ........ r75592 | georg.brandl | 2009-10-22 09:05:48 +0200 (Do, 22 Okt 2009) | 1 line Fix punctuation. ........ r75593 | georg.brandl | 2009-10-22 09:06:49 +0200 (Do, 22 Okt 2009) | 1 line Revert unintended change. ........ r75594 | georg.brandl | 2009-10-22 09:56:02 +0200 (Do, 22 Okt 2009) | 1 line Fix markup. ........ r75595 | georg.brandl | 2009-10-22 09:56:56 +0200 (Do, 22 Okt 2009) | 1 line Fix duplicate target. ........ r75596 | georg.brandl | 2009-10-22 10:05:04 +0200 (Do, 22 Okt 2009) | 1 line Add a new directive marking up implementation details and start using it. ........ r75600 | georg.brandl | 2009-10-22 13:01:46 +0200 (Do, 22 Okt 2009) | 1 line Make it more robust. ........ r75602 | georg.brandl | 2009-10-22 13:28:06 +0200 (Do, 22 Okt 2009) | 1 line Document new directive. ........ r75603 | georg.brandl | 2009-10-22 13:28:23 +0200 (Do, 22 Okt 2009) | 1 line Allow short form with text as argument. ........ r75604 | georg.brandl | 2009-10-22 13:36:50 +0200 (Do, 22 Okt 2009) | 1 line Fix stylesheet for multi-paragraph impl-details. ........ r75605 | georg.brandl | 2009-10-22 13:48:10 +0200 (Do, 22 Okt 2009) | 1 line Use "impl-detail" directive where applicable. ........ r75606 | georg.brandl | 2009-10-22 17:00:06 +0200 (Do, 22 Okt 2009) | 1 line #6324: membership test tries iteration via __iter__. ........ r75607 | georg.brandl | 2009-10-22 17:04:09 +0200 (Do, 22 Okt 2009) | 1 line #7088: document new functions in signal as Unix-only. ........ r75610 | georg.brandl | 2009-10-22 17:27:24 +0200 (Do, 22 Okt 2009) | 1 line Reorder __slots__ fine print and add a clarification. ........ r75611 | georg.brandl | 2009-10-22 17:42:32 +0200 (Do, 22 Okt 2009) | 1 line #7035: improve docs of the various _errors() functions, and give them docstrings. ........ r75612 | georg.brandl | 2009-10-22 17:52:15 +0200 (Do, 22 Okt 2009) | 1 line #7156: document curses as Unix-only. ........ r75613 | georg.brandl | 2009-10-22 17:54:35 +0200 (Do, 22 Okt 2009) | 1 line #6977: getopt does not support optional option arguments. ........ r75616 | georg.brandl | 2009-10-22 18:17:05 +0200 (Do, 22 Okt 2009) | 1 line Add proper references. ........ r75617 | georg.brandl | 2009-10-22 18:20:55 +0200 (Do, 22 Okt 2009) | 1 line Make printout margin important. ........ r75623 | georg.brandl | 2009-10-23 10:14:44 +0200 (Fr, 23 Okt 2009) | 1 line #7188: fix optionxform() docs. ........ r75627 | fred.drake | 2009-10-23 15:04:51 +0200 (Fr, 23 Okt 2009) | 2 lines add further note about what's passed to optionxform ........ r75640 | neil.schemenauer | 2009-10-23 21:58:17 +0200 (Fr, 23 Okt 2009) | 2 lines Improve some docstrings in the 'warnings' module. ........ r75647 | georg.brandl | 2009-10-24 12:04:19 +0200 (Sa, 24 Okt 2009) | 1 line Fix markup. ........ r75696 | georg.brandl | 2009-10-25 21:25:43 +0100 (So, 25 Okt 2009) | 1 line Fix a demo. ........ r75795 | georg.brandl | 2009-10-27 16:10:22 +0100 (Di, 27 Okt 2009) | 1 line Fix a strange mis-edit. ........ ................ --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index af19111dfb..cdb32d3eac 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1976,9 +1976,9 @@ it so that it's implementing the class :class:`peel_banana`, a subclass of Subclasses of :class:`Command` must define the following methods. -.. method:: Command.initialize_options()(S) +.. method:: Command.initialize_options() - et default values for all the options that this command supports. Note that + Set default values for all the options that this command supports. Note that these defaults may be overridden by other commands, by the setup script, by config files, or by the command-line. Thus, this is not the place to code dependencies between options; generally, :meth:`initialize_options` From 346e55759d30a1b39c780b7bce449b143d869b51 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Tue, 27 Oct 2009 23:06:10 +0000 Subject: [PATCH 112/330] Fixed #1180: Option to ignore ~/.pydistutils.cfg in Distutils --- builtdist.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index e58937d200..c7b756bed1 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -241,7 +241,8 @@ tedious and error-prone, so it's usually best to put them in the setup configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If you distribute or package many Python module distributions, you might want to put options that apply to all of them in your personal Distutils configuration -file (:file:`~/.pydistutils.cfg`). +file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable +this file, you can pass the --no-user-cfg option to setup.py. There are three steps to building a binary RPM package, all of which are handled automatically by the Distutils: From 224df7839952086e8e7452df21abb9ccf9891119 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Tue, 27 Oct 2009 23:12:01 +0000 Subject: [PATCH 113/330] Merged revisions 75893 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r75893 | tarek.ziade | 2009-10-28 00:06:10 +0100 (Wed, 28 Oct 2009) | 1 line Fixed #1180: Option to ignore ~/.pydistutils.cfg in Distutils ........ --- builtdist.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index e58937d200..c7b756bed1 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -241,7 +241,8 @@ tedious and error-prone, so it's usually best to put them in the setup configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If you distribute or package many Python module distributions, you might want to put options that apply to all of them in your personal Distutils configuration -file (:file:`~/.pydistutils.cfg`). +file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable +this file, you can pass the --no-user-cfg option to setup.py. There are three steps to building a binary RPM package, all of which are handled automatically by the Distutils: From 9b092f0e7358cfad0517de44e0c46665a733e8c4 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Fri, 13 Nov 2009 02:25:08 +0000 Subject: [PATCH 114/330] Merged revisions 75149,75260-75263,75265-75267,75292,75300,75376,75405,75429-75433,75437,75445,75501,75551,75572,75589-75591,75657,75742,75868,75952-75957,76057,76105,76139,76143,76162,76223 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r75149 | gregory.p.smith | 2009-09-29 16:56:31 -0500 (Tue, 29 Sep 2009) | 3 lines Mention issue6972 in extractall docs about overwriting things outside of the supplied path. ........ r75260 | andrew.kuchling | 2009-10-05 16:24:20 -0500 (Mon, 05 Oct 2009) | 1 line Wording fix ........ r75261 | andrew.kuchling | 2009-10-05 16:24:35 -0500 (Mon, 05 Oct 2009) | 1 line Fix narkup ........ r75262 | andrew.kuchling | 2009-10-05 16:25:03 -0500 (Mon, 05 Oct 2009) | 1 line Document 'skip' parameter to constructor ........ r75263 | andrew.kuchling | 2009-10-05 16:25:35 -0500 (Mon, 05 Oct 2009) | 1 line Note side benefit of socket.create_connection() ........ r75265 | andrew.kuchling | 2009-10-05 17:31:11 -0500 (Mon, 05 Oct 2009) | 1 line Reword sentence ........ r75266 | andrew.kuchling | 2009-10-05 17:32:48 -0500 (Mon, 05 Oct 2009) | 1 line Use standard comma punctuation; reword some sentences in the docs ........ r75267 | andrew.kuchling | 2009-10-05 17:42:56 -0500 (Mon, 05 Oct 2009) | 1 line Backport r73983: Document the thousands separator. ........ r75292 | benjamin.peterson | 2009-10-08 22:11:36 -0500 (Thu, 08 Oct 2009) | 1 line death to old CVS keyword ........ r75300 | benjamin.peterson | 2009-10-09 16:48:14 -0500 (Fri, 09 Oct 2009) | 1 line fix some coding style ........ r75376 | benjamin.peterson | 2009-10-11 20:26:07 -0500 (Sun, 11 Oct 2009) | 1 line platform we don't care about ........ r75405 | neil.schemenauer | 2009-10-14 12:17:14 -0500 (Wed, 14 Oct 2009) | 4 lines Issue #1754094: Improve the stack depth calculation in the compiler. There should be no other effect than a small decrease in memory use. Patch by Christopher Tur Lesniewski-Laas. ........ r75429 | benjamin.peterson | 2009-10-14 20:47:28 -0500 (Wed, 14 Oct 2009) | 1 line pep8ify if blocks ........ r75430 | benjamin.peterson | 2009-10-14 20:49:37 -0500 (Wed, 14 Oct 2009) | 1 line use floor division and add a test that exercises the tabsize codepath ........ r75431 | benjamin.peterson | 2009-10-14 20:56:25 -0500 (Wed, 14 Oct 2009) | 1 line change test to what I intended ........ r75432 | benjamin.peterson | 2009-10-14 22:05:39 -0500 (Wed, 14 Oct 2009) | 1 line some cleanups ........ r75433 | benjamin.peterson | 2009-10-14 22:06:55 -0500 (Wed, 14 Oct 2009) | 1 line make inspect.isabstract() always return a boolean; add a test for it, too #7069 ........ r75437 | benjamin.peterson | 2009-10-15 10:44:46 -0500 (Thu, 15 Oct 2009) | 1 line only clear a module's __dict__ if the module is the only one with a reference to it #7140 ........ r75445 | vinay.sajip | 2009-10-16 09:06:44 -0500 (Fri, 16 Oct 2009) | 1 line Issue #7120: logging: Removed import of multiprocessing which is causing crash in GAE. ........ r75501 | antoine.pitrou | 2009-10-18 13:37:11 -0500 (Sun, 18 Oct 2009) | 3 lines Add a comment about unreachable code, and fix a typo ........ r75551 | benjamin.peterson | 2009-10-19 22:14:10 -0500 (Mon, 19 Oct 2009) | 1 line use property api ........ r75572 | benjamin.peterson | 2009-10-20 16:55:17 -0500 (Tue, 20 Oct 2009) | 1 line clarify buffer arg #7178 ........ r75589 | benjamin.peterson | 2009-10-21 21:26:47 -0500 (Wed, 21 Oct 2009) | 1 line whitespace ........ r75590 | benjamin.peterson | 2009-10-21 21:36:47 -0500 (Wed, 21 Oct 2009) | 1 line rewrite to be nice to other implementations ........ r75591 | benjamin.peterson | 2009-10-21 21:50:38 -0500 (Wed, 21 Oct 2009) | 4 lines rewrite for style, clarify, and comments Also, use the hasattr() like scheme of allowing BaseException exceptions through. ........ r75657 | antoine.pitrou | 2009-10-24 07:41:27 -0500 (Sat, 24 Oct 2009) | 3 lines Fix compilation error in debug mode. ........ r75742 | benjamin.peterson | 2009-10-26 17:51:16 -0500 (Mon, 26 Oct 2009) | 1 line use 'is' instead of id() ........ r75868 | benjamin.peterson | 2009-10-27 15:59:18 -0500 (Tue, 27 Oct 2009) | 1 line test expect base classes ........ r75952 | georg.brandl | 2009-10-29 15:38:32 -0500 (Thu, 29 Oct 2009) | 1 line Use the correct function name in docstring. ........ r75953 | georg.brandl | 2009-10-29 15:39:50 -0500 (Thu, 29 Oct 2009) | 1 line Remove mention of the old -X command line switch. ........ r75954 | georg.brandl | 2009-10-29 15:53:00 -0500 (Thu, 29 Oct 2009) | 1 line Use constants instead of magic integers for test result. Do not re-run with --verbose3 for environment changing tests. ........ r75955 | georg.brandl | 2009-10-29 15:54:03 -0500 (Thu, 29 Oct 2009) | 1 line Use a single style for all the docstrings in the math module. ........ r75956 | georg.brandl | 2009-10-29 16:16:34 -0500 (Thu, 29 Oct 2009) | 1 line I do not think the "railroad" program mentioned is still available. ........ r75957 | georg.brandl | 2009-10-29 16:44:56 -0500 (Thu, 29 Oct 2009) | 1 line Fix constant name. ........ r76057 | benjamin.peterson | 2009-11-02 09:06:45 -0600 (Mon, 02 Nov 2009) | 1 line prevent a rather unlikely segfault ........ r76105 | georg.brandl | 2009-11-04 01:38:12 -0600 (Wed, 04 Nov 2009) | 1 line #7259: show correct equivalent for operator.i* operations in docstring; fix minor issues in operator docs. ........ r76139 | benjamin.peterson | 2009-11-06 19:04:38 -0600 (Fri, 06 Nov 2009) | 1 line spelling ........ r76143 | georg.brandl | 2009-11-07 02:26:07 -0600 (Sat, 07 Nov 2009) | 1 line #7271: fix typo. ........ r76162 | benjamin.peterson | 2009-11-08 22:10:53 -0600 (Sun, 08 Nov 2009) | 1 line discuss how to use -p ........ r76223 | georg.brandl | 2009-11-12 02:29:46 -0600 (Thu, 12 Nov 2009) | 1 line Give the profile module a module directive. ........ --- apiref.rst | 2 +- examples.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/apiref.rst b/apiref.rst index cdb32d3eac..69ec0de99b 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1952,7 +1952,7 @@ This is described in more detail in :pep:`301`. The ``check`` command performs some tests on the meta-data of a package. -It makes sure for example that all required meta-data are provided through +For example, it verifies that all required meta-data are provided as the arguments passed to the :func:`setup` function. .. % todo diff --git a/examples.rst b/examples.rst index d5918a5eb2..648063b217 100644 --- a/examples.rst +++ b/examples.rst @@ -236,10 +236,10 @@ With exactly the same source tree layout, this extension can be put in the Checking a package ================== -The ``check`` command allows you to verify if your package meta-data are -meeting the minimum requirements to build a distribution. +The ``check`` command allows you to verify if your package meta-data +meet the minimum requirements to build a distribution. -To run it, just call it over your :file:`setup.py` script. If something is +To run it, just call it using your :file:`setup.py` script. If something is missing, ``check`` will display a warning. Let's take an example with a simple script:: @@ -252,7 +252,7 @@ Running the ``check`` command will display some warnings:: $ python setup.py check running check - warning: check: missing required meta-data: version ,url + warning: check: missing required meta-data: version, url warning: check: missing meta-data: either (author and author_email) or (maintainer and maintainer_email) must be supplied From 44d173702293d65a98798e45e6f1b8b413d9514d Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Fri, 13 Nov 2009 02:29:35 +0000 Subject: [PATCH 115/330] Merged revisions 76235 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ................ r76235 | benjamin.peterson | 2009-11-12 20:25:08 -0600 (Thu, 12 Nov 2009) | 170 lines Merged revisions 75149,75260-75263,75265-75267,75292,75300,75376,75405,75429-75433,75437,75445,75501,75551,75572,75589-75591,75657,75742,75868,75952-75957,76057,76105,76139,76143,76162,76223 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r75149 | gregory.p.smith | 2009-09-29 16:56:31 -0500 (Tue, 29 Sep 2009) | 3 lines Mention issue6972 in extractall docs about overwriting things outside of the supplied path. ........ r75260 | andrew.kuchling | 2009-10-05 16:24:20 -0500 (Mon, 05 Oct 2009) | 1 line Wording fix ........ r75261 | andrew.kuchling | 2009-10-05 16:24:35 -0500 (Mon, 05 Oct 2009) | 1 line Fix narkup ........ r75262 | andrew.kuchling | 2009-10-05 16:25:03 -0500 (Mon, 05 Oct 2009) | 1 line Document 'skip' parameter to constructor ........ r75263 | andrew.kuchling | 2009-10-05 16:25:35 -0500 (Mon, 05 Oct 2009) | 1 line Note side benefit of socket.create_connection() ........ r75265 | andrew.kuchling | 2009-10-05 17:31:11 -0500 (Mon, 05 Oct 2009) | 1 line Reword sentence ........ r75266 | andrew.kuchling | 2009-10-05 17:32:48 -0500 (Mon, 05 Oct 2009) | 1 line Use standard comma punctuation; reword some sentences in the docs ........ r75267 | andrew.kuchling | 2009-10-05 17:42:56 -0500 (Mon, 05 Oct 2009) | 1 line Backport r73983: Document the thousands separator. ........ r75292 | benjamin.peterson | 2009-10-08 22:11:36 -0500 (Thu, 08 Oct 2009) | 1 line death to old CVS keyword ........ r75300 | benjamin.peterson | 2009-10-09 16:48:14 -0500 (Fri, 09 Oct 2009) | 1 line fix some coding style ........ r75376 | benjamin.peterson | 2009-10-11 20:26:07 -0500 (Sun, 11 Oct 2009) | 1 line platform we don't care about ........ r75405 | neil.schemenauer | 2009-10-14 12:17:14 -0500 (Wed, 14 Oct 2009) | 4 lines Issue #1754094: Improve the stack depth calculation in the compiler. There should be no other effect than a small decrease in memory use. Patch by Christopher Tur Lesniewski-Laas. ........ r75429 | benjamin.peterson | 2009-10-14 20:47:28 -0500 (Wed, 14 Oct 2009) | 1 line pep8ify if blocks ........ r75430 | benjamin.peterson | 2009-10-14 20:49:37 -0500 (Wed, 14 Oct 2009) | 1 line use floor division and add a test that exercises the tabsize codepath ........ r75431 | benjamin.peterson | 2009-10-14 20:56:25 -0500 (Wed, 14 Oct 2009) | 1 line change test to what I intended ........ r75432 | benjamin.peterson | 2009-10-14 22:05:39 -0500 (Wed, 14 Oct 2009) | 1 line some cleanups ........ r75433 | benjamin.peterson | 2009-10-14 22:06:55 -0500 (Wed, 14 Oct 2009) | 1 line make inspect.isabstract() always return a boolean; add a test for it, too #7069 ........ r75437 | benjamin.peterson | 2009-10-15 10:44:46 -0500 (Thu, 15 Oct 2009) | 1 line only clear a module's __dict__ if the module is the only one with a reference to it #7140 ........ r75445 | vinay.sajip | 2009-10-16 09:06:44 -0500 (Fri, 16 Oct 2009) | 1 line Issue #7120: logging: Removed import of multiprocessing which is causing crash in GAE. ........ r75501 | antoine.pitrou | 2009-10-18 13:37:11 -0500 (Sun, 18 Oct 2009) | 3 lines Add a comment about unreachable code, and fix a typo ........ r75551 | benjamin.peterson | 2009-10-19 22:14:10 -0500 (Mon, 19 Oct 2009) | 1 line use property api ........ r75572 | benjamin.peterson | 2009-10-20 16:55:17 -0500 (Tue, 20 Oct 2009) | 1 line clarify buffer arg #7178 ........ r75589 | benjamin.peterson | 2009-10-21 21:26:47 -0500 (Wed, 21 Oct 2009) | 1 line whitespace ........ r75590 | benjamin.peterson | 2009-10-21 21:36:47 -0500 (Wed, 21 Oct 2009) | 1 line rewrite to be nice to other implementations ........ r75591 | benjamin.peterson | 2009-10-21 21:50:38 -0500 (Wed, 21 Oct 2009) | 4 lines rewrite for style, clarify, and comments Also, use the hasattr() like scheme of allowing BaseException exceptions through. ........ r75657 | antoine.pitrou | 2009-10-24 07:41:27 -0500 (Sat, 24 Oct 2009) | 3 lines Fix compilation error in debug mode. ........ r75742 | benjamin.peterson | 2009-10-26 17:51:16 -0500 (Mon, 26 Oct 2009) | 1 line use 'is' instead of id() ........ r75868 | benjamin.peterson | 2009-10-27 15:59:18 -0500 (Tue, 27 Oct 2009) | 1 line test expect base classes ........ r75952 | georg.brandl | 2009-10-29 15:38:32 -0500 (Thu, 29 Oct 2009) | 1 line Use the correct function name in docstring. ........ r75953 | georg.brandl | 2009-10-29 15:39:50 -0500 (Thu, 29 Oct 2009) | 1 line Remove mention of the old -X command line switch. ........ r75954 | georg.brandl | 2009-10-29 15:53:00 -0500 (Thu, 29 Oct 2009) | 1 line Use constants instead of magic integers for test result. Do not re-run with --verbose3 for environment changing tests. ........ r75955 | georg.brandl | 2009-10-29 15:54:03 -0500 (Thu, 29 Oct 2009) | 1 line Use a single style for all the docstrings in the math module. ........ r75956 | georg.brandl | 2009-10-29 16:16:34 -0500 (Thu, 29 Oct 2009) | 1 line I do not think the "railroad" program mentioned is still available. ........ r75957 | georg.brandl | 2009-10-29 16:44:56 -0500 (Thu, 29 Oct 2009) | 1 line Fix constant name. ........ r76057 | benjamin.peterson | 2009-11-02 09:06:45 -0600 (Mon, 02 Nov 2009) | 1 line prevent a rather unlikely segfault ........ r76105 | georg.brandl | 2009-11-04 01:38:12 -0600 (Wed, 04 Nov 2009) | 1 line #7259: show correct equivalent for operator.i* operations in docstring; fix minor issues in operator docs. ........ r76139 | benjamin.peterson | 2009-11-06 19:04:38 -0600 (Fri, 06 Nov 2009) | 1 line spelling ........ r76143 | georg.brandl | 2009-11-07 02:26:07 -0600 (Sat, 07 Nov 2009) | 1 line #7271: fix typo. ........ r76162 | benjamin.peterson | 2009-11-08 22:10:53 -0600 (Sun, 08 Nov 2009) | 1 line discuss how to use -p ........ r76223 | georg.brandl | 2009-11-12 02:29:46 -0600 (Thu, 12 Nov 2009) | 1 line Give the profile module a module directive. ........ ................ --- apiref.rst | 2 +- examples.rst | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/apiref.rst b/apiref.rst index cdb32d3eac..69ec0de99b 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1952,7 +1952,7 @@ This is described in more detail in :pep:`301`. The ``check`` command performs some tests on the meta-data of a package. -It makes sure for example that all required meta-data are provided through +For example, it verifies that all required meta-data are provided as the arguments passed to the :func:`setup` function. .. % todo diff --git a/examples.rst b/examples.rst index d5918a5eb2..648063b217 100644 --- a/examples.rst +++ b/examples.rst @@ -236,10 +236,10 @@ With exactly the same source tree layout, this extension can be put in the Checking a package ================== -The ``check`` command allows you to verify if your package meta-data are -meeting the minimum requirements to build a distribution. +The ``check`` command allows you to verify if your package meta-data +meet the minimum requirements to build a distribution. -To run it, just call it over your :file:`setup.py` script. If something is +To run it, just call it using your :file:`setup.py` script. If something is missing, ``check`` will display a warning. Let's take an example with a simple script:: @@ -252,7 +252,7 @@ Running the ``check`` command will display some warnings:: $ python setup.py check running check - warning: check: missing required meta-data: version ,url + warning: check: missing required meta-data: version, url warning: check: missing meta-data: either (author and author_email) or (maintainer and maintainer_email) must be supplied From 248234e32106251f18db55ea6b4601c2c75ced0d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Tue, 8 Dec 2009 08:56:49 +0000 Subject: [PATCH 116/330] Issue #7457: added a read_pkg_file method to distutils.dist.DistributionMetadata so we can read back PKG-INFO files --- examples.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/examples.rst b/examples.rst index 648063b217..35de57e4ad 100644 --- a/examples.rst +++ b/examples.rst @@ -285,6 +285,48 @@ by using the `docutils` parser:: warning: check: Title underline too short. (line 2) warning: check: Could not finish the parsing. +Reading the metadata +===================== + +The :func:`distutils.core.setup` function provides a command-line interface +that allows you to query the metadata fields of a project through the +`setup.py` script of a given project:: + + $ python setup.py --name + distribute + +This call reads the `name` metadata by running the +:func:`distutils.core.setup` function. Although, when a source or binary +distribution is created with Distutils, the metadata fields are written +in a static file called :file:`PKG-INFO`. When a Distutils-based project is +installed in Python, the :file:`PKG-INFO` file is copied alongside the modules +and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, +where `NAME` is the name of the project, `VERSION` its version as defined +in the Metadata, and `pyX.X` the major and minor version of Python like +`2.7` or `3.2`. + +You can read back this static file, by using the +:class:`distutils.dist.DistributionMetadata` class and its +:func:`read_pkg_file` method:: + + >>> from distutils.dist import DistributionMetadata + >>> metadata = DistributionMetadata() + >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info')) + >>> metadata.name + 'distribute' + >>> metadata.version + '0.6.8' + >>> metadata.description + 'Easily download, build, install, upgrade, and uninstall Python packages' + +Notice that the class can also be instanciated with a metadata file path to +loads its values:: + + >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info' + >>> DistributionMetadata(pkg_info_path).name + 'distribute' + + .. % \section{Multiple extension modules} .. % \label{multiple-ext} From 2043b0884a5627a74d6d082c191f883cad0229f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Tue, 8 Dec 2009 09:45:25 +0000 Subject: [PATCH 117/330] Merged revisions 76702,76704 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r76702 | tarek.ziade | 2009-12-08 09:56:49 +0100 (Tue, 08 Dec 2009) | 1 line Issue #7457: added a read_pkg_file method to distutils.dist.DistributionMetadata so we can read back PKG-INFO files ........ r76704 | tarek.ziade | 2009-12-08 10:39:51 +0100 (Tue, 08 Dec 2009) | 1 line removed the usage of rfc822 in favor of email.message.Message ........ --- examples.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/examples.rst b/examples.rst index 648063b217..35de57e4ad 100644 --- a/examples.rst +++ b/examples.rst @@ -285,6 +285,48 @@ by using the `docutils` parser:: warning: check: Title underline too short. (line 2) warning: check: Could not finish the parsing. +Reading the metadata +===================== + +The :func:`distutils.core.setup` function provides a command-line interface +that allows you to query the metadata fields of a project through the +`setup.py` script of a given project:: + + $ python setup.py --name + distribute + +This call reads the `name` metadata by running the +:func:`distutils.core.setup` function. Although, when a source or binary +distribution is created with Distutils, the metadata fields are written +in a static file called :file:`PKG-INFO`. When a Distutils-based project is +installed in Python, the :file:`PKG-INFO` file is copied alongside the modules +and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, +where `NAME` is the name of the project, `VERSION` its version as defined +in the Metadata, and `pyX.X` the major and minor version of Python like +`2.7` or `3.2`. + +You can read back this static file, by using the +:class:`distutils.dist.DistributionMetadata` class and its +:func:`read_pkg_file` method:: + + >>> from distutils.dist import DistributionMetadata + >>> metadata = DistributionMetadata() + >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info')) + >>> metadata.name + 'distribute' + >>> metadata.version + '0.6.8' + >>> metadata.description + 'Easily download, build, install, upgrade, and uninstall Python packages' + +Notice that the class can also be instanciated with a metadata file path to +loads its values:: + + >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info' + >>> DistributionMetadata(pkg_info_path).name + 'distribute' + + .. % \section{Multiple extension modules} .. % \label{multiple-ext} From 6a6e16822b953fd9bdf5489af7998f30ef867685 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 13 Dec 2009 23:24:13 +0000 Subject: [PATCH 118/330] reorganized the distutils doc a bit : the MANIFEST.in template system has its own section now. This is easier to find and follow --- commandref.rst | 44 --------------- sourcedist.rst | 142 ++++++++++++++++++++++++++++++++++--------------- 2 files changed, 98 insertions(+), 88 deletions(-) diff --git a/commandref.rst b/commandref.rst index fbe40de6c2..7282961bd4 100644 --- a/commandref.rst +++ b/commandref.rst @@ -48,50 +48,6 @@ This command installs all (Python) scripts in the distribution. .. % \label{clean-cmd} -.. _sdist-cmd: - -Creating a source distribution: the :command:`sdist` command -============================================================ - -**\*\*** fragment moved down from above: needs context! **\*\*** - -The manifest template commands are: - -+-------------------------------------------+-----------------------------------------------+ -| Command | Description | -+===========================================+===============================================+ -| :command:`include pat1 pat2 ...` | include all files matching any of the listed | -| | patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | -| | patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | -| ...` | the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | -| ...` | the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | -| | matching --- & any of the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | -| | matching --- & any of the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`prune dir` | exclude all files under *dir* | -+-------------------------------------------+-----------------------------------------------+ -| :command:`graft dir` | include all files under *dir* | -+-------------------------------------------+-----------------------------------------------+ - -The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of -regular filename characters, ``?`` matches any single regular filename -character, and ``[range]`` matches any of the characters in *range* (e.g., -``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename -character" is platform-specific: on Unix it is anything except slash; on Windows -anything except backslash or colon. - -**\*\*** Windows support not there yet **\*\*** - .. % \section{Creating a built distribution: the .. % \protect\command{bdist} command family} .. % \label{bdist-cmds} diff --git a/sourcedist.rst b/sourcedist.rst index 94fa338c19..150d1e600c 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -111,9 +111,68 @@ per line, regular files (or symlinks to them) only. If you do supply your own :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. +See :ref:`manifest_template` section for a syntax reference. + +.. _manifest-options: + +Manifest-related options +======================== + +The normal course of operations for the :command:`sdist` command is as follows: + +* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` + and create the manifest + +* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest + with just the default file set + +* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more + recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading + :file:`MANIFEST.in` + +* use the list of files now in :file:`MANIFEST` (either just generated or read + in) to create the source distribution archive(s) + +There are a couple of options that modify this behaviour. First, use the +:option:`--no-defaults` and :option:`--no-prune` to disable the standard +"include" and "exclude" sets. + +Second, you might want to force the manifest to be regenerated---for example, if +you have added or removed files or directories that match an existing pattern in +the manifest template, you should regenerate the manifest:: + + python setup.py sdist --force-manifest + +Or, you might just want to (re)generate the manifest, but not create a source +distribution:: + + python setup.py sdist --manifest-only + +:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a +shortcut for :option:`--manifest-only`, and :option:`-f` for +:option:`--force-manifest`. + +.. _manifest_template: + +The MANIFEST.in template +======================== + +A :file:`MANIFEST.in` file can be added in a project to define the list of +files to include in the distribution built by the :command:`sdist` command. + +When :command:`sdist` is run, it will look for the :file:`MANIFEST.in` file +and interpret it to generate the :file:`MANIFEST` file that contains the +list of files that will be included in the package. + +This mechanism can be used when the default list of files is not enough. +(See :ref:`manifest`). + +Principle +--------- + The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an -example, again we turn to the Distutils' own manifest template:: +example, let's look at the Distutils' own manifest template:: include *.txt recursive-include examples *.txt *.py @@ -125,9 +184,7 @@ matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching :file:`examples/sample?/build`. All of this is done *after* the standard include set, so you can exclude files from the standard set with explicit instructions in the manifest template. (Or, you can use the -:option:`--no-defaults` option to disable the standard set entirely.) There are -several other commands available in the manifest template mini-language; see -section :ref:`sdist-cmd`. +:option:`--no-defaults` option to disable the standard set entirely.) The order of commands in the manifest template matters: initially, we have the list of default files as described above, and each command in the template adds @@ -181,44 +238,41 @@ should always be slash-separated; the Distutils will take care of converting them to the standard representation on your platform. That way, the manifest template is portable across operating systems. - -.. _manifest-options: - -Manifest-related options -======================== - -The normal course of operations for the :command:`sdist` command is as follows: - -* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` - and create the manifest - -* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest - with just the default file set - -* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more - recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading - :file:`MANIFEST.in` - -* use the list of files now in :file:`MANIFEST` (either just generated or read - in) to create the source distribution archive(s) - -There are a couple of options that modify this behaviour. First, use the -:option:`--no-defaults` and :option:`--no-prune` to disable the standard -"include" and "exclude" sets. - -Second, you might want to force the manifest to be regenerated---for example, if -you have added or removed files or directories that match an existing pattern in -the manifest template, you should regenerate the manifest:: - - python setup.py sdist --force-manifest - -Or, you might just want to (re)generate the manifest, but not create a source -distribution:: - - python setup.py sdist --manifest-only - -:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a -shortcut for :option:`--manifest-only`, and :option:`-f` for -:option:`--force-manifest`. - +Commands +-------- + +The manifest template commands are: + ++-------------------------------------------+-----------------------------------------------+ +| Command | Description | ++===========================================+===============================================+ +| :command:`include pat1 pat2 ...` | include all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`prune dir` | exclude all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ +| :command:`graft dir` | include all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ + +The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of +regular filename characters, ``?`` matches any single regular filename +character, and ``[range]`` matches any of the characters in *range* (e.g., +``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename +character" is platform-specific: on Unix it is anything except slash; on Windows +anything except backslash or colon. From 8528749169ed703c80a45ec7ad7120e326734d81 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 13 Dec 2009 23:26:18 +0000 Subject: [PATCH 119/330] Merged revisions 76826 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r76826 | tarek.ziade | 2009-12-14 00:24:13 +0100 (Mon, 14 Dec 2009) | 1 line reorganized the distutils doc a bit : the MANIFEST.in template system has its own section now. This is easier to find and follow ........ --- commandref.rst | 44 --------------- sourcedist.rst | 142 ++++++++++++++++++++++++++++++++++--------------- 2 files changed, 98 insertions(+), 88 deletions(-) diff --git a/commandref.rst b/commandref.rst index fbe40de6c2..7282961bd4 100644 --- a/commandref.rst +++ b/commandref.rst @@ -48,50 +48,6 @@ This command installs all (Python) scripts in the distribution. .. % \label{clean-cmd} -.. _sdist-cmd: - -Creating a source distribution: the :command:`sdist` command -============================================================ - -**\*\*** fragment moved down from above: needs context! **\*\*** - -The manifest template commands are: - -+-------------------------------------------+-----------------------------------------------+ -| Command | Description | -+===========================================+===============================================+ -| :command:`include pat1 pat2 ...` | include all files matching any of the listed | -| | patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | -| | patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | -| ...` | the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | -| ...` | the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | -| | matching --- & any of the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | -| | matching --- & any of the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`prune dir` | exclude all files under *dir* | -+-------------------------------------------+-----------------------------------------------+ -| :command:`graft dir` | include all files under *dir* | -+-------------------------------------------+-----------------------------------------------+ - -The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of -regular filename characters, ``?`` matches any single regular filename -character, and ``[range]`` matches any of the characters in *range* (e.g., -``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename -character" is platform-specific: on Unix it is anything except slash; on Windows -anything except backslash or colon. - -**\*\*** Windows support not there yet **\*\*** - .. % \section{Creating a built distribution: the .. % \protect\command{bdist} command family} .. % \label{bdist-cmds} diff --git a/sourcedist.rst b/sourcedist.rst index 94fa338c19..150d1e600c 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -111,9 +111,68 @@ per line, regular files (or symlinks to them) only. If you do supply your own :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. +See :ref:`manifest_template` section for a syntax reference. + +.. _manifest-options: + +Manifest-related options +======================== + +The normal course of operations for the :command:`sdist` command is as follows: + +* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` + and create the manifest + +* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest + with just the default file set + +* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more + recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading + :file:`MANIFEST.in` + +* use the list of files now in :file:`MANIFEST` (either just generated or read + in) to create the source distribution archive(s) + +There are a couple of options that modify this behaviour. First, use the +:option:`--no-defaults` and :option:`--no-prune` to disable the standard +"include" and "exclude" sets. + +Second, you might want to force the manifest to be regenerated---for example, if +you have added or removed files or directories that match an existing pattern in +the manifest template, you should regenerate the manifest:: + + python setup.py sdist --force-manifest + +Or, you might just want to (re)generate the manifest, but not create a source +distribution:: + + python setup.py sdist --manifest-only + +:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a +shortcut for :option:`--manifest-only`, and :option:`-f` for +:option:`--force-manifest`. + +.. _manifest_template: + +The MANIFEST.in template +======================== + +A :file:`MANIFEST.in` file can be added in a project to define the list of +files to include in the distribution built by the :command:`sdist` command. + +When :command:`sdist` is run, it will look for the :file:`MANIFEST.in` file +and interpret it to generate the :file:`MANIFEST` file that contains the +list of files that will be included in the package. + +This mechanism can be used when the default list of files is not enough. +(See :ref:`manifest`). + +Principle +--------- + The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an -example, again we turn to the Distutils' own manifest template:: +example, let's look at the Distutils' own manifest template:: include *.txt recursive-include examples *.txt *.py @@ -125,9 +184,7 @@ matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching :file:`examples/sample?/build`. All of this is done *after* the standard include set, so you can exclude files from the standard set with explicit instructions in the manifest template. (Or, you can use the -:option:`--no-defaults` option to disable the standard set entirely.) There are -several other commands available in the manifest template mini-language; see -section :ref:`sdist-cmd`. +:option:`--no-defaults` option to disable the standard set entirely.) The order of commands in the manifest template matters: initially, we have the list of default files as described above, and each command in the template adds @@ -181,44 +238,41 @@ should always be slash-separated; the Distutils will take care of converting them to the standard representation on your platform. That way, the manifest template is portable across operating systems. - -.. _manifest-options: - -Manifest-related options -======================== - -The normal course of operations for the :command:`sdist` command is as follows: - -* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` - and create the manifest - -* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest - with just the default file set - -* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more - recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading - :file:`MANIFEST.in` - -* use the list of files now in :file:`MANIFEST` (either just generated or read - in) to create the source distribution archive(s) - -There are a couple of options that modify this behaviour. First, use the -:option:`--no-defaults` and :option:`--no-prune` to disable the standard -"include" and "exclude" sets. - -Second, you might want to force the manifest to be regenerated---for example, if -you have added or removed files or directories that match an existing pattern in -the manifest template, you should regenerate the manifest:: - - python setup.py sdist --force-manifest - -Or, you might just want to (re)generate the manifest, but not create a source -distribution:: - - python setup.py sdist --manifest-only - -:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a -shortcut for :option:`--manifest-only`, and :option:`-f` for -:option:`--force-manifest`. - +Commands +-------- + +The manifest template commands are: + ++-------------------------------------------+-----------------------------------------------+ +| Command | Description | ++===========================================+===============================================+ +| :command:`include pat1 pat2 ...` | include all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`prune dir` | exclude all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ +| :command:`graft dir` | include all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ + +The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of +regular filename characters, ``?`` matches any single regular filename +character, and ``[range]`` matches any of the characters in *range* (e.g., +``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename +character" is platform-specific: on Unix it is anything except slash; on Windows +anything except backslash or colon. From a5305c583b6e7f0cae475e18a7289e0daa3f74e9 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 19 Dec 2009 22:41:49 +0000 Subject: [PATCH 120/330] #7388: "python".capitalize() in the Doc --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index bf4eeeb89a..faefd21692 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -649,7 +649,7 @@ information is sometimes used to indicate sub-releases. These are 1.0.1a2 the second alpha release of the first patch version of 1.0 -:option:`classifiers` are specified in a python list:: +:option:`classifiers` are specified in a Python list:: setup(..., classifiers=[ From 6cb0612412d77eb0733fe5079973606ffc5c651d Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 19 Dec 2009 22:59:01 +0000 Subject: [PATCH 121/330] Merged revisions 76904 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r76904 | ezio.melotti | 2009-12-20 00:41:49 +0200 (Sun, 20 Dec 2009) | 1 line #7388: "python".capitalize() in the Doc ........ --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index a258e28bc8..06d3e9fd99 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -620,7 +620,7 @@ information is sometimes used to indicate sub-releases. These are 1.0.1a2 the second alpha release of the first patch version of 1.0 -:option:`classifiers` are specified in a python list:: +:option:`classifiers` are specified in a Python list:: setup(..., classifiers=[ From f682830b7edc7d08b9c7cfe255bee7dfa09d784b Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 19 Dec 2009 23:26:38 +0000 Subject: [PATCH 122/330] Merged revisions 76904 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r76904 | ezio.melotti | 2009-12-20 00:41:49 +0200 (Sun, 20 Dec 2009) | 1 line #7388: "python".capitalize() in the Doc ........ --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index e7c630054a..5ec94c7ea5 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -646,7 +646,7 @@ information is sometimes used to indicate sub-releases. These are 1.0.1a2 the second alpha release of the first patch version of 1.0 -:option:`classifiers` are specified in a python list:: +:option:`classifiers` are specified in a Python list:: setup(..., classifiers=[ From 475eb4a561a8c98361f447877818b453247c619f Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Sat, 19 Dec 2009 23:33:46 +0000 Subject: [PATCH 123/330] Merged revisions 76906 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ................ r76906 | ezio.melotti | 2009-12-20 01:26:38 +0200 (Sun, 20 Dec 2009) | 9 lines Merged revisions 76904 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r76904 | ezio.melotti | 2009-12-20 00:41:49 +0200 (Sun, 20 Dec 2009) | 1 line #7388: "python".capitalize() in the Doc ........ ................ --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index e7c630054a..5ec94c7ea5 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -646,7 +646,7 @@ information is sometimes used to indicate sub-releases. These are 1.0.1a2 the second alpha release of the first patch version of 1.0 -:option:`classifiers` are specified in a python list:: +:option:`classifiers` are specified in a Python list:: setup(..., classifiers=[ From 589d459876b5203e5852f2bde5032353227b1c6f Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 17 Jan 2010 23:33:53 +0000 Subject: [PATCH 124/330] Fix internal reference. --- examples.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/examples.rst b/examples.rst index 35de57e4ad..60656e787d 100644 --- a/examples.rst +++ b/examples.rst @@ -285,8 +285,11 @@ by using the `docutils` parser:: warning: check: Title underline too short. (line 2) warning: check: Could not finish the parsing. + +.. _reading-metadata: + Reading the metadata -===================== +==================== The :func:`distutils.core.setup` function provides a command-line interface that allows you to query the metadata fields of a project through the From 0c547064b8f4cf77847eef5b7b941e681181de25 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Wed, 3 Feb 2010 02:35:45 +0000 Subject: [PATCH 125/330] Merged revisions 77484,77487,77561,77570,77593,77603,77608,77667,77702-77703,77739,77858,77887,77889 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r77484 | skip.montanaro | 2010-01-13 19:12:34 -0600 (Wed, 13 Jan 2010) | 4 lines Update PyEval_EvalFrame to PyEval_EvalFrameEx. This looks to have been done partially before. Also add a comment describing how this might have to work with different versions of the interpreter. ........ r77487 | ezio.melotti | 2010-01-14 05:34:10 -0600 (Thu, 14 Jan 2010) | 1 line Fixed typo ........ r77561 | georg.brandl | 2010-01-17 02:42:30 -0600 (Sun, 17 Jan 2010) | 1 line #7699: improve datetime docs: straightforward linking to strftime/strptime section, mark classmethods as such. ........ r77570 | georg.brandl | 2010-01-17 06:14:42 -0600 (Sun, 17 Jan 2010) | 1 line Add note about usage of STRINGLIB_EMPTY. ........ r77593 | georg.brandl | 2010-01-17 17:33:53 -0600 (Sun, 17 Jan 2010) | 1 line Fix internal reference. ........ r77603 | benjamin.peterson | 2010-01-18 17:07:56 -0600 (Mon, 18 Jan 2010) | 8 lines data descriptors do not override the class dictionary if __get__ is not defined Adjust documentation and add a test to verify this behavior. See http://mail.python.org/pipermail/python-dev/2010-January/095637.html for discussion. ........ r77608 | gregory.p.smith | 2010-01-19 02:19:03 -0600 (Tue, 19 Jan 2010) | 6 lines Do not compile stubs for the sha2 series hashes in the openssl hashlib module when the openssl version is too old to support them. That leads both compiled code bloat and to unittests attempting to test implementations that don't exist for comparison purposes on such platforms. ........ r77667 | mark.dickinson | 2010-01-21 12:32:27 -0600 (Thu, 21 Jan 2010) | 1 line Add two more test_strtod test values. ........ r77702 | georg.brandl | 2010-01-23 02:43:31 -0600 (Sat, 23 Jan 2010) | 1 line #7762: fix refcount annotation of PyUnicode_Tailmatch(). ........ r77703 | georg.brandl | 2010-01-23 02:47:54 -0600 (Sat, 23 Jan 2010) | 1 line #7725: fix referencing issue. ........ r77739 | benjamin.peterson | 2010-01-24 21:52:52 -0600 (Sun, 24 Jan 2010) | 1 line mention from_float() in error message ........ r77858 | georg.brandl | 2010-01-30 11:57:48 -0600 (Sat, 30 Jan 2010) | 1 line #7802: fix invalid example (heh). ........ r77887 | georg.brandl | 2010-01-31 12:51:49 -0600 (Sun, 31 Jan 2010) | 5 lines Fix-up ftplib documentation: move exception descriptions to toplevel, not inside a class remove attribution in "versionadded" spell and grammar check docstring of FTP_TLS ........ r77889 | michael.foord | 2010-01-31 13:59:26 -0600 (Sun, 31 Jan 2010) | 1 line Minor modification to unittest documentation. ........ --- examples.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/examples.rst b/examples.rst index 35de57e4ad..60656e787d 100644 --- a/examples.rst +++ b/examples.rst @@ -285,8 +285,11 @@ by using the `docutils` parser:: warning: check: Title underline too short. (line 2) warning: check: Could not finish the parsing. + +.. _reading-metadata: + Reading the metadata -===================== +==================== The :func:`distutils.core.setup` function provides a command-line interface that allows you to query the metadata fields of a project through the From 66e8f6dba46c5c100a5433bd6c8424452bec3f9a Mon Sep 17 00:00:00 2001 From: "Andrew M. Kuchling" Date: Mon, 22 Feb 2010 02:08:45 +0000 Subject: [PATCH 126/330] Re-word --- sourcedist.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 150d1e600c..57e363be2f 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -54,9 +54,9 @@ Notes: requires the :program:`compress` program. Notice that this format is now pending for deprecation and will be removed in the future versions of Python. -When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or ``tar``), you -can specify under Unix the ``owner`` and ``group`` names that will be set for -each member of the archive. +When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or +``tar``) under Unix, you can specify the ``owner`` and ``group`` names +that will be set for each member of the archive. For example, if you want all files of the archive to be owned by root:: From f086d6d5f5dbe36c6d43e2f89f391ee7bd30c202 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 12 Mar 2010 10:02:03 +0000 Subject: [PATCH 127/330] Fix warnings from "make check". --- examples.rst | 16 ++++++++-------- uploading.rst | 8 ++++---- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/examples.rst b/examples.rst index 60656e787d..a5a0239909 100644 --- a/examples.rst +++ b/examples.rst @@ -257,9 +257,9 @@ Running the ``check`` command will display some warnings:: (maintainer and maintainer_email) must be supplied -If you use the reStructuredText syntax in the `long_description` field and +If you use the reStructuredText syntax in the ``long_description`` field and `docutils `_ is installed you can check if -the syntax is fine with the ``check`` command, using the `restructuredtext` +the syntax is fine with the ``check`` command, using the ``restructuredtext`` option. For example, if the :file:`setup.py` script is changed like this:: @@ -278,7 +278,7 @@ For example, if the :file:`setup.py` script is changed like this:: url='http://example.com', long_description=desc) Where the long description is broken, ``check`` will be able to detect it -by using the `docutils` parser:: +by using the :mod:`docutils` parser:: $ pythontrunk setup.py check --restructuredtext running check @@ -293,20 +293,20 @@ Reading the metadata The :func:`distutils.core.setup` function provides a command-line interface that allows you to query the metadata fields of a project through the -`setup.py` script of a given project:: +:file:`setup.py` script of a given project:: $ python setup.py --name distribute -This call reads the `name` metadata by running the +This call reads the ``name`` metadata by running the :func:`distutils.core.setup` function. Although, when a source or binary distribution is created with Distutils, the metadata fields are written in a static file called :file:`PKG-INFO`. When a Distutils-based project is installed in Python, the :file:`PKG-INFO` file is copied alongside the modules and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, -where `NAME` is the name of the project, `VERSION` its version as defined -in the Metadata, and `pyX.X` the major and minor version of Python like -`2.7` or `3.2`. +where ``NAME`` is the name of the project, ``VERSION`` its version as defined +in the Metadata, and ``pyX.X`` the major and minor version of Python like +``2.7`` or ``3.2``. You can read back this static file, by using the :class:`distutils.dist.DistributionMetadata` class and its diff --git a/uploading.rst b/uploading.rst index 84388c2124..1da85362cf 100644 --- a/uploading.rst +++ b/uploading.rst @@ -62,13 +62,13 @@ in the package:: setup(name='Distutils', long_description=open('README.txt')) -In that case, `README.txt` is a regular reStructuredText text file located -in the root of the package besides `setup.py`. +In that case, :file:`README.txt` is a regular reStructuredText text file located +in the root of the package besides :file:`setup.py`. To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the `docutils` package +:program:`rst2html` program that is provided by the :mod:`docutils` package and check the ``long_description`` from the command line:: $ python setup.py --long-description | rst2html.py > output.html -`docutils` will display a warning if there's something wrong with your syntax. +:mod:`docutils` will display a warning if there's something wrong with your syntax. From 65dd20e0fe51c10c37edcd496c1319a1fab415c0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 12 Mar 2010 10:06:40 +0000 Subject: [PATCH 128/330] Merged revisions 78859-78860 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r78859 | georg.brandl | 2010-03-12 10:57:43 +0100 (Fr, 12 Mär 2010) | 1 line Get rid of backticks. ........ r78860 | georg.brandl | 2010-03-12 11:02:03 +0100 (Fr, 12 Mär 2010) | 1 line Fix warnings from "make check". ........ --- examples.rst | 16 ++++++++-------- uploading.rst | 8 ++++---- 2 files changed, 12 insertions(+), 12 deletions(-) diff --git a/examples.rst b/examples.rst index 60656e787d..a5a0239909 100644 --- a/examples.rst +++ b/examples.rst @@ -257,9 +257,9 @@ Running the ``check`` command will display some warnings:: (maintainer and maintainer_email) must be supplied -If you use the reStructuredText syntax in the `long_description` field and +If you use the reStructuredText syntax in the ``long_description`` field and `docutils `_ is installed you can check if -the syntax is fine with the ``check`` command, using the `restructuredtext` +the syntax is fine with the ``check`` command, using the ``restructuredtext`` option. For example, if the :file:`setup.py` script is changed like this:: @@ -278,7 +278,7 @@ For example, if the :file:`setup.py` script is changed like this:: url='http://example.com', long_description=desc) Where the long description is broken, ``check`` will be able to detect it -by using the `docutils` parser:: +by using the :mod:`docutils` parser:: $ pythontrunk setup.py check --restructuredtext running check @@ -293,20 +293,20 @@ Reading the metadata The :func:`distutils.core.setup` function provides a command-line interface that allows you to query the metadata fields of a project through the -`setup.py` script of a given project:: +:file:`setup.py` script of a given project:: $ python setup.py --name distribute -This call reads the `name` metadata by running the +This call reads the ``name`` metadata by running the :func:`distutils.core.setup` function. Although, when a source or binary distribution is created with Distutils, the metadata fields are written in a static file called :file:`PKG-INFO`. When a Distutils-based project is installed in Python, the :file:`PKG-INFO` file is copied alongside the modules and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, -where `NAME` is the name of the project, `VERSION` its version as defined -in the Metadata, and `pyX.X` the major and minor version of Python like -`2.7` or `3.2`. +where ``NAME`` is the name of the project, ``VERSION`` its version as defined +in the Metadata, and ``pyX.X`` the major and minor version of Python like +``2.7`` or ``3.2``. You can read back this static file, by using the :class:`distutils.dist.DistributionMetadata` class and its diff --git a/uploading.rst b/uploading.rst index e9472453d3..7b790b1e02 100644 --- a/uploading.rst +++ b/uploading.rst @@ -60,13 +60,13 @@ in the package:: setup(name='Distutils', long_description=open('README.txt')) -In that case, `README.txt` is a regular reStructuredText text file located -in the root of the package besides `setup.py`. +In that case, :file:`README.txt` is a regular reStructuredText text file located +in the root of the package besides :file:`setup.py`. To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the `docutils` package +:program:`rst2html` program that is provided by the :mod:`docutils` package and check the ``long_description`` from the command line:: $ python setup.py --long-description | rst2html.py > output.html -`docutils` will display a warning if there's something wrong with your syntax. +:mod:`docutils` will display a warning if there's something wrong with your syntax. From a2de19b6a2677a1f47f9d35d6368915337228573 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sun, 21 Mar 2010 22:03:03 +0000 Subject: [PATCH 129/330] Merged revisions 77952,78030,78102,78104,78107,78206,78216,78296-78297,78328,78331-78332,78336,78339,78343,78378-78379,78415,78559,78717,78791 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r77952 | mark.dickinson | 2010-02-03 10:50:14 -0600 (Wed, 03 Feb 2010) | 1 line Fix test_inspect.py data to match recent change to inspect_fodder.py (r77942). ........ r78030 | benjamin.peterson | 2010-02-06 14:14:10 -0600 (Sat, 06 Feb 2010) | 1 line check type_getattro for correctness in a descriptor corner case ........ r78102 | andrew.kuchling | 2010-02-07 19:35:35 -0600 (Sun, 07 Feb 2010) | 1 line Move distutils into its own subsection; add various items ........ r78104 | andrew.kuchling | 2010-02-08 07:22:24 -0600 (Mon, 08 Feb 2010) | 1 line Add two items; move a subsection ........ r78107 | antoine.pitrou | 2010-02-08 14:25:47 -0600 (Mon, 08 Feb 2010) | 3 lines Clarify and correct description for ccbench and iobench. ........ r78206 | r.david.murray | 2010-02-16 11:55:26 -0600 (Tue, 16 Feb 2010) | 3 lines Make the references to Popen in the description of Call and check_call into links. ........ r78216 | andrew.kuchling | 2010-02-18 08:16:48 -0600 (Thu, 18 Feb 2010) | 1 line Add various items ........ r78296 | andrew.kuchling | 2010-02-21 20:08:45 -0600 (Sun, 21 Feb 2010) | 1 line Re-word ........ r78297 | andrew.kuchling | 2010-02-21 20:29:10 -0600 (Sun, 21 Feb 2010) | 1 line #7076: mention SystemRandom class near start of the module docs; reword change description for clarity. Noted by Shawn Ligocki. ........ r78328 | jack.diederich | 2010-02-22 12:17:16 -0600 (Mon, 22 Feb 2010) | 1 line fixes issue #7530, serve_forever() ........ r78331 | andrew.kuchling | 2010-02-22 12:38:23 -0600 (Mon, 22 Feb 2010) | 1 line Fix comment typo ........ r78332 | andrew.kuchling | 2010-02-22 12:42:07 -0600 (Mon, 22 Feb 2010) | 2 lines #7627: MH.remove() would fail if the MH mailbox was locked; it would call _unlock_file() and pass it a closed file object. Noted by Rob Austein. ........ r78336 | jack.diederich | 2010-02-22 13:55:22 -0600 (Mon, 22 Feb 2010) | 1 line fixes issue #1522237, bad init check in _threading_local ........ r78339 | jack.diederich | 2010-02-22 15:27:38 -0600 (Mon, 22 Feb 2010) | 1 line * fix issue#7476 ........ r78343 | andrew.kuchling | 2010-02-22 16:48:41 -0600 (Mon, 22 Feb 2010) | 10 lines #2560: remove an unnecessary 'for' loop from my_fgets() in Parser/myreadline.c. Noted by Joseph Armbruster; patch by Jessica McKellar. The original code was 'for (;;) {...}', where ... ended with a 'return -2' statement and did not contain a 'break' or 'continue' statement. Therefore, the body of the loop is always executed once. Once upon a time there was a 'continue' in the loop, but it was removed in rev36346, committed by mwh on Wed Jul 7 17:44:12 2004. ........ r78378 | jack.diederich | 2010-02-23 11:23:30 -0600 (Tue, 23 Feb 2010) | 1 line fixup markup error ........ r78379 | jack.diederich | 2010-02-23 13:34:06 -0600 (Tue, 23 Feb 2010) | 1 line issue#6442 use in operator instead of has_key ........ r78415 | dirkjan.ochtman | 2010-02-23 22:00:52 -0600 (Tue, 23 Feb 2010) | 1 line Issue #7733: add explicit reference in asyncore docs. ........ r78559 | andrew.kuchling | 2010-03-01 13:45:21 -0600 (Mon, 01 Mar 2010) | 1 line #7637: update discussion of minidom.unlink() and garbage collection ........ r78717 | benjamin.peterson | 2010-03-05 21:13:33 -0600 (Fri, 05 Mar 2010) | 1 line settscdump is definitely an implementation detail ........ r78791 | andrew.kuchling | 2010-03-08 06:00:39 -0600 (Mon, 08 Mar 2010) | 1 line Add various items ........ --- sourcedist.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 150d1e600c..57e363be2f 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -54,9 +54,9 @@ Notes: requires the :program:`compress` program. Notice that this format is now pending for deprecation and will be removed in the future versions of Python. -When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or ``tar``), you -can specify under Unix the ``owner`` and ``group`` names that will be set for -each member of the archive. +When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or +``tar``) under Unix, you can specify the ``owner`` and ``group`` names +that will be set for each member of the archive. For example, if you want all files of the archive to be owned by root:: From 4264b34d4d242fed290ab4f5dd6d4728fb7b9a66 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Fri, 2 Apr 2010 21:34:19 +0000 Subject: [PATCH 130/330] removed documentation on code that was reverted and pushed into distutils2 --- apiref.rst | 13 ------- examples.rst | 97 ---------------------------------------------------- 2 files changed, 110 deletions(-) diff --git a/apiref.rst b/apiref.rst index a70c8071f1..6541fc21ae 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1926,19 +1926,6 @@ This is described in more detail in :pep:`301`. .. % todo -:mod:`distutils.command.check` --- Check the meta-data of a package -=================================================================== - -.. module:: distutils.command.check - :synopsis: Check the metadata of a package - - -The ``check`` command performs some tests on the meta-data of a package. -For example, it verifies that all required meta-data are provided as -the arguments passed to the :func:`setup` function. - -.. % todo - Creating a new Distutils command ================================ diff --git a/examples.rst b/examples.rst index a5a0239909..b495928657 100644 --- a/examples.rst +++ b/examples.rst @@ -233,103 +233,6 @@ With exactly the same source tree layout, this extension can be put in the ext_modules=[Extension('foopkg.foo', ['foo.c'])], ) -Checking a package -================== - -The ``check`` command allows you to verify if your package meta-data -meet the minimum requirements to build a distribution. - -To run it, just call it using your :file:`setup.py` script. If something is -missing, ``check`` will display a warning. - -Let's take an example with a simple script:: - - from distutils.core import setup - - setup(name='foobar') - -Running the ``check`` command will display some warnings:: - - $ python setup.py check - running check - warning: check: missing required meta-data: version, url - warning: check: missing meta-data: either (author and author_email) or - (maintainer and maintainer_email) must be supplied - - -If you use the reStructuredText syntax in the ``long_description`` field and -`docutils `_ is installed you can check if -the syntax is fine with the ``check`` command, using the ``restructuredtext`` -option. - -For example, if the :file:`setup.py` script is changed like this:: - - from distutils.core import setup - - desc = """\ - My description - ============= - - This is the description of the ``foobar`` package. - """ - - setup(name='foobar', version='1', author='tarek', - author_email='tarek@ziade.org', - url='http://example.com', long_description=desc) - -Where the long description is broken, ``check`` will be able to detect it -by using the :mod:`docutils` parser:: - - $ pythontrunk setup.py check --restructuredtext - running check - warning: check: Title underline too short. (line 2) - warning: check: Could not finish the parsing. - - -.. _reading-metadata: - -Reading the metadata -==================== - -The :func:`distutils.core.setup` function provides a command-line interface -that allows you to query the metadata fields of a project through the -:file:`setup.py` script of a given project:: - - $ python setup.py --name - distribute - -This call reads the ``name`` metadata by running the -:func:`distutils.core.setup` function. Although, when a source or binary -distribution is created with Distutils, the metadata fields are written -in a static file called :file:`PKG-INFO`. When a Distutils-based project is -installed in Python, the :file:`PKG-INFO` file is copied alongside the modules -and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, -where ``NAME`` is the name of the project, ``VERSION`` its version as defined -in the Metadata, and ``pyX.X`` the major and minor version of Python like -``2.7`` or ``3.2``. - -You can read back this static file, by using the -:class:`distutils.dist.DistributionMetadata` class and its -:func:`read_pkg_file` method:: - - >>> from distutils.dist import DistributionMetadata - >>> metadata = DistributionMetadata() - >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info')) - >>> metadata.name - 'distribute' - >>> metadata.version - '0.6.8' - >>> metadata.description - 'Easily download, build, install, upgrade, and uninstall Python packages' - -Notice that the class can also be instanciated with a metadata file path to -loads its values:: - - >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info' - >>> DistributionMetadata(pkg_info_path).name - 'distribute' - - .. % \section{Multiple extension modules} .. % \label{multiple-ext} From f13cd6af789a9976c0785cf40afac7f334bd2ff1 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sun, 11 Apr 2010 16:12:57 +0000 Subject: [PATCH 131/330] Merged revisions 79307,79408,79430,79533,79542,79579-79580,79585-79587,79607-79608,79622,79717,79820,79822,79828,79862,79875,79923-79924,79941-79943,79945,79947,79951-79952 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r79307 | florent.xicluna | 2010-03-22 17:45:50 -0500 (Mon, 22 Mar 2010) | 2 lines #7667: Fix doctest failures with non-ASCII paths. ........ r79408 | victor.stinner | 2010-03-24 20:18:38 -0500 (Wed, 24 Mar 2010) | 2 lines Fix a gcc warning introduced by r79397. ........ r79430 | brian.curtin | 2010-03-25 18:48:54 -0500 (Thu, 25 Mar 2010) | 2 lines Fix #6538. Markup RegexObject and MatchObject as classes. Patch by Ryan Arana. ........ r79533 | barry.warsaw | 2010-03-31 16:07:16 -0500 (Wed, 31 Mar 2010) | 6 lines - Issue #8233: When run as a script, py_compile.py optionally takes a single argument `-` which tells it to read files to compile from stdin. Each line is read on demand and the named file is compiled immediately. (Original patch by Piotr O?\197?\188arowski). ........ r79542 | r.david.murray | 2010-03-31 20:28:39 -0500 (Wed, 31 Mar 2010) | 3 lines A couple small grammar fixes in test.rst, and rewrite the check_warnings docs to be clearer. ........ r79579 | georg.brandl | 2010-04-02 03:34:41 -0500 (Fri, 02 Apr 2010) | 1 line Add 2.6.5. ........ r79580 | georg.brandl | 2010-04-02 03:39:09 -0500 (Fri, 02 Apr 2010) | 1 line #2768: add a note on how to get a file descriptor. ........ r79585 | georg.brandl | 2010-04-02 04:03:18 -0500 (Fri, 02 Apr 2010) | 1 line Remove col-spanning cells in logging docs. ........ r79586 | georg.brandl | 2010-04-02 04:07:42 -0500 (Fri, 02 Apr 2010) | 1 line Document PyImport_ExecCodeModuleEx(). ........ r79587 | georg.brandl | 2010-04-02 04:11:49 -0500 (Fri, 02 Apr 2010) | 1 line #8012: clarification in generator glossary entry. ........ r79607 | andrew.kuchling | 2010-04-02 12:48:23 -0500 (Fri, 02 Apr 2010) | 1 line #6647: document that catch_warnings is not thread-safe ........ r79608 | andrew.kuchling | 2010-04-02 12:54:26 -0500 (Fri, 02 Apr 2010) | 1 line #6647: add note to two examples ........ r79622 | tarek.ziade | 2010-04-02 16:34:19 -0500 (Fri, 02 Apr 2010) | 1 line removed documentation on code that was reverted and pushed into distutils2 ........ r79717 | antoine.pitrou | 2010-04-03 16:22:38 -0500 (Sat, 03 Apr 2010) | 4 lines Fix wording / typography, and a slightly misleading statement (memoryviews don't support complex structures right now) ........ r79820 | benjamin.peterson | 2010-04-05 22:34:09 -0500 (Mon, 05 Apr 2010) | 1 line ready _sre types ........ r79822 | georg.brandl | 2010-04-06 03:18:15 -0500 (Tue, 06 Apr 2010) | 1 line #8320: document return value of recv_into(). ........ r79828 | georg.brandl | 2010-04-06 09:33:44 -0500 (Tue, 06 Apr 2010) | 1 line Add JP. ........ r79862 | georg.brandl | 2010-04-06 15:27:59 -0500 (Tue, 06 Apr 2010) | 1 line Fix syntax. ........ r79875 | mark.dickinson | 2010-04-06 17:18:23 -0500 (Tue, 06 Apr 2010) | 1 line More NaN consistency doc fixes. ........ r79923 | georg.brandl | 2010-04-10 06:15:24 -0500 (Sat, 10 Apr 2010) | 1 line #8360: skipTest was added in 2.7. ........ r79924 | georg.brandl | 2010-04-10 06:16:59 -0500 (Sat, 10 Apr 2010) | 1 line #8346: update version. ........ r79941 | andrew.kuchling | 2010-04-10 20:39:36 -0500 (Sat, 10 Apr 2010) | 1 line Two grammar fixes ........ r79942 | andrew.kuchling | 2010-04-10 20:40:06 -0500 (Sat, 10 Apr 2010) | 1 line Punctuation fix ........ r79943 | andrew.kuchling | 2010-04-10 20:40:30 -0500 (Sat, 10 Apr 2010) | 1 line Add various items ........ r79945 | andrew.kuchling | 2010-04-10 20:40:49 -0500 (Sat, 10 Apr 2010) | 1 line name correct ........ r79947 | andrew.kuchling | 2010-04-10 20:44:13 -0500 (Sat, 10 Apr 2010) | 1 line Remove distutils section ........ r79951 | andrew.kuchling | 2010-04-11 07:48:08 -0500 (Sun, 11 Apr 2010) | 1 line Two typo fixes ........ r79952 | andrew.kuchling | 2010-04-11 07:49:37 -0500 (Sun, 11 Apr 2010) | 1 line Add two items ........ --- apiref.rst | 13 ------- examples.rst | 97 ---------------------------------------------------- 2 files changed, 110 deletions(-) diff --git a/apiref.rst b/apiref.rst index 69ec0de99b..6bcf3a7c25 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1944,19 +1944,6 @@ This is described in more detail in :pep:`301`. .. % todo -:mod:`distutils.command.check` --- Check the meta-data of a package -=================================================================== - -.. module:: distutils.command.check - :synopsis: Check the metadata of a package - - -The ``check`` command performs some tests on the meta-data of a package. -For example, it verifies that all required meta-data are provided as -the arguments passed to the :func:`setup` function. - -.. % todo - Creating a new Distutils command ================================ diff --git a/examples.rst b/examples.rst index a5a0239909..b495928657 100644 --- a/examples.rst +++ b/examples.rst @@ -233,103 +233,6 @@ With exactly the same source tree layout, this extension can be put in the ext_modules=[Extension('foopkg.foo', ['foo.c'])], ) -Checking a package -================== - -The ``check`` command allows you to verify if your package meta-data -meet the minimum requirements to build a distribution. - -To run it, just call it using your :file:`setup.py` script. If something is -missing, ``check`` will display a warning. - -Let's take an example with a simple script:: - - from distutils.core import setup - - setup(name='foobar') - -Running the ``check`` command will display some warnings:: - - $ python setup.py check - running check - warning: check: missing required meta-data: version, url - warning: check: missing meta-data: either (author and author_email) or - (maintainer and maintainer_email) must be supplied - - -If you use the reStructuredText syntax in the ``long_description`` field and -`docutils `_ is installed you can check if -the syntax is fine with the ``check`` command, using the ``restructuredtext`` -option. - -For example, if the :file:`setup.py` script is changed like this:: - - from distutils.core import setup - - desc = """\ - My description - ============= - - This is the description of the ``foobar`` package. - """ - - setup(name='foobar', version='1', author='tarek', - author_email='tarek@ziade.org', - url='http://example.com', long_description=desc) - -Where the long description is broken, ``check`` will be able to detect it -by using the :mod:`docutils` parser:: - - $ pythontrunk setup.py check --restructuredtext - running check - warning: check: Title underline too short. (line 2) - warning: check: Could not finish the parsing. - - -.. _reading-metadata: - -Reading the metadata -==================== - -The :func:`distutils.core.setup` function provides a command-line interface -that allows you to query the metadata fields of a project through the -:file:`setup.py` script of a given project:: - - $ python setup.py --name - distribute - -This call reads the ``name`` metadata by running the -:func:`distutils.core.setup` function. Although, when a source or binary -distribution is created with Distutils, the metadata fields are written -in a static file called :file:`PKG-INFO`. When a Distutils-based project is -installed in Python, the :file:`PKG-INFO` file is copied alongside the modules -and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, -where ``NAME`` is the name of the project, ``VERSION`` its version as defined -in the Metadata, and ``pyX.X`` the major and minor version of Python like -``2.7`` or ``3.2``. - -You can read back this static file, by using the -:class:`distutils.dist.DistributionMetadata` class and its -:func:`read_pkg_file` method:: - - >>> from distutils.dist import DistributionMetadata - >>> metadata = DistributionMetadata() - >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info')) - >>> metadata.name - 'distribute' - >>> metadata.version - '0.6.8' - >>> metadata.description - 'Easily download, build, install, upgrade, and uninstall Python packages' - -Notice that the class can also be instanciated with a metadata file path to -loads its values:: - - >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info' - >>> DistributionMetadata(pkg_info_path).name - 'distribute' - - .. % \section{Multiple extension modules} .. % \label{multiple-ext} From 3b468f46bede0b5931a52e0b12e4ba7c625ba4f5 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Mon, 17 May 2010 10:54:43 +0000 Subject: [PATCH 132/330] upgraded distutils docs w.r.t. the manifest regeneration --- sourcedist.rst | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 57e363be2f..f6809c95a0 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -137,20 +137,12 @@ There are a couple of options that modify this behaviour. First, use the :option:`--no-defaults` and :option:`--no-prune` to disable the standard "include" and "exclude" sets. -Second, you might want to force the manifest to be regenerated---for example, if -you have added or removed files or directories that match an existing pattern in -the manifest template, you should regenerate the manifest:: - - python setup.py sdist --force-manifest - -Or, you might just want to (re)generate the manifest, but not create a source -distribution:: +Second, you might just want to (re)generate the manifest, but not create a +source distribution:: python setup.py sdist --manifest-only -:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a -shortcut for :option:`--manifest-only`, and :option:`-f` for -:option:`--force-manifest`. +:option:`-o` is a sortcut for :option:`--manifest-only`. .. _manifest_template: From dc26c03ab1cb89dcccdec13fb785daa53df4ae41 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Mon, 17 May 2010 11:00:17 +0000 Subject: [PATCH 133/330] Merged revisions 81261 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r81261 | tarek.ziade | 2010-05-17 12:54:43 +0200 (Mon, 17 May 2010) | 1 line upgraded distutils docs w.r.t. the manifest regeneration ........ --- sourcedist.rst | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 960cc0ae4d..b45515d8d9 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -191,19 +191,11 @@ There are a couple of options that modify this behaviour. First, use the :option:`--no-defaults` and :option:`--no-prune` to disable the standard "include" and "exclude" sets. -Second, you might want to force the manifest to be regenerated---for example, if -you have added or removed files or directories that match an existing pattern in -the manifest template, you should regenerate the manifest:: - - python setup.py sdist --force-manifest - -Or, you might just want to (re)generate the manifest, but not create a source +Second, you might just want to (re)generate the manifest, but not create a source distribution:: python setup.py sdist --manifest-only -:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a -shortcut for :option:`--manifest-only`, and :option:`-f` for -:option:`--force-manifest`. +:option:`-o` is a shortcut for :option:`--manifest-only`. From c6066c2a3f6dfb15662e7078599cee493ad7842f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Mon, 17 May 2010 11:01:57 +0000 Subject: [PATCH 134/330] Merged revisions 81261 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r81261 | tarek.ziade | 2010-05-17 12:54:43 +0200 (Mon, 17 May 2010) | 1 line upgraded distutils docs w.r.t. the manifest regeneration ........ --- sourcedist.rst | 14 +++----------- 1 file changed, 3 insertions(+), 11 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 57e363be2f..f6809c95a0 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -137,20 +137,12 @@ There are a couple of options that modify this behaviour. First, use the :option:`--no-defaults` and :option:`--no-prune` to disable the standard "include" and "exclude" sets. -Second, you might want to force the manifest to be regenerated---for example, if -you have added or removed files or directories that match an existing pattern in -the manifest template, you should regenerate the manifest:: - - python setup.py sdist --force-manifest - -Or, you might just want to (re)generate the manifest, but not create a source -distribution:: +Second, you might just want to (re)generate the manifest, but not create a +source distribution:: python setup.py sdist --manifest-only -:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a -shortcut for :option:`--manifest-only`, and :option:`-f` for -:option:`--force-manifest`. +:option:`-o` is a sortcut for :option:`--manifest-only`. .. _manifest_template: From ca09c90f23a877a2863465c95883d29ece867c49 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Mon, 17 May 2010 11:04:41 +0000 Subject: [PATCH 135/330] Merged revisions 81263 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ................ r81263 | tarek.ziade | 2010-05-17 13:01:57 +0200 (Mon, 17 May 2010) | 9 lines Merged revisions 81261 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r81261 | tarek.ziade | 2010-05-17 12:54:43 +0200 (Mon, 17 May 2010) | 1 line upgraded distutils docs w.r.t. the manifest regeneration ........ ................ --- sourcedist.rst | 12 ++---------- 1 file changed, 2 insertions(+), 10 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 0c786c5a0a..96e891bd68 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -198,19 +198,11 @@ There are a couple of options that modify this behaviour. First, use the :option:`--no-defaults` and :option:`--no-prune` to disable the standard "include" and "exclude" sets. -Second, you might want to force the manifest to be regenerated---for example, if -you have added or removed files or directories that match an existing pattern in -the manifest template, you should regenerate the manifest:: - - python setup.py sdist --force-manifest - -Or, you might just want to (re)generate the manifest, but not create a source +Second, you might just want to (re)generate the manifest, but not create a source distribution:: python setup.py sdist --manifest-only -:option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a -shortcut for :option:`--manifest-only`, and :option:`-f` for -:option:`--force-manifest`. +:option:`-o` is a shortcut for :option:`--manifest-only`. From e94e377fc4e64e6fb81db889a40be92ca212aa05 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 6 Jun 2010 20:05:20 +0000 Subject: [PATCH 136/330] Fixed #8909: now the doc details the size of the bitmap used in distutils' bdist_wininst --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index c7b756bed1..ab37c0f7a8 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -322,7 +322,7 @@ the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` option. By default the installer will display the cool "Python Powered" logo when it is -run, but you can also supply your own bitmap which must be a Windows +run, but you can also supply your own 152x161 bitmap which must be a Windows :file:`.bmp` file with the :option:`--bitmap` option. The installer will also display a large title on the desktop background window From 77573e737a92aeb54c0754546308efee5575c4aa Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 6 Jun 2010 20:10:03 +0000 Subject: [PATCH 137/330] Merged revisions 81788 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r81788 | tarek.ziade | 2010-06-06 22:05:20 +0200 (Sun, 06 Jun 2010) | 1 line Fixed #8909: now the doc details the size of the bitmap used in distutils' bdist_wininst ........ --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index 25d392348b..ade5dfa561 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -318,7 +318,7 @@ the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` option. By default the installer will display the cool "Python Powered" logo when it is -run, but you can also supply your own bitmap which must be a Windows +run, but you can also supply your own 152x161 bitmap which must be a Windows :file:`.bmp` file with the :option:`--bitmap` option. The installer will also display a large title on the desktop background window From 0404ca224abb6ace9c9435286639613f94530213 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 6 Jun 2010 20:18:42 +0000 Subject: [PATCH 138/330] Merged revisions 81788 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r81788 | tarek.ziade | 2010-06-06 22:05:20 +0200 (Sun, 06 Jun 2010) | 1 line Fixed #8909: now the doc details the size of the bitmap used in distutils' bdist_wininst ........ --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index c7b756bed1..ab37c0f7a8 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -322,7 +322,7 @@ the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` option. By default the installer will display the cool "Python Powered" logo when it is -run, but you can also supply your own bitmap which must be a Windows +run, but you can also supply your own 152x161 bitmap which must be a Windows :file:`.bmp` file with the :option:`--bitmap` option. The installer will also display a large title on the desktop background window From 3725f9e576aea207da75bf3c3c524e5a9000d870 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sun, 6 Jun 2010 20:23:10 +0000 Subject: [PATCH 139/330] Merged revisions 81790 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ................ r81790 | tarek.ziade | 2010-06-06 22:18:42 +0200 (Sun, 06 Jun 2010) | 9 lines Merged revisions 81788 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r81788 | tarek.ziade | 2010-06-06 22:05:20 +0200 (Sun, 06 Jun 2010) | 1 line Fixed #8909: now the doc details the size of the bitmap used in distutils' bdist_wininst ........ ................ --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index e58937d200..74cc80af41 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -321,7 +321,7 @@ the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` option. By default the installer will display the cool "Python Powered" logo when it is -run, but you can also supply your own bitmap which must be a Windows +run, but you can also supply your own 152x161 bitmap which must be a Windows :file:`.bmp` file with the :option:`--bitmap` option. The installer will also display a large title on the desktop background window From 6740653b602a377830fa36624ba463a7bf7a4717 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 27 Jun 2010 10:55:38 +0000 Subject: [PATCH 140/330] Two typos. --- builtdist.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index ab37c0f7a8..5832552bfa 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -322,7 +322,7 @@ the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` option. By default the installer will display the cool "Python Powered" logo when it is -run, but you can also supply your own 152x161 bitmap which must be a Windows +run, but you can also supply your own 152x261 bitmap which must be a Windows :file:`.bmp` file with the :option:`--bitmap` option. The installer will also display a large title on the desktop background window @@ -375,7 +375,7 @@ check or modify your existing install.) The Postinstallation script --------------------------- -Starting with Python 2.3, a postinstallation script can be specified which the +Starting with Python 2.3, a postinstallation script can be specified with the :option:`--install-script` option. The basename of the script must be specified, and the script filename must also be listed in the scripts argument to the setup function. From 992d53b3906c27551a40d5385f1b07ce70abb454 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sun, 27 Jun 2010 22:32:30 +0000 Subject: [PATCH 141/330] Merged revisions 80605-80609,80642-80646,80651-80652,80674,80684-80686,80748,80852,80854,80870,80872-80873,80907,80915-80916,80951-80952,80976-80977,80985,81038-81040,81042,81053,81070,81104-81105,81114,81125,81245,81285,81402,81463,81516,81562-81563,81567,81593,81635,81680-81681,81684,81801,81888,81931-81933,81939-81942,81963,81984,81991,82120,82188,82264-82267 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r80605 | andrew.kuchling | 2010-04-28 19:22:16 -0500 (Wed, 28 Apr 2010) | 1 line Add various items ........ r80606 | andrew.kuchling | 2010-04-28 20:44:30 -0500 (Wed, 28 Apr 2010) | 6 lines Fix doubled 'the'. Markup fixes to use :exc:, :option: in a few places. (Glitch: unittest.main's -c ends up a link to the Python interpreter's -c option. Should we skip using :option: for that switch, or disable the auto-linking somehow?) ........ r80607 | andrew.kuchling | 2010-04-28 20:45:41 -0500 (Wed, 28 Apr 2010) | 1 line Add various unittest items ........ r80608 | benjamin.peterson | 2010-04-28 22:18:05 -0500 (Wed, 28 Apr 2010) | 1 line update pypy description ........ r80609 | benjamin.peterson | 2010-04-28 22:30:59 -0500 (Wed, 28 Apr 2010) | 1 line update pypy url ........ r80642 | andrew.kuchling | 2010-04-29 19:49:09 -0500 (Thu, 29 Apr 2010) | 1 line Always add space after RFC; reword paragraph ........ r80643 | andrew.kuchling | 2010-04-29 19:52:31 -0500 (Thu, 29 Apr 2010) | 6 lines Reword paragraph to make its meaning clearer. Antoine Pitrou: is my version of the paragraph still correct? R. David Murray: is this more understandable than the previous version? ........ r80644 | andrew.kuchling | 2010-04-29 20:02:15 -0500 (Thu, 29 Apr 2010) | 1 line Fix typos ........ r80645 | andrew.kuchling | 2010-04-29 20:32:47 -0500 (Thu, 29 Apr 2010) | 1 line Markup fix; clarify by adding 'in that order' ........ r80646 | andrew.kuchling | 2010-04-29 20:33:40 -0500 (Thu, 29 Apr 2010) | 1 line Add various items; rearrange unittest section a bit ........ r80651 | andrew.kuchling | 2010-04-30 08:46:55 -0500 (Fri, 30 Apr 2010) | 1 line Minor grammar re-wording ........ r80652 | andrew.kuchling | 2010-04-30 08:47:34 -0500 (Fri, 30 Apr 2010) | 1 line Add item ........ r80674 | andrew.kuchling | 2010-04-30 20:19:16 -0500 (Fri, 30 Apr 2010) | 1 line Add various items ........ r80684 | andrew.kuchling | 2010-05-01 07:05:52 -0500 (Sat, 01 May 2010) | 1 line Minor grammar fix ........ r80685 | andrew.kuchling | 2010-05-01 07:06:51 -0500 (Sat, 01 May 2010) | 1 line Describe memoryview ........ r80686 | antoine.pitrou | 2010-05-01 07:16:39 -0500 (Sat, 01 May 2010) | 4 lines Fix attribution. Travis didn't do much and he did a bad work. (yes, this is a sensitive subject, sorry) ........ r80748 | andrew.kuchling | 2010-05-03 20:24:22 -0500 (Mon, 03 May 2010) | 1 line Add some more items; the urlparse change is added twice ........ r80852 | andrew.kuchling | 2010-05-05 20:09:47 -0500 (Wed, 05 May 2010) | 1 line Reword paragraph; fix filename, which should be pyconfig.h ........ r80854 | andrew.kuchling | 2010-05-05 20:10:56 -0500 (Wed, 05 May 2010) | 1 line Add various items ........ r80870 | andrew.kuchling | 2010-05-06 09:14:09 -0500 (Thu, 06 May 2010) | 1 line Describe ElementTree 1.3; rearrange new-module sections; describe dict views as sets; small edits and items ........ r80872 | andrew.kuchling | 2010-05-06 12:21:59 -0500 (Thu, 06 May 2010) | 1 line Add 2 items; record ideas for two initial sections; clarify wording ........ r80873 | andrew.kuchling | 2010-05-06 12:27:57 -0500 (Thu, 06 May 2010) | 1 line Change section title; point to unittest2 ........ r80907 | andrew.kuchling | 2010-05-06 20:45:14 -0500 (Thu, 06 May 2010) | 1 line Add a new section on the development plan; add an item ........ r80915 | antoine.pitrou | 2010-05-07 05:15:51 -0500 (Fri, 07 May 2010) | 3 lines Fix some markup and a class name. Also, wrap a long line. ........ r80916 | andrew.kuchling | 2010-05-07 06:30:47 -0500 (Fri, 07 May 2010) | 1 line Re-word text ........ r80951 | andrew.kuchling | 2010-05-07 20:15:26 -0500 (Fri, 07 May 2010) | 1 line Add two items ........ r80952 | andrew.kuchling | 2010-05-07 20:35:55 -0500 (Fri, 07 May 2010) | 1 line Get accents correct ........ r80976 | andrew.kuchling | 2010-05-08 08:28:03 -0500 (Sat, 08 May 2010) | 1 line Add logging.dictConfig example; give up on writing a Ttk example ........ r80977 | andrew.kuchling | 2010-05-08 08:29:46 -0500 (Sat, 08 May 2010) | 1 line Markup fixes ........ r80985 | andrew.kuchling | 2010-05-08 10:39:46 -0500 (Sat, 08 May 2010) | 7 lines Write summary of the 2.7 release; rewrite the future section some more; mention PYTHONWARNINGS env. var; tweak some examples for readability. And with this commit, the "What's New" is done... except for a complete read-through to polish the text, and fixing any reported errors, but those tasks can easily wait until after beta2. ........ r81038 | benjamin.peterson | 2010-05-09 16:09:40 -0500 (Sun, 09 May 2010) | 1 line finish clause ........ r81039 | andrew.kuchling | 2010-05-10 09:18:27 -0500 (Mon, 10 May 2010) | 1 line Markup fix; re-word a sentence ........ r81040 | andrew.kuchling | 2010-05-10 09:20:12 -0500 (Mon, 10 May 2010) | 1 line Use title case ........ r81042 | andrew.kuchling | 2010-05-10 10:03:35 -0500 (Mon, 10 May 2010) | 1 line Link to unittest2 article ........ r81053 | florent.xicluna | 2010-05-10 14:59:22 -0500 (Mon, 10 May 2010) | 2 lines Add a link on maketrans(). ........ r81070 | andrew.kuchling | 2010-05-10 18:13:41 -0500 (Mon, 10 May 2010) | 1 line Fix typo ........ r81104 | andrew.kuchling | 2010-05-11 19:38:44 -0500 (Tue, 11 May 2010) | 1 line Revision pass: lots of edits, typo fixes, rearrangements ........ r81105 | andrew.kuchling | 2010-05-11 19:40:47 -0500 (Tue, 11 May 2010) | 1 line Let's call this done ........ r81114 | andrew.kuchling | 2010-05-12 08:56:07 -0500 (Wed, 12 May 2010) | 1 line Grammar fix ........ r81125 | andrew.kuchling | 2010-05-12 13:56:48 -0500 (Wed, 12 May 2010) | 1 line #8696: add documentation for logging.config.dictConfig (PEP 391) ........ r81245 | andrew.kuchling | 2010-05-16 18:31:16 -0500 (Sun, 16 May 2010) | 1 line Add cross-reference to later section ........ r81285 | vinay.sajip | 2010-05-18 03:16:27 -0500 (Tue, 18 May 2010) | 1 line Fixed minor typo in ReST markup. ........ r81402 | vinay.sajip | 2010-05-21 12:41:34 -0500 (Fri, 21 May 2010) | 1 line Updated logging documentation with more dictConfig information. ........ r81463 | georg.brandl | 2010-05-22 03:17:23 -0500 (Sat, 22 May 2010) | 1 line #8785: less confusing description of regex.find*. ........ r81516 | andrew.kuchling | 2010-05-25 08:34:08 -0500 (Tue, 25 May 2010) | 1 line Add three items ........ r81562 | andrew.kuchling | 2010-05-27 08:22:53 -0500 (Thu, 27 May 2010) | 1 line Rewrite wxWidgets section ........ r81563 | andrew.kuchling | 2010-05-27 08:30:09 -0500 (Thu, 27 May 2010) | 1 line Remove top-level 'General Questions' section, pushing up the questions it contains ........ r81567 | andrew.kuchling | 2010-05-27 16:29:59 -0500 (Thu, 27 May 2010) | 1 line Add item ........ r81593 | georg.brandl | 2010-05-29 03:46:18 -0500 (Sat, 29 May 2010) | 1 line #8616: add new turtle demo "nim". ........ r81635 | georg.brandl | 2010-06-01 02:25:23 -0500 (Tue, 01 Jun 2010) | 1 line Put docs for RegexObject.search() before RegexObject.match() to mirror re.search() and re.match() order. ........ r81680 | vinay.sajip | 2010-06-03 17:34:42 -0500 (Thu, 03 Jun 2010) | 1 line Issue #8890: Documentation changed to avoid reference to temporary files. ........ r81681 | sean.reifschneider | 2010-06-03 20:51:26 -0500 (Thu, 03 Jun 2010) | 2 lines Issue8810: Clearing up docstring for tzinfo.utcoffset. ........ r81684 | vinay.sajip | 2010-06-04 08:41:02 -0500 (Fri, 04 Jun 2010) | 1 line Issue #8890: Documentation changed to avoid reference to temporary files - other cases covered. ........ r81801 | andrew.kuchling | 2010-06-07 08:38:40 -0500 (Mon, 07 Jun 2010) | 1 line #8875: Remove duplicated paragraph ........ r81888 | andrew.kuchling | 2010-06-10 20:54:58 -0500 (Thu, 10 Jun 2010) | 1 line Add a few more items ........ r81931 | georg.brandl | 2010-06-12 01:26:54 -0500 (Sat, 12 Jun 2010) | 1 line Fix punctuation. ........ r81932 | georg.brandl | 2010-06-12 01:28:58 -0500 (Sat, 12 Jun 2010) | 1 line Document that an existing directory raises in mkdir(). ........ r81933 | georg.brandl | 2010-06-12 01:45:33 -0500 (Sat, 12 Jun 2010) | 1 line Update version in README. ........ r81939 | georg.brandl | 2010-06-12 04:45:01 -0500 (Sat, 12 Jun 2010) | 1 line Use newer toctree syntax. ........ r81940 | georg.brandl | 2010-06-12 04:45:28 -0500 (Sat, 12 Jun 2010) | 1 line Add document on how to build. ........ r81941 | georg.brandl | 2010-06-12 04:45:58 -0500 (Sat, 12 Jun 2010) | 1 line Fix gratuitous indentation. ........ r81942 | georg.brandl | 2010-06-12 04:46:03 -0500 (Sat, 12 Jun 2010) | 1 line Update README. ........ r81963 | andrew.kuchling | 2010-06-12 15:00:55 -0500 (Sat, 12 Jun 2010) | 1 line Grammar fix ........ r81984 | georg.brandl | 2010-06-14 10:58:39 -0500 (Mon, 14 Jun 2010) | 1 line #8993: fix reference. ........ r81991 | andrew.kuchling | 2010-06-14 19:38:58 -0500 (Mon, 14 Jun 2010) | 1 line Add another bunch of items ........ r82120 | andrew.kuchling | 2010-06-20 16:45:45 -0500 (Sun, 20 Jun 2010) | 1 line Note that Python 3.x isn't covered; add forward ref. for UTF-8; note error in 2.5 and up ........ r82188 | benjamin.peterson | 2010-06-23 19:02:46 -0500 (Wed, 23 Jun 2010) | 1 line remove reverted changed ........ r82264 | georg.brandl | 2010-06-27 05:47:47 -0500 (Sun, 27 Jun 2010) | 1 line Confusing punctuation. ........ r82265 | georg.brandl | 2010-06-27 05:49:23 -0500 (Sun, 27 Jun 2010) | 1 line Use designated syntax for optional grammar element. ........ r82266 | georg.brandl | 2010-06-27 05:51:44 -0500 (Sun, 27 Jun 2010) | 1 line Fix URL. ........ r82267 | georg.brandl | 2010-06-27 05:55:38 -0500 (Sun, 27 Jun 2010) | 1 line Two typos. ........ --- builtdist.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index ab37c0f7a8..5832552bfa 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -322,7 +322,7 @@ the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` option. By default the installer will display the cool "Python Powered" logo when it is -run, but you can also supply your own 152x161 bitmap which must be a Windows +run, but you can also supply your own 152x261 bitmap which must be a Windows :file:`.bmp` file with the :option:`--bitmap` option. The installer will also display a large title on the desktop background window @@ -375,7 +375,7 @@ check or modify your existing install.) The Postinstallation script --------------------------- -Starting with Python 2.3, a postinstallation script can be specified which the +Starting with Python 2.3, a postinstallation script can be specified with the :option:`--install-script` option. The basename of the script must be specified, and the script filename must also be listed in the scripts argument to the setup function. From f2cf15e856745a97e3dcd06666bf18da92c64d2f Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 7 Jul 2010 18:51:43 +0000 Subject: [PATCH 142/330] Make comment out of an awkward note. --- sourcedist.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index f6809c95a0..2cfdf698dd 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -76,10 +76,10 @@ source distribution: :option:`packages` options * all C source files mentioned in the :option:`ext_modules` or - :option:`libraries` options ( + :option:`libraries` options - **\*\*** getting C library sources currently broken---no - :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) + .. XXX Getting C library sources is currently broken -- no + :meth:`get_source_files` method in :file:`build_clib.py`! * scripts identified by the :option:`scripts` option See :ref:`distutils-installing-scripts`. From b4705574c0bf11c4e14989a098ed3780fa28157f Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 7 Jul 2010 19:04:36 +0000 Subject: [PATCH 143/330] Turn more notes into comments. --- apiref.rst | 5 ++--- builtdist.rst | 4 ++-- setupscript.rst | 4 ++-- 3 files changed, 6 insertions(+), 7 deletions(-) diff --git a/apiref.rst b/apiref.rst index 6bcf3a7c25..9f957401e8 100644 --- a/apiref.rst +++ b/apiref.rst @@ -995,7 +995,7 @@ directories. errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is true). -**\*\*** Some of this could be replaced with the shutil module? **\*\*** +.. XXX Some of this could be replaced with the shutil module? :mod:`distutils.file_util` --- Single file operations @@ -1311,8 +1311,7 @@ provides the following additional features: the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. -**\*\*** Should be replaced with :mod:`optik` (which is also now known as -:mod:`optparse` in Python 2.3 and later). **\*\*** +.. XXX Should be replaced with :mod:`optparse`. .. function:: fancy_getopt(options, negative_opt, object, args) diff --git a/builtdist.rst b/builtdist.rst index 5832552bfa..8ce94d35db 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -146,8 +146,8 @@ commands. Creating dumb built distributions ================================= -**\*\*** Need to document absolute vs. prefix-relative packages here, but first -I have to implement it! **\*\*** +.. XXX Need to document absolute vs. prefix-relative packages here, but first + I have to implement it! .. _creating-rpms: diff --git a/setupscript.rst b/setupscript.rst index 5ec94c7ea5..9208e36995 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -207,7 +207,7 @@ However, you can also include SWIG interface (:file:`.i`) files in the list; the SWIG on the interface file and compile the resulting C/C++ file into your extension. -**\*\*** SWIG support is rough around the edges and largely untested! **\*\*** +.. XXX SWIG support is rough around the edges and largely untested! This warning notwithstanding, options to SWIG can be currently passed like this:: @@ -326,7 +326,7 @@ include the location in ``library_dirs``:: (Again, this sort of non-portable construct should be avoided if you intend to distribute your code.) -**\*\*** Should mention clib libraries here or somewhere else! **\*\*** +.. XXX Should mention clib libraries here or somewhere else! Other options From 7b63bbfe3a635ace5503fc862a40cf51d8a0beff Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 7 Jul 2010 19:05:35 +0000 Subject: [PATCH 144/330] Merged revisions 82629,82632 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82629 | georg.brandl | 2010-07-07 20:51:43 +0200 (Mi, 07 Jul 2010) | 1 line Make comment out of an awkward note. ........ r82632 | georg.brandl | 2010-07-07 21:04:36 +0200 (Mi, 07 Jul 2010) | 1 line Turn more notes into comments. ........ --- apiref.rst | 5 ++--- builtdist.rst | 4 ++-- setupscript.rst | 4 ++-- sourcedist.rst | 6 +++--- 4 files changed, 9 insertions(+), 10 deletions(-) diff --git a/apiref.rst b/apiref.rst index 6541fc21ae..bce22bf1bd 100644 --- a/apiref.rst +++ b/apiref.rst @@ -995,7 +995,7 @@ directories. errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is true). -**\*\*** Some of this could be replaced with the shutil module? **\*\*** +.. XXX Some of this could be replaced with the shutil module? :mod:`distutils.file_util` --- Single file operations @@ -1311,8 +1311,7 @@ provides the following additional features: the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. -**\*\*** Should be replaced with :mod:`optik` (which is also now known as -:mod:`optparse` in Python 2.3 and later). **\*\*** +.. XXX Should be replaced with :mod:`optparse`. .. function:: fancy_getopt(options, negative_opt, object, args) diff --git a/builtdist.rst b/builtdist.rst index 5832552bfa..8ce94d35db 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -146,8 +146,8 @@ commands. Creating dumb built distributions ================================= -**\*\*** Need to document absolute vs. prefix-relative packages here, but first -I have to implement it! **\*\*** +.. XXX Need to document absolute vs. prefix-relative packages here, but first + I have to implement it! .. _creating-rpms: diff --git a/setupscript.rst b/setupscript.rst index faefd21692..e457918026 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -207,7 +207,7 @@ However, you can also include SWIG interface (:file:`.i`) files in the list; the SWIG on the interface file and compile the resulting C/C++ file into your extension. -**\*\*** SWIG support is rough around the edges and largely untested! **\*\*** +.. XXX SWIG support is rough around the edges and largely untested! This warning notwithstanding, options to SWIG can be currently passed like this:: @@ -326,7 +326,7 @@ include the location in ``library_dirs``:: (Again, this sort of non-portable construct should be avoided if you intend to distribute your code.) -**\*\*** Should mention clib libraries here or somewhere else! **\*\*** +.. XXX Should mention clib libraries here or somewhere else! Other options diff --git a/sourcedist.rst b/sourcedist.rst index f6809c95a0..2cfdf698dd 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -76,10 +76,10 @@ source distribution: :option:`packages` options * all C source files mentioned in the :option:`ext_modules` or - :option:`libraries` options ( + :option:`libraries` options - **\*\*** getting C library sources currently broken---no - :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) + .. XXX Getting C library sources is currently broken -- no + :meth:`get_source_files` method in :file:`build_clib.py`! * scripts identified by the :option:`scripts` option See :ref:`distutils-installing-scripts`. From 5e69fd320d2c90942d88becf7063881eef21f017 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 9 Jul 2010 07:51:43 +0000 Subject: [PATCH 145/330] Merged revisions 82548,82634-82635 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/release27-maint ................ r82548 | georg.brandl | 2010-07-04 19:28:33 +0200 (So, 04 Jul 2010) | 1 line #8472: fix misleading reference to ifilterfalse() in filter() docs. ................ r82634 | georg.brandl | 2010-07-07 21:05:35 +0200 (Mi, 07 Jul 2010) | 13 lines Merged revisions 82629,82632 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82629 | georg.brandl | 2010-07-07 20:51:43 +0200 (Mi, 07 Jul 2010) | 1 line Make comment out of an awkward note. ........ r82632 | georg.brandl | 2010-07-07 21:04:36 +0200 (Mi, 07 Jul 2010) | 1 line Turn more notes into comments. ........ ................ r82635 | georg.brandl | 2010-07-07 21:09:12 +0200 (Mi, 07 Jul 2010) | 9 lines Merged revisions 82615 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82615 | georg.brandl | 2010-07-07 00:58:50 +0200 (Mi, 07 Jul 2010) | 1 line Fix typo. ........ ................ --- apiref.rst | 5 ++--- builtdist.rst | 4 ++-- setupscript.rst | 4 ++-- sourcedist.rst | 6 +++--- 4 files changed, 9 insertions(+), 10 deletions(-) diff --git a/apiref.rst b/apiref.rst index 71116e6d87..7874415f52 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1012,7 +1012,7 @@ directories. errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is true). -**\*\*** Some of this could be replaced with the shutil module? **\*\*** +.. XXX Some of this could be replaced with the shutil module? :mod:`distutils.file_util` --- Single file operations @@ -1328,8 +1328,7 @@ provides the following additional features: the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. -**\*\*** Should be replaced with :mod:`optik` (which is also now known as -:mod:`optparse` in Python 2.3 and later). **\*\*** +.. XXX Should be replaced with :mod:`optparse`. .. function:: fancy_getopt(options, negative_opt, object, args) diff --git a/builtdist.rst b/builtdist.rst index ade5dfa561..8615cbb243 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -143,8 +143,8 @@ commands. Creating dumb built distributions ================================= -**\*\*** Need to document absolute vs. prefix-relative packages here, but first -I have to implement it! **\*\*** +.. XXX Need to document absolute vs. prefix-relative packages here, but first + I have to implement it! .. _creating-rpms: diff --git a/setupscript.rst b/setupscript.rst index 06d3e9fd99..b63e2094ca 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -207,7 +207,7 @@ However, you can also include SWIG interface (:file:`.i`) files in the list; the SWIG on the interface file and compile the resulting C/C++ file into your extension. -**\*\*** SWIG support is rough around the edges and largely untested! **\*\*** +.. XXX SWIG support is rough around the edges and largely untested! This warning notwithstanding, options to SWIG can be currently passed like this:: @@ -326,7 +326,7 @@ include the location in ``library_dirs``:: (Again, this sort of non-portable construct should be avoided if you intend to distribute your code.) -**\*\*** Should mention clib libraries here or somewhere else! **\*\*** +.. XXX Should mention clib libraries here or somewhere else! Other options diff --git a/sourcedist.rst b/sourcedist.rst index b45515d8d9..9febd10622 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -68,10 +68,10 @@ source distribution: :option:`packages` options * all C source files mentioned in the :option:`ext_modules` or - :option:`libraries` options ( + :option:`libraries` options - **\*\*** getting C library sources currently broken---no - :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) + .. XXX Getting C library sources is currently broken -- no + :meth:`get_source_files` method in :file:`build_clib.py`! * scripts identified by the :option:`scripts` option From f5f3356560b2ae2aee58beb2851f762461a47bf7 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 11 Jul 2010 10:22:44 +0000 Subject: [PATCH 146/330] #9223: link to Command class reference, and move Command interface docs nearer to class docs. --- apiref.rst | 156 ++++++++++++++++++++++++++------------------------ extending.rst | 4 +- 2 files changed, 82 insertions(+), 78 deletions(-) diff --git a/apiref.rst b/apiref.rst index 9f957401e8..2401da3f6c 100644 --- a/apiref.rst +++ b/apiref.rst @@ -147,11 +147,11 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and In addition, the :mod:`distutils.core` module exposed a number of classes that live elsewhere. -* :class:`Extension` from :mod:`distutils.extension` +* :class:`~distutils.extension.Extension` from :mod:`distutils.extension` -* :class:`Command` from :mod:`distutils.cmd` +* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd` -* :class:`Distribution` from :mod:`distutils.dist` +* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist` A short description of each of these follows, but see the relevant module for the full reference. @@ -1679,8 +1679,8 @@ lines, and joining lines with backslashes. =================================================================== .. module:: distutils.cmd - :synopsis: This module provides the abstract base class Command. This class is subclassed - by the modules in the distutils.command subpackage. + :synopsis: This module provides the abstract base class Command. This class + is subclassed by the modules in the distutils.command subpackage. This module supplies the abstract base class :class:`Command`. @@ -1690,20 +1690,84 @@ This module supplies the abstract base class :class:`Command`. Abstract base class for defining command classes, the "worker bees" of the Distutils. A useful analogy for command classes is to think of them as - subroutines with local variables called *options*. The options are declared in - :meth:`initialize_options` and defined (given their final values) in - :meth:`finalize_options`, both of which must be defined by every command class. - The distinction between the two is necessary because option values might come - from the outside world (command line, config file, ...), and any options - dependent on other options must be computed after these outside influences have - been processed --- hence :meth:`finalize_options`. The body of the subroutine, - where it does all its work based on the values of its options, is the - :meth:`run` method, which must also be implemented by every command class. - - The class constructor takes a single argument *dist*, a :class:`Distribution` + subroutines with local variables called *options*. The options are declared + in :meth:`initialize_options` and defined (given their final values) in + :meth:`finalize_options`, both of which must be defined by every command + class. The distinction between the two is necessary because option values + might come from the outside world (command line, config file, ...), and any + options dependent on other options must be computed after these outside + influences have been processed --- hence :meth:`finalize_options`. The body + of the subroutine, where it does all its work based on the values of its + options, is the :meth:`run` method, which must also be implemented by every + command class. + + The class constructor takes a single argument *dist*, a :class:`Distribution` instance. +Creating a new Distutils command +================================ + +This section outlines the steps to create a new Distutils command. + +A new command lives in a module in the :mod:`distutils.command` package. There +is a sample template in that directory called :file:`command_template`. Copy +this file to a new module with the same name as the new command you're +implementing. This module should implement a class with the same name as the +module (and the command). So, for instance, to create the command +``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy +:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit +it so that it's implementing the class :class:`peel_banana`, a subclass of +:class:`distutils.cmd.Command`. + +Subclasses of :class:`Command` must define the following methods. + +.. method:: Command.initialize_options() + + Set default values for all the options that this command supports. Note that + these defaults may be overridden by other commands, by the setup script, by + config files, or by the command-line. Thus, this is not the place to code + dependencies between options; generally, :meth:`initialize_options` + implementations are just a bunch of ``self.foo = None`` assignments. + + +.. method:: Command.finalize_options() + + Set final values for all the options that this command supports. This is + always called as late as possible, ie. after any option assignments from the + command-line or from other commands have been done. Thus, this is the place + to to code option dependencies: if *foo* depends on *bar*, then it is safe to + set *foo* from *bar* as long as *foo* still has the same value it was + assigned in :meth:`initialize_options`. + + +.. method:: Command.run() + + A command's raison d'etre: carry out the action it exists to perform, controlled + by the options initialized in :meth:`initialize_options`, customized by other + commands, the setup script, the command-line, and config files, and finalized in + :meth:`finalize_options`. All terminal output and filesystem interaction should + be done by :meth:`run`. + + +.. attribute:: Command.sub_commands + + *sub_commands* formalizes the notion of a "family" of commands, + e.g. ``install`` as the parent with sub-commands ``install_lib``, + ``install_headers``, etc. The parent of a family of commands defines + *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, + predicate)``, with *command_name* a string and *predicate* a function, a + string or ``None``. *predicate* is a method of the parent command that + determines whether the corresponding command is applicable in the current + situation. (E.g. we ``install_headers`` is only applicable if we have any C + header files to install.) If *predicate* is ``None``, that command is always + applicable. + + *sub_commands* is usually defined at the *end* of a class, because + predicates can be methods of the class, so they must already have been + defined. The canonical example is the :command:`install` command. + + :mod:`distutils.command` --- Individual Distutils commands ========================================================== @@ -1942,63 +2006,3 @@ The ``register`` command registers the package with the Python Package Index. This is described in more detail in :pep:`301`. .. % todo - - -Creating a new Distutils command -================================ - -This section outlines the steps to create a new Distutils command. - -A new command lives in a module in the :mod:`distutils.command` package. There -is a sample template in that directory called :file:`command_template`. Copy -this file to a new module with the same name as the new command you're -implementing. This module should implement a class with the same name as the -module (and the command). So, for instance, to create the command -``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy -:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit -it so that it's implementing the class :class:`peel_banana`, a subclass of -:class:`distutils.cmd.Command`. - -Subclasses of :class:`Command` must define the following methods. - - -.. method:: Command.initialize_options() - - Set default values for all the options that this command supports. Note that - these defaults may be overridden by other commands, by the setup script, by - config files, or by the command-line. Thus, this is not the place to code - dependencies between options; generally, :meth:`initialize_options` - implementations are just a bunch of ``self.foo = None`` assignments. - - -.. method:: Command.finalize_options() - - Set final values for all the options that this command supports. This is - always called as late as possible, ie. after any option assignments from the - command-line or from other commands have been done. Thus, this is the place - to to code option dependencies: if *foo* depends on *bar*, then it is safe to - set *foo* from *bar* as long as *foo* still has the same value it was - assigned in :meth:`initialize_options`. - - -.. method:: Command.run() - - A command's raison d'etre: carry out the action it exists to perform, controlled - by the options initialized in :meth:`initialize_options`, customized by other - commands, the setup script, the command-line, and config files, and finalized in - :meth:`finalize_options`. All terminal output and filesystem interaction should - be done by :meth:`run`. - -*sub_commands* formalizes the notion of a "family" of commands, eg. ``install`` -as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The -parent of a family of commands defines *sub_commands* as a class attribute; it's -a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string -and *predicate* a function, a string or None. *predicate* is a method of -the parent command that determines whether the corresponding command is -applicable in the current situation. (Eg. we ``install_headers`` is only -applicable if we have any C header files to install.) If *predicate* is None, -that command is always applicable. - -*sub_commands* is usually defined at the \*end\* of a class, because predicates -can be methods of the class, so they must already have been defined. The -canonical example is the :command:`install` command. diff --git a/extending.rst b/extending.rst index 972ff02c03..5a70d031cc 100644 --- a/extending.rst +++ b/extending.rst @@ -15,8 +15,8 @@ want to modify existing commands; many simply add a few file extensions that should be copied into packages in addition to :file:`.py` files as a convenience. -Most distutils command implementations are subclasses of the :class:`Command` -class from :mod:`distutils.cmd`. New commands may directly inherit from +Most distutils command implementations are subclasses of the +:class:`distutils.cmd.Command` class. New commands may directly inherit from :class:`Command`, while replacements often derive from :class:`Command` indirectly, directly subclassing the command they are replacing. Commands are required to derive from :class:`Command`. From 94425f1e61d91cae32f6a41e09851eb5996cd33d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 11 Jul 2010 10:29:37 +0000 Subject: [PATCH 147/330] Merged revisions 82806 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82806 | georg.brandl | 2010-07-11 12:22:44 +0200 (So, 11 Jul 2010) | 1 line #9223: link to Command class reference, and move Command interface docs nearer to class docs. ........ --- extending.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/extending.rst b/extending.rst index 972ff02c03..5a70d031cc 100644 --- a/extending.rst +++ b/extending.rst @@ -15,8 +15,8 @@ want to modify existing commands; many simply add a few file extensions that should be copied into packages in addition to :file:`.py` files as a convenience. -Most distutils command implementations are subclasses of the :class:`Command` -class from :mod:`distutils.cmd`. New commands may directly inherit from +Most distutils command implementations are subclasses of the +:class:`distutils.cmd.Command` class. New commands may directly inherit from :class:`Command`, while replacements often derive from :class:`Command` indirectly, directly subclassing the command they are replacing. Commands are required to derive from :class:`Command`. From 263d5b42ba34fd27851a8d176dc3019e42ba6b8f Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 11 Jul 2010 10:41:07 +0000 Subject: [PATCH 148/330] Merged revisions 82301 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ................ r82301 | benjamin.peterson | 2010-06-28 00:32:30 +0200 (Mo, 28 Jun 2010) | 303 lines Merged revisions 80605-80609,80642-80646,80651-80652,80674,80684-80686,80748,80852,80854,80870,80872-80873,80907,80915-80916,80951-80952,80976-80977,80985,81038-81040,81042,81053,81070,81104-81105,81114,81125,81245,81285,81402,81463,81516,81562-81563,81567,81593,81635,81680-81681,81684,81801,81888,81931-81933,81939-81942,81963,81984,81991,82120,82188,82264-82267 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r80605 | andrew.kuchling | 2010-04-28 19:22:16 -0500 (Wed, 28 Apr 2010) | 1 line Add various items ........ r80606 | andrew.kuchling | 2010-04-28 20:44:30 -0500 (Wed, 28 Apr 2010) | 6 lines Fix doubled 'the'. Markup fixes to use :exc:, :option: in a few places. (Glitch: unittest.main's -c ends up a link to the Python interpreter's -c option. Should we skip using :option: for that switch, or disable the auto-linking somehow?) ........ r80607 | andrew.kuchling | 2010-04-28 20:45:41 -0500 (Wed, 28 Apr 2010) | 1 line Add various unittest items ........ r80608 | benjamin.peterson | 2010-04-28 22:18:05 -0500 (Wed, 28 Apr 2010) | 1 line update pypy description ........ r80609 | benjamin.peterson | 2010-04-28 22:30:59 -0500 (Wed, 28 Apr 2010) | 1 line update pypy url ........ r80642 | andrew.kuchling | 2010-04-29 19:49:09 -0500 (Thu, 29 Apr 2010) | 1 line Always add space after RFC; reword paragraph ........ r80643 | andrew.kuchling | 2010-04-29 19:52:31 -0500 (Thu, 29 Apr 2010) | 6 lines Reword paragraph to make its meaning clearer. Antoine Pitrou: is my version of the paragraph still correct? R. David Murray: is this more understandable than the previous version? ........ r80644 | andrew.kuchling | 2010-04-29 20:02:15 -0500 (Thu, 29 Apr 2010) | 1 line Fix typos ........ r80645 | andrew.kuchling | 2010-04-29 20:32:47 -0500 (Thu, 29 Apr 2010) | 1 line Markup fix; clarify by adding 'in that order' ........ r80646 | andrew.kuchling | 2010-04-29 20:33:40 -0500 (Thu, 29 Apr 2010) | 1 line Add various items; rearrange unittest section a bit ........ r80651 | andrew.kuchling | 2010-04-30 08:46:55 -0500 (Fri, 30 Apr 2010) | 1 line Minor grammar re-wording ........ r80652 | andrew.kuchling | 2010-04-30 08:47:34 -0500 (Fri, 30 Apr 2010) | 1 line Add item ........ r80674 | andrew.kuchling | 2010-04-30 20:19:16 -0500 (Fri, 30 Apr 2010) | 1 line Add various items ........ r80684 | andrew.kuchling | 2010-05-01 07:05:52 -0500 (Sat, 01 May 2010) | 1 line Minor grammar fix ........ r80685 | andrew.kuchling | 2010-05-01 07:06:51 -0500 (Sat, 01 May 2010) | 1 line Describe memoryview ........ r80686 | antoine.pitrou | 2010-05-01 07:16:39 -0500 (Sat, 01 May 2010) | 4 lines Fix attribution. Travis didn't do much and he did a bad work. (yes, this is a sensitive subject, sorry) ........ r80748 | andrew.kuchling | 2010-05-03 20:24:22 -0500 (Mon, 03 May 2010) | 1 line Add some more items; the urlparse change is added twice ........ r80852 | andrew.kuchling | 2010-05-05 20:09:47 -0500 (Wed, 05 May 2010) | 1 line Reword paragraph; fix filename, which should be pyconfig.h ........ r80854 | andrew.kuchling | 2010-05-05 20:10:56 -0500 (Wed, 05 May 2010) | 1 line Add various items ........ r80870 | andrew.kuchling | 2010-05-06 09:14:09 -0500 (Thu, 06 May 2010) | 1 line Describe ElementTree 1.3; rearrange new-module sections; describe dict views as sets; small edits and items ........ r80872 | andrew.kuchling | 2010-05-06 12:21:59 -0500 (Thu, 06 May 2010) | 1 line Add 2 items; record ideas for two initial sections; clarify wording ........ r80873 | andrew.kuchling | 2010-05-06 12:27:57 -0500 (Thu, 06 May 2010) | 1 line Change section title; point to unittest2 ........ r80907 | andrew.kuchling | 2010-05-06 20:45:14 -0500 (Thu, 06 May 2010) | 1 line Add a new section on the development plan; add an item ........ r80915 | antoine.pitrou | 2010-05-07 05:15:51 -0500 (Fri, 07 May 2010) | 3 lines Fix some markup and a class name. Also, wrap a long line. ........ r80916 | andrew.kuchling | 2010-05-07 06:30:47 -0500 (Fri, 07 May 2010) | 1 line Re-word text ........ r80951 | andrew.kuchling | 2010-05-07 20:15:26 -0500 (Fri, 07 May 2010) | 1 line Add two items ........ r80952 | andrew.kuchling | 2010-05-07 20:35:55 -0500 (Fri, 07 May 2010) | 1 line Get accents correct ........ r80976 | andrew.kuchling | 2010-05-08 08:28:03 -0500 (Sat, 08 May 2010) | 1 line Add logging.dictConfig example; give up on writing a Ttk example ........ r80977 | andrew.kuchling | 2010-05-08 08:29:46 -0500 (Sat, 08 May 2010) | 1 line Markup fixes ........ r80985 | andrew.kuchling | 2010-05-08 10:39:46 -0500 (Sat, 08 May 2010) | 7 lines Write summary of the 2.7 release; rewrite the future section some more; mention PYTHONWARNINGS env. var; tweak some examples for readability. And with this commit, the "What's New" is done... except for a complete read-through to polish the text, and fixing any reported errors, but those tasks can easily wait until after beta2. ........ r81038 | benjamin.peterson | 2010-05-09 16:09:40 -0500 (Sun, 09 May 2010) | 1 line finish clause ........ r81039 | andrew.kuchling | 2010-05-10 09:18:27 -0500 (Mon, 10 May 2010) | 1 line Markup fix; re-word a sentence ........ r81040 | andrew.kuchling | 2010-05-10 09:20:12 -0500 (Mon, 10 May 2010) | 1 line Use title case ........ r81042 | andrew.kuchling | 2010-05-10 10:03:35 -0500 (Mon, 10 May 2010) | 1 line Link to unittest2 article ........ r81053 | florent.xicluna | 2010-05-10 14:59:22 -0500 (Mon, 10 May 2010) | 2 lines Add a link on maketrans(). ........ r81070 | andrew.kuchling | 2010-05-10 18:13:41 -0500 (Mon, 10 May 2010) | 1 line Fix typo ........ r81104 | andrew.kuchling | 2010-05-11 19:38:44 -0500 (Tue, 11 May 2010) | 1 line Revision pass: lots of edits, typo fixes, rearrangements ........ r81105 | andrew.kuchling | 2010-05-11 19:40:47 -0500 (Tue, 11 May 2010) | 1 line Let's call this done ........ r81114 | andrew.kuchling | 2010-05-12 08:56:07 -0500 (Wed, 12 May 2010) | 1 line Grammar fix ........ r81125 | andrew.kuchling | 2010-05-12 13:56:48 -0500 (Wed, 12 May 2010) | 1 line #8696: add documentation for logging.config.dictConfig (PEP 391) ........ r81245 | andrew.kuchling | 2010-05-16 18:31:16 -0500 (Sun, 16 May 2010) | 1 line Add cross-reference to later section ........ r81285 | vinay.sajip | 2010-05-18 03:16:27 -0500 (Tue, 18 May 2010) | 1 line Fixed minor typo in ReST markup. ........ r81402 | vinay.sajip | 2010-05-21 12:41:34 -0500 (Fri, 21 May 2010) | 1 line Updated logging documentation with more dictConfig information. ........ r81463 | georg.brandl | 2010-05-22 03:17:23 -0500 (Sat, 22 May 2010) | 1 line #8785: less confusing description of regex.find*. ........ r81516 | andrew.kuchling | 2010-05-25 08:34:08 -0500 (Tue, 25 May 2010) | 1 line Add three items ........ r81562 | andrew.kuchling | 2010-05-27 08:22:53 -0500 (Thu, 27 May 2010) | 1 line Rewrite wxWidgets section ........ r81563 | andrew.kuchling | 2010-05-27 08:30:09 -0500 (Thu, 27 May 2010) | 1 line Remove top-level 'General Questions' section, pushing up the questions it contains ........ r81567 | andrew.kuchling | 2010-05-27 16:29:59 -0500 (Thu, 27 May 2010) | 1 line Add item ........ r81593 | georg.brandl | 2010-05-29 03:46:18 -0500 (Sat, 29 May 2010) | 1 line #8616: add new turtle demo "nim". ........ r81635 | georg.brandl | 2010-06-01 02:25:23 -0500 (Tue, 01 Jun 2010) | 1 line Put docs for RegexObject.search() before RegexObject.match() to mirror re.search() and re.match() order. ........ r81680 | vinay.sajip | 2010-06-03 17:34:42 -0500 (Thu, 03 Jun 2010) | 1 line Issue #8890: Documentation changed to avoid reference to temporary files. ........ r81681 | sean.reifschneider | 2010-06-03 20:51:26 -0500 (Thu, 03 Jun 2010) | 2 lines Issue8810: Clearing up docstring for tzinfo.utcoffset. ........ r81684 | vinay.sajip | 2010-06-04 08:41:02 -0500 (Fri, 04 Jun 2010) | 1 line Issue #8890: Documentation changed to avoid reference to temporary files - other cases covered. ........ r81801 | andrew.kuchling | 2010-06-07 08:38:40 -0500 (Mon, 07 Jun 2010) | 1 line #8875: Remove duplicated paragraph ........ r81888 | andrew.kuchling | 2010-06-10 20:54:58 -0500 (Thu, 10 Jun 2010) | 1 line Add a few more items ........ r81931 | georg.brandl | 2010-06-12 01:26:54 -0500 (Sat, 12 Jun 2010) | 1 line Fix punctuation. ........ r81932 | georg.brandl | 2010-06-12 01:28:58 -0500 (Sat, 12 Jun 2010) | 1 line Document that an existing directory raises in mkdir(). ........ r81933 | georg.brandl | 2010-06-12 01:45:33 -0500 (Sat, 12 Jun 2010) | 1 line Update version in README. ........ r81939 | georg.brandl | 2010-06-12 04:45:01 -0500 (Sat, 12 Jun 2010) | 1 line Use newer toctree syntax. ........ r81940 | georg.brandl | 2010-06-12 04:45:28 -0500 (Sat, 12 Jun 2010) | 1 line Add document on how to build. ........ r81941 | georg.brandl | 2010-06-12 04:45:58 -0500 (Sat, 12 Jun 2010) | 1 line Fix gratuitous indentation. ........ r81942 | georg.brandl | 2010-06-12 04:46:03 -0500 (Sat, 12 Jun 2010) | 1 line Update README. ........ r81963 | andrew.kuchling | 2010-06-12 15:00:55 -0500 (Sat, 12 Jun 2010) | 1 line Grammar fix ........ r81984 | georg.brandl | 2010-06-14 10:58:39 -0500 (Mon, 14 Jun 2010) | 1 line #8993: fix reference. ........ r81991 | andrew.kuchling | 2010-06-14 19:38:58 -0500 (Mon, 14 Jun 2010) | 1 line Add another bunch of items ........ r82120 | andrew.kuchling | 2010-06-20 16:45:45 -0500 (Sun, 20 Jun 2010) | 1 line Note that Python 3.x isn't covered; add forward ref. for UTF-8; note error in 2.5 and up ........ r82188 | benjamin.peterson | 2010-06-23 19:02:46 -0500 (Wed, 23 Jun 2010) | 1 line remove reverted changed ........ r82264 | georg.brandl | 2010-06-27 05:47:47 -0500 (Sun, 27 Jun 2010) | 1 line Confusing punctuation. ........ r82265 | georg.brandl | 2010-06-27 05:49:23 -0500 (Sun, 27 Jun 2010) | 1 line Use designated syntax for optional grammar element. ........ r82266 | georg.brandl | 2010-06-27 05:51:44 -0500 (Sun, 27 Jun 2010) | 1 line Fix URL. ........ r82267 | georg.brandl | 2010-06-27 05:55:38 -0500 (Sun, 27 Jun 2010) | 1 line Two typos. ........ ................ --- builtdist.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 74cc80af41..ee06fb41d2 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -321,7 +321,7 @@ the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` option. By default the installer will display the cool "Python Powered" logo when it is -run, but you can also supply your own 152x161 bitmap which must be a Windows +run, but you can also supply your own 152x261 bitmap which must be a Windows :file:`.bmp` file with the :option:`--bitmap` option. The installer will also display a large title on the desktop background window @@ -374,7 +374,7 @@ check or modify your existing install.) The Postinstallation script --------------------------- -Starting with Python 2.3, a postinstallation script can be specified which the +Starting with Python 2.3, a postinstallation script can be specified with the :option:`--install-script` option. The basename of the script must be specified, and the script filename must also be listed in the scripts argument to the setup function. From 1a567ee302b058dc0160367d4c99f4b0a08d3257 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 14 Jul 2010 08:53:18 +0000 Subject: [PATCH 149/330] Remove XXX from text. --- apiref.rst | 14 ++++++++------ 1 file changed, 8 insertions(+), 6 deletions(-) diff --git a/apiref.rst b/apiref.rst index 2401da3f6c..d65c59fd25 100644 --- a/apiref.rst +++ b/apiref.rst @@ -21,7 +21,9 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and .. function:: setup(arguments) The basic do-everything function that does most everything you could ever ask - for from a Distutils method. See XXXXX + for from a Distutils method. + + .. See XXXXX The setup function takes a large number of arguments. These are laid out in the following table. @@ -1743,11 +1745,11 @@ Subclasses of :class:`Command` must define the following methods. .. method:: Command.run() - A command's raison d'etre: carry out the action it exists to perform, controlled - by the options initialized in :meth:`initialize_options`, customized by other - commands, the setup script, the command-line, and config files, and finalized in - :meth:`finalize_options`. All terminal output and filesystem interaction should - be done by :meth:`run`. + A command's raison d'etre: carry out the action it exists to perform, + controlled by the options initialized in :meth:`initialize_options`, + customized by other commands, the setup script, the command-line, and config + files, and finalized in :meth:`finalize_options`. All terminal output and + filesystem interaction should be done by :meth:`run`. .. attribute:: Command.sub_commands From f8e9820cda8762565ce6963a73a0fbf898b589ad Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 14 Jul 2010 08:55:55 +0000 Subject: [PATCH 150/330] Merged revisions 82872,82874 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82872 | georg.brandl | 2010-07-14 10:53:18 +0200 (Mi, 14 Jul 2010) | 1 line Remove XXX from text. ........ r82874 | georg.brandl | 2010-07-14 10:54:40 +0200 (Mi, 14 Jul 2010) | 1 line #9235: fix missing import of sys. ........ --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index bce22bf1bd..ae34565b8b 100644 --- a/apiref.rst +++ b/apiref.rst @@ -21,7 +21,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and .. function:: setup(arguments) The basic do-everything function that does most everything you could ever ask - for from a Distutils method. See XXXXX + for from a Distutils method. The setup function takes a large number of arguments. These are laid out in the following table. From 23ed68c47c69e7ed6110169170b1590fcff36efc Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Tarek=20Ziad=C3=A9?= Date: Sat, 31 Jul 2010 09:10:51 +0000 Subject: [PATCH 151/330] reverted distutils doc to its 3.1 state --- apiref.rst | 178 +++++++++++++++++++++++++----------------------- builtdist.rst | 7 +- commandref.rst | 44 ++++++++++++ examples.rst | 52 ++++++++++++++ extending.rst | 4 +- setupscript.rst | 4 +- sourcedist.rst | 150 ++++++++++++---------------------------- uploading.rst | 8 +-- 8 files changed, 244 insertions(+), 203 deletions(-) diff --git a/apiref.rst b/apiref.rst index d65c59fd25..69ec0de99b 100644 --- a/apiref.rst +++ b/apiref.rst @@ -21,9 +21,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and .. function:: setup(arguments) The basic do-everything function that does most everything you could ever ask - for from a Distutils method. - - .. See XXXXX + for from a Distutils method. See XXXXX The setup function takes a large number of arguments. These are laid out in the following table. @@ -149,11 +147,11 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and In addition, the :mod:`distutils.core` module exposed a number of classes that live elsewhere. -* :class:`~distutils.extension.Extension` from :mod:`distutils.extension` +* :class:`Extension` from :mod:`distutils.extension` -* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd` +* :class:`Command` from :mod:`distutils.cmd` -* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist` +* :class:`Distribution` from :mod:`distutils.dist` A short description of each of these follows, but see the relevant module for the full reference. @@ -997,7 +995,7 @@ directories. errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is true). -.. XXX Some of this could be replaced with the shutil module? +**\*\*** Some of this could be replaced with the shutil module? **\*\*** :mod:`distutils.file_util` --- Single file operations @@ -1313,7 +1311,8 @@ provides the following additional features: the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. -.. XXX Should be replaced with :mod:`optparse`. +**\*\*** Should be replaced with :mod:`optik` (which is also now known as +:mod:`optparse` in Python 2.3 and later). **\*\*** .. function:: fancy_getopt(options, negative_opt, object, args) @@ -1681,8 +1680,8 @@ lines, and joining lines with backslashes. =================================================================== .. module:: distutils.cmd - :synopsis: This module provides the abstract base class Command. This class - is subclassed by the modules in the distutils.command subpackage. + :synopsis: This module provides the abstract base class Command. This class is subclassed + by the modules in the distutils.command subpackage. This module supplies the abstract base class :class:`Command`. @@ -1692,84 +1691,20 @@ This module supplies the abstract base class :class:`Command`. Abstract base class for defining command classes, the "worker bees" of the Distutils. A useful analogy for command classes is to think of them as - subroutines with local variables called *options*. The options are declared - in :meth:`initialize_options` and defined (given their final values) in - :meth:`finalize_options`, both of which must be defined by every command - class. The distinction between the two is necessary because option values - might come from the outside world (command line, config file, ...), and any - options dependent on other options must be computed after these outside - influences have been processed --- hence :meth:`finalize_options`. The body - of the subroutine, where it does all its work based on the values of its - options, is the :meth:`run` method, which must also be implemented by every - command class. - - The class constructor takes a single argument *dist*, a :class:`Distribution` + subroutines with local variables called *options*. The options are declared in + :meth:`initialize_options` and defined (given their final values) in + :meth:`finalize_options`, both of which must be defined by every command class. + The distinction between the two is necessary because option values might come + from the outside world (command line, config file, ...), and any options + dependent on other options must be computed after these outside influences have + been processed --- hence :meth:`finalize_options`. The body of the subroutine, + where it does all its work based on the values of its options, is the + :meth:`run` method, which must also be implemented by every command class. + + The class constructor takes a single argument *dist*, a :class:`Distribution` instance. -Creating a new Distutils command -================================ - -This section outlines the steps to create a new Distutils command. - -A new command lives in a module in the :mod:`distutils.command` package. There -is a sample template in that directory called :file:`command_template`. Copy -this file to a new module with the same name as the new command you're -implementing. This module should implement a class with the same name as the -module (and the command). So, for instance, to create the command -``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy -:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit -it so that it's implementing the class :class:`peel_banana`, a subclass of -:class:`distutils.cmd.Command`. - -Subclasses of :class:`Command` must define the following methods. - -.. method:: Command.initialize_options() - - Set default values for all the options that this command supports. Note that - these defaults may be overridden by other commands, by the setup script, by - config files, or by the command-line. Thus, this is not the place to code - dependencies between options; generally, :meth:`initialize_options` - implementations are just a bunch of ``self.foo = None`` assignments. - - -.. method:: Command.finalize_options() - - Set final values for all the options that this command supports. This is - always called as late as possible, ie. after any option assignments from the - command-line or from other commands have been done. Thus, this is the place - to to code option dependencies: if *foo* depends on *bar*, then it is safe to - set *foo* from *bar* as long as *foo* still has the same value it was - assigned in :meth:`initialize_options`. - - -.. method:: Command.run() - - A command's raison d'etre: carry out the action it exists to perform, - controlled by the options initialized in :meth:`initialize_options`, - customized by other commands, the setup script, the command-line, and config - files, and finalized in :meth:`finalize_options`. All terminal output and - filesystem interaction should be done by :meth:`run`. - - -.. attribute:: Command.sub_commands - - *sub_commands* formalizes the notion of a "family" of commands, - e.g. ``install`` as the parent with sub-commands ``install_lib``, - ``install_headers``, etc. The parent of a family of commands defines - *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, - predicate)``, with *command_name* a string and *predicate* a function, a - string or ``None``. *predicate* is a method of the parent command that - determines whether the corresponding command is applicable in the current - situation. (E.g. we ``install_headers`` is only applicable if we have any C - header files to install.) If *predicate* is ``None``, that command is always - applicable. - - *sub_commands* is usually defined at the *end* of a class, because - predicates can be methods of the class, so they must already have been - defined. The canonical example is the :command:`install` command. - - :mod:`distutils.command` --- Individual Distutils commands ========================================================== @@ -2008,3 +1943,76 @@ The ``register`` command registers the package with the Python Package Index. This is described in more detail in :pep:`301`. .. % todo + +:mod:`distutils.command.check` --- Check the meta-data of a package +=================================================================== + +.. module:: distutils.command.check + :synopsis: Check the metadata of a package + + +The ``check`` command performs some tests on the meta-data of a package. +For example, it verifies that all required meta-data are provided as +the arguments passed to the :func:`setup` function. + +.. % todo + + +Creating a new Distutils command +================================ + +This section outlines the steps to create a new Distutils command. + +A new command lives in a module in the :mod:`distutils.command` package. There +is a sample template in that directory called :file:`command_template`. Copy +this file to a new module with the same name as the new command you're +implementing. This module should implement a class with the same name as the +module (and the command). So, for instance, to create the command +``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy +:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit +it so that it's implementing the class :class:`peel_banana`, a subclass of +:class:`distutils.cmd.Command`. + +Subclasses of :class:`Command` must define the following methods. + + +.. method:: Command.initialize_options() + + Set default values for all the options that this command supports. Note that + these defaults may be overridden by other commands, by the setup script, by + config files, or by the command-line. Thus, this is not the place to code + dependencies between options; generally, :meth:`initialize_options` + implementations are just a bunch of ``self.foo = None`` assignments. + + +.. method:: Command.finalize_options() + + Set final values for all the options that this command supports. This is + always called as late as possible, ie. after any option assignments from the + command-line or from other commands have been done. Thus, this is the place + to to code option dependencies: if *foo* depends on *bar*, then it is safe to + set *foo* from *bar* as long as *foo* still has the same value it was + assigned in :meth:`initialize_options`. + + +.. method:: Command.run() + + A command's raison d'etre: carry out the action it exists to perform, controlled + by the options initialized in :meth:`initialize_options`, customized by other + commands, the setup script, the command-line, and config files, and finalized in + :meth:`finalize_options`. All terminal output and filesystem interaction should + be done by :meth:`run`. + +*sub_commands* formalizes the notion of a "family" of commands, eg. ``install`` +as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The +parent of a family of commands defines *sub_commands* as a class attribute; it's +a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string +and *predicate* a function, a string or None. *predicate* is a method of +the parent command that determines whether the corresponding command is +applicable in the current situation. (Eg. we ``install_headers`` is only +applicable if we have any C header files to install.) If *predicate* is None, +that command is always applicable. + +*sub_commands* is usually defined at the \*end\* of a class, because predicates +can be methods of the class, so they must already have been defined. The +canonical example is the :command:`install` command. diff --git a/builtdist.rst b/builtdist.rst index 8ce94d35db..ee06fb41d2 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -146,8 +146,8 @@ commands. Creating dumb built distributions ================================= -.. XXX Need to document absolute vs. prefix-relative packages here, but first - I have to implement it! +**\*\*** Need to document absolute vs. prefix-relative packages here, but first +I have to implement it! **\*\*** .. _creating-rpms: @@ -241,8 +241,7 @@ tedious and error-prone, so it's usually best to put them in the setup configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If you distribute or package many Python module distributions, you might want to put options that apply to all of them in your personal Distutils configuration -file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable -this file, you can pass the --no-user-cfg option to setup.py. +file (:file:`~/.pydistutils.cfg`). There are three steps to building a binary RPM package, all of which are handled automatically by the Distutils: diff --git a/commandref.rst b/commandref.rst index 7282961bd4..fbe40de6c2 100644 --- a/commandref.rst +++ b/commandref.rst @@ -48,6 +48,50 @@ This command installs all (Python) scripts in the distribution. .. % \label{clean-cmd} +.. _sdist-cmd: + +Creating a source distribution: the :command:`sdist` command +============================================================ + +**\*\*** fragment moved down from above: needs context! **\*\*** + +The manifest template commands are: + ++-------------------------------------------+-----------------------------------------------+ +| Command | Description | ++===========================================+===============================================+ +| :command:`include pat1 pat2 ...` | include all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | +| | patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | +| ...` | the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | +| | matching --- & any of the listed patterns | ++-------------------------------------------+-----------------------------------------------+ +| :command:`prune dir` | exclude all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ +| :command:`graft dir` | include all files under *dir* | ++-------------------------------------------+-----------------------------------------------+ + +The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of +regular filename characters, ``?`` matches any single regular filename +character, and ``[range]`` matches any of the characters in *range* (e.g., +``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename +character" is platform-specific: on Unix it is anything except slash; on Windows +anything except backslash or colon. + +**\*\*** Windows support not there yet **\*\*** + .. % \section{Creating a built distribution: the .. % \protect\command{bdist} command family} .. % \label{bdist-cmds} diff --git a/examples.rst b/examples.rst index b495928657..648063b217 100644 --- a/examples.rst +++ b/examples.rst @@ -233,6 +233,58 @@ With exactly the same source tree layout, this extension can be put in the ext_modules=[Extension('foopkg.foo', ['foo.c'])], ) +Checking a package +================== + +The ``check`` command allows you to verify if your package meta-data +meet the minimum requirements to build a distribution. + +To run it, just call it using your :file:`setup.py` script. If something is +missing, ``check`` will display a warning. + +Let's take an example with a simple script:: + + from distutils.core import setup + + setup(name='foobar') + +Running the ``check`` command will display some warnings:: + + $ python setup.py check + running check + warning: check: missing required meta-data: version, url + warning: check: missing meta-data: either (author and author_email) or + (maintainer and maintainer_email) must be supplied + + +If you use the reStructuredText syntax in the `long_description` field and +`docutils `_ is installed you can check if +the syntax is fine with the ``check`` command, using the `restructuredtext` +option. + +For example, if the :file:`setup.py` script is changed like this:: + + from distutils.core import setup + + desc = """\ + My description + ============= + + This is the description of the ``foobar`` package. + """ + + setup(name='foobar', version='1', author='tarek', + author_email='tarek@ziade.org', + url='http://example.com', long_description=desc) + +Where the long description is broken, ``check`` will be able to detect it +by using the `docutils` parser:: + + $ pythontrunk setup.py check --restructuredtext + running check + warning: check: Title underline too short. (line 2) + warning: check: Could not finish the parsing. + .. % \section{Multiple extension modules} .. % \label{multiple-ext} diff --git a/extending.rst b/extending.rst index 5a70d031cc..972ff02c03 100644 --- a/extending.rst +++ b/extending.rst @@ -15,8 +15,8 @@ want to modify existing commands; many simply add a few file extensions that should be copied into packages in addition to :file:`.py` files as a convenience. -Most distutils command implementations are subclasses of the -:class:`distutils.cmd.Command` class. New commands may directly inherit from +Most distutils command implementations are subclasses of the :class:`Command` +class from :mod:`distutils.cmd`. New commands may directly inherit from :class:`Command`, while replacements often derive from :class:`Command` indirectly, directly subclassing the command they are replacing. Commands are required to derive from :class:`Command`. diff --git a/setupscript.rst b/setupscript.rst index 9208e36995..5ec94c7ea5 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -207,7 +207,7 @@ However, you can also include SWIG interface (:file:`.i`) files in the list; the SWIG on the interface file and compile the resulting C/C++ file into your extension. -.. XXX SWIG support is rough around the edges and largely untested! +**\*\*** SWIG support is rough around the edges and largely untested! **\*\*** This warning notwithstanding, options to SWIG can be currently passed like this:: @@ -326,7 +326,7 @@ include the location in ``library_dirs``:: (Again, this sort of non-portable construct should be avoided if you intend to distribute your code.) -.. XXX Should mention clib libraries here or somewhere else! +**\*\*** Should mention clib libraries here or somewhere else! **\*\*** Other options diff --git a/sourcedist.rst b/sourcedist.rst index 2cfdf698dd..96e891bd68 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -26,16 +26,16 @@ to create a gzipped tarball and a zip file. The available formats are: +===========+=========================+=========+ | ``zip`` | zip file (:file:`.zip`) | (1),(3) | +-----------+-------------------------+---------+ -| ``gztar`` | gzip'ed tar file | \(2) | +| ``gztar`` | gzip'ed tar file | (2),(4) | | | (:file:`.tar.gz`) | | +-----------+-------------------------+---------+ -| ``bztar`` | bzip2'ed tar file | | +| ``bztar`` | bzip2'ed tar file | \(4) | | | (:file:`.tar.bz2`) | | +-----------+-------------------------+---------+ | ``ztar`` | compressed tar file | \(4) | | | (:file:`.tar.Z`) | | +-----------+-------------------------+---------+ -| ``tar`` | tar file (:file:`.tar`) | | +| ``tar`` | tar file (:file:`.tar`) | \(4) | +-----------+-------------------------+---------+ Notes: @@ -51,16 +51,8 @@ Notes: of the standard Python library since Python 1.6) (4) - requires the :program:`compress` program. Notice that this format is now - pending for deprecation and will be removed in the future versions of Python. - -When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or -``tar``) under Unix, you can specify the ``owner`` and ``group`` names -that will be set for each member of the archive. - -For example, if you want all files of the archive to be owned by root:: - - python setup.py sdist --owner=root --group=root + requires external utilities: :program:`tar` and possibly one of :program:`gzip`, + :program:`bzip2`, or :program:`compress` .. _manifest: @@ -76,10 +68,10 @@ source distribution: :option:`packages` options * all C source files mentioned in the :option:`ext_modules` or - :option:`libraries` options + :option:`libraries` options ( - .. XXX Getting C library sources is currently broken -- no - :meth:`get_source_files` method in :file:`build_clib.py`! + **\*\*** getting C library sources currently broken---no + :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) * scripts identified by the :option:`scripts` option See :ref:`distutils-installing-scripts`. @@ -111,60 +103,9 @@ per line, regular files (or symlinks to them) only. If you do supply your own :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. -See :ref:`manifest_template` section for a syntax reference. - -.. _manifest-options: - -Manifest-related options -======================== - -The normal course of operations for the :command:`sdist` command is as follows: - -* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` - and create the manifest - -* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest - with just the default file set - -* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more - recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading - :file:`MANIFEST.in` - -* use the list of files now in :file:`MANIFEST` (either just generated or read - in) to create the source distribution archive(s) - -There are a couple of options that modify this behaviour. First, use the -:option:`--no-defaults` and :option:`--no-prune` to disable the standard -"include" and "exclude" sets. - -Second, you might just want to (re)generate the manifest, but not create a -source distribution:: - - python setup.py sdist --manifest-only - -:option:`-o` is a sortcut for :option:`--manifest-only`. - -.. _manifest_template: - -The MANIFEST.in template -======================== - -A :file:`MANIFEST.in` file can be added in a project to define the list of -files to include in the distribution built by the :command:`sdist` command. - -When :command:`sdist` is run, it will look for the :file:`MANIFEST.in` file -and interpret it to generate the :file:`MANIFEST` file that contains the -list of files that will be included in the package. - -This mechanism can be used when the default list of files is not enough. -(See :ref:`manifest`). - -Principle ---------- - The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an -example, let's look at the Distutils' own manifest template:: +example, again we turn to the Distutils' own manifest template:: include *.txt recursive-include examples *.txt *.py @@ -176,7 +117,9 @@ matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching :file:`examples/sample?/build`. All of this is done *after* the standard include set, so you can exclude files from the standard set with explicit instructions in the manifest template. (Or, you can use the -:option:`--no-defaults` option to disable the standard set entirely.) +:option:`--no-defaults` option to disable the standard set entirely.) There are +several other commands available in the manifest template mini-language; see +section :ref:`sdist-cmd`. The order of commands in the manifest template matters: initially, we have the list of default files as described above, and each command in the template adds @@ -230,41 +173,36 @@ should always be slash-separated; the Distutils will take care of converting them to the standard representation on your platform. That way, the manifest template is portable across operating systems. -Commands --------- - -The manifest template commands are: - -+-------------------------------------------+-----------------------------------------------+ -| Command | Description | -+===========================================+===============================================+ -| :command:`include pat1 pat2 ...` | include all files matching any of the listed | -| | patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`exclude pat1 pat2 ...` | exclude all files matching any of the listed | -| | patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of | -| ...` | the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of | -| ...` | the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`global-include pat1 pat2 ...` | include all files anywhere in the source tree | -| | matching --- & any of the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`global-exclude pat1 pat2 ...` | exclude all files anywhere in the source tree | -| | matching --- & any of the listed patterns | -+-------------------------------------------+-----------------------------------------------+ -| :command:`prune dir` | exclude all files under *dir* | -+-------------------------------------------+-----------------------------------------------+ -| :command:`graft dir` | include all files under *dir* | -+-------------------------------------------+-----------------------------------------------+ - -The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of -regular filename characters, ``?`` matches any single regular filename -character, and ``[range]`` matches any of the characters in *range* (e.g., -``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename -character" is platform-specific: on Unix it is anything except slash; on Windows -anything except backslash or colon. + +.. _manifest-options: + +Manifest-related options +======================== + +The normal course of operations for the :command:`sdist` command is as follows: + +* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` + and create the manifest + +* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest + with just the default file set + +* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more + recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading + :file:`MANIFEST.in` + +* use the list of files now in :file:`MANIFEST` (either just generated or read + in) to create the source distribution archive(s) + +There are a couple of options that modify this behaviour. First, use the +:option:`--no-defaults` and :option:`--no-prune` to disable the standard +"include" and "exclude" sets. + +Second, you might just want to (re)generate the manifest, but not create a source +distribution:: + + python setup.py sdist --manifest-only + +:option:`-o` is a shortcut for :option:`--manifest-only`. + diff --git a/uploading.rst b/uploading.rst index 7b790b1e02..e9472453d3 100644 --- a/uploading.rst +++ b/uploading.rst @@ -60,13 +60,13 @@ in the package:: setup(name='Distutils', long_description=open('README.txt')) -In that case, :file:`README.txt` is a regular reStructuredText text file located -in the root of the package besides :file:`setup.py`. +In that case, `README.txt` is a regular reStructuredText text file located +in the root of the package besides `setup.py`. To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the :mod:`docutils` package +:program:`rst2html` program that is provided by the `docutils` package and check the ``long_description`` from the command line:: $ python setup.py --long-description | rst2html.py > output.html -:mod:`docutils` will display a warning if there's something wrong with your syntax. +`docutils` will display a warning if there's something wrong with your syntax. From dcec444354902b2fabc1d5a9a4050a9a31504b49 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sat, 31 Jul 2010 09:15:10 +0000 Subject: [PATCH 152/330] After distutils doc reversal, change back **bold todo** items to XXX comments. --- apiref.rst | 6 ++---- builtdist.rst | 10 +++++----- commandref.rst | 4 ++-- setupscript.rst | 4 ++-- sourcedist.rst | 4 ++-- 5 files changed, 13 insertions(+), 15 deletions(-) diff --git a/apiref.rst b/apiref.rst index 69ec0de99b..26d04d1fd4 100644 --- a/apiref.rst +++ b/apiref.rst @@ -995,7 +995,7 @@ directories. errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is true). -**\*\*** Some of this could be replaced with the shutil module? **\*\*** +.. XXX Some of this could be replaced with the shutil module? :mod:`distutils.file_util` --- Single file operations @@ -1311,9 +1311,7 @@ provides the following additional features: the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. -**\*\*** Should be replaced with :mod:`optik` (which is also now known as -:mod:`optparse` in Python 2.3 and later). **\*\*** - +.. XXX Should be replaced with optparse .. function:: fancy_getopt(options, negative_opt, object, args) diff --git a/builtdist.rst b/builtdist.rst index ee06fb41d2..d3c067b3c3 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -141,13 +141,13 @@ The following sections give details on the individual :command:`bdist_\*` commands. -.. _creating-dumb: +.. .. _creating-dumb: -Creating dumb built distributions -================================= +.. Creating dumb built distributions +.. ================================= -**\*\*** Need to document absolute vs. prefix-relative packages here, but first -I have to implement it! **\*\*** +.. XXX Need to document absolute vs. prefix-relative packages here, but first + I have to implement it! .. _creating-rpms: diff --git a/commandref.rst b/commandref.rst index fbe40de6c2..6a2ac960f1 100644 --- a/commandref.rst +++ b/commandref.rst @@ -53,7 +53,7 @@ This command installs all (Python) scripts in the distribution. Creating a source distribution: the :command:`sdist` command ============================================================ -**\*\*** fragment moved down from above: needs context! **\*\*** +.. XXX fragment moved down from above: needs context! The manifest template commands are: @@ -90,7 +90,7 @@ character, and ``[range]`` matches any of the characters in *range* (e.g., character" is platform-specific: on Unix it is anything except slash; on Windows anything except backslash or colon. -**\*\*** Windows support not there yet **\*\*** +.. XXX Windows support not there yet .. % \section{Creating a built distribution: the .. % \protect\command{bdist} command family} diff --git a/setupscript.rst b/setupscript.rst index 5ec94c7ea5..9208e36995 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -207,7 +207,7 @@ However, you can also include SWIG interface (:file:`.i`) files in the list; the SWIG on the interface file and compile the resulting C/C++ file into your extension. -**\*\*** SWIG support is rough around the edges and largely untested! **\*\*** +.. XXX SWIG support is rough around the edges and largely untested! This warning notwithstanding, options to SWIG can be currently passed like this:: @@ -326,7 +326,7 @@ include the location in ``library_dirs``:: (Again, this sort of non-portable construct should be avoided if you intend to distribute your code.) -**\*\*** Should mention clib libraries here or somewhere else! **\*\*** +.. XXX Should mention clib libraries here or somewhere else! Other options diff --git a/sourcedist.rst b/sourcedist.rst index 96e891bd68..b829f1d5fe 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -70,8 +70,8 @@ source distribution: * all C source files mentioned in the :option:`ext_modules` or :option:`libraries` options ( - **\*\*** getting C library sources currently broken---no - :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) + .. XXX getting C library sources currently broken---no + :meth:`get_source_files` method in :file:`build_clib.py`! * scripts identified by the :option:`scripts` option See :ref:`distutils-installing-scripts`. From b05ac957a65fccbdd2a48eb9483f495db8ce2070 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 1 Aug 2010 22:19:17 +0000 Subject: [PATCH 153/330] Merged revisions 82793-82794,82807,82876,83432 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/release27-maint ................ r82793 | georg.brandl | 2010-07-11 10:56:18 +0200 (So, 11 Jul 2010) | 9 lines Merged revisions 82790 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82790 | georg.brandl | 2010-07-11 10:36:20 +0200 (So, 11 Jul 2010) | 1 line #3214 followup: add link to ABC entry. ........ ................ r82794 | georg.brandl | 2010-07-11 10:57:05 +0200 (So, 11 Jul 2010) | 9 lines Merged revisions 82789 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82789 | georg.brandl | 2010-07-11 10:33:16 +0200 (So, 11 Jul 2010) | 1 line Silence makeindex. ........ ................ r82807 | georg.brandl | 2010-07-11 12:29:37 +0200 (So, 11 Jul 2010) | 9 lines Merged revisions 82806 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82806 | georg.brandl | 2010-07-11 12:22:44 +0200 (So, 11 Jul 2010) | 1 line #9223: link to Command class reference, and move Command interface docs nearer to class docs. ........ ................ r82876 | georg.brandl | 2010-07-14 10:55:55 +0200 (Mi, 14 Jul 2010) | 13 lines Merged revisions 82872,82874 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r82872 | georg.brandl | 2010-07-14 10:53:18 +0200 (Mi, 14 Jul 2010) | 1 line Remove XXX from text. ........ r82874 | georg.brandl | 2010-07-14 10:54:40 +0200 (Mi, 14 Jul 2010) | 1 line #9235: fix missing import of sys. ........ ................ r83432 | georg.brandl | 2010-08-01 21:21:26 +0200 (So, 01 Aug 2010) | 13 lines Merged revisions 83328,83341 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r83328 | raymond.hettinger | 2010-07-31 12:14:41 +0200 (Sa, 31 Jul 2010) | 1 line Document how to change OrderedDict update order from first to last. ........ r83341 | georg.brandl | 2010-07-31 13:40:07 +0200 (Sa, 31 Jul 2010) | 1 line #9430: document timedelta str() and repr(). ........ ................ --- apiref.rst | 2 +- extending.rst | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 7874415f52..0a885983d6 100644 --- a/apiref.rst +++ b/apiref.rst @@ -21,7 +21,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and .. function:: setup(arguments) The basic do-everything function that does most everything you could ever ask - for from a Distutils method. See XXXXX + for from a Distutils method. The setup function takes a large number of arguments. These are laid out in the following table. diff --git a/extending.rst b/extending.rst index 972ff02c03..5a70d031cc 100644 --- a/extending.rst +++ b/extending.rst @@ -15,8 +15,8 @@ want to modify existing commands; many simply add a few file extensions that should be copied into packages in addition to :file:`.py` files as a convenience. -Most distutils command implementations are subclasses of the :class:`Command` -class from :mod:`distutils.cmd`. New commands may directly inherit from +Most distutils command implementations are subclasses of the +:class:`distutils.cmd.Command` class. New commands may directly inherit from :class:`Command`, while replacements often derive from :class:`Command` indirectly, directly subclassing the command they are replacing. Commands are required to derive from :class:`Command`. From c9a96a1402791a4d1a2970e249079be51b432230 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 2 Aug 2010 19:16:34 +0000 Subject: [PATCH 154/330] #7973: Fix distutils options spelling. --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index d3c067b3c3..581f0f6a55 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -176,7 +176,7 @@ easily specify multiple formats in one run. If you need to do both, you can explicitly specify multiple :command:`bdist_\*` commands and their options:: python setup.py bdist_rpm --packager="John Doe " \ - bdist_wininst --target_version="2.0" + bdist_wininst --target-version="2.0" Creating RPM packages is driven by a :file:`.spec` file, much as using the Distutils is driven by the setup script. To make your life easier, the From 2f483dd7d9a631834b794ce7bbf110b7433b05f6 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 2 Aug 2010 21:44:25 +0000 Subject: [PATCH 155/330] Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r83536 | georg.brandl | 2010-08-02 19:49:25 +0200 (Mo, 02 Aug 2010) | 1 line #8578: mention danger of not incref'ing weak referenced object. ........ r83546 | georg.brandl | 2010-08-02 21:16:34 +0200 (Mo, 02 Aug 2010) | 1 line #7973: Fix distutils options spelling. ........ r83547 | georg.brandl | 2010-08-02 21:19:26 +0200 (Mo, 02 Aug 2010) | 1 line #7386: add example that shows that trailing path separators are stripped. ........ r83548 | georg.brandl | 2010-08-02 21:23:34 +0200 (Mo, 02 Aug 2010) | 1 line #8172: how does one use a property? ........ r83550 | georg.brandl | 2010-08-02 21:32:43 +0200 (Mo, 02 Aug 2010) | 1 line #9451: strengthen warning about __*__ special name usage. ........ r83554 | georg.brandl | 2010-08-02 21:43:05 +0200 (Mo, 02 Aug 2010) | 1 line #7280: note about nasmw.exe. ........ r83555 | georg.brandl | 2010-08-02 21:44:48 +0200 (Mo, 02 Aug 2010) | 1 line #8861: remove unused variable. ........ r83558 | georg.brandl | 2010-08-02 22:05:19 +0200 (Mo, 02 Aug 2010) | 1 line #8648: document UTF-7 codec functions. ........ r83563 | georg.brandl | 2010-08-02 22:21:21 +0200 (Mo, 02 Aug 2010) | 1 line #9037: add example how to raise custom exceptions from C code. ........ r83565 | georg.brandl | 2010-08-02 22:27:20 +0200 (Mo, 02 Aug 2010) | 1 line #9111: document that do_help() looks at docstrings. ........ r83571 | georg.brandl | 2010-08-02 22:44:34 +0200 (Mo, 02 Aug 2010) | 1 line Clarify that abs() is not a namespace. ........ r83574 | georg.brandl | 2010-08-02 22:47:56 +0200 (Mo, 02 Aug 2010) | 1 line #6867: epoll.register() returns None. ........ r83575 | georg.brandl | 2010-08-02 22:52:10 +0200 (Mo, 02 Aug 2010) | 1 line #9238: zipfile does handle archive comments. ........ --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index 8ce94d35db..1886d85053 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -176,7 +176,7 @@ easily specify multiple formats in one run. If you need to do both, you can explicitly specify multiple :command:`bdist_\*` commands and their options:: python setup.py bdist_rpm --packager="John Doe " \ - bdist_wininst --target_version="2.0" + bdist_wininst --target-version="2.0" Creating RPM packages is driven by a :file:`.spec` file, much as using the Distutils is driven by the setup script. To make your life easier, the From ed9c8fb86c905231d78541a86680814b0cbadaa3 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Mon, 2 Aug 2010 21:45:43 +0000 Subject: [PATCH 156/330] Merged revisions 83593 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/release27-maint ................ r83593 | georg.brandl | 2010-08-02 23:44:25 +0200 (Mo, 02 Aug 2010) | 57 lines Merged revisions 83536,83546-83548,83550,83554-83555,83558,83563,83565,83571,83574-83575 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r83536 | georg.brandl | 2010-08-02 19:49:25 +0200 (Mo, 02 Aug 2010) | 1 line #8578: mention danger of not incref'ing weak referenced object. ........ r83546 | georg.brandl | 2010-08-02 21:16:34 +0200 (Mo, 02 Aug 2010) | 1 line #7973: Fix distutils options spelling. ........ r83547 | georg.brandl | 2010-08-02 21:19:26 +0200 (Mo, 02 Aug 2010) | 1 line #7386: add example that shows that trailing path separators are stripped. ........ r83548 | georg.brandl | 2010-08-02 21:23:34 +0200 (Mo, 02 Aug 2010) | 1 line #8172: how does one use a property? ........ r83550 | georg.brandl | 2010-08-02 21:32:43 +0200 (Mo, 02 Aug 2010) | 1 line #9451: strengthen warning about __*__ special name usage. ........ r83554 | georg.brandl | 2010-08-02 21:43:05 +0200 (Mo, 02 Aug 2010) | 1 line #7280: note about nasmw.exe. ........ r83555 | georg.brandl | 2010-08-02 21:44:48 +0200 (Mo, 02 Aug 2010) | 1 line #8861: remove unused variable. ........ r83558 | georg.brandl | 2010-08-02 22:05:19 +0200 (Mo, 02 Aug 2010) | 1 line #8648: document UTF-7 codec functions. ........ r83563 | georg.brandl | 2010-08-02 22:21:21 +0200 (Mo, 02 Aug 2010) | 1 line #9037: add example how to raise custom exceptions from C code. ........ r83565 | georg.brandl | 2010-08-02 22:27:20 +0200 (Mo, 02 Aug 2010) | 1 line #9111: document that do_help() looks at docstrings. ........ r83571 | georg.brandl | 2010-08-02 22:44:34 +0200 (Mo, 02 Aug 2010) | 1 line Clarify that abs() is not a namespace. ........ r83574 | georg.brandl | 2010-08-02 22:47:56 +0200 (Mo, 02 Aug 2010) | 1 line #6867: epoll.register() returns None. ........ r83575 | georg.brandl | 2010-08-02 22:52:10 +0200 (Mo, 02 Aug 2010) | 1 line #9238: zipfile does handle archive comments. ........ ................ --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index 8615cbb243..f1dad77174 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -173,7 +173,7 @@ easily specify multiple formats in one run. If you need to do both, you can explicitly specify multiple :command:`bdist_\*` commands and their options:: python setup.py bdist_rpm --packager="John Doe " \ - bdist_wininst --target_version="2.0" + bdist_wininst --target-version="2.0" Creating RPM packages is driven by a :file:`.spec` file, much as using the Distutils is driven by the setup script. To make your life easier, the From 39f890ee9eeae8c9a99c144175eee6046dfb5017 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 14 Aug 2010 02:30:34 +0000 Subject: [PATCH 157/330] Use a marker in generated MANIFEST files, don't touch files without it. Fixes #8688. --- sourcedist.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index b829f1d5fe..8a083a2859 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -103,6 +103,10 @@ per line, regular files (or symlinks to them) only. If you do supply your own :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. +.. versionadded:: 3.2 + :file:`MANIFEST` files start with a comment indicated they are generated. + Files without this comment are not overwritten or removed. + The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an example, again we turn to the Distutils' own manifest template:: @@ -187,10 +191,6 @@ The normal course of operations for the :command:`sdist` command is as follows: * if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest with just the default file set -* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more - recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading - :file:`MANIFEST.in` - * use the list of files now in :file:`MANIFEST` (either just generated or read in) to create the source distribution archive(s) @@ -205,4 +205,7 @@ distribution:: :option:`-o` is a shortcut for :option:`--manifest-only`. - +.. versionchanged:: 3.2 + An existing generated :file:`MANIFEST` will be regenerated without + :command:`sdist` comparing its modification time to the one of + :file:`MANIFEST.in` or :file:`setup.py`. From fbfa411d9907fbf90da2783a29e4f02d78ac92a7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 14 Aug 2010 02:36:26 +0000 Subject: [PATCH 158/330] Merged revisions 83993 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r83993 | eric.araujo | 2010-08-14 04:30:34 +0200 (sam., 14 août 2010) | 2 lines Use a marker in generated MANIFEST files, don't touch files without it. Fixes #8688. ........ --- sourcedist.rst | 13 ++++++++----- 1 file changed, 8 insertions(+), 5 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 96e891bd68..72cd154eb1 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -103,6 +103,10 @@ per line, regular files (or symlinks to them) only. If you do supply your own :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. +.. versionadded:: 3.2 + :file:`MANIFEST` files start with a comment indicated they are generated. + Files without this comment are not overwritten or removed. + The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an example, again we turn to the Distutils' own manifest template:: @@ -187,10 +191,6 @@ The normal course of operations for the :command:`sdist` command is as follows: * if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest with just the default file set -* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more - recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading - :file:`MANIFEST.in` - * use the list of files now in :file:`MANIFEST` (either just generated or read in) to create the source distribution archive(s) @@ -205,4 +205,7 @@ distribution:: :option:`-o` is a shortcut for :option:`--manifest-only`. - +.. versionchanged:: 3.2 + An existing generated :file:`MANIFEST` will be regenerated without + :command:`sdist` comparing its modification time to the one of + :file:`MANIFEST.in` or :file:`setup.py`. From 3c46db2ea074e833c1350210ac6403931ce7b06c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 14 Aug 2010 02:45:58 +0000 Subject: [PATCH 159/330] Fix version{added,changed} and spacing in NEWS --- sourcedist.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 72cd154eb1..6d09fdb340 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -103,7 +103,7 @@ per line, regular files (or symlinks to them) only. If you do supply your own :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. -.. versionadded:: 3.2 +.. versionadded:: 3.1 :file:`MANIFEST` files start with a comment indicated they are generated. Files without this comment are not overwritten or removed. @@ -205,7 +205,7 @@ distribution:: :option:`-o` is a shortcut for :option:`--manifest-only`. -.. versionchanged:: 3.2 +.. versionchanged:: 3.1 An existing generated :file:`MANIFEST` will be regenerated without :command:`sdist` comparing its modification time to the one of :file:`MANIFEST.in` or :file:`setup.py`. From 5d9dbc9166139e0d77af44bcdc9694d9e8df28a4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 14 Aug 2010 03:07:46 +0000 Subject: [PATCH 160/330] Merged revisions 83993 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r83993 | eric.araujo | 2010-08-14 04:30:34 +0200 (sam., 14 août 2010) | 2 lines Use a marker in generated MANIFEST files, don't touch files without it. Fixes #8688. ........ --- sourcedist.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/sourcedist.rst b/sourcedist.rst index 2cfdf698dd..739964e7fb 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -162,6 +162,10 @@ This mechanism can be used when the default list of files is not enough. Principle --------- +.. versionadded:: 2.7 + :file:`MANIFEST` files start with a comment indicated they are generated. + Files without this comment are not overwritten or removed. + The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an example, let's look at the Distutils' own manifest template:: @@ -268,3 +272,7 @@ character, and ``[range]`` matches any of the characters in *range* (e.g., character" is platform-specific: on Unix it is anything except slash; on Windows anything except backslash or colon. +.. versionchanged:: 2.7 + An existing generated :file:`MANIFEST` will be regenerated without + :command:`sdist` comparing its modification time to the one of + :file:`MANIFEST.in` or :file:`setup.py`. From 9e1e39bc3ab5663c8ff181f902dd63098384be46 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 14 Aug 2010 03:59:54 +0000 Subject: [PATCH 161/330] Manually merge r83995: Fix version{added,changed} and spacing in NEWS --- sourcedist.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 8a083a2859..ea5b02c45a 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -103,7 +103,7 @@ per line, regular files (or symlinks to them) only. If you do supply your own :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. -.. versionadded:: 3.2 +.. versionadded:: 3.1 :file:`MANIFEST` files start with a comment indicated they are generated. Files without this comment are not overwritten or removed. @@ -205,7 +205,7 @@ distribution:: :option:`-o` is a shortcut for :option:`--manifest-only`. -.. versionchanged:: 3.2 +.. versionchanged:: 3.1 An existing generated :file:`MANIFEST` will be regenerated without :command:`sdist` comparing its modification time to the one of :file:`MANIFEST.in` or :file:`setup.py`. From 09abd8491ccf60ab0eab61adbdc17889ce6182a3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 14 Aug 2010 23:44:13 +0000 Subject: [PATCH 162/330] Fix typo --- sourcedist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sourcedist.rst b/sourcedist.rst index ea5b02c45a..2c2d995c1b 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -104,7 +104,7 @@ per line, regular files (or symlinks to them) only. If you do supply your own described above does not apply in this case. .. versionadded:: 3.1 - :file:`MANIFEST` files start with a comment indicated they are generated. + :file:`MANIFEST` files start with a comment indicating they are generated. Files without this comment are not overwritten or removed. The manifest template has one command per line, where each command specifies a From 74644b45357c2b7f269cff662b1a29e656a52b14 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 14 Aug 2010 23:49:42 +0000 Subject: [PATCH 163/330] Merged revisions 84050 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r84050 | eric.araujo | 2010-08-15 01:44:13 +0200 (dim., 15 août 2010) | 1 line Fix typo ........ --- sourcedist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sourcedist.rst b/sourcedist.rst index 6d09fdb340..c2b4efeb7e 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -104,7 +104,7 @@ per line, regular files (or symlinks to them) only. If you do supply your own described above does not apply in this case. .. versionadded:: 3.1 - :file:`MANIFEST` files start with a comment indicated they are generated. + :file:`MANIFEST` files start with a comment indicating they are generated. Files without this comment are not overwritten or removed. The manifest template has one command per line, where each command specifies a From 0e4d8016471c0e18aadf20e4634eee1cc5913995 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 14 Aug 2010 23:51:39 +0000 Subject: [PATCH 164/330] Merged revisions 84050 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r84050 | eric.araujo | 2010-08-15 01:44:13 +0200 (dim., 15 août 2010) | 1 line Fix typo ........ --- sourcedist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sourcedist.rst b/sourcedist.rst index 739964e7fb..9287d8cb73 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -163,7 +163,7 @@ Principle --------- .. versionadded:: 2.7 - :file:`MANIFEST` files start with a comment indicated they are generated. + :file:`MANIFEST` files start with a comment indicating they are generated. Files without this comment are not overwritten or removed. The manifest template has one command per line, where each command specifies a From 10cb2e23be315ab637fec05375539aec55fa31e4 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 15 Aug 2010 00:49:35 +0000 Subject: [PATCH 165/330] Fix bad merge --- sourcedist.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 9287d8cb73..c549c908d8 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -111,6 +111,10 @@ per line, regular files (or symlinks to them) only. If you do supply your own :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. +.. versionadded:: 2.7 + :file:`MANIFEST` files start with a comment indicating they are generated. + Files without this comment are not overwritten or removed. + See :ref:`manifest_template` section for a syntax reference. .. _manifest-options: @@ -162,10 +166,6 @@ This mechanism can be used when the default list of files is not enough. Principle --------- -.. versionadded:: 2.7 - :file:`MANIFEST` files start with a comment indicating they are generated. - Files without this comment are not overwritten or removed. - The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an example, let's look at the Distutils' own manifest template:: From 2331bf9b53847259d9cb5031d4e66577b2a5ce9e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 17 Aug 2010 15:07:14 +0000 Subject: [PATCH 166/330] Consistency check for versionadded/changed directives. --- sourcedist.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 2c2d995c1b..15d0bafd71 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -206,6 +206,6 @@ distribution:: :option:`-o` is a shortcut for :option:`--manifest-only`. .. versionchanged:: 3.1 - An existing generated :file:`MANIFEST` will be regenerated without - :command:`sdist` comparing its modification time to the one of - :file:`MANIFEST.in` or :file:`setup.py`. + An existing generated :file:`MANIFEST` will be regenerated without + :command:`sdist` comparing its modification time to the one of + :file:`MANIFEST.in` or :file:`setup.py`. From a2b83ebe9d57c595a7f6983c54145804e4c475c8 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Tue, 21 Sep 2010 14:48:28 +0000 Subject: [PATCH 167/330] #9911: doc copyedits. --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index 581f0f6a55..d646328a63 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -357,7 +357,7 @@ would create a 64bit installation executable on your 32bit version of Windows. To cross-compile, you must download the Python source code and cross-compile Python itself for the platform you are targetting - it is not possible from a -binary installtion of Python (as the .lib etc file for other platforms are +binary installation of Python (as the .lib etc file for other platforms are not included.) In practice, this means the user of a 32 bit operating system will need to use Visual Studio 2008 to open the :file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the From a3c1f8f8d1f07e4faf617369e67c6177bd71697a Mon Sep 17 00:00:00 2001 From: Brian Curtin Date: Sat, 25 Sep 2010 02:36:46 +0000 Subject: [PATCH 168/330] #9934. Correct a typo that was already fixed on py3k. --- sourcedist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sourcedist.rst b/sourcedist.rst index c549c908d8..fc860de68e 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -146,7 +146,7 @@ source distribution:: python setup.py sdist --manifest-only -:option:`-o` is a sortcut for :option:`--manifest-only`. +:option:`-o` is a shortcut for :option:`--manifest-only`. .. _manifest_template: From f109561f5ac4963ae406e02bbdd9bb14a5593b60 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 6 Oct 2010 07:55:35 +0000 Subject: [PATCH 169/330] Merged revisions 77236,77383,77399,77857,78238,78861-78862,78958 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ................ r77236 | georg.brandl | 2010-01-02 15:51:12 +0100 (Sa, 02 Jan 2010) | 1 line #7592: remove duplicate description. ................ r77383 | georg.brandl | 2010-01-09 10:48:46 +0100 (Sa, 09 Jan 2010) | 9 lines Merged revisions 77382 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r77382 | georg.brandl | 2010-01-09 10:47:11 +0100 (Sa, 09 Jan 2010) | 1 line #7422: make it clear that getargspec() only works on Python functions. ........ ................ r77399 | georg.brandl | 2010-01-09 23:39:42 +0100 (Sa, 09 Jan 2010) | 1 line Remove redundant brackets in signatures. ................ r77857 | georg.brandl | 2010-01-30 18:54:04 +0100 (Sa, 30 Jan 2010) | 1 line #7814: fix wrong example function usage. ................ r78238 | georg.brandl | 2010-02-19 10:10:15 +0100 (Fr, 19 Feb 2010) | 1 line #5341: fix parenthesis placement. ................ r78861 | georg.brandl | 2010-03-12 11:04:37 +0100 (Fr, 12 Mär 2010) | 1 line Make tool compatible with 2.x and 3.x. ................ r78862 | georg.brandl | 2010-03-12 11:06:40 +0100 (Fr, 12 Mär 2010) | 13 lines Merged revisions 78859-78860 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r78859 | georg.brandl | 2010-03-12 10:57:43 +0100 (Fr, 12 Mär 2010) | 1 line Get rid of backticks. ........ r78860 | georg.brandl | 2010-03-12 11:02:03 +0100 (Fr, 12 Mär 2010) | 1 line Fix warnings from "make check". ........ ................ r78958 | georg.brandl | 2010-03-14 11:51:01 +0100 (So, 14 Mär 2010) | 37 lines Merged revisions 78101,78115,78117,78182,78188,78245,78386,78496 via svnmerge from svn+ssh://pythondev@svn.python.org/python/trunk ........ r78101 | georg.brandl | 2010-02-08 01:04:54 +0100 (Mo, 08 Feb 2010) | 1 line Fix test_fnmatch. ........ r78115 | georg.brandl | 2010-02-08 23:40:51 +0100 (Mo, 08 Feb 2010) | 1 line Fix missing string formatting placeholder. ........ r78117 | georg.brandl | 2010-02-08 23:48:37 +0100 (Mo, 08 Feb 2010) | 1 line Convert test failure from output-producing to self.fail(). ........ r78182 | georg.brandl | 2010-02-14 09:18:23 +0100 (So, 14 Feb 2010) | 1 line #7926: fix stray parens. ........ r78188 | georg.brandl | 2010-02-14 14:38:12 +0100 (So, 14 Feb 2010) | 1 line #7926: fix-up wording. ........ r78245 | georg.brandl | 2010-02-19 20:36:08 +0100 (Fr, 19 Feb 2010) | 1 line #7967: PyXML is no more. ........ r78386 | georg.brandl | 2010-02-23 22:48:57 +0100 (Di, 23 Feb 2010) | 1 line #6544: fix refleak in kqueue, occurring in certain error conditions. ........ r78496 | georg.brandl | 2010-02-27 15:58:08 +0100 (Sa, 27 Feb 2010) | 1 line Link to http://www.python.org/dev/workflow/ from bugs page. ........ ................ --- examples.rst | 6 +++--- uploading.rst | 8 ++++---- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/examples.rst b/examples.rst index 648063b217..6c2773874c 100644 --- a/examples.rst +++ b/examples.rst @@ -257,9 +257,9 @@ Running the ``check`` command will display some warnings:: (maintainer and maintainer_email) must be supplied -If you use the reStructuredText syntax in the `long_description` field and +If you use the reStructuredText syntax in the ``long_description`` field and `docutils `_ is installed you can check if -the syntax is fine with the ``check`` command, using the `restructuredtext` +the syntax is fine with the ``check`` command, using the ``restructuredtext`` option. For example, if the :file:`setup.py` script is changed like this:: @@ -278,7 +278,7 @@ For example, if the :file:`setup.py` script is changed like this:: url='http://example.com', long_description=desc) Where the long description is broken, ``check`` will be able to detect it -by using the `docutils` parser:: +by using the :mod:`docutils` parser:: $ pythontrunk setup.py check --restructuredtext running check diff --git a/uploading.rst b/uploading.rst index e9472453d3..7b790b1e02 100644 --- a/uploading.rst +++ b/uploading.rst @@ -60,13 +60,13 @@ in the package:: setup(name='Distutils', long_description=open('README.txt')) -In that case, `README.txt` is a regular reStructuredText text file located -in the root of the package besides `setup.py`. +In that case, :file:`README.txt` is a regular reStructuredText text file located +in the root of the package besides :file:`setup.py`. To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the `docutils` package +:program:`rst2html` program that is provided by the :mod:`docutils` package and check the ``long_description`` from the command line:: $ python setup.py --long-description | rst2html.py > output.html -`docutils` will display a warning if there's something wrong with your syntax. +:mod:`docutils` will display a warning if there's something wrong with your syntax. From de2bfbd9382b7030a32f9338ff150c33c454c8e1 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 6 Oct 2010 08:13:26 +0000 Subject: [PATCH 170/330] Merged revisions 82629,82632,82724,82757-82758,82760-82763,82798-82799,82801 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ........ r82629 | georg.brandl | 2010-07-07 20:51:43 +0200 (Mi, 07 Jul 2010) | 1 line Make comment out of an awkward note. ........ r82632 | georg.brandl | 2010-07-07 21:04:36 +0200 (Mi, 07 Jul 2010) | 1 line Turn more notes into comments. ........ r82724 | georg.brandl | 2010-07-09 09:33:15 +0200 (Fr, 09 Jul 2010) | 1 line 2.7 is now stable. ........ r82757 | georg.brandl | 2010-07-10 10:58:37 +0200 (Sa, 10 Jul 2010) | 1 line Fix markup. ........ r82758 | georg.brandl | 2010-07-10 12:23:40 +0200 (Sa, 10 Jul 2010) | 1 line Emphasize role of count for Pascal string. ........ r82760 | georg.brandl | 2010-07-10 12:39:57 +0200 (Sa, 10 Jul 2010) | 1 line #3214: improve description of duck-typing in glossary. ........ r82761 | georg.brandl | 2010-07-10 13:40:13 +0200 (Sa, 10 Jul 2010) | 1 line #1434090: properly append child in expatbuilder doctype handler. ........ r82762 | georg.brandl | 2010-07-10 13:51:06 +0200 (Sa, 10 Jul 2010) | 1 line #8338: fix outdated class name. ........ r82763 | georg.brandl | 2010-07-10 14:01:34 +0200 (Sa, 10 Jul 2010) | 1 line #8456: fix signature of sqlite3.connect(). ........ r82798 | georg.brandl | 2010-07-11 11:23:11 +0200 (So, 11 Jul 2010) | 1 line #6774: explain shutdown() behavior varying with platform. ........ r82799 | georg.brandl | 2010-07-11 11:26:57 +0200 (So, 11 Jul 2010) | 1 line Fix typo. ........ r82801 | georg.brandl | 2010-07-11 11:33:39 +0200 (So, 11 Jul 2010) | 1 line #9184: fix default value for "buffering" param of open(). ........ --- apiref.rst | 5 ++--- builtdist.rst | 4 ++-- setupscript.rst | 4 ++-- sourcedist.rst | 6 +++--- 4 files changed, 9 insertions(+), 10 deletions(-) diff --git a/apiref.rst b/apiref.rst index 69ec0de99b..366c713b3f 100644 --- a/apiref.rst +++ b/apiref.rst @@ -995,7 +995,7 @@ directories. errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is true). -**\*\*** Some of this could be replaced with the shutil module? **\*\*** +.. XXX Some of this could be replaced with the shutil module? :mod:`distutils.file_util` --- Single file operations @@ -1311,8 +1311,7 @@ provides the following additional features: the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. -**\*\*** Should be replaced with :mod:`optik` (which is also now known as -:mod:`optparse` in Python 2.3 and later). **\*\*** +.. XXX Should be replaced with :mod:`optparse`. .. function:: fancy_getopt(options, negative_opt, object, args) diff --git a/builtdist.rst b/builtdist.rst index ee06fb41d2..4f086c64fb 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -146,8 +146,8 @@ commands. Creating dumb built distributions ================================= -**\*\*** Need to document absolute vs. prefix-relative packages here, but first -I have to implement it! **\*\*** +.. XXX Need to document absolute vs. prefix-relative packages here, but first + I have to implement it! .. _creating-rpms: diff --git a/setupscript.rst b/setupscript.rst index 5ec94c7ea5..9208e36995 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -207,7 +207,7 @@ However, you can also include SWIG interface (:file:`.i`) files in the list; the SWIG on the interface file and compile the resulting C/C++ file into your extension. -**\*\*** SWIG support is rough around the edges and largely untested! **\*\*** +.. XXX SWIG support is rough around the edges and largely untested! This warning notwithstanding, options to SWIG can be currently passed like this:: @@ -326,7 +326,7 @@ include the location in ``library_dirs``:: (Again, this sort of non-portable construct should be avoided if you intend to distribute your code.) -**\*\*** Should mention clib libraries here or somewhere else! **\*\*** +.. XXX Should mention clib libraries here or somewhere else! Other options diff --git a/sourcedist.rst b/sourcedist.rst index c2b4efeb7e..0c29c19f70 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -68,10 +68,10 @@ source distribution: :option:`packages` options * all C source files mentioned in the :option:`ext_modules` or - :option:`libraries` options ( + :option:`libraries` options - **\*\*** getting C library sources currently broken---no - :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***) + .. XXX Getting C library sources is currently broken -- no + :meth:`get_source_files` method in :file:`build_clib.py`! * scripts identified by the :option:`scripts` option See :ref:`distutils-installing-scripts`. From f078ab0127de9efe44f21fa37f2c78cd78b43771 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 6 Oct 2010 08:26:09 +0000 Subject: [PATCH 171/330] Merged revisions 82805-82806,83523-83527,83536,83538,83542,83546-83548,83550-83555,83558,83560 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ........ r82805 | georg.brandl | 2010-07-11 11:42:10 +0200 (So, 11 Jul 2010) | 1 line #7935: cross-reference to ast.literal_eval() from eval() docs. ........ r82806 | georg.brandl | 2010-07-11 12:22:44 +0200 (So, 11 Jul 2010) | 1 line #9223: link to Command class reference, and move Command interface docs nearer to class docs. ........ r83523 | georg.brandl | 2010-08-02 14:06:18 +0200 (Mo, 02 Aug 2010) | 1 line #9209 and #7781: fix two crashes in pstats interactive browser. ........ r83524 | georg.brandl | 2010-08-02 14:20:23 +0200 (Mo, 02 Aug 2010) | 1 line #9428: fix running scripts from profile/cProfile with their own name and the right namespace. Same fix as for trace.py in #1690103. ........ r83525 | georg.brandl | 2010-08-02 14:36:24 +0200 (Mo, 02 Aug 2010) | 1 line Get rid of spurious "threading" entries in trace output. ........ r83526 | georg.brandl | 2010-08-02 14:40:22 +0200 (Mo, 02 Aug 2010) | 1 line Fix softspace relic. ........ r83527 | georg.brandl | 2010-08-02 14:48:46 +0200 (Mo, 02 Aug 2010) | 1 line #3821: beginnings of a trace.py unittest. ........ r83536 | georg.brandl | 2010-08-02 19:49:25 +0200 (Mo, 02 Aug 2010) | 1 line #8578: mention danger of not incref'ing weak referenced object. ........ r83538 | georg.brandl | 2010-08-02 20:10:13 +0200 (Mo, 02 Aug 2010) | 1 line #6928: fix class docs w.r.t. new metaclasses. ........ r83542 | georg.brandl | 2010-08-02 20:56:54 +0200 (Mo, 02 Aug 2010) | 1 line Move test_SimpleHTTPServer into test_httpservers. ........ r83546 | georg.brandl | 2010-08-02 21:16:34 +0200 (Mo, 02 Aug 2010) | 1 line #7973: Fix distutils options spelling. ........ r83547 | georg.brandl | 2010-08-02 21:19:26 +0200 (Mo, 02 Aug 2010) | 1 line #7386: add example that shows that trailing path separators are stripped. ........ r83548 | georg.brandl | 2010-08-02 21:23:34 +0200 (Mo, 02 Aug 2010) | 1 line #8172: how does one use a property? ........ r83550 | georg.brandl | 2010-08-02 21:32:43 +0200 (Mo, 02 Aug 2010) | 1 line #9451: strengthen warning about __*__ special name usage. ........ r83551 | georg.brandl | 2010-08-02 21:35:06 +0200 (Mo, 02 Aug 2010) | 1 line Remove XXX comment that was displayed. ........ r83552 | georg.brandl | 2010-08-02 21:36:36 +0200 (Mo, 02 Aug 2010) | 1 line #9438: clarify that constant names also cannot be assigned as attributes. ........ r83553 | georg.brandl | 2010-08-02 21:39:17 +0200 (Mo, 02 Aug 2010) | 1 line Remove redundant information. ........ r83554 | georg.brandl | 2010-08-02 21:43:05 +0200 (Mo, 02 Aug 2010) | 1 line #7280: note about nasmw.exe. ........ r83555 | georg.brandl | 2010-08-02 21:44:48 +0200 (Mo, 02 Aug 2010) | 1 line #8861: remove unused variable. ........ r83558 | georg.brandl | 2010-08-02 22:05:19 +0200 (Mo, 02 Aug 2010) | 1 line #8648: document UTF-7 codec functions. ........ r83560 | georg.brandl | 2010-08-02 22:16:18 +0200 (Mo, 02 Aug 2010) | 1 line #9087: update json docstrings -- unicode and long do not exist anymore. ........ --- apiref.rst | 169 ++++++++++++++++++++++++-------------------------- builtdist.rst | 2 +- extending.rst | 4 +- 3 files changed, 83 insertions(+), 92 deletions(-) diff --git a/apiref.rst b/apiref.rst index 366c713b3f..2401da3f6c 100644 --- a/apiref.rst +++ b/apiref.rst @@ -147,11 +147,11 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and In addition, the :mod:`distutils.core` module exposed a number of classes that live elsewhere. -* :class:`Extension` from :mod:`distutils.extension` +* :class:`~distutils.extension.Extension` from :mod:`distutils.extension` -* :class:`Command` from :mod:`distutils.cmd` +* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd` -* :class:`Distribution` from :mod:`distutils.dist` +* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist` A short description of each of these follows, but see the relevant module for the full reference. @@ -1679,8 +1679,8 @@ lines, and joining lines with backslashes. =================================================================== .. module:: distutils.cmd - :synopsis: This module provides the abstract base class Command. This class is subclassed - by the modules in the distutils.command subpackage. + :synopsis: This module provides the abstract base class Command. This class + is subclassed by the modules in the distutils.command subpackage. This module supplies the abstract base class :class:`Command`. @@ -1690,20 +1690,84 @@ This module supplies the abstract base class :class:`Command`. Abstract base class for defining command classes, the "worker bees" of the Distutils. A useful analogy for command classes is to think of them as - subroutines with local variables called *options*. The options are declared in - :meth:`initialize_options` and defined (given their final values) in - :meth:`finalize_options`, both of which must be defined by every command class. - The distinction between the two is necessary because option values might come - from the outside world (command line, config file, ...), and any options - dependent on other options must be computed after these outside influences have - been processed --- hence :meth:`finalize_options`. The body of the subroutine, - where it does all its work based on the values of its options, is the - :meth:`run` method, which must also be implemented by every command class. - - The class constructor takes a single argument *dist*, a :class:`Distribution` + subroutines with local variables called *options*. The options are declared + in :meth:`initialize_options` and defined (given their final values) in + :meth:`finalize_options`, both of which must be defined by every command + class. The distinction between the two is necessary because option values + might come from the outside world (command line, config file, ...), and any + options dependent on other options must be computed after these outside + influences have been processed --- hence :meth:`finalize_options`. The body + of the subroutine, where it does all its work based on the values of its + options, is the :meth:`run` method, which must also be implemented by every + command class. + + The class constructor takes a single argument *dist*, a :class:`Distribution` instance. +Creating a new Distutils command +================================ + +This section outlines the steps to create a new Distutils command. + +A new command lives in a module in the :mod:`distutils.command` package. There +is a sample template in that directory called :file:`command_template`. Copy +this file to a new module with the same name as the new command you're +implementing. This module should implement a class with the same name as the +module (and the command). So, for instance, to create the command +``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy +:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit +it so that it's implementing the class :class:`peel_banana`, a subclass of +:class:`distutils.cmd.Command`. + +Subclasses of :class:`Command` must define the following methods. + +.. method:: Command.initialize_options() + + Set default values for all the options that this command supports. Note that + these defaults may be overridden by other commands, by the setup script, by + config files, or by the command-line. Thus, this is not the place to code + dependencies between options; generally, :meth:`initialize_options` + implementations are just a bunch of ``self.foo = None`` assignments. + + +.. method:: Command.finalize_options() + + Set final values for all the options that this command supports. This is + always called as late as possible, ie. after any option assignments from the + command-line or from other commands have been done. Thus, this is the place + to to code option dependencies: if *foo* depends on *bar*, then it is safe to + set *foo* from *bar* as long as *foo* still has the same value it was + assigned in :meth:`initialize_options`. + + +.. method:: Command.run() + + A command's raison d'etre: carry out the action it exists to perform, controlled + by the options initialized in :meth:`initialize_options`, customized by other + commands, the setup script, the command-line, and config files, and finalized in + :meth:`finalize_options`. All terminal output and filesystem interaction should + be done by :meth:`run`. + + +.. attribute:: Command.sub_commands + + *sub_commands* formalizes the notion of a "family" of commands, + e.g. ``install`` as the parent with sub-commands ``install_lib``, + ``install_headers``, etc. The parent of a family of commands defines + *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, + predicate)``, with *command_name* a string and *predicate* a function, a + string or ``None``. *predicate* is a method of the parent command that + determines whether the corresponding command is applicable in the current + situation. (E.g. we ``install_headers`` is only applicable if we have any C + header files to install.) If *predicate* is ``None``, that command is always + applicable. + + *sub_commands* is usually defined at the *end* of a class, because + predicates can be methods of the class, so they must already have been + defined. The canonical example is the :command:`install` command. + + :mod:`distutils.command` --- Individual Distutils commands ========================================================== @@ -1942,76 +2006,3 @@ The ``register`` command registers the package with the Python Package Index. This is described in more detail in :pep:`301`. .. % todo - -:mod:`distutils.command.check` --- Check the meta-data of a package -=================================================================== - -.. module:: distutils.command.check - :synopsis: Check the metadata of a package - - -The ``check`` command performs some tests on the meta-data of a package. -For example, it verifies that all required meta-data are provided as -the arguments passed to the :func:`setup` function. - -.. % todo - - -Creating a new Distutils command -================================ - -This section outlines the steps to create a new Distutils command. - -A new command lives in a module in the :mod:`distutils.command` package. There -is a sample template in that directory called :file:`command_template`. Copy -this file to a new module with the same name as the new command you're -implementing. This module should implement a class with the same name as the -module (and the command). So, for instance, to create the command -``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy -:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit -it so that it's implementing the class :class:`peel_banana`, a subclass of -:class:`distutils.cmd.Command`. - -Subclasses of :class:`Command` must define the following methods. - - -.. method:: Command.initialize_options() - - Set default values for all the options that this command supports. Note that - these defaults may be overridden by other commands, by the setup script, by - config files, or by the command-line. Thus, this is not the place to code - dependencies between options; generally, :meth:`initialize_options` - implementations are just a bunch of ``self.foo = None`` assignments. - - -.. method:: Command.finalize_options() - - Set final values for all the options that this command supports. This is - always called as late as possible, ie. after any option assignments from the - command-line or from other commands have been done. Thus, this is the place - to to code option dependencies: if *foo* depends on *bar*, then it is safe to - set *foo* from *bar* as long as *foo* still has the same value it was - assigned in :meth:`initialize_options`. - - -.. method:: Command.run() - - A command's raison d'etre: carry out the action it exists to perform, controlled - by the options initialized in :meth:`initialize_options`, customized by other - commands, the setup script, the command-line, and config files, and finalized in - :meth:`finalize_options`. All terminal output and filesystem interaction should - be done by :meth:`run`. - -*sub_commands* formalizes the notion of a "family" of commands, eg. ``install`` -as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The -parent of a family of commands defines *sub_commands* as a class attribute; it's -a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string -and *predicate* a function, a string or None. *predicate* is a method of -the parent command that determines whether the corresponding command is -applicable in the current situation. (Eg. we ``install_headers`` is only -applicable if we have any C header files to install.) If *predicate* is None, -that command is always applicable. - -*sub_commands* is usually defined at the \*end\* of a class, because predicates -can be methods of the class, so they must already have been defined. The -canonical example is the :command:`install` command. diff --git a/builtdist.rst b/builtdist.rst index 4f086c64fb..1cd5891457 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -176,7 +176,7 @@ easily specify multiple formats in one run. If you need to do both, you can explicitly specify multiple :command:`bdist_\*` commands and their options:: python setup.py bdist_rpm --packager="John Doe " \ - bdist_wininst --target_version="2.0" + bdist_wininst --target-version="2.0" Creating RPM packages is driven by a :file:`.spec` file, much as using the Distutils is driven by the setup script. To make your life easier, the diff --git a/extending.rst b/extending.rst index 972ff02c03..5a70d031cc 100644 --- a/extending.rst +++ b/extending.rst @@ -15,8 +15,8 @@ want to modify existing commands; many simply add a few file extensions that should be copied into packages in addition to :file:`.py` files as a convenience. -Most distutils command implementations are subclasses of the :class:`Command` -class from :mod:`distutils.cmd`. New commands may directly inherit from +Most distutils command implementations are subclasses of the +:class:`distutils.cmd.Command` class. New commands may directly inherit from :class:`Command`, while replacements often derive from :class:`Command` indirectly, directly subclassing the command they are replacing. Commands are required to derive from :class:`Command`. From b20a0d1597990f57ebaa42b1381b4a6da6230873 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 6 Oct 2010 08:43:56 +0000 Subject: [PATCH 172/330] Merged revisions 84142 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ........ r84142 | georg.brandl | 2010-08-17 17:07:14 +0200 (Di, 17 Aug 2010) | 1 line Consistency check for versionadded/changed directives. ........ --- sourcedist.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 0c29c19f70..2dea83d06c 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -206,6 +206,6 @@ distribution:: :option:`-o` is a shortcut for :option:`--manifest-only`. .. versionchanged:: 3.1 - An existing generated :file:`MANIFEST` will be regenerated without - :command:`sdist` comparing its modification time to the one of - :file:`MANIFEST.in` or :file:`setup.py`. + An existing generated :file:`MANIFEST` will be regenerated without + :command:`sdist` comparing its modification time to the one of + :file:`MANIFEST.in` or :file:`setup.py`. From 5e92a9a68c539904db1d114cec6430253bf31da0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 6 Oct 2010 08:56:53 +0000 Subject: [PATCH 173/330] Merged revisions 84945 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ........ r84945 | georg.brandl | 2010-09-21 16:48:28 +0200 (Di, 21 Sep 2010) | 1 line #9911: doc copyedits. ........ --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index 1cd5891457..2a91ee32ff 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -357,7 +357,7 @@ would create a 64bit installation executable on your 32bit version of Windows. To cross-compile, you must download the Python source code and cross-compile Python itself for the platform you are targetting - it is not possible from a -binary installtion of Python (as the .lib etc file for other platforms are +binary installation of Python (as the .lib etc file for other platforms are not included.) In practice, this means the user of a 32 bit operating system will need to use Visual Studio 2008 to open the :file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the From a08d7b106d9d5c8b213a4b32bcd233f93c85a43e Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 6 Oct 2010 09:32:48 +0000 Subject: [PATCH 174/330] Merged revisions 84945 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k ........ r84945 | georg.brandl | 2010-09-21 16:48:28 +0200 (Di, 21 Sep 2010) | 1 line #9911: doc copyedits. ........ --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index 1886d85053..8c83d11c62 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -358,7 +358,7 @@ would create a 64bit installation executable on your 32bit version of Windows. To cross-compile, you must download the Python source code and cross-compile Python itself for the platform you are targetting - it is not possible from a -binary installtion of Python (as the .lib etc file for other platforms are +binary installation of Python (as the .lib etc file for other platforms are not included.) In practice, this means the user of a 32 bit operating system will need to use Visual Studio 2008 to open the :file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the From e0da8b0a4fc4fd3ae3ff7fbefa7a6087284c0559 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 6 Oct 2010 10:11:56 +0000 Subject: [PATCH 175/330] Migrate to Sphinx 1.0 C language constructs. --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index d646328a63..8c4fe82bb9 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -427,7 +427,7 @@ built-in functions in the installation script. Which folders are available depends on the exact Windows version, and probably also the configuration. For details refer to Microsoft's documentation of the - :cfunc:`SHGetSpecialFolderPath` function. + :c:func:`SHGetSpecialFolderPath` function. .. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) From 8e2e84dea705d567e43193a73eff8cc2f96bee82 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 6 Oct 2010 10:26:05 +0000 Subject: [PATCH 176/330] Fix errors found by "make suspicious". --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 26d04d1fd4..8a68417433 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1845,7 +1845,7 @@ This module supplies the abstract base class :class:`Command`. to your setup.py, and later:: - cmdclass = {'build_py':build_py} + cmdclass = {'build_py': build_py} to the invocation of setup(). From d3f2167b48e384322419a8eacd39e73f64d9aeac Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 6 Oct 2010 10:38:58 +0000 Subject: [PATCH 177/330] Merged revisions 85274 via svnmerge from svn+ssh://svn.python.org/python/branches/py3k ........ r85274 | georg.brandl | 2010-10-06 12:26:05 +0200 (Mi, 06 Okt 2010) | 1 line Fix errors found by "make suspicious". ........ --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 2401da3f6c..f76f72b8f2 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1910,7 +1910,7 @@ Subclasses of :class:`Command` must define the following methods. to your setup.py, and later:: - cmdclass = {'build_py':build_py} + cmdclass = {'build_py': build_py} to the invocation of setup(). From af05960a2b8f8f0c3b6248430e21c4bee86c1467 Mon Sep 17 00:00:00 2001 From: Senthil Kumaran Date: Fri, 15 Oct 2010 13:29:33 +0000 Subject: [PATCH 178/330] Fix sphinx role markups. --- examples.rst | 10 +++++----- uploading.rst | 11 ++++++----- 2 files changed, 11 insertions(+), 10 deletions(-) diff --git a/examples.rst b/examples.rst index 648063b217..e31ff72917 100644 --- a/examples.rst +++ b/examples.rst @@ -257,10 +257,9 @@ Running the ``check`` command will display some warnings:: (maintainer and maintainer_email) must be supplied -If you use the reStructuredText syntax in the `long_description` field and -`docutils `_ is installed you can check if -the syntax is fine with the ``check`` command, using the `restructuredtext` -option. +If you use the reStructuredText syntax in the ``long_description`` field and +`docutils`_ is installed you can check if the syntax is fine with the +``check`` command, using the ``restructuredtext`` option. For example, if the :file:`setup.py` script is changed like this:: @@ -278,7 +277,7 @@ For example, if the :file:`setup.py` script is changed like this:: url='http://example.com', long_description=desc) Where the long description is broken, ``check`` will be able to detect it -by using the `docutils` parser:: +by using the :mod:`docutils` parser:: $ pythontrunk setup.py check --restructuredtext running check @@ -291,3 +290,4 @@ by using the `docutils` parser:: .. % \section{Putting it all together} +.. _docutils: http://docutils.sourceforge.net diff --git a/uploading.rst b/uploading.rst index e9472453d3..68c1e52d56 100644 --- a/uploading.rst +++ b/uploading.rst @@ -60,13 +60,14 @@ in the package:: setup(name='Distutils', long_description=open('README.txt')) -In that case, `README.txt` is a regular reStructuredText text file located -in the root of the package besides `setup.py`. +In that case, :file:`README.txt` is a regular reStructuredText text file located +in the root of the package besides :file:`setup.py`. To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the `docutils` package -and check the ``long_description`` from the command line:: +:program:`rst2html` program that is provided by the :mod:`docutils` package and +check the ``long_description`` from the command line:: $ python setup.py --long-description | rst2html.py > output.html -`docutils` will display a warning if there's something wrong with your syntax. +:mod:`docutils` will display a warning if there's something wrong with your +syntax. From 5f1300db97a5430ff15633740af65d93129f4f69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 15 Dec 2010 20:26:30 +0000 Subject: [PATCH 179/330] Fix wrong name in docstring and doc (#10693). Original patch by Eli Bendersky. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 8a68417433..a7dc68e3a9 100644 --- a/apiref.rst +++ b/apiref.rst @@ -888,7 +888,7 @@ tarballs or zipfiles. .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) Create a zip file from all files in and under *base_dir*. The output zip file - will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python + will be named *base_name* + :file:`.zip`. Uses either the :mod:`zipfile` Python module (if available) or the InfoZIP :file:`zip` utility (if installed and found on the default search path). If neither tool is available, raises :exc:`DistutilsExecError`. Returns the name of the output zip file. From 4c1ab89bc4dca4a312f679b7a4cd6ac86b3fa605 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 15 Dec 2010 20:30:51 +0000 Subject: [PATCH 180/330] Merged revisions 87277 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r87277 | eric.araujo | 2010-12-15 21:26:30 +0100 (mer., 15 déc. 2010) | 2 lines Fix wrong name in docstring and doc (#10693). Original patch by Eli Bendersky. ........ --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index f76f72b8f2..81de1ad1ea 100644 --- a/apiref.rst +++ b/apiref.rst @@ -888,7 +888,7 @@ tarballs or zipfiles. .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) Create a zip file from all files in and under *base_dir*. The output zip file - will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python + will be named *base_name* + :file:`.zip`. Uses either the :mod:`zipfile` Python module (if available) or the InfoZIP :file:`zip` utility (if installed and found on the default search path). If neither tool is available, raises :exc:`DistutilsExecError`. Returns the name of the output zip file. From 42a2856eeb15746ac51abac828d764a1d19b0a93 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 15 Dec 2010 20:33:50 +0000 Subject: [PATCH 181/330] Merged revisions 87277 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r87277 | eric.araujo | 2010-12-15 21:26:30 +0100 (mer., 15 déc. 2010) | 2 lines Fix wrong name in docstring and doc (#10693). Original patch by Eli Benderski. ........ --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index ae34565b8b..b28a3afdc9 100644 --- a/apiref.rst +++ b/apiref.rst @@ -888,7 +888,7 @@ tarballs or zipfiles. .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) Create a zip file from all files in and under *base_dir*. The output zip file - will be named *base_dir* + :file:`.zip`. Uses either the :mod:`zipfile` Python + will be named *base_name* + :file:`.zip`. Uses either the :mod:`zipfile` Python module (if available) or the InfoZIP :file:`zip` utility (if installed and found on the default search path). If neither tool is available, raises :exc:`DistutilsExecError`. Returns the name of the output zip file. From 6e1e6d6ccf758863a59ae27a4fa2a0e9efbe2a5d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 25 Feb 2011 21:40:34 +0000 Subject: [PATCH 182/330] Add missing read() in distutils doc. --- uploading.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/uploading.rst b/uploading.rst index 68c1e52d56..1b3cb589ec 100644 --- a/uploading.rst +++ b/uploading.rst @@ -57,8 +57,11 @@ in the package:: from distutils.core import setup + with open('README.txt') as file: + long_description = file.read() + setup(name='Distutils', - long_description=open('README.txt')) + long_description=long_description) In that case, :file:`README.txt` is a regular reStructuredText text file located in the root of the package besides :file:`setup.py`. From 66006595be9a42b97f5ff651dd887b924e47ab3c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 25 Feb 2011 21:45:06 +0000 Subject: [PATCH 183/330] Merged revisions 88613 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r88613 | eric.araujo | 2011-02-25 22:40:34 +0100 (ven., 25 févr. 2011) | 2 lines Add missing read() in distutils doc. ........ --- uploading.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/uploading.rst b/uploading.rst index 68c1e52d56..1b3cb589ec 100644 --- a/uploading.rst +++ b/uploading.rst @@ -57,8 +57,11 @@ in the package:: from distutils.core import setup + with open('README.txt') as file: + long_description = file.read() + setup(name='Distutils', - long_description=open('README.txt')) + long_description=long_description) In that case, :file:`README.txt` is a regular reStructuredText text file located in the root of the package besides :file:`setup.py`. From f56d8ab822529f4652e09e68c47e9c3267756e42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 25 Feb 2011 21:46:00 +0000 Subject: [PATCH 184/330] Merged revisions 88613 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r88613 | eric.araujo | 2011-02-25 22:40:34 +0100 (ven., 25 févr. 2011) | 2 lines Add missing read() in distutils doc. ........ --- uploading.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/uploading.rst b/uploading.rst index 7b790b1e02..fd0c50873c 100644 --- a/uploading.rst +++ b/uploading.rst @@ -57,8 +57,11 @@ in the package:: from distutils.core import setup + with open('README.txt') as file: + long_description = file.read() + setup(name='Distutils', - long_description=open('README.txt')) + long_description=long_description) In that case, :file:`README.txt` is a regular reStructuredText text file located in the root of the package besides :file:`setup.py`. From a0b2d678468aa9f37cd340617125eeb9939a6045 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 25 Feb 2011 21:47:55 +0000 Subject: [PATCH 185/330] Merged revisions 88613 via svnmerge from svn+ssh://pythondev@svn.python.org/python/branches/py3k MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit ........ r88613 | eric.araujo | 2011-02-25 22:40:34 +0100 (ven., 25 févr. 2011) | 2 lines Add missing read() in distutils doc. ........ --- uploading.rst | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/uploading.rst b/uploading.rst index 1da85362cf..936402b5ba 100644 --- a/uploading.rst +++ b/uploading.rst @@ -59,8 +59,11 @@ in the package:: from distutils.core import setup + with open('README.txt') as file: + long_description = file.read() + setup(name='Distutils', - long_description=open('README.txt')) + long_description=long_description) In that case, :file:`README.txt` is a regular reStructuredText text file located in the root of the package besides :file:`setup.py`. From 710e7b13221573af9680d5a630619cd97c5bacc9 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Fri, 15 Apr 2011 18:05:09 +0300 Subject: [PATCH 186/330] #11843: remove duplicate line from table in distutil doc. --- builtdist.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 2a91ee32ff..2697ba04cb 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -88,8 +88,6 @@ The available formats for built distributions are: +-------------+------------------------------+---------+ | ``sdux`` | HP-UX :program:`swinstall` | | +-------------+------------------------------+---------+ -| ``rpm`` | RPM | \(5) | -+-------------+------------------------------+---------+ | ``wininst`` | self-extracting ZIP file for | \(4) | | | Windows | | +-------------+------------------------------+---------+ From 7efd31fdf3c158603aec6f00ecee09a6a315754e Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Fri, 15 Apr 2011 18:05:09 +0300 Subject: [PATCH 187/330] #11843: remove duplicate line from table in distutil doc. --- builtdist.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 8c83d11c62..b4f2f1a1e1 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -88,8 +88,6 @@ The available formats for built distributions are: +-------------+------------------------------+---------+ | ``sdux`` | HP-UX :program:`swinstall` | | +-------------+------------------------------+---------+ -| ``rpm`` | RPM | \(5) | -+-------------+------------------------------+---------+ | ``wininst`` | self-extracting ZIP file for | \(4) | | | Windows | | +-------------+------------------------------+---------+ From 2a6a811381d7fb04fc577856ea8bf16b1f07f803 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 22 Apr 2011 21:27:10 +0200 Subject: [PATCH 188/330] Fix weird executable name --- examples.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples.rst b/examples.rst index 6c2773874c..e8d1ec9937 100644 --- a/examples.rst +++ b/examples.rst @@ -280,7 +280,7 @@ For example, if the :file:`setup.py` script is changed like this:: Where the long description is broken, ``check`` will be able to detect it by using the :mod:`docutils` parser:: - $ pythontrunk setup.py check --restructuredtext + $ python setup.py check --restructuredtext running check warning: check: Title underline too short. (line 2) warning: check: Could not finish the parsing. From 6d1b398e037490c74f1048dae3c402097e0fb0d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Martin=20v=2E=20L=C3=B6wis?= Date: Mon, 9 May 2011 08:05:43 +0200 Subject: [PATCH 189/330] Stop trying to use _xmlplus in the xml module. Closes #11164. Patch by Arfrever Frehtes Taifersar Arahesis. --- introduction.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/introduction.rst b/introduction.rst index b772b01004..8dc604d0d0 100644 --- a/introduction.rst +++ b/introduction.rst @@ -187,7 +187,7 @@ modules using the Distutils: module distribution a collection of Python modules distributed together as a single downloadable resource and meant to be installed *en masse*. Examples of some well-known - module distributions are Numeric Python, PyXML, PIL (the Python Imaging + module distributions are NumPy, SciPy, PIL (the Python Imaging Library), or mxBase. (This would be called a *package*, except that term is already taken in the Python context: a single module distribution may contain zero, one, or many Python packages.) From f56f36671f1d2046dd91d9c6a904a8c3f4c9c460 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 29 May 2011 00:11:59 +0200 Subject: [PATCH 190/330] Backport doc improvements for distutils.cmd.Command (#9223). Original commit by Georg Brandl. --- apiref.rst | 156 +++++++++++++++++++++++++++-------------------------- 1 file changed, 80 insertions(+), 76 deletions(-) diff --git a/apiref.rst b/apiref.rst index b28a3afdc9..275d3e61b8 100644 --- a/apiref.rst +++ b/apiref.rst @@ -147,11 +147,11 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and In addition, the :mod:`distutils.core` module exposed a number of classes that live elsewhere. -* :class:`Extension` from :mod:`distutils.extension` +* :class:`~distutils.extension.Extension` from :mod:`distutils.extension` -* :class:`Command` from :mod:`distutils.cmd` +* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd` -* :class:`Distribution` from :mod:`distutils.dist` +* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist` A short description of each of these follows, but see the relevant module for the full reference. @@ -1679,8 +1679,8 @@ lines, and joining lines with backslashes. =================================================================== .. module:: distutils.cmd - :synopsis: This module provides the abstract base class Command. This class is subclassed - by the modules in the distutils.command subpackage. + :synopsis: This module provides the abstract base class Command. This class + is subclassed by the modules in the distutils.command subpackage. This module supplies the abstract base class :class:`Command`. @@ -1690,20 +1690,84 @@ This module supplies the abstract base class :class:`Command`. Abstract base class for defining command classes, the "worker bees" of the Distutils. A useful analogy for command classes is to think of them as - subroutines with local variables called *options*. The options are declared in - :meth:`initialize_options` and defined (given their final values) in - :meth:`finalize_options`, both of which must be defined by every command class. - The distinction between the two is necessary because option values might come - from the outside world (command line, config file, ...), and any options - dependent on other options must be computed after these outside influences have - been processed --- hence :meth:`finalize_options`. The body of the subroutine, - where it does all its work based on the values of its options, is the - :meth:`run` method, which must also be implemented by every command class. - - The class constructor takes a single argument *dist*, a :class:`Distribution` + subroutines with local variables called *options*. The options are declared + in :meth:`initialize_options` and defined (given their final values) in + :meth:`finalize_options`, both of which must be defined by every command + class. The distinction between the two is necessary because option values + might come from the outside world (command line, config file, ...), and any + options dependent on other options must be computed after these outside + influences have been processed --- hence :meth:`finalize_options`. The body + of the subroutine, where it does all its work based on the values of its + options, is the :meth:`run` method, which must also be implemented by every + command class. + + The class constructor takes a single argument *dist*, a :class:`Distribution` instance. +Creating a new Distutils command +================================ + +This section outlines the steps to create a new Distutils command. + +A new command lives in a module in the :mod:`distutils.command` package. There +is a sample template in that directory called :file:`command_template`. Copy +this file to a new module with the same name as the new command you're +implementing. This module should implement a class with the same name as the +module (and the command). So, for instance, to create the command +``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy +:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit +it so that it's implementing the class :class:`peel_banana`, a subclass of +:class:`distutils.cmd.Command`. + +Subclasses of :class:`Command` must define the following methods. + +.. method:: Command.initialize_options() + + Set default values for all the options that this command supports. Note that + these defaults may be overridden by other commands, by the setup script, by + config files, or by the command-line. Thus, this is not the place to code + dependencies between options; generally, :meth:`initialize_options` + implementations are just a bunch of ``self.foo = None`` assignments. + + +.. method:: Command.finalize_options() + + Set final values for all the options that this command supports. This is + always called as late as possible, ie. after any option assignments from the + command-line or from other commands have been done. Thus, this is the place + to to code option dependencies: if *foo* depends on *bar*, then it is safe to + set *foo* from *bar* as long as *foo* still has the same value it was + assigned in :meth:`initialize_options`. + + +.. method:: Command.run() + + A command's raison d'etre: carry out the action it exists to perform, controlled + by the options initialized in :meth:`initialize_options`, customized by other + commands, the setup script, the command-line, and config files, and finalized in + :meth:`finalize_options`. All terminal output and filesystem interaction should + be done by :meth:`run`. + + +.. attribute:: Command.sub_commands + + *sub_commands* formalizes the notion of a "family" of commands, + e.g. ``install`` as the parent with sub-commands ``install_lib``, + ``install_headers``, etc. The parent of a family of commands defines + *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name, + predicate)``, with *command_name* a string and *predicate* a function, a + string or ``None``. *predicate* is a method of the parent command that + determines whether the corresponding command is applicable in the current + situation. (E.g. ``install_headers`` is only applicable if we have any C + header files to install.) If *predicate* is ``None``, that command is always + applicable. + + *sub_commands* is usually defined at the *end* of a class, because + predicates can be methods of the class, so they must already have been + defined. The canonical example is the :command:`install` command. + + :mod:`distutils.command` --- Individual Distutils commands ========================================================== @@ -1924,63 +1988,3 @@ The ``register`` command registers the package with the Python Package Index. This is described in more detail in :pep:`301`. .. % todo - - -Creating a new Distutils command -================================ - -This section outlines the steps to create a new Distutils command. - -A new command lives in a module in the :mod:`distutils.command` package. There -is a sample template in that directory called :file:`command_template`. Copy -this file to a new module with the same name as the new command you're -implementing. This module should implement a class with the same name as the -module (and the command). So, for instance, to create the command -``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy -:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit -it so that it's implementing the class :class:`peel_banana`, a subclass of -:class:`distutils.cmd.Command`. - -Subclasses of :class:`Command` must define the following methods. - - -.. method:: Command.initialize_options() - - Set default values for all the options that this command supports. Note that - these defaults may be overridden by other commands, by the setup script, by - config files, or by the command-line. Thus, this is not the place to code - dependencies between options; generally, :meth:`initialize_options` - implementations are just a bunch of ``self.foo = None`` assignments. - - -.. method:: Command.finalize_options() - - Set final values for all the options that this command supports. This is - always called as late as possible, ie. after any option assignments from the - command-line or from other commands have been done. Thus, this is the place - to to code option dependencies: if *foo* depends on *bar*, then it is safe to - set *foo* from *bar* as long as *foo* still has the same value it was - assigned in :meth:`initialize_options`. - - -.. method:: Command.run() - - A command's raison d'etre: carry out the action it exists to perform, controlled - by the options initialized in :meth:`initialize_options`, customized by other - commands, the setup script, the command-line, and config files, and finalized in - :meth:`finalize_options`. All terminal output and filesystem interaction should - be done by :meth:`run`. - -*sub_commands* formalizes the notion of a "family" of commands, eg. ``install`` -as the parent with sub-commands ``install_lib``, ``install_headers``, etc. The -parent of a family of commands defines *sub_commands* as a class attribute; it's -a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string -and *predicate* an unbound method, a string or None. *predicate* is a method of -the parent command that determines whether the corresponding command is -applicable in the current situation. (Eg. we ``install_headers`` is only -applicable if we have any C header files to install.) If *predicate* is None, -that command is always applicable. - -*sub_commands* is usually defined at the \*end\* of a class, because predicates -can be unbound methods, so they must already have been defined. The canonical -example is the :command:`install` command. From 3f3344d9f1e06162bbcf379129d7e4663482853c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 29 May 2011 00:14:45 +0200 Subject: [PATCH 191/330] Minor touch-ups in distutils.cmd.Command doc --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 81de1ad1ea..74446bcd67 100644 --- a/apiref.rst +++ b/apiref.rst @@ -21,7 +21,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and .. function:: setup(arguments) The basic do-everything function that does most everything you could ever ask - for from a Distutils method. See XXXXX + for from a Distutils method. The setup function takes a large number of arguments. These are laid out in the following table. @@ -1759,7 +1759,7 @@ Subclasses of :class:`Command` must define the following methods. predicate)``, with *command_name* a string and *predicate* a function, a string or ``None``. *predicate* is a method of the parent command that determines whether the corresponding command is applicable in the current - situation. (E.g. we ``install_headers`` is only applicable if we have any C + situation. (E.g. ``install_headers`` is only applicable if we have any C header files to install.) If *predicate* is ``None``, that command is always applicable. From d1e86e1fa4db473f5fb29f5d360a3695a6a78599 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 29 May 2011 00:22:06 +0200 Subject: [PATCH 192/330] Re-add missing doc stub for the distutils check command --- apiref.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/apiref.rst b/apiref.rst index 74446bcd67..712fffbe33 100644 --- a/apiref.rst +++ b/apiref.rst @@ -2006,3 +2006,17 @@ The ``register`` command registers the package with the Python Package Index. This is described in more detail in :pep:`301`. .. % todo + + +:mod:`distutils.command.check` --- Check the meta-data of a package +=================================================================== + +.. module:: distutils.command.check + :synopsis: Check the metadata of a package + + +The ``check`` command performs some tests on the meta-data of a package. +For example, it verifies that all required meta-data are provided as +the arguments passed to the :func:`setup` function. + +.. % todo From 46fe9bda5094ec5a73958972ec8392e8566bc92d Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 29 May 2011 00:31:30 +0200 Subject: [PATCH 193/330] Re-add missing doc stub for the distutils check command --- apiref.rst | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/apiref.rst b/apiref.rst index 275d3e61b8..3990c0756d 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1988,3 +1988,17 @@ The ``register`` command registers the package with the Python Package Index. This is described in more detail in :pep:`301`. .. % todo + + +:mod:`distutils.command.check` --- Check the meta-data of a package +=================================================================== + +.. module:: distutils.command.check + :synopsis: Check the metadata of a package + + +The ``check`` command performs some tests on the meta-data of a package. +For example, it verifies that all required meta-data are provided as +the arguments passed to the :func:`setup` function. + +.. % todo From bc1e827b5711a9f44dc6a141a5aecc3b9486c02e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 29 May 2011 18:05:53 +0200 Subject: [PATCH 194/330] Branch merge --- apiref.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/apiref.rst b/apiref.rst index 59f7b85209..dc5bcf2ba0 100644 --- a/apiref.rst +++ b/apiref.rst @@ -2006,6 +2006,7 @@ This is described in more detail in :pep:`301`. .. % todo + :mod:`distutils.command.check` --- Check the meta-data of a package =================================================================== From 1147a55d6fd361bf31472a3f1f2a391e2ae6ac2a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Tue, 31 May 2011 21:50:22 +0200 Subject: [PATCH 195/330] Fix markup: arguments in a class directive are __init__ arguments, not base classes --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 3990c0756d..28af893648 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1815,7 +1815,7 @@ Subclasses of :class:`Command` must define the following methods. .. module:: distutils.command.bdist_msi :synopsis: Build a binary distribution as a Windows MSI file -.. class:: bdist_msi(Command) +.. class:: bdist_msi Builds a `Windows Installer`_ (.msi) binary package. From 4274c39b315c4b36b315278dd32a20017fef8186 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Tue, 31 May 2011 21:50:38 +0200 Subject: [PATCH 196/330] Fix markup: arguments in a class directive are __init__ arguments, not base classes --- apiref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index dc5bcf2ba0..1fb6f9e45f 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1814,7 +1814,7 @@ Subclasses of :class:`Command` must define the following methods. .. module:: distutils.command.bdist_msi :synopsis: Build a binary distribution as a Windows MSI file -.. class:: bdist_msi(Command) +.. class:: bdist_msi Builds a `Windows Installer`_ (.msi) binary package. @@ -1893,9 +1893,9 @@ Subclasses of :class:`Command` must define the following methods. :synopsis: Build the .py/.pyc files of a package -.. class:: build_py(Command) +.. class:: build_py -.. class:: build_py_2to3(build_py) +.. class:: build_py_2to3 Alternative implementation of build_py which also runs the 2to3 conversion library on each .py file that is going to be From 0bd45cae63b8d60c78ac7847f7c8f93440e4c64a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 1 Jun 2011 20:42:49 +0200 Subject: [PATCH 197/330] Add documentation for the packaging module. This updates the user guide to refer to Packaging instead of Distutils. Some files still require an update. --- index.rst | 13 + install.rst | 1005 +++++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 1018 insertions(+) create mode 100644 install.rst diff --git a/index.rst b/index.rst index ace8280894..5fa25a6d58 100644 --- a/index.rst +++ b/index.rst @@ -29,3 +29,16 @@ very little overhead for build/release/install mechanics. extending.rst commandref.rst apiref.rst + +Another document describes how to install modules and extensions packaged +following the above guidelines: + +.. toctree:: + + install.rst + + +.. seealso:: + + :ref:`packaging-index` and :ref:`packaging-install-index` + Documentation of Packaging, the new version of Distutils. diff --git a/install.rst b/install.rst new file mode 100644 index 0000000000..31c1d7ff12 --- /dev/null +++ b/install.rst @@ -0,0 +1,1005 @@ +.. highlightlang:: none + +.. _install-index: + +***************************** + Installing Python Modules +***************************** + +:Author: Greg Ward +:Release: |version| +:Date: |today| + +.. TODO: Fill in XXX comments + +.. The audience for this document includes people who don't know anything + about Python and aren't about to learn the language just in order to + install and maintain it for their users, i.e. system administrators. + Thus, I have to be sure to explain the basics at some point: + sys.path and PYTHONPATH at least. Should probably give pointers to + other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. + + Finally, it might be useful to include all the material from my "Care + and Feeding of a Python Installation" talk in here somewhere. Yow! + +.. topic:: Abstract + + This document describes the Python Distribution Utilities ("Distutils") from the + end-user's point-of-view, describing how to extend the capabilities of a + standard Python installation by building and installing third-party Python + modules and extensions. + + +.. _inst-intro: + +Introduction +============ + +Although Python's extensive standard library covers many programming needs, +there often comes a time when you need to add some new functionality to your +Python installation in the form of third-party modules. This might be necessary +to support your own programming, or to support an application that you want to +use and that happens to be written in Python. + +In the past, there has been little support for adding third-party modules to an +existing Python installation. With the introduction of the Python Distribution +Utilities (Distutils for short) in Python 2.0, this changed. + +This document is aimed primarily at the people who need to install third-party +Python modules: end-users and system administrators who just need to get some +Python application running, and existing Python programmers who want to add some +new goodies to their toolbox. You don't need to know Python to read this +document; there will be some brief forays into using Python's interactive mode +to explore your installation, but that's it. If you're looking for information +on how to distribute your own Python modules so that others may use them, see +the :ref:`distutils-index` manual. + + +.. _inst-trivial-install: + +Best case: trivial installation +------------------------------- + +In the best case, someone will have prepared a special version of the module +distribution you want to install that is targeted specifically at your platform +and is installed just like any other software on your platform. For example, +the module developer might make an executable installer available for Windows +users, an RPM package for users of RPM-based Linux systems (Red Hat, SuSE, +Mandrake, and many others), a Debian package for users of Debian-based Linux +systems, and so forth. + +In that case, you would download the installer appropriate to your platform and +do the obvious thing with it: run it if it's an executable installer, ``rpm +--install`` it if it's an RPM, etc. You don't need to run Python or a setup +script, you don't need to compile anything---you might not even need to read any +instructions (although it's always a good idea to do so anyways). + +Of course, things will not always be that easy. You might be interested in a +module distribution that doesn't have an easy-to-use installer for your +platform. In that case, you'll have to start with the source distribution +released by the module's author/maintainer. Installing from a source +distribution is not too hard, as long as the modules are packaged in the +standard way. The bulk of this document is about building and installing +modules from standard source distributions. + + +.. _inst-new-standard: + +The new standard: Distutils +--------------------------- + +If you download a module source distribution, you can tell pretty quickly if it +was packaged and distributed in the standard way, i.e. using the Distutils. +First, the distribution's name and version number will be featured prominently +in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or +:file:`widget-0.9.7.zip`. Next, the archive will unpack into a similarly-named +directory: :file:`foo-1.0` or :file:`widget-0.9.7`. Additionally, the +distribution will contain a setup script :file:`setup.py`, and a file named +:file:`README.txt` or possibly just :file:`README`, which should explain that +building and installing the module distribution is a simple matter of running :: + + python setup.py install + +If all these things are true, then you already know how to build and install the +modules you've just downloaded: Run the command above. Unless you need to +install things in a non-standard way or customize the build process, you don't +really need this manual. Or rather, the above command is everything you need to +get out of this manual. + + +.. _inst-standard-install: + +Standard Build and Install +========================== + +As described in section :ref:`inst-new-standard`, building and installing a module +distribution using the Distutils is usually one simple command:: + + python setup.py install + +On Unix, you'd run this command from a shell prompt; on Windows, you have to +open a command prompt window ("DOS box") and do it there; on Mac OS X, you open +a :command:`Terminal` window to get a shell prompt. + + +.. _inst-platform-variations: + +Platform variations +------------------- + +You should always run the setup command from the distribution root directory, +i.e. the top-level subdirectory that the module source distribution unpacks +into. For example, if you've just downloaded a module source distribution +:file:`foo-1.0.tar.gz` onto a Unix system, the normal thing to do is:: + + gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0 + cd foo-1.0 + python setup.py install + +On Windows, you'd probably download :file:`foo-1.0.zip`. If you downloaded the +archive file to :file:`C:\\Temp`, then it would unpack into +:file:`C:\\Temp\\foo-1.0`; you can use either a archive manipulator with a +graphical user interface (such as WinZip) or a command-line tool (such as +:program:`unzip` or :program:`pkunzip`) to unpack the archive. Then, open a +command prompt window ("DOS box"), and run:: + + cd c:\Temp\foo-1.0 + python setup.py install + + +.. _inst-splitting-up: + +Splitting the job up +-------------------- + +Running ``setup.py install`` builds and installs all modules in one run. If you +prefer to work incrementally---especially useful if you want to customize the +build process, or if things are going wrong---you can use the setup script to do +one thing at a time. This is particularly helpful when the build and install +will be done by different users---for example, you might want to build a module +distribution and hand it off to a system administrator for installation (or do +it yourself, with super-user privileges). + +For example, you can build everything in one step, and then install everything +in a second step, by invoking the setup script twice:: + + python setup.py build + python setup.py install + +If you do this, you will notice that running the :command:`install` command +first runs the :command:`build` command, which---in this case---quickly notices +that it has nothing to do, since everything in the :file:`build` directory is +up-to-date. + +You may not need this ability to break things down often if all you do is +install modules downloaded off the 'net, but it's very handy for more advanced +tasks. If you get into distributing your own Python modules and extensions, +you'll run lots of individual Distutils commands on their own. + + +.. _inst-how-build-works: + +How building works +------------------ + +As implied above, the :command:`build` command is responsible for putting the +files to install into a *build directory*. By default, this is :file:`build` +under the distribution root; if you're excessively concerned with speed, or want +to keep the source tree pristine, you can change the build directory with the +:option:`--build-base` option. For example:: + + python setup.py build --build-base=/tmp/pybuild/foo-1.0 + +(Or you could do this permanently with a directive in your system or personal +Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this +isn't necessary. + +The default layout for the build tree is as follows:: + + --- build/ --- lib/ + or + --- build/ --- lib./ + temp./ + +where ```` expands to a brief description of the current OS/hardware +platform and Python version. The first form, with just a :file:`lib` directory, +is used for "pure module distributions"---that is, module distributions that +include only pure Python modules. If a module distribution contains any +extensions (modules written in C/C++), then the second form, with two ```` +directories, is used. In that case, the :file:`temp.{plat}` directory holds +temporary files generated by the compile/link process that don't actually get +installed. In either case, the :file:`lib` (or :file:`lib.{plat}`) directory +contains all Python modules (pure Python and extensions) that will be installed. + +In the future, more directories will be added to handle Python scripts, +documentation, binary executables, and whatever else is needed to handle the job +of installing Python modules and applications. + + +.. _inst-how-install-works: + +How installation works +---------------------- + +After the :command:`build` command runs (whether you run it explicitly, or the +:command:`install` command does it for you), the work of the :command:`install` +command is relatively simple: all it has to do is copy everything under +:file:`build/lib` (or :file:`build/lib.{plat}`) to your chosen installation +directory. + +If you don't choose an installation directory---i.e., if you just run ``setup.py +install``\ ---then the :command:`install` command installs to the standard +location for third-party Python modules. This location varies by platform and +by how you built/installed Python itself. On Unix (and Mac OS X, which is also +Unix-based), it also depends on whether the module distribution being installed +is pure Python or contains extensions ("non-pure"): + ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Platform | Standard installation location | Default value | Notes | ++=================+=====================================================+==================================================+=======+ +| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ +| Windows | :file:`{prefix}\\Lib\\site-packages` | :file:`C:\\Python{XY}\\Lib\\site-packages` | \(2) | ++-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ + +Notes: + +(1) + Most Linux distributions include Python as a standard part of the system, so + :file:`{prefix}` and :file:`{exec-prefix}` are usually both :file:`/usr` on + Linux. If you build Python yourself on Linux (or any Unix-like system), the + default :file:`{prefix}` and :file:`{exec-prefix}` are :file:`/usr/local`. + +(2) + The default installation directory on Windows was :file:`C:\\Program + Files\\Python` under Python 1.6a1, 1.5.2, and earlier. + +:file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python +is installed to, and where it finds its libraries at run-time. They are always +the same under Windows, and very often the same under Unix and Mac OS X. You +can find out what your Python installation uses for :file:`{prefix}` and +:file:`{exec-prefix}` by running Python in interactive mode and typing a few +simple commands. Under Unix, just type ``python`` at the shell prompt. Under +Windows, choose :menuselection:`Start --> Programs --> Python X.Y --> +Python (command line)`. Once the interpreter is started, you type Python code +at the prompt. For example, on my Linux system, I type the three Python +statements shown below, and get the output as shown, to find out my +:file:`{prefix}` and :file:`{exec-prefix}`:: + + Python 2.4 (#26, Aug 7 2004, 17:19:02) + Type "help", "copyright", "credits" or "license" for more information. + >>> import sys + >>> sys.prefix + '/usr' + >>> sys.exec_prefix + '/usr' + +If you don't want to install modules to the standard location, or if you don't +have permission to write there, then you need to read about alternate +installations in section :ref:`inst-alt-install`. If you want to customize your +installation directories more heavily, see section :ref:`inst-custom-install` on +custom installations. + + +.. _inst-alt-install: + +Alternate Installation +====================== + +Often, it is necessary or desirable to install modules to a location other than +the standard location for third-party Python modules. For example, on a Unix +system you might not have permission to write to the standard third-party module +directory. Or you might wish to try out a module before making it a standard +part of your local Python installation. This is especially true when upgrading +a distribution already present: you want to make sure your existing base of +scripts still works with the new version before actually upgrading. + +The Distutils :command:`install` command is designed to make installing module +distributions to an alternate location simple and painless. The basic idea is +that you supply a base directory for the installation, and the +:command:`install` command picks a set of directories (called an *installation +scheme*) under this base directory in which to install files. The details +differ across platforms, so read whichever of the following sections applies to +you. + + +.. _inst-alt-install-prefix: + +Alternate installation: the home scheme +--------------------------------------- + +The idea behind the "home scheme" is that you build and maintain a personal +stash of Python modules. This scheme's name is derived from the idea of a +"home" directory on Unix, since it's not unusual for a Unix user to make their +home directory have a layout similar to :file:`/usr/` or :file:`/usr/local/`. +This scheme can be used by anyone, regardless of the operating system they +are installing for. + +Installing a new module distribution is as simple as :: + + python setup.py install --home= + +where you can supply any directory you like for the :option:`--home` option. On +Unix, lazy typists can just type a tilde (``~``); the :command:`install` command +will expand this to your home directory:: + + python setup.py install --home=~ + +The :option:`--home` option defines the installation base directory. Files are +installed to the following directories under the installation base as follows: + ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{home}/bin` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{home}/share` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ + + +.. _inst-alt-install-home: + +Alternate installation: Unix (the prefix scheme) +------------------------------------------------ + +The "prefix scheme" is useful when you wish to use one Python installation to +perform the build/install (i.e., to run the setup script), but install modules +into the third-party module directory of a different Python installation (or +something that looks like a different Python installation). If this sounds a +trifle unusual, it is---that's why the "home scheme" comes first. However, +there are at least two known cases where the prefix scheme will be useful. + +First, consider that many Linux distributions put Python in :file:`/usr`, rather +than the more traditional :file:`/usr/local`. This is entirely appropriate, +since in those cases Python is part of "the system" rather than a local add-on. +However, if you are installing Python modules from source, you probably want +them to go in :file:`/usr/local/lib/python2.{X}` rather than +:file:`/usr/lib/python2.{X}`. This can be done with :: + + /usr/bin/python setup.py install --prefix=/usr/local + +Another possibility is a network filesystem where the name used to write to a +remote directory is different from the name used to read it: for example, the +Python interpreter accessed as :file:`/usr/local/bin/python` might search for +modules in :file:`/usr/local/lib/python2.{X}`, but those modules would have to +be installed to, say, :file:`/mnt/{@server}/export/lib/python2.{X}`. This could +be done with :: + + /usr/local/bin/python setup.py install --prefix=/mnt/@server/export + +In either case, the :option:`--prefix` option defines the installation base, and +the :option:`--exec-prefix` option defines the platform-specific installation +base, which is used for platform-specific files. (Currently, this just means +non-pure module distributions, but could be expanded to C libraries, binary +executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to +:option:`--prefix`. Files are installed as follows: + ++------------------------------+-----------------------------------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+=====================================================+=============================+ +| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | ++------------------------------+-----------------------------------------------------+-----------------------------+ +| data | :file:`{prefix}/share` | :option:`--install-data` | ++------------------------------+-----------------------------------------------------+-----------------------------+ + +There is no requirement that :option:`--prefix` or :option:`--exec-prefix` +actually point to an alternate Python installation; if the directories listed +above do not already exist, they are created at installation time. + +Incidentally, the real reason the prefix scheme is important is simply that a +standard Unix installation uses the prefix scheme, but with :option:`--prefix` +and :option:`--exec-prefix` supplied by Python itself as ``sys.prefix`` and +``sys.exec_prefix``. Thus, you might think you'll never use the prefix scheme, +but every time you run ``python setup.py install`` without any other options, +you're using it. + +Note that installing extensions to an alternate Python installation has no +effect on how those extensions are built: in particular, the Python header files +(:file:`Python.h` and friends) installed with the Python interpreter used to run +the setup script will be used in compiling extensions. It is your +responsibility to ensure that the interpreter used to run extensions installed +in this way is compatible with the interpreter used to build them. The best way +to do this is to ensure that the two interpreters are the same version of Python +(possibly different builds, or possibly copies of the same build). (Of course, +if your :option:`--prefix` and :option:`--exec-prefix` don't even point to an +alternate Python installation, this is immaterial.) + + +.. _inst-alt-install-windows: + +Alternate installation: Windows (the prefix scheme) +--------------------------------------------------- + +Windows has no concept of a user's home directory, and since the standard Python +installation under Windows is simpler than under Unix, the :option:`--prefix` +option has traditionally been used to install additional packages in separate +locations on Windows. :: + + python setup.py install --prefix="\Temp\Python" + +to install modules to the :file:`\\Temp\\Python` directory on the current drive. + +The installation base is defined by the :option:`--prefix` option; the +:option:`--exec-prefix` option is not supported under Windows. Files are +installed as follows: + ++------------------------------+---------------------------+-----------------------------+ +| Type of file | Installation Directory | Override option | ++==============================+===========================+=============================+ +| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | ++------------------------------+---------------------------+-----------------------------+ +| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | ++------------------------------+---------------------------+-----------------------------+ +| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | ++------------------------------+---------------------------+-----------------------------+ +| data | :file:`{prefix}\\Data` | :option:`--install-data` | ++------------------------------+---------------------------+-----------------------------+ + + +.. _inst-custom-install: + +Custom Installation +=================== + +Sometimes, the alternate installation schemes described in section +:ref:`inst-alt-install` just don't do what you want. You might want to tweak just +one or two directories while keeping everything under the same base directory, +or you might want to completely redefine the installation scheme. In either +case, you're creating a *custom installation scheme*. + +You probably noticed the column of "override options" in the tables describing +the alternate installation schemes above. Those options are how you define a +custom installation scheme. These override options can be relative, absolute, +or explicitly defined in terms of one of the installation base directories. +(There are two installation base directories, and they are normally the same--- +they only differ when you use the Unix "prefix scheme" and supply different +:option:`--prefix` and :option:`--exec-prefix` options.) + +For example, say you're installing a module distribution to your home directory +under Unix---but you want scripts to go in :file:`~/scripts` rather than +:file:`~/bin`. As you might expect, you can override this directory with the +:option:`--install-scripts` option; in this case, it makes most sense to supply +a relative path, which will be interpreted relative to the installation base +directory (your home directory, in this case):: + + python setup.py install --home=~ --install-scripts=scripts + +Another Unix example: suppose your Python installation was built and installed +with a prefix of :file:`/usr/local/python`, so under a standard installation +scripts will wind up in :file:`/usr/local/python/bin`. If you want them in +:file:`/usr/local/bin` instead, you would supply this absolute directory for the +:option:`--install-scripts` option:: + + python setup.py install --install-scripts=/usr/local/bin + +(This performs an installation using the "prefix scheme," where the prefix is +whatever your Python interpreter was installed with--- :file:`/usr/local/python` +in this case.) + +If you maintain Python on Windows, you might want third-party modules to live in +a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}` +itself. This is almost as easy as customizing the script installation directory +---you just have to remember that there are two types of modules to worry about, +pure modules and non-pure modules (i.e., modules from a non-pure distribution). +For example:: + + python setup.py install --install-purelib=Site --install-platlib=Site + +The specified installation directories are relative to :file:`{prefix}`. Of +course, you also have to ensure that these directories are in Python's module +search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See +section :ref:`inst-search-path` to find out how to modify Python's search path. + +If you want to define an entire installation scheme, you just have to supply all +of the installation directory options. The recommended way to do this is to +supply relative paths; for example, if you want to maintain all Python +module-related files under :file:`python` in your home directory, and you want a +separate directory for each platform that you use your home directory from, you +might define the following installation scheme:: + + python setup.py install --home=~ \ + --install-purelib=python/lib \ + --install-platlib=python/lib.$PLAT \ + --install-scripts=python/scripts + --install-data=python/data + +or, equivalently, :: + + python setup.py install --home=~/python \ + --install-purelib=lib \ + --install-platlib='lib.$PLAT' \ + --install-scripts=scripts + --install-data=data + +``$PLAT`` is not (necessarily) an environment variable---it will be expanded by +the Distutils as it parses your command line options, just as it does when +parsing your configuration file(s). + +Obviously, specifying the entire installation scheme every time you install a +new module distribution would be very tedious. Thus, you can put these options +into your Distutils config file (see section :ref:`inst-config-files`):: + + [install] + install-base=$HOME + install-purelib=python/lib + install-platlib=python/lib.$PLAT + install-scripts=python/scripts + install-data=python/data + +or, equivalently, :: + + [install] + install-base=$HOME/python + install-purelib=lib + install-platlib=lib.$PLAT + install-scripts=scripts + install-data=data + +Note that these two are *not* equivalent if you supply a different installation +base directory when you run the setup script. For example, :: + + python setup.py install --install-base=/tmp + +would install pure modules to :file:`{/tmp/python/lib}` in the first case, and +to :file:`{/tmp/lib}` in the second case. (For the second case, you probably +want to supply an installation base of :file:`/tmp/python`.) + +You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample +configuration file input. These are Distutils configuration variables, which +bear a strong resemblance to environment variables. In fact, you can use +environment variables in config files on platforms that have such a notion but +the Distutils additionally define a few extra variables that may not be in your +environment, such as ``$PLAT``. (And of course, on systems that don't have +environment variables, such as Mac OS 9, the configuration variables supplied by +the Distutils are the only ones you can use.) See section :ref:`inst-config-files` +for details. + +.. XXX need some Windows examples---when would custom installation schemes be + needed on those platforms? + + +.. XXX I'm not sure where this section should go. + +.. _inst-search-path: + +Modifying Python's Search Path +------------------------------ + +When the Python interpreter executes an :keyword:`import` statement, it searches +for both Python code and extension modules along a search path. A default value +for the path is configured into the Python binary when the interpreter is built. +You can determine the path by importing the :mod:`sys` module and printing the +value of ``sys.path``. :: + + $ python + Python 2.2 (#11, Oct 3 2002, 13:31:27) + [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2 + Type "help", "copyright", "credits" or "license" for more information. + >>> import sys + >>> sys.path + ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2', + '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload', + '/usr/local/lib/python2.3/site-packages'] + >>> + +The null string in ``sys.path`` represents the current working directory. + +The expected convention for locally installed packages is to put them in the +:file:`{...}/site-packages/` directory, but you may want to install Python +modules into some arbitrary directory. For example, your site may have a +convention of keeping all software related to the web server under :file:`/www`. +Add-on Python modules might then belong in :file:`/www/python`, and in order to +import them, this directory must be added to ``sys.path``. There are several +different ways to add the directory. + +The most convenient way is to add a path configuration file to a directory +that's already on Python's path, usually to the :file:`.../site-packages/` +directory. Path configuration files have an extension of :file:`.pth`, and each +line must contain a single path that will be appended to ``sys.path``. (Because +the new paths are appended to ``sys.path``, modules in the added directories +will not override standard modules. This means you can't use this mechanism for +installing fixed versions of standard modules.) + +Paths can be absolute or relative, in which case they're relative to the +directory containing the :file:`.pth` file. See the documentation of +the :mod:`site` module for more information. + +A slightly less convenient way is to edit the :file:`site.py` file in Python's +standard library, and modify ``sys.path``. :file:`site.py` is automatically +imported when the Python interpreter is executed, unless the :option:`-S` switch +is supplied to suppress this behaviour. So you could simply edit +:file:`site.py` and add two lines to it:: + + import sys + sys.path.append('/www/python/') + +However, if you reinstall the same major version of Python (perhaps when +upgrading from 2.2 to 2.2.2, for example) :file:`site.py` will be overwritten by +the stock version. You'd have to remember that it was modified and save a copy +before doing the installation. + +There are two environment variables that can modify ``sys.path``. +:envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python +installation. For example, if :envvar:`PYTHONHOME` is set to ``/www/python``, +the search path will be set to ``['', '/www/python/lib/pythonX.Y/', +'/www/python/lib/pythonX.Y/plat-linux2', ...]``. + +The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be +added to the beginning of ``sys.path``. For example, if :envvar:`PYTHONPATH` is +set to ``/www/python:/opt/py``, the search path will begin with +``['/www/python', '/opt/py']``. (Note that directories must exist in order to +be added to ``sys.path``; the :mod:`site` module removes paths that don't +exist.) + +Finally, ``sys.path`` is just a regular Python list, so any Python application +can modify it by adding or removing entries. + + +.. _inst-config-files: + +Distutils Configuration Files +============================= + +As mentioned above, you can use Distutils configuration files to record personal +or site preferences for any Distutils options. That is, any option to any +command can be stored in one of two or three (depending on your platform) +configuration files, which will be consulted before the command-line is parsed. +This means that configuration files will override default values, and the +command-line will in turn override configuration files. Furthermore, if +multiple configuration files apply, values from "earlier" files are overridden +by "later" files. + + +.. _inst-config-filenames: + +Location and names of config files +---------------------------------- + +The names and locations of the configuration files vary slightly across +platforms. On Unix and Mac OS X, the three configuration files (in the order +they are processed) are: + ++--------------+----------------------------------------------------------+-------+ +| Type of file | Location and filename | Notes | ++==============+==========================================================+=======+ +| system | :file:`{prefix}/lib/python{ver}/distutils/distutils.cfg` | \(1) | ++--------------+----------------------------------------------------------+-------+ +| personal | :file:`$HOME/.pydistutils.cfg` | \(2) | ++--------------+----------------------------------------------------------+-------+ +| local | :file:`setup.cfg` | \(3) | ++--------------+----------------------------------------------------------+-------+ + +And on Windows, the configuration files are: + ++--------------+-------------------------------------------------+-------+ +| Type of file | Location and filename | Notes | ++==============+=================================================+=======+ +| system | :file:`{prefix}\\Lib\\distutils\\distutils.cfg` | \(4) | ++--------------+-------------------------------------------------+-------+ +| personal | :file:`%HOME%\\pydistutils.cfg` | \(5) | ++--------------+-------------------------------------------------+-------+ +| local | :file:`setup.cfg` | \(3) | ++--------------+-------------------------------------------------+-------+ + +On all platforms, the "personal" file can be temporarily disabled by +passing the `--no-user-cfg` option. + +Notes: + +(1) + Strictly speaking, the system-wide configuration file lives in the directory + where the Distutils are installed; under Python 1.6 and later on Unix, this is + as shown. For Python 1.5.2, the Distutils will normally be installed to + :file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system + configuration file should be put there under Python 1.5.2. + +(2) + On Unix, if the :envvar:`HOME` environment variable is not defined, the user's + home directory will be determined with the :func:`getpwuid` function from the + standard :mod:`pwd` module. This is done by the :func:`os.path.expanduser` + function used by Distutils. + +(3) + I.e., in the current directory (usually the location of the setup script). + +(4) + (See also note (1).) Under Python 1.6 and later, Python's default "installation + prefix" is :file:`C:\\Python`, so the system configuration file is normally + :file:`C:\\Python\\Lib\\distutils\\distutils.cfg`. Under Python 1.5.2, the + default prefix was :file:`C:\\Program Files\\Python`, and the Distutils were not + part of the standard library---so the system configuration file would be + :file:`C:\\Program Files\\Python\\distutils\\distutils.cfg` in a standard Python + 1.5.2 installation under Windows. + +(5) + On Windows, if the :envvar:`HOME` environment variable is not defined, + :envvar:`USERPROFILE` then :envvar:`HOMEDRIVE` and :envvar:`HOMEPATH` will + be tried. This is done by the :func:`os.path.expanduser` function used + by Distutils. + + +.. _inst-config-syntax: + +Syntax of config files +---------------------- + +The Distutils configuration files all have the same syntax. The config files +are grouped into sections. There is one section for each Distutils command, +plus a ``global`` section for global options that affect every command. Each +section consists of one option per line, specified as ``option=value``. + +For example, the following is a complete config file that just forces all +commands to run quietly by default:: + + [global] + verbose=0 + +If this is installed as the system config file, it will affect all processing of +any Python module distribution by any user on the current system. If it is +installed as your personal config file (on systems that support them), it will +affect only module distributions processed by you. And if it is used as the +:file:`setup.cfg` for a particular module distribution, it affects only that +distribution. + +You could override the default "build base" directory and make the +:command:`build\*` commands always forcibly rebuild all files with the +following:: + + [build] + build-base=blib + force=1 + +which corresponds to the command-line arguments :: + + python setup.py build --build-base=blib --force + +except that including the :command:`build` command on the command-line means +that command will be run. Including a particular command in config files has no +such implication; it only means that if the command is run, the options in the +config file will apply. (Or if other commands that derive values from it are +run, they will use the values in the config file.) + +You can find out the complete list of options for any command using the +:option:`--help` option, e.g.:: + + python setup.py build --help + +and you can find out the complete list of global options by using +:option:`--help` without a command:: + + python setup.py --help + +See also the "Reference" section of the "Distributing Python Modules" manual. + + +.. _inst-building-ext: + +Building Extensions: Tips and Tricks +==================================== + +Whenever possible, the Distutils try to use the configuration information made +available by the Python interpreter used to run the :file:`setup.py` script. +For example, the same compiler and linker flags used to compile Python will also +be used for compiling extensions. Usually this will work well, but in +complicated situations this might be inappropriate. This section discusses how +to override the usual Distutils behaviour. + + +.. _inst-tweak-flags: + +Tweaking compiler/linker flags +------------------------------ + +Compiling a Python extension written in C or C++ will sometimes require +specifying custom flags for the compiler and linker in order to use a particular +library or produce a special kind of object code. This is especially true if the +extension hasn't been tested on your platform, or if you're trying to +cross-compile Python. + +In the most general case, the extension author might have foreseen that +compiling the extensions would be complicated, and provided a :file:`Setup` file +for you to edit. This will likely only be done if the module distribution +contains many separate extension modules, or if they often require elaborate +sets of compiler flags in order to work. + +A :file:`Setup` file, if present, is parsed in order to get a list of extensions +to build. Each line in a :file:`Setup` describes a single module. Lines have +the following structure:: + + module ... [sourcefile ...] [cpparg ...] [library ...] + + +Let's examine each of the fields in turn. + +* *module* is the name of the extension module to be built, and should be a + valid Python identifier. You can't just change this in order to rename a module + (edits to the source code would also be needed), so this should be left alone. + +* *sourcefile* is anything that's likely to be a source code file, at least + judging by the filename. Filenames ending in :file:`.c` are assumed to be + written in C, filenames ending in :file:`.C`, :file:`.cc`, and :file:`.c++` are + assumed to be C++, and filenames ending in :file:`.m` or :file:`.mm` are assumed + to be in Objective C. + +* *cpparg* is an argument for the C preprocessor, and is anything starting with + :option:`-I`, :option:`-D`, :option:`-U` or :option:`-C`. + +* *library* is anything ending in :file:`.a` or beginning with :option:`-l` or + :option:`-L`. + +If a particular platform requires a special library on your platform, you can +add it by editing the :file:`Setup` file and running ``python setup.py build``. +For example, if the module defined by the line :: + + foo foomodule.c + +must be linked with the math library :file:`libm.a` on your platform, simply add +:option:`-lm` to the line:: + + foo foomodule.c -lm + +Arbitrary switches intended for the compiler or the linker can be supplied with +the :option:`-Xcompiler` *arg* and :option:`-Xlinker` *arg* options:: + + foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm + +The next option after :option:`-Xcompiler` and :option:`-Xlinker` will be +appended to the proper command line, so in the above example the compiler will +be passed the :option:`-o32` option, and the linker will be passed +:option:`-shared`. If a compiler option requires an argument, you'll have to +supply multiple :option:`-Xcompiler` options; for example, to pass ``-x c++`` +the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``. + +Compiler flags can also be supplied through setting the :envvar:`CFLAGS` +environment variable. If set, the contents of :envvar:`CFLAGS` will be added to +the compiler flags specified in the :file:`Setup` file. + + +.. _inst-non-ms-compilers: + +Using non-Microsoft compilers on Windows +---------------------------------------- + +.. sectionauthor:: Rene Liebscher + + + +Borland/CodeGear C++ +^^^^^^^^^^^^^^^^^^^^ + +This subsection describes the necessary steps to use Distutils with the Borland +C++ compiler version 5.5. First you have to know that Borland's object file +format (OMF) is different from the format used by the Python version you can +download from the Python or ActiveState Web site. (Python is built with +Microsoft Visual C++, which uses COFF as the object file format.) For this +reason you have to convert Python's library :file:`python25.lib` into the +Borland format. You can do this as follows: + +.. Should we mention that users have to create cfg-files for the compiler? +.. see also http://community.borland.com/article/0,1410,21205,00.html + +:: + + coff2omf python25.lib python25_bcpp.lib + +The :file:`coff2omf` program comes with the Borland compiler. The file +:file:`python25.lib` is in the :file:`Libs` directory of your Python +installation. If your extension uses other libraries (zlib, ...) you have to +convert them too. + +The converted files have to reside in the same directories as the normal +libraries. + +How does Distutils manage to use these libraries with their changed names? If +the extension needs a library (eg. :file:`foo`) Distutils checks first if it +finds a library with suffix :file:`_bcpp` (eg. :file:`foo_bcpp.lib`) and then +uses this library. In the case it doesn't find such a special library it uses +the default name (:file:`foo.lib`.) [#]_ + +To let Distutils compile your extension with Borland C++ you now have to type:: + + python setup.py build --compiler=bcpp + +If you want to use the Borland C++ compiler as the default, you could specify +this in your personal or system-wide configuration file for Distutils (see +section :ref:`inst-config-files`.) + + +.. seealso:: + + `C++Builder Compiler `_ + Information about the free C++ compiler from Borland, including links to the + download pages. + + `Creating Python Extensions Using Borland's Free Compiler `_ + Document describing how to use Borland's free command-line C++ compiler to build + Python. + + +GNU C / Cygwin / MinGW +^^^^^^^^^^^^^^^^^^^^^^ + +This section describes the necessary steps to use Distutils with the GNU C/C++ +compilers in their Cygwin and MinGW distributions. [#]_ For a Python interpreter +that was built with Cygwin, everything should work without any of these +following steps. + +Not all extensions can be built with MinGW or Cygwin, but many can. Extensions +most likely to not work are those that use C++ or depend on Microsoft Visual C +extensions. + +To let Distutils compile your extension with Cygwin you have to type:: + + python setup.py build --compiler=cygwin + +and for Cygwin in no-cygwin mode [#]_ or for MinGW type:: + + python setup.py build --compiler=mingw32 + +If you want to use any of these options/compilers as default, you should +consider writing it in your personal or system-wide configuration file for +Distutils (see section :ref:`inst-config-files`.) + +Older Versions of Python and MinGW +"""""""""""""""""""""""""""""""""" +The following instructions only apply if you're using a version of Python +inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with +binutils-2.13.90-20030111-1). + +These compilers require some special libraries. This task is more complex than +for Borland's C++, because there is no program to convert the library. First +you have to create a list of symbols which the Python DLL exports. (You can find +a good program for this task at +http://www.emmestech.com/software/pexports-0.43/download_pexports.html). + +.. I don't understand what the next line means. --amk +.. (inclusive the references on data structures.) + +:: + + pexports python25.dll >python25.def + +The location of an installed :file:`python25.dll` will depend on the +installation options and the version and language of Windows. In a "just for +me" installation, it will appear in the root of the installation directory. In +a shared installation, it will be located in the system directory. + +Then you can create from these information an import library for gcc. :: + + /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a + +The resulting library has to be placed in the same directory as +:file:`python25.lib`. (Should be the :file:`libs` directory under your Python +installation directory.) + +If your extension uses other libraries (zlib,...) you might have to convert +them too. The converted files have to reside in the same directories as the +normal libraries do. + + +.. seealso:: + + `Building Python modules on MS Windows platform with MinGW `_ + Information about building the required libraries for the MinGW environment. + + +.. rubric:: Footnotes + +.. [#] This also means you could replace all existing COFF-libraries with OMF-libraries + of the same name. + +.. [#] Check http://sources.redhat.com/cygwin/ and http://www.mingw.org/ for more + information + +.. [#] Then you have no POSIX emulation available, but you also don't need + :file:`cygwin1.dll`. From 82e62fd143c94e964b2fadf8c170e020d8d75f42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 2 Jun 2011 15:45:25 +0200 Subject: [PATCH 198/330] Packaging doc: Add missing index file, improve main page description. Also promote notices from distutils doc to deprecation boxes. --- index.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/index.rst b/index.rst index 5fa25a6d58..b3a5231769 100644 --- a/index.rst +++ b/index.rst @@ -14,6 +14,10 @@ the module developer's point of view, describing how to use the Distutils to make Python modules and extensions easily available to a wider audience with very little overhead for build/release/install mechanics. +.. deprecated:: 3.3 + :mod:`packaging` replaces Distutils. See :ref:`packaging-index` and + :ref:`packaging-install-index`. + .. toctree:: :maxdepth: 2 :numbered: @@ -36,9 +40,3 @@ following the above guidelines: .. toctree:: install.rst - - -.. seealso:: - - :ref:`packaging-index` and :ref:`packaging-install-index` - Documentation of Packaging, the new version of Distutils. From 0e80c6a68aa1b407ee7b24b07437fb475fcff485 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 8 Jun 2011 01:11:36 +0200 Subject: [PATCH 199/330] Add examples that work on Windows to distutils docs (#1626300) --- introduction.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/introduction.rst b/introduction.rst index 8dc604d0d0..57d34a4b57 100644 --- a/introduction.rst +++ b/introduction.rst @@ -79,11 +79,17 @@ Some observations: for an example) To create a source distribution for this module, you would create a setup -script, :file:`setup.py`, containing the above code, and run:: +script, :file:`setup.py`, containing the above code, and run this command from a +terminal:: python setup.py sdist -which will create an archive file (e.g., tarball on Unix, ZIP file on Windows) +For Windows, open a command prompt windows ("DOS box") and change the command +to:: + + setup.py sdist + +:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows) containing your setup script :file:`setup.py`, and your module :file:`foo.py`. The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and will unpack into a directory :file:`foo-1.0`. From d35dc0044c7db20dbb7b4eb22b9f17b9182418ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 8 Jun 2011 01:11:36 +0200 Subject: [PATCH 200/330] Add examples that work on Windows to distutils docs (#1626300) --- introduction.rst | 10 ++++++++-- 1 file changed, 8 insertions(+), 2 deletions(-) diff --git a/introduction.rst b/introduction.rst index b772b01004..2d5dbc727b 100644 --- a/introduction.rst +++ b/introduction.rst @@ -79,11 +79,17 @@ Some observations: for an example) To create a source distribution for this module, you would create a setup -script, :file:`setup.py`, containing the above code, and run:: +script, :file:`setup.py`, containing the above code, and run this command from a +terminal:: python setup.py sdist -which will create an archive file (e.g., tarball on Unix, ZIP file on Windows) +For Windows, open a command prompt windows ("DOS box") and change the command +to:: + + setup.py sdist + +:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows) containing your setup script :file:`setup.py`, and your module :file:`foo.py`. The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and will unpack into a directory :file:`foo-1.0`. From d37f3f9214b898bf97be32265dd8f644a027e71d Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 15 Jul 2011 19:09:49 +0200 Subject: [PATCH 201/330] Remove duplicate "numbered" options for toctrees. --- index.rst | 1 - 1 file changed, 1 deletion(-) diff --git a/index.rst b/index.rst index b3a5231769..c8dd9f46a8 100644 --- a/index.rst +++ b/index.rst @@ -20,7 +20,6 @@ very little overhead for build/release/install mechanics. .. toctree:: :maxdepth: 2 - :numbered: introduction.rst setupscript.rst From 94a05c36b5eaf0ececd4bb589c583d5ce4828c32 Mon Sep 17 00:00:00 2001 From: R David Murray Date: Mon, 18 Jul 2011 12:38:03 -0400 Subject: [PATCH 202/330] Better English. --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index 9208e36995..606ea0f2f4 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -72,7 +72,7 @@ Thus, when you say ``packages = ['foo']`` in your setup script, you are promising that the Distutils will find a file :file:`foo/__init__.py` (which might be spelled differently on your system, but you get the idea) relative to the directory where your setup script lives. If you break this promise, the -Distutils will issue a warning but still process the broken package anyways. +Distutils will issue a warning but still process the broken package anyway. If you use a different convention to lay out your source directory, that's no problem: you just have to supply the :option:`package_dir` option to tell the From 767cc28fd1e1d8f8b031c3c3f5cd76e62cc215a4 Mon Sep 17 00:00:00 2001 From: R David Murray Date: Mon, 18 Jul 2011 12:39:54 -0400 Subject: [PATCH 203/330] Better English. --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index e457918026..d10931b55a 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -72,7 +72,7 @@ Thus, when you say ``packages = ['foo']`` in your setup script, you are promising that the Distutils will find a file :file:`foo/__init__.py` (which might be spelled differently on your system, but you get the idea) relative to the directory where your setup script lives. If you break this promise, the -Distutils will issue a warning but still process the broken package anyways. +Distutils will issue a warning but still process the broken package anyway. If you use a different convention to lay out your source directory, that's no problem: you just have to supply the :option:`package_dir` option to tell the From 5f643038aee5c08c385167462e3eb4e38f4a09ac Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 28 Jul 2011 22:50:18 +0200 Subject: [PATCH 204/330] Turn raw URI into real link --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 28af893648..63eca411e5 100644 --- a/apiref.rst +++ b/apiref.rst @@ -72,8 +72,8 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | | be built | :class:`distutils.core.Extension` | +--------------------+--------------------------------+-------------------------------------------------------------+ | *classifiers* | A list of categories for the | The list of available | - | | package | categorizations is at | - | | | http://pypi.python.org/pypi?:action=list_classifiers. | + | | package | categorizations is available on `PyPI | + | | | `_. | +--------------------+--------------------------------+-------------------------------------------------------------+ | *distclass* | the :class:`Distribution` | A subclass of | | | class to use | :class:`distutils.core.Distribution` | From de09587f2c1efde5491543b67b318569f39cec0c Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 28 Jul 2011 22:50:18 +0200 Subject: [PATCH 205/330] Turn raw URI into real link --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 1fb6f9e45f..124d891a49 100644 --- a/apiref.rst +++ b/apiref.rst @@ -72,8 +72,8 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | | be built | :class:`distutils.core.Extension` | +--------------------+--------------------------------+-------------------------------------------------------------+ | *classifiers* | A list of categories for the | The list of available | - | | package | categorizations is at | - | | | http://pypi.python.org/pypi?:action=list_classifiers. | + | | package | categorizations is available on `PyPI | + | | | `_. | +--------------------+--------------------------------+-------------------------------------------------------------+ | *distclass* | the :class:`Distribution` | A subclass of | | | class to use | :class:`distutils.core.Distribution` | From ace431e8b45d656e9eef369750ea93b76384c3e3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 31 Jul 2011 02:04:00 +0200 Subject: [PATCH 206/330] Fix regression with distutils MANIFEST handing (#11104, #8688). MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The changed behavior of sdist in 2.7 broke packaging for projects that wanted to use a manually-maintained MANIFEST file (instead of having a MANIFEST.in template and letting distutils generate the MANIFEST). The fixes that were committed for #8688 (d29399100973 by Tarek and f7639dcdffc3 by me) did not fix all issues exposed in the bug report, and also added one problem: the MANIFEST file format gained comments, but the read_manifest method was not updated to handle (i.e. ignore) them. This changeset should fix everything; the tests have been expanded and I successfully tested with Mercurial, which suffered from this regression. I have grouped the versionchanged directives for these bugs in one place and added micro version numbers to help users know the quirks of the exact version they’re using. I also removed a stanza in the docs that was forgotten in Tarek’s first changeset. Initial report, thorough diagnosis and patch by John Dennis, further work on the patch by Stephen Thorne, and a few edits and additions by me. --- sourcedist.rst | 29 +++++++++++++++++------------ 1 file changed, 17 insertions(+), 12 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index fc860de68e..a9858d01bf 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -111,12 +111,22 @@ per line, regular files (or symlinks to them) only. If you do supply your own :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. -.. versionadded:: 2.7 +.. versionchanged:: 2.7 + An existing generated :file:`MANIFEST` will be regenerated without + :command:`sdist` comparing its modification time to the one of + :file:`MANIFEST.in` or :file:`setup.py`. + +.. versionchanged:: 2.7.1 :file:`MANIFEST` files start with a comment indicating they are generated. Files without this comment are not overwritten or removed. +.. versionchanged:: 2.7.3 + :command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in` + exists, like it did before 2.7. + See :ref:`manifest_template` section for a syntax reference. + .. _manifest-options: Manifest-related options @@ -124,16 +134,16 @@ Manifest-related options The normal course of operations for the :command:`sdist` command is as follows: -* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` - and create the manifest +* if the manifest file (:file:`MANIFEST` by default) exists and the first line + does not have a comment indicating it is generated from :file:`MANIFEST.in`, + then it is used as is, unaltered + +* if the manifest file doesn't exist or has been previously automatically + generated, read :file:`MANIFEST.in` and create the manifest * if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest with just the default file set -* if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more - recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading - :file:`MANIFEST.in` - * use the list of files now in :file:`MANIFEST` (either just generated or read in) to create the source distribution archive(s) @@ -271,8 +281,3 @@ character, and ``[range]`` matches any of the characters in *range* (e.g., ``a-z``, ``a-zA-Z``, ``a-f0-9_.``). The definition of "regular filename character" is platform-specific: on Unix it is anything except slash; on Windows anything except backslash or colon. - -.. versionchanged:: 2.7 - An existing generated :file:`MANIFEST` will be regenerated without - :command:`sdist` comparing its modification time to the one of - :file:`MANIFEST.in` or :file:`setup.py`. From ad7d9f50922222e9982872374a2eef10d2f72155 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 31 Jul 2011 04:06:12 +0200 Subject: [PATCH 207/330] Fix regression with distutils MANIFEST handing (#11104, #8688). MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The changed behavior of sdist in 3.1 broke packaging for projects that wanted to use a manually-maintained MANIFEST file (instead of having a MANIFEST.in template and letting distutils generate the MANIFEST). The fixes that were committed for #8688 (76643c286b9f by Tarek and d54da9248ed9 by me) did not fix all issues exposed in the bug report, and also added one problem: the MANIFEST file format gained comments, but the read_manifest method was not updated to handle (i.e. ignore) them. This changeset should fix everything; the tests have been expanded and I successfully tested the 2.7 version with Mercurial, which suffered from this regression. I have grouped the versionchanged directives for these bugs in one place and added micro version numbers to help users know the quirks of the exact version they’re using. Initial report, thorough diagnosis and patch by John Dennis, further work on the patch by Stephen Thorne, and a few edits and additions by me. --- sourcedist.rst | 25 +++++++++++++++++-------- 1 file changed, 17 insertions(+), 8 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 15d0bafd71..1666436be0 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -103,10 +103,20 @@ per line, regular files (or symlinks to them) only. If you do supply your own :file:`MANIFEST`, you must specify everything: the default set of files described above does not apply in this case. -.. versionadded:: 3.1 +.. versionchanged:: 3.1 + An existing generated :file:`MANIFEST` will be regenerated without + :command:`sdist` comparing its modification time to the one of + :file:`MANIFEST.in` or :file:`setup.py`. + +.. versionchanged:: 3.1.3 :file:`MANIFEST` files start with a comment indicating they are generated. Files without this comment are not overwritten or removed. +.. versionchanged:: 3.2.2 + :command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in` + exists, like it used to do. + + The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an example, again we turn to the Distutils' own manifest template:: @@ -185,8 +195,12 @@ Manifest-related options The normal course of operations for the :command:`sdist` command is as follows: -* if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in` - and create the manifest +* if the manifest file (:file:`MANIFEST` by default) exists and the first line + does not have a comment indicating it is generated from :file:`MANIFEST.in`, + then it is used as is, unaltered + +* if the manifest file doesn't exist or has been previously automatically + generated, read :file:`MANIFEST.in` and create the manifest * if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest with just the default file set @@ -204,8 +218,3 @@ distribution:: python setup.py sdist --manifest-only :option:`-o` is a shortcut for :option:`--manifest-only`. - -.. versionchanged:: 3.1 - An existing generated :file:`MANIFEST` will be regenerated without - :command:`sdist` comparing its modification time to the one of - :file:`MANIFEST.in` or :file:`setup.py`. From cfe933a2a95855de4660da028f3f9e422ec5b8c2 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 6 Aug 2011 16:58:15 +0200 Subject: [PATCH 208/330] Merge doc changes from 3.2 (#8617, #10745). MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit In the install and library docs, I changed the text to refer to packaging instead of distutils. I also checked that the documented paths correctly reflect what’s really defined in sysconfig; the main difference with paths defined in distutils.install is that include directories don’t end with the distribution name anymore (i.e. distutils uses include/python3.3/spam, sysconfig include/python3.3), I have no idea why. --- install.rst | 186 +++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 132 insertions(+), 54 deletions(-) diff --git a/install.rst b/install.rst index 6f4de7a37d..171ef984eb 100644 --- a/install.rst +++ b/install.rst @@ -279,6 +279,14 @@ statements shown below, and get the output as shown, to find out my >>> sys.exec_prefix '/usr' +A few other placeholders are used in this document: :file:`{X.Y}` stands for the +version of Python, for example ``3.2``; :file:`{abiflags}` will be replaced by +the value of :data:`sys.abiflags` or the empty string for platforms which don't +define ABI flags; :file:`{distname}` will be replaced by the name of the module +distribution being installed. Dots and capitalization are important in the +paths; for example, a value that uses ``python3.2`` on UNIX will typically use +``Python32`` on Windows. + If you don't want to install modules to the standard location, or if you don't have permission to write there, then you need to read about alternate installations in section :ref:`inst-alt-install`. If you want to customize your @@ -307,8 +315,61 @@ scheme*) under this base directory in which to install files. The details differ across platforms, so read whichever of the following sections applies to you. +Note that the various alternate installation schemes are mutually exclusive: you +can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or +``--install-base`` and ``--install-platbase``, but you can't mix from these +groups. + + +.. _inst-alt-install-user: + +Alternate installation: the user scheme +--------------------------------------- + +This scheme is designed to be the most convenient solution for users that don't +have write permission to the global site-packages directory or don't want to +install into it. It is enabled with a simple option:: + + python setup.py install --user + +Files will be installed into subdirectories of :data:`site.USER_BASE` (written +as :file:`{userbase}` hereafter). This scheme installs pure Python modules and +extension modules in the same location (also known as :data:`site.USER_SITE`). +Here are the values for UNIX, including Mac OS X: + +=============== =========================================================== +Type of file Installation directory +=============== =========================================================== +modules :file:`{userbase}/lib/python{X.Y}/site-packages` +scripts :file:`{userbase}/bin` +data :file:`{userbase}` +C headers :file:`{userbase}/include/python{X.Y}{abiflags}/{distname}` +=============== =========================================================== + +And here are the values used on Windows: + +=============== =========================================================== +Type of file Installation directory +=============== =========================================================== +modules :file:`{userbase}\\Python{XY}\\site-packages` +scripts :file:`{userbase}\\Scripts` +data :file:`{userbase}` +C headers :file:`{userbase}\\Python{XY}\\Include\\{distname}` +=============== =========================================================== + +The advantage of using this scheme compared to the other ones described below is +that the user site-packages directory is under normal conditions always included +in :data:`sys.path` (see :mod:`site` for more information), which means that +there is no additional step to perform after running the :file:`setup.py` script +to finalize the installation. + +The :command:`build_ext` command also has a ``--user`` option to add +:file:`{userbase}/include` to the compiler search path for header files and +:file:`{userbase}/lib` to the compiler search path for libraries as well as to +the runtime search path for shared C libraries (rpath). -.. _inst-alt-install-prefix: + +.. _inst-alt-install-home: Alternate installation: the home scheme --------------------------------------- @@ -330,23 +391,27 @@ will expand this to your home directory:: python setup.py install --home=~ +To make Python find the distributions installed with this scheme, you may have +to :ref:`modify Python's search path ` or edit +:mod:`sitecustomize` (see :mod:`site`) to call :func:`site.addsitedir` or edit +:data:`sys.path`. + The :option:`--home` option defines the installation base directory. Files are installed to the following directories under the installation base as follows: -+------------------------------+---------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===========================+=============================+ -| pure module distribution | :file:`{home}/lib/python` | :option:`--install-purelib` | -+------------------------------+---------------------------+-----------------------------+ -| non-pure module distribution | :file:`{home}/lib/python` | :option:`--install-platlib` | -+------------------------------+---------------------------+-----------------------------+ -| scripts | :file:`{home}/bin` | :option:`--install-scripts` | -+------------------------------+---------------------------+-----------------------------+ -| data | :file:`{home}/share` | :option:`--install-data` | -+------------------------------+---------------------------+-----------------------------+ +=============== =========================================================== +Type of file Installation directory +=============== =========================================================== +modules :file:`{home}/lib/python` +scripts :file:`{home}/bin` +data :file:`{home}` +C headers :file:`{home}/include/python/{distname}` +=============== =========================================================== +(Mentally replace slashes with backslashes if you're on Windows.) -.. _inst-alt-install-home: + +.. _inst-alt-install-prefix-unix: Alternate installation: Unix (the prefix scheme) ------------------------------------------------ @@ -355,7 +420,7 @@ The "prefix scheme" is useful when you wish to use one Python installation to perform the build/install (i.e., to run the setup script), but install modules into the third-party module directory of a different Python installation (or something that looks like a different Python installation). If this sounds a -trifle unusual, it is---that's why the "home scheme" comes first. However, +trifle unusual, it is---that's why the user and home schemes come before. However, there are at least two known cases where the prefix scheme will be useful. First, consider that many Linux distributions put Python in :file:`/usr`, rather @@ -383,17 +448,15 @@ non-pure module distributions, but could be expanded to C libraries, binary executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to :option:`--prefix`. Files are installed as follows: -+------------------------------+-----------------------------------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+=====================================================+=============================+ -| pure module distribution | :file:`{prefix}/lib/python{X.Y}/site-packages` | :option:`--install-purelib` | -+------------------------------+-----------------------------------------------------+-----------------------------+ -| non-pure module distribution | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :option:`--install-platlib` | -+------------------------------+-----------------------------------------------------+-----------------------------+ -| scripts | :file:`{prefix}/bin` | :option:`--install-scripts` | -+------------------------------+-----------------------------------------------------+-----------------------------+ -| data | :file:`{prefix}/share` | :option:`--install-data` | -+------------------------------+-----------------------------------------------------+-----------------------------+ +================= ========================================================== +Type of file Installation directory +================= ========================================================== +Python modules :file:`{prefix}/lib/python{X.Y}/site-packages` +extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages` +scripts :file:`{prefix}/bin` +data :file:`{prefix}` +C headers :file:`{prefix}/include/python{X.Y}{abiflags}/{distname}` +================= ========================================================== There is no requirement that :option:`--prefix` or :option:`--exec-prefix` actually point to an alternate Python installation; if the directories listed @@ -418,7 +481,7 @@ if your :option:`--prefix` and :option:`--exec-prefix` don't even point to an alternate Python installation, this is immaterial.) -.. _inst-alt-install-windows: +.. _inst-alt-install-prefix-windows: Alternate installation: Windows (the prefix scheme) --------------------------------------------------- @@ -433,20 +496,18 @@ locations on Windows. :: to install modules to the :file:`\\Temp\\Python` directory on the current drive. The installation base is defined by the :option:`--prefix` option; the -:option:`--exec-prefix` option is not supported under Windows. Files are -installed as follows: - -+------------------------------+---------------------------+-----------------------------+ -| Type of file | Installation Directory | Override option | -+==============================+===========================+=============================+ -| pure module distribution | :file:`{prefix}` | :option:`--install-purelib` | -+------------------------------+---------------------------+-----------------------------+ -| non-pure module distribution | :file:`{prefix}` | :option:`--install-platlib` | -+------------------------------+---------------------------+-----------------------------+ -| scripts | :file:`{prefix}\\Scripts` | :option:`--install-scripts` | -+------------------------------+---------------------------+-----------------------------+ -| data | :file:`{prefix}\\Data` | :option:`--install-data` | -+------------------------------+---------------------------+-----------------------------+ +:option:`--exec-prefix` option is not supported under Windows, which means that +pure Python modules and extension modules are installed into the same location. +Files are installed as follows: + +=============== ========================================================== +Type of file Installation directory +=============== ========================================================== +modules :file:`{prefix}\\Lib\\site-packages` +scripts :file:`{prefix}\\Scripts` +data :file:`{prefix}` +C headers :file:`{prefix}\\Include\\{distname}` +=============== ========================================================== .. _inst-custom-install: @@ -460,13 +521,29 @@ one or two directories while keeping everything under the same base directory, or you might want to completely redefine the installation scheme. In either case, you're creating a *custom installation scheme*. -You probably noticed the column of "override options" in the tables describing -the alternate installation schemes above. Those options are how you define a -custom installation scheme. These override options can be relative, absolute, +To create a custom installation scheme, you start with one of the alternate +schemes and override some of the installation directories used for the various +types of files, using these options: + +====================== ======================= +Type of file Override option +====================== ======================= +Python modules ``--install-purelib`` +extension modules ``--install-platlib`` +all modules ``--install-lib`` +scripts ``--install-scripts`` +data ``--install-data`` +C headers ``--install-headers`` +====================== ======================= + +These override options can be relative, absolute, or explicitly defined in terms of one of the installation base directories. (There are two installation base directories, and they are normally the same--- they only differ when you use the Unix "prefix scheme" and supply different -:option:`--prefix` and :option:`--exec-prefix` options.) +``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` will +override values computed or given for ``--install-purelib`` and +``--install-platlib``, and is recommended for schemes that don't make a +difference between Python and extension modules.) For example, say you're installing a module distribution to your home directory under Unix---but you want scripts to go in :file:`~/scripts` rather than @@ -493,15 +570,16 @@ If you maintain Python on Windows, you might want third-party modules to live in a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}` itself. This is almost as easy as customizing the script installation directory ---you just have to remember that there are two types of modules to worry about, -pure modules and non-pure modules (i.e., modules from a non-pure distribution). -For example:: +Python and extension modules, which can conveniently be both controlled by one +option:: - python setup.py install --install-purelib=Site --install-platlib=Site + python setup.py install --install-lib=Site -The specified installation directories are relative to :file:`{prefix}`. Of -course, you also have to ensure that these directories are in Python's module -search path, such as by putting a :file:`.pth` file in :file:`{prefix}`. See -section :ref:`inst-search-path` to find out how to modify Python's search path. +The specified installation directory is relative to :file:`{prefix}`. Of +course, you also have to ensure that this directory is in Python's module +search path, such as by putting a :file:`.pth` file in a site directory (see +:mod:`site`). See section :ref:`inst-search-path` to find out how to modify +Python's search path. If you want to define an entire installation scheme, you just have to supply all of the installation directory options. The recommended way to do this is to @@ -553,8 +631,8 @@ base directory when you run the setup script. For example, :: python setup.py install --install-base=/tmp -would install pure modules to :file:`{/tmp/python/lib}` in the first case, and -to :file:`{/tmp/lib}` in the second case. (For the second case, you probably +would install pure modules to :file:`/tmp/python/lib` in the first case, and +to :file:`/tmp/lib` in the second case. (For the second case, you probably want to supply an installation base of :file:`/tmp/python`.) You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample @@ -571,7 +649,7 @@ for details. needed on those platforms? -.. XXX I'm not sure where this section should go. +.. XXX Move this to Doc/using .. _inst-search-path: From 9a88371cf91792b8add45e59df93779b999ab193 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 02:30:15 +0200 Subject: [PATCH 209/330] Remove obsolete term + indicate how to find the program (#1626300). Suggested by Terry J. Reedy. --- introduction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/introduction.rst b/introduction.rst index 57d34a4b57..0ece646c34 100644 --- a/introduction.rst +++ b/introduction.rst @@ -84,8 +84,8 @@ terminal:: python setup.py sdist -For Windows, open a command prompt windows ("DOS box") and change the command -to:: +For Windows, open a command prompt window (:menuselection:`Start --> +Accessories`) and change the command to:: setup.py sdist From 0721964ec5ee134de925d9de461011e3bbd4231e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 03:44:36 +0200 Subject: [PATCH 210/330] Fix typo in command name --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index 606ea0f2f4..80292432a9 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -254,7 +254,7 @@ code: it's probably better to write C code like :: If you need to include header files from some other Python extension, you can take advantage of the fact that header files are installed in a consistent way -by the Distutils :command:`install_header` command. For example, the Numerical +by the Distutils :command:`install_headers` command. For example, the Numerical Python header files are installed (on a standard Unix installation) to :file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ according to your platform and Python installation.) Since the Python include From 293f2694efc151dcc51cb876668c168bf9c66b69 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 09:29:56 +0200 Subject: [PATCH 211/330] Remove obsolete term + indicate how to find the program (#1626300). Suggested by Terry J. Reedy. --- introduction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/introduction.rst b/introduction.rst index 2d5dbc727b..fc6184fa57 100644 --- a/introduction.rst +++ b/introduction.rst @@ -84,8 +84,8 @@ terminal:: python setup.py sdist -For Windows, open a command prompt windows ("DOS box") and change the command -to:: +For Windows, open a command prompt windows (:menuselection:`Start --> +Accessories`) and change the command to:: setup.py sdist From 2571448a2f71aa397e669cdc5c9d3591404c9b62 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 19 Aug 2011 09:30:26 +0200 Subject: [PATCH 212/330] Fix typo in command name --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index d10931b55a..cce78b03cd 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -254,7 +254,7 @@ code: it's probably better to write C code like :: If you need to include header files from some other Python extension, you can take advantage of the fact that header files are installed in a consistent way -by the Distutils :command:`install_header` command. For example, the Numerical +by the Distutils :command:`install_headers` command. For example, the Numerical Python header files are installed (on a standard Unix installation) to :file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ according to your platform and Python installation.) Since the Python include From 507f7dcd713208d7cd3d1e82a5a5ffea88f1d333 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 26 Aug 2011 00:44:37 +0200 Subject: [PATCH 213/330] Fix type information in distutils API reference (#9302). Initial patch by Yue Shuaijie. --- apiref.rst | 56 +++++++++++++++++++++++++++--------------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/apiref.rst b/apiref.rst index 124d891a49..351f2b54bc 100644 --- a/apiref.rst +++ b/apiref.rst @@ -31,8 +31,9 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and +====================+================================+=============================================================+ | *name* | The name of the package | a string | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *version* | The version number of the | See :mod:`distutils.version` | - | | package | | + | *version* | The version number of the | a string | + | | package; see | | + | | :mod:`distutils.version` | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *description* | A single line describing the | a string | | | package | | @@ -49,14 +50,14 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | | maintainer, if different from | | | | the author | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *maintainer_email* | The email address of the | | + | *maintainer_email* | The email address of the | a string | | | current maintainer, if | | | | different from the author | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *url* | A URL for the package | a URL | + | *url* | A URL for the package | a string | | | (homepage) | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *download_url* | A URL to download the package | a URL | + | *download_url* | A URL to download the package | a string | +--------------------+--------------------------------+-------------------------------------------------------------+ | *packages* | A list of Python packages that | a list of strings | | | distutils will manipulate | | @@ -68,14 +69,13 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | | files to be built and | | | | installed | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *ext_modules* | A list of Python extensions to | A list of instances of | + | *ext_modules* | A list of Python extensions to | a list of instances of | | | be built | :class:`distutils.core.Extension` | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *classifiers* | A list of categories for the | The list of available | - | | package | categorizations is available on `PyPI | - | | | `_. | + | *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI | + | | package | `_. | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *distclass* | the :class:`Distribution` | A subclass of | + | *distclass* | the :class:`Distribution` | a subclass of | | | class to use | :class:`distutils.core.Distribution` | +--------------------+--------------------------------+-------------------------------------------------------------+ | *script_name* | The name of the setup.py | a string | @@ -85,15 +85,15 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *script_args* | Arguments to supply to the | a list of strings | | | setup script | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *options* | default options for the setup | a string | + | *options* | default options for the setup | a dictionary | | | script | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *license* | The license for the package | a string | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *keywords* | Descriptive meta-data, see | | + | *keywords* | Descriptive meta-data, see | a list of strings or a comma-separated string | | | :pep:`314` | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *platforms* | | | + | *platforms* | | a list of strings or a comma-separated string | +--------------------+--------------------------------+-------------------------------------------------------------+ | *cmdclass* | A mapping of command names to | a dictionary | | | :class:`Command` subclasses | | @@ -165,13 +165,13 @@ the full reference. +------------------------+--------------------------------+---------------------------+ | argument name | value | type | +========================+================================+===========================+ - | *name* | the full name of the | string | + | *name* | the full name of the | a string | | | extension, including any | | | | packages --- ie. *not* a | | | | filename or pathname, but | | | | Python dotted name | | +------------------------+--------------------------------+---------------------------+ - | *sources* | list of source filenames, | string | + | *sources* | list of source filenames, | a list of strings | | | relative to the distribution | | | | root (where the setup script | | | | lives), in Unix form (slash- | | @@ -184,12 +184,12 @@ the full reference. | | as source for a Python | | | | extension. | | +------------------------+--------------------------------+---------------------------+ - | *include_dirs* | list of directories to search | string | + | *include_dirs* | list of directories to search | a list of strings | | | for C/C++ header files (in | | | | Unix form for portability) | | +------------------------+--------------------------------+---------------------------+ - | *define_macros* | list of macros to define; each | (string, string) tuple or | - | | macro is defined using a | (name, ``None``) | + | *define_macros* | list of macros to define; each | a list of tuples | + | | macro is defined using a | | | | 2-tuple ``(name, value)``, | | | | where *value* is | | | | either the string to define it | | @@ -200,31 +200,31 @@ the full reference. | | on Unix C compiler command | | | | line) | | +------------------------+--------------------------------+---------------------------+ - | *undef_macros* | list of macros to undefine | string | + | *undef_macros* | list of macros to undefine | a list of strings | | | explicitly | | +------------------------+--------------------------------+---------------------------+ - | *library_dirs* | list of directories to search | string | + | *library_dirs* | list of directories to search | a list of strings | | | for C/C++ libraries at link | | | | time | | +------------------------+--------------------------------+---------------------------+ - | *libraries* | list of library names (not | string | + | *libraries* | list of library names (not | a list of strings | | | filenames or paths) to link | | | | against | | +------------------------+--------------------------------+---------------------------+ - | *runtime_library_dirs* | list of directories to search | string | + | *runtime_library_dirs* | list of directories to search | a list of strings | | | for C/C++ libraries at run | | | | time (for shared extensions, | | | | this is when the extension is | | | | loaded) | | +------------------------+--------------------------------+---------------------------+ - | *extra_objects* | list of extra files to link | string | + | *extra_objects* | list of extra files to link | a list of strings | | | with (eg. object files not | | | | implied by 'sources', static | | | | library that must be | | | | explicitly specified, binary | | | | resource files, etc.) | | +------------------------+--------------------------------+---------------------------+ - | *extra_compile_args* | any extra platform- and | string | + | *extra_compile_args* | any extra platform- and | a list of strings | | | compiler-specific information | | | | to use when compiling the | | | | source files in 'sources'. For | | @@ -235,7 +235,7 @@ the full reference. | | for other platforms it could | | | | be anything. | | +------------------------+--------------------------------+---------------------------+ - | *extra_link_args* | any extra platform- and | string | + | *extra_link_args* | any extra platform- and | a list of strings | | | compiler-specific information | | | | to use when linking object | | | | files together to create the | | @@ -244,7 +244,7 @@ the full reference. | | Similar interpretation as for | | | | 'extra_compile_args'. | | +------------------------+--------------------------------+---------------------------+ - | *export_symbols* | list of symbols to be exported | string | + | *export_symbols* | list of symbols to be exported | a list of strings | | | from a shared extension. Not | | | | used on all platforms, and not | | | | generally necessary for Python | | @@ -252,10 +252,10 @@ the full reference. | | export exactly one symbol: | | | | ``init`` + extension_name. | | +------------------------+--------------------------------+---------------------------+ - | *depends* | list of files that the | string | + | *depends* | list of files that the | a list of strings | | | extension depends on | | +------------------------+--------------------------------+---------------------------+ - | *language* | extension language (i.e. | string | + | *language* | extension language (i.e. | a string | | | ``'c'``, ``'c++'``, | | | | ``'objc'``). Will be detected | | | | from the source extensions if | | From 5fae7cdc580f3b288d4b87606c5e174086c37b42 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 26 Aug 2011 00:45:18 +0200 Subject: [PATCH 214/330] =?UTF-8?q?Document=20the=20"optional"=20argument?= =?UTF-8?q?=20of=20distutils=E2=80=99=20Extension=20class?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apiref.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/apiref.rst b/apiref.rst index 124d891a49..2d3d8e37b0 100644 --- a/apiref.rst +++ b/apiref.rst @@ -261,6 +261,11 @@ the full reference. | | from the source extensions if | | | | not provided. | | +------------------------+--------------------------------+---------------------------+ + | *optional* | specifies that a build failure | a boolean | + | | in the extension should not | | + | | abort the build process, but | | + | | simply skip the extension. | | + +------------------------+--------------------------------+---------------------------+ .. class:: Distribution From b31194bc0231d834aaec9b2a780ef0520cb0b877 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 26 Aug 2011 00:45:18 +0200 Subject: [PATCH 215/330] =?UTF-8?q?Document=20the=20"optional"=20argument?= =?UTF-8?q?=20of=20distutils=E2=80=99=20Extension=20class?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apiref.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/apiref.rst b/apiref.rst index 351f2b54bc..4c849a9bf0 100644 --- a/apiref.rst +++ b/apiref.rst @@ -261,6 +261,11 @@ the full reference. | | from the source extensions if | | | | not provided. | | +------------------------+--------------------------------+---------------------------+ + | *optional* | specifies that a build failure | a boolean | + | | in the extension should not | | + | | abort the build process, but | | + | | simply skip the extension. | | + +------------------------+--------------------------------+---------------------------+ .. class:: Distribution From fb19b67c957ed33d5ece60f922963ef4a187dde3 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 26 Aug 2011 02:08:20 +0200 Subject: [PATCH 216/330] Fix type information in distutils API reference (#9302). Initial patch by Yue Shuaijie. --- apiref.rst | 56 +++++++++++++++++++++++++++--------------------------- 1 file changed, 28 insertions(+), 28 deletions(-) diff --git a/apiref.rst b/apiref.rst index 63eca411e5..30829b8f64 100644 --- a/apiref.rst +++ b/apiref.rst @@ -31,8 +31,9 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and +====================+================================+=============================================================+ | *name* | The name of the package | a string | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *version* | The version number of the | See :mod:`distutils.version` | - | | package | | + | *version* | The version number of the | a string | + | | package; see | | + | | :mod:`distutils.version` | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *description* | A single line describing the | a string | | | package | | @@ -49,14 +50,14 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | | maintainer, if different from | | | | the author | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *maintainer_email* | The email address of the | | + | *maintainer_email* | The email address of the | a string | | | current maintainer, if | | | | different from the author | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *url* | A URL for the package | a URL | + | *url* | A URL for the package | a string | | | (homepage) | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *download_url* | A URL to download the package | a URL | + | *download_url* | A URL to download the package | a string | +--------------------+--------------------------------+-------------------------------------------------------------+ | *packages* | A list of Python packages that | a list of strings | | | distutils will manipulate | | @@ -68,14 +69,13 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | | files to be built and | | | | installed | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *ext_modules* | A list of Python extensions to | A list of instances of | + | *ext_modules* | A list of Python extensions to | a list of instances of | | | be built | :class:`distutils.core.Extension` | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *classifiers* | A list of categories for the | The list of available | - | | package | categorizations is available on `PyPI | - | | | `_. | + | *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI | + | | package | `_. | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *distclass* | the :class:`Distribution` | A subclass of | + | *distclass* | the :class:`Distribution` | a subclass of | | | class to use | :class:`distutils.core.Distribution` | +--------------------+--------------------------------+-------------------------------------------------------------+ | *script_name* | The name of the setup.py | a string | @@ -85,15 +85,15 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | *script_args* | Arguments to supply to the | a list of strings | | | setup script | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *options* | default options for the setup | a string | + | *options* | default options for the setup | a dictionary | | | script | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *license* | The license for the package | a string | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *keywords* | Descriptive meta-data, see | | + | *keywords* | Descriptive meta-data, see | a list of strings or a comma-separated string | | | :pep:`314` | | +--------------------+--------------------------------+-------------------------------------------------------------+ - | *platforms* | | | + | *platforms* | | a list of strings or a comma-separated string | +--------------------+--------------------------------+-------------------------------------------------------------+ | *cmdclass* | A mapping of command names to | a dictionary | | | :class:`Command` subclasses | | @@ -165,13 +165,13 @@ the full reference. +------------------------+--------------------------------+---------------------------+ | argument name | value | type | +========================+================================+===========================+ - | *name* | the full name of the | string | + | *name* | the full name of the | a string | | | extension, including any | | | | packages --- ie. *not* a | | | | filename or pathname, but | | | | Python dotted name | | +------------------------+--------------------------------+---------------------------+ - | *sources* | list of source filenames, | string | + | *sources* | list of source filenames, | a list of strings | | | relative to the distribution | | | | root (where the setup script | | | | lives), in Unix form (slash- | | @@ -184,12 +184,12 @@ the full reference. | | as source for a Python | | | | extension. | | +------------------------+--------------------------------+---------------------------+ - | *include_dirs* | list of directories to search | string | + | *include_dirs* | list of directories to search | a list of strings | | | for C/C++ header files (in | | | | Unix form for portability) | | +------------------------+--------------------------------+---------------------------+ - | *define_macros* | list of macros to define; each | (string, string) tuple or | - | | macro is defined using a | (name, ``None``) | + | *define_macros* | list of macros to define; each | a list of tuples | + | | macro is defined using a | | | | 2-tuple ``(name, value)``, | | | | where *value* is | | | | either the string to define it | | @@ -200,31 +200,31 @@ the full reference. | | on Unix C compiler command | | | | line) | | +------------------------+--------------------------------+---------------------------+ - | *undef_macros* | list of macros to undefine | string | + | *undef_macros* | list of macros to undefine | a list of strings | | | explicitly | | +------------------------+--------------------------------+---------------------------+ - | *library_dirs* | list of directories to search | string | + | *library_dirs* | list of directories to search | a list of strings | | | for C/C++ libraries at link | | | | time | | +------------------------+--------------------------------+---------------------------+ - | *libraries* | list of library names (not | string | + | *libraries* | list of library names (not | a list of strings | | | filenames or paths) to link | | | | against | | +------------------------+--------------------------------+---------------------------+ - | *runtime_library_dirs* | list of directories to search | string | + | *runtime_library_dirs* | list of directories to search | a list of strings | | | for C/C++ libraries at run | | | | time (for shared extensions, | | | | this is when the extension is | | | | loaded) | | +------------------------+--------------------------------+---------------------------+ - | *extra_objects* | list of extra files to link | string | + | *extra_objects* | list of extra files to link | a list of strings | | | with (eg. object files not | | | | implied by 'sources', static | | | | library that must be | | | | explicitly specified, binary | | | | resource files, etc.) | | +------------------------+--------------------------------+---------------------------+ - | *extra_compile_args* | any extra platform- and | string | + | *extra_compile_args* | any extra platform- and | a list of strings | | | compiler-specific information | | | | to use when compiling the | | | | source files in 'sources'. For | | @@ -235,7 +235,7 @@ the full reference. | | for other platforms it could | | | | be anything. | | +------------------------+--------------------------------+---------------------------+ - | *extra_link_args* | any extra platform- and | string | + | *extra_link_args* | any extra platform- and | a list of strings | | | compiler-specific information | | | | to use when linking object | | | | files together to create the | | @@ -244,7 +244,7 @@ the full reference. | | Similar interpretation as for | | | | 'extra_compile_args'. | | +------------------------+--------------------------------+---------------------------+ - | *export_symbols* | list of symbols to be exported | string | + | *export_symbols* | list of symbols to be exported | a list of strings | | | from a shared extension. Not | | | | used on all platforms, and not | | | | generally necessary for Python | | @@ -252,10 +252,10 @@ the full reference. | | export exactly one symbol: | | | | ``init`` + extension_name. | | +------------------------+--------------------------------+---------------------------+ - | *depends* | list of files that the | string | + | *depends* | list of files that the | a list of strings | | | extension depends on | | +------------------------+--------------------------------+---------------------------+ - | *language* | extension language (i.e. | string | + | *language* | extension language (i.e. | a string | | | ``'c'``, ``'c++'``, | | | | ``'objc'``). Will be detected | | | | from the source extensions if | | From 9d4440f483c3ea96dc631f00947542967239ba4e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 26 Aug 2011 00:45:18 +0200 Subject: [PATCH 217/330] =?UTF-8?q?Document=20the=20"optional"=20argument?= =?UTF-8?q?=20of=20distutils=E2=80=99=20Extension=20class?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apiref.rst | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/apiref.rst b/apiref.rst index 30829b8f64..eae9078843 100644 --- a/apiref.rst +++ b/apiref.rst @@ -261,6 +261,11 @@ the full reference. | | from the source extensions if | | | | not provided. | | +------------------------+--------------------------------+---------------------------+ + | *optional* | specifies that a build failure | a boolean | + | | in the extension should not | | + | | abort the build process, but | | + | | simply skip the extension. | | + +------------------------+--------------------------------+---------------------------+ .. class:: Distribution From c0e0935a5648471ef2a0731cfd20f90b87e8f893 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 26 Aug 2011 01:23:20 +0200 Subject: [PATCH 218/330] =?UTF-8?q?Synchronize=20packaging=20docs=20with?= =?UTF-8?q?=20distutils=E2=80=99=20(includes=20fix=20for=20#9302)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 4c849a9bf0..3adbc52054 100644 --- a/apiref.rst +++ b/apiref.rst @@ -160,7 +160,7 @@ the full reference. .. class:: Extension The Extension class describes a single C or C++extension module in a setup - script. It accepts the following keyword arguments in its constructor + script. It accepts the following keyword arguments in its constructor: +------------------------+--------------------------------+---------------------------+ | argument name | value | type | From 031fcc91961307ebaebe476bc57e88673dbbe58b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 8 Oct 2011 00:34:13 +0200 Subject: [PATCH 219/330] Fix distutils byte-compilation to comply with PEP 3147 (#11254). Patch by Jeff Ramnani. Tested with -B, -O and -OO. --- apiref.rst | 11 ++++++++--- 1 file changed, 8 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 4c849a9bf0..e3d41ccb89 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1204,9 +1204,9 @@ other utility module. .. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None]) Byte-compile a collection of Python source files to either :file:`.pyc` or - :file:`.pyo` files in the same directory. *py_files* is a list of files to - compile; any files that don't end in :file:`.py` are silently skipped. - *optimize* must be one of the following: + :file:`.pyo` files in a :file:`__pycache__` subdirectory (see :pep:`3147`). + *py_files* is a list of files to compile; any files that don't end in + :file:`.py` are silently skipped. *optimize* must be one of the following: * ``0`` - don't optimize (generate :file:`.pyc`) * ``1`` - normal optimization (like ``python -O``) @@ -1231,6 +1231,11 @@ other utility module. is used by the script generated in indirect mode; unless you know what you're doing, leave it set to ``None``. + .. versionchanged:: 3.2.3 + Create ``.pyc`` or ``.pyo`` files with an :func:`import magic tag + ` in their name, in a :file:`__pycache__` subdirectory + instead of files without tag in the current directory. + .. function:: rfc822_escape(header) From 4aae50e5107eab0b3f873206a8dfbbb4fb2843f7 Mon Sep 17 00:00:00 2001 From: Antoine Pitrou Date: Wed, 12 Oct 2011 18:35:18 +0200 Subject: [PATCH 220/330] Replace a mention of EnvironmentError in the distutils docs. --- apiref.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/apiref.rst b/apiref.rst index 407b80d19c..091cba16e1 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1162,12 +1162,11 @@ other utility module. .. function:: grok_environment_error(exc[, prefix='error: ']) - Generate a useful error message from an :exc:`EnvironmentError` (:exc:`IOError` - or :exc:`OSError`) exception object. Handles Python 1.5.1 and later styles, - and does what it can to deal with exception objects that don't have a filename - (which happens when the error is due to a two-file operation, such as - :func:`rename` or :func:`link`). Returns the error message as a string - prefixed with *prefix*. + Generate a useful error message from an :exc:`OSError` exception object. + Handles Python 1.5.1 and later styles, and does what it can to deal with + exception objects that don't have a filename (which happens when the error + is due to a two-file operation, such as :func:`rename` or :func:`link`). + Returns the error message as a string prefixed with *prefix*. .. function:: split_quoted(s) From 242b2bdd0f7f206239ad9e3da18eabde9e4a8e9d Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 19 Oct 2011 10:39:35 +0300 Subject: [PATCH 221/330] Remove duplication. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index eae9078843..c394eee8ea 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1741,7 +1741,7 @@ Subclasses of :class:`Command` must define the following methods. Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place - to to code option dependencies: if *foo* depends on *bar*, then it is safe to + to code option dependencies: if *foo* depends on *bar*, then it is safe to set *foo* from *bar* as long as *foo* still has the same value it was assigned in :meth:`initialize_options`. From d6f3f000772d812a08dac3f99ff4f298f927292e Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 19 Oct 2011 10:58:56 +0300 Subject: [PATCH 222/330] Remove duplication. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index e3d41ccb89..b3def22afa 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1745,7 +1745,7 @@ Subclasses of :class:`Command` must define the following methods. Set final values for all the options that this command supports. This is always called as late as possible, ie. after any option assignments from the command-line or from other commands have been done. Thus, this is the place - to to code option dependencies: if *foo* depends on *bar*, then it is safe to + to code option dependencies: if *foo* depends on *bar*, then it is safe to set *foo* from *bar* as long as *foo* still has the same value it was assigned in :meth:`initialize_options`. From d3e8c277519c0dfbfc4e2caf9eb0098db9f855cf Mon Sep 17 00:00:00 2001 From: Sandro Tosi Date: Sat, 14 Jan 2012 16:42:02 +0100 Subject: [PATCH 223/330] update to new C roles and directives --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index b4f2f1a1e1..7a1145999d 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -426,7 +426,7 @@ built-in functions in the installation script. Which folders are available depends on the exact Windows version, and probably also the configuration. For details refer to Microsoft's documentation of the - :cfunc:`SHGetSpecialFolderPath` function. + :c:func:`SHGetSpecialFolderPath` function. .. function:: create_shortcut(target, description, filename[, arguments[, workdir[, iconpath[, iconindex]]]]) From 0fc0953d716995ec253787012d967fa3769c48dd Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 15 Jan 2012 02:25:31 +0100 Subject: [PATCH 224/330] Hide or remove user-visible XXX notes from distutils doc (#13716). MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Requested by Florent Xicluna with the rationale that they make the docs look unfinished. I’ve also removed a few XXX notes that were not visible in the HTML but could waste contributors’ time by suggesting improvements that are never going to happen for distutils. --- apiref.rst | 36 +++++++++++------------------------- 1 file changed, 11 insertions(+), 25 deletions(-) diff --git a/apiref.rst b/apiref.rst index b3def22afa..e15dc76c83 100644 --- a/apiref.rst +++ b/apiref.rst @@ -449,7 +449,9 @@ This module provides the following functions. Define a preprocessor macro for all compilations driven by this compiler object. The optional parameter *value* should be a string; if it is not supplied, then the macro will be defined without an explicit value and the exact outcome - depends on the compiler used (XXX true? does ANSI say anything about this?) + depends on the compiler used. + + .. XXX true? does ANSI say anything about this? .. method:: CCompiler.undefine_macro(name) @@ -603,7 +605,9 @@ This module provides the following functions. *output_libname* should be a library name, not a filename; the filename will be inferred from the library name. *output_dir* is the directory where the library - file will be put. XXX defaults to what? + file will be put. + + .. XXX defaults to what? *debug* is a boolean; if true, debugging information will be included in the library (note that on most platforms, it is the compile step where this matters: @@ -723,30 +727,29 @@ This module provides the following functions. Invokes :func:`distutils.util.execute` This method invokes a Python function *func* with the given arguments *args*, after logging and taking into account - the *dry_run* flag. XXX see also. + the *dry_run* flag. .. method:: CCompiler.spawn(cmd) Invokes :func:`distutils.util.spawn`. This invokes an external process to run - the given command. XXX see also. + the given command. .. method:: CCompiler.mkpath(name[, mode=511]) Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any - missing ancestor directories. XXX see also. + missing ancestor directories. .. method:: CCompiler.move_file(src, dst) - Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. XXX see - also. + Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. .. method:: CCompiler.announce(msg[, level=1]) - Write a message using :func:`distutils.log.debug`. XXX see also. + Write a message using :func:`distutils.log.debug`. .. method:: CCompiler.warn(msg) @@ -874,8 +877,6 @@ tarballs or zipfiles. prefix of all files and directories in the archive. *root_dir* and *base_dir* both default to the current directory. Returns the name of the archive file. - .. XXX This should be changed to support bz2 files. - .. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) @@ -887,8 +888,6 @@ tarballs or zipfiles. possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2` or :file:`.Z`). Return the output filename. - .. XXX This should be replaced with calls to the :mod:`tarfile` module. - .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) @@ -1000,8 +999,6 @@ directories. errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is true). -.. XXX Some of this could be replaced with the shutil module? - :mod:`distutils.file_util` --- Single file operations ===================================================== @@ -1115,8 +1112,6 @@ other utility module. * ``macosx-10.6-intel`` - .. % XXX isn't this also provided by some other non-distutils module? - .. function:: convert_path(pathname) @@ -1321,8 +1316,6 @@ provides the following additional features: the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. -.. XXX Should be replaced with optparse - .. function:: fancy_getopt(options, negative_opt, object, args) Wrapper function. *options* is a list of ``(long_option, short_option, @@ -1338,9 +1331,6 @@ provides the following additional features: Wraps *text* to less than *width* wide. - .. XXX Should be replaced with :mod:`textwrap` (which is available in Python - 2.3 and later). - .. class:: FancyGetopt([option_table=None]) @@ -1403,10 +1393,6 @@ filesystem and building lists of files. :synopsis: A simple logging mechanism, 282-style -.. XXX Should be replaced with standard :mod:`logging` module. - - - :mod:`distutils.spawn` --- Spawn a sub-process ============================================== From b15d21cd7f2baa8a7b16c6cc85e20352d915fce0 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Fri, 10 Feb 2012 05:31:28 +0100 Subject: [PATCH 225/330] =?UTF-8?q?distutils=202.7=E2=80=99s=20Extension?= =?UTF-8?q?=20does=20not=20support=20optional=20(#13865).?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reported by Miki Tebeka. --- apiref.rst | 5 ----- setupscript.rst | 4 ---- 2 files changed, 9 deletions(-) diff --git a/apiref.rst b/apiref.rst index c394eee8ea..692d5cf60b 100644 --- a/apiref.rst +++ b/apiref.rst @@ -261,11 +261,6 @@ the full reference. | | from the source extensions if | | | | not provided. | | +------------------------+--------------------------------+---------------------------+ - | *optional* | specifies that a build failure | a boolean | - | | in the extension should not | | - | | abort the build process, but | | - | | simply skip the extension. | | - +------------------------+--------------------------------+---------------------------+ .. class:: Distribution diff --git a/setupscript.rst b/setupscript.rst index cce78b03cd..165bfcd716 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -334,10 +334,6 @@ Other options There are still some other options which can be used to handle special cases. -The :option:`optional` option is a boolean; if it is true, -a build failure in the extension will not abort the build process, but -instead simply not install the failing extension. - The :option:`extra_objects` option is a list of object files to be passed to the linker. These files must not have extensions, as the default extension for the compiler is used. From 91f14ee308523587c63990b729cb910863ad1950 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 26 Feb 2012 01:21:31 +0100 Subject: [PATCH 226/330] Hide or remove user-visible XXX notes from distutils doc (#13716). MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Requested by Florent Xicluna with the rationale that they make the docs look unfinished. When I get to replace the XXX notes with the real info for packaging, I’ll backport it. Also removed a few XXX notes that were not visible in the HTML but could waste contributors’ time by suggesting improvements that are never going to happen for distutils. --- apiref.rst | 38 +++++++++++--------------------------- 1 file changed, 11 insertions(+), 27 deletions(-) diff --git a/apiref.rst b/apiref.rst index 692d5cf60b..ba4fc9f5a5 100644 --- a/apiref.rst +++ b/apiref.rst @@ -444,7 +444,9 @@ This module provides the following functions. Define a preprocessor macro for all compilations driven by this compiler object. The optional parameter *value* should be a string; if it is not supplied, then the macro will be defined without an explicit value and the exact outcome - depends on the compiler used (XXX true? does ANSI say anything about this?) + depends on the compiler used. + + .. XXX true? does ANSI say anything about this? .. method:: CCompiler.undefine_macro(name) @@ -598,7 +600,9 @@ This module provides the following functions. *output_libname* should be a library name, not a filename; the filename will be inferred from the library name. *output_dir* is the directory where the library - file will be put. XXX defaults to what? + file will be put. + + .. XXX defaults to what? *debug* is a boolean; if true, debugging information will be included in the library (note that on most platforms, it is the compile step where this matters: @@ -718,30 +722,29 @@ This module provides the following functions. Invokes :func:`distutils.util.execute` This method invokes a Python function *func* with the given arguments *args*, after logging and taking into account - the *dry_run* flag. XXX see also. + the *dry_run* flag. .. method:: CCompiler.spawn(cmd) Invokes :func:`distutils.util.spawn`. This invokes an external process to run - the given command. XXX see also. + the given command. .. method:: CCompiler.mkpath(name[, mode=511]) Invokes :func:`distutils.dir_util.mkpath`. This creates a directory and any - missing ancestor directories. XXX see also. + missing ancestor directories. .. method:: CCompiler.move_file(src, dst) - Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. XXX see - also. + Invokes :meth:`distutils.file_util.move_file`. Renames *src* to *dst*. .. method:: CCompiler.announce(msg[, level=1]) - Write a message using :func:`distutils.log.debug`. XXX see also. + Write a message using :func:`distutils.log.debug`. .. method:: CCompiler.warn(msg) @@ -869,8 +872,6 @@ tarballs or zipfiles. prefix of all files and directories in the archive. *root_dir* and *base_dir* both default to the current directory. Returns the name of the archive file. - .. XXX This should be changed to support bz2 files. - .. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) @@ -882,8 +883,6 @@ tarballs or zipfiles. possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2` or :file:`.Z`). Return the output filename. - .. XXX This should be replaced with calls to the :mod:`tarfile` module. - .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) @@ -995,8 +994,6 @@ directories. errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is true). -.. XXX Some of this could be replaced with the shutil module? - :mod:`distutils.file_util` --- Single file operations ===================================================== @@ -1110,8 +1107,6 @@ other utility module. * ``macosx-10.6-intel`` - .. % XXX isn't this also provided by some other non-distutils module? - .. function:: convert_path(pathname) @@ -1311,8 +1306,6 @@ provides the following additional features: the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the command line sets *verbose* to false. -.. XXX Should be replaced with :mod:`optparse`. - .. function:: fancy_getopt(options, negative_opt, object, args) @@ -1329,8 +1322,6 @@ provides the following additional features: Wraps *text* to less than *width* wide. - .. XXX Should be replaced with :mod:`textwrap` (which is available in Python - 2.3 and later). .. class:: FancyGetopt([option_table=None]) @@ -1394,10 +1385,6 @@ filesystem and building lists of files. :synopsis: A simple logging mechanism, 282-style -.. XXX Should be replaced with standard :mod:`logging` module. - - - :mod:`distutils.spawn` --- Spawn a sub-process ============================================== @@ -1894,9 +1881,6 @@ Subclasses of :class:`Command` must define the following methods. :synopsis: Build the .py/.pyc files of a package -.. % todo - - :mod:`distutils.command.build_scripts` --- Build the scripts of a package ========================================================================= From 735007304c03c90d0bd3a9d620d685d1d98d07d9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 24 Jun 2012 00:07:41 -0400 Subject: [PATCH 227/330] Remove packaging from the standard library. Distutils2 will live on on PyPI and be included in the stdlib when it is ready. See discussion starting at http://mail.python.org/pipermail/python-dev/2012-June/120430.html --- index.rst | 12 +----------- 1 file changed, 1 insertion(+), 11 deletions(-) diff --git a/index.rst b/index.rst index c8dd9f46a8..ace8280894 100644 --- a/index.rst +++ b/index.rst @@ -14,12 +14,9 @@ the module developer's point of view, describing how to use the Distutils to make Python modules and extensions easily available to a wider audience with very little overhead for build/release/install mechanics. -.. deprecated:: 3.3 - :mod:`packaging` replaces Distutils. See :ref:`packaging-index` and - :ref:`packaging-install-index`. - .. toctree:: :maxdepth: 2 + :numbered: introduction.rst setupscript.rst @@ -32,10 +29,3 @@ very little overhead for build/release/install mechanics. extending.rst commandref.rst apiref.rst - -Another document describes how to install modules and extensions packaged -following the above guidelines: - -.. toctree:: - - install.rst From 7cd414c52b6bded5e4a3d327eaa4cc546d6d24f9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sun, 24 Jun 2012 00:09:56 -0400 Subject: [PATCH 228/330] Move distutils install doc back into place. (This was not done in the previous commit because Mercurial would have shown it as a modified file instead of a moved file.) --- install.rst | 1086 --------------------------------------------------- 1 file changed, 1086 deletions(-) delete mode 100644 install.rst diff --git a/install.rst b/install.rst deleted file mode 100644 index b20f1fbd17..0000000000 --- a/install.rst +++ /dev/null @@ -1,1086 +0,0 @@ -.. highlightlang:: none - -.. _install-index: - -***************************** - Installing Python Modules -***************************** - -:Author: Greg Ward -:Release: |version| -:Date: |today| - -.. TODO: Fill in XXX comments - -.. The audience for this document includes people who don't know anything - about Python and aren't about to learn the language just in order to - install and maintain it for their users, i.e. system administrators. - Thus, I have to be sure to explain the basics at some point: - sys.path and PYTHONPATH at least. Should probably give pointers to - other docs on "import site", PYTHONSTARTUP, PYTHONHOME, etc. - - Finally, it might be useful to include all the material from my "Care - and Feeding of a Python Installation" talk in here somewhere. Yow! - -.. topic:: Abstract - - This document describes the Python Distribution Utilities ("Distutils") from the - end-user's point-of-view, describing how to extend the capabilities of a - standard Python installation by building and installing third-party Python - modules and extensions. - - -.. _inst-intro: - -Introduction -============ - -Although Python's extensive standard library covers many programming needs, -there often comes a time when you need to add some new functionality to your -Python installation in the form of third-party modules. This might be necessary -to support your own programming, or to support an application that you want to -use and that happens to be written in Python. - -In the past, there has been little support for adding third-party modules to an -existing Python installation. With the introduction of the Python Distribution -Utilities (Distutils for short) in Python 2.0, this changed. - -This document is aimed primarily at the people who need to install third-party -Python modules: end-users and system administrators who just need to get some -Python application running, and existing Python programmers who want to add some -new goodies to their toolbox. You don't need to know Python to read this -document; there will be some brief forays into using Python's interactive mode -to explore your installation, but that's it. If you're looking for information -on how to distribute your own Python modules so that others may use them, see -the :ref:`distutils-index` manual. - - -.. _inst-trivial-install: - -Best case: trivial installation -------------------------------- - -In the best case, someone will have prepared a special version of the module -distribution you want to install that is targeted specifically at your platform -and is installed just like any other software on your platform. For example, -the module developer might make an executable installer available for Windows -users, an RPM package for users of RPM-based Linux systems (Red Hat, SuSE, -Mandrake, and many others), a Debian package for users of Debian-based Linux -systems, and so forth. - -In that case, you would download the installer appropriate to your platform and -do the obvious thing with it: run it if it's an executable installer, ``rpm ---install`` it if it's an RPM, etc. You don't need to run Python or a setup -script, you don't need to compile anything---you might not even need to read any -instructions (although it's always a good idea to do so anyway). - -Of course, things will not always be that easy. You might be interested in a -module distribution that doesn't have an easy-to-use installer for your -platform. In that case, you'll have to start with the source distribution -released by the module's author/maintainer. Installing from a source -distribution is not too hard, as long as the modules are packaged in the -standard way. The bulk of this document is about building and installing -modules from standard source distributions. - - -.. _inst-new-standard: - -The new standard: Distutils ---------------------------- - -If you download a module source distribution, you can tell pretty quickly if it -was packaged and distributed in the standard way, i.e. using the Distutils. -First, the distribution's name and version number will be featured prominently -in the name of the downloaded archive, e.g. :file:`foo-1.0.tar.gz` or -:file:`widget-0.9.7.zip`. Next, the archive will unpack into a similarly-named -directory: :file:`foo-1.0` or :file:`widget-0.9.7`. Additionally, the -distribution will contain a setup script :file:`setup.py`, and a file named -:file:`README.txt` or possibly just :file:`README`, which should explain that -building and installing the module distribution is a simple matter of running -one command from a terminal:: - - python setup.py install - -For Windows, this command should be run from a command prompt window -(:menuselection:`Start --> Accessories`):: - - setup.py install - -If all these things are true, then you already know how to build and install the -modules you've just downloaded: Run the command above. Unless you need to -install things in a non-standard way or customize the build process, you don't -really need this manual. Or rather, the above command is everything you need to -get out of this manual. - - -.. _inst-standard-install: - -Standard Build and Install -========================== - -As described in section :ref:`inst-new-standard`, building and installing a module -distribution using the Distutils is usually one simple command to run from a -terminal:: - - python setup.py install - - -.. _inst-platform-variations: - -Platform variations -------------------- - -You should always run the setup command from the distribution root directory, -i.e. the top-level subdirectory that the module source distribution unpacks -into. For example, if you've just downloaded a module source distribution -:file:`foo-1.0.tar.gz` onto a Unix system, the normal thing to do is:: - - gunzip -c foo-1.0.tar.gz | tar xf - # unpacks into directory foo-1.0 - cd foo-1.0 - python setup.py install - -On Windows, you'd probably download :file:`foo-1.0.zip`. If you downloaded the -archive file to :file:`C:\\Temp`, then it would unpack into -:file:`C:\\Temp\\foo-1.0`; you can use either a archive manipulator with a -graphical user interface (such as WinZip) or a command-line tool (such as -:program:`unzip` or :program:`pkunzip`) to unpack the archive. Then, open a -command prompt window and run:: - - cd c:\Temp\foo-1.0 - python setup.py install - - -.. _inst-splitting-up: - -Splitting the job up --------------------- - -Running ``setup.py install`` builds and installs all modules in one run. If you -prefer to work incrementally---especially useful if you want to customize the -build process, or if things are going wrong---you can use the setup script to do -one thing at a time. This is particularly helpful when the build and install -will be done by different users---for example, you might want to build a module -distribution and hand it off to a system administrator for installation (or do -it yourself, with super-user privileges). - -For example, you can build everything in one step, and then install everything -in a second step, by invoking the setup script twice:: - - python setup.py build - python setup.py install - -If you do this, you will notice that running the :command:`install` command -first runs the :command:`build` command, which---in this case---quickly notices -that it has nothing to do, since everything in the :file:`build` directory is -up-to-date. - -You may not need this ability to break things down often if all you do is -install modules downloaded off the 'net, but it's very handy for more advanced -tasks. If you get into distributing your own Python modules and extensions, -you'll run lots of individual Distutils commands on their own. - - -.. _inst-how-build-works: - -How building works ------------------- - -As implied above, the :command:`build` command is responsible for putting the -files to install into a *build directory*. By default, this is :file:`build` -under the distribution root; if you're excessively concerned with speed, or want -to keep the source tree pristine, you can change the build directory with the -:option:`--build-base` option. For example:: - - python setup.py build --build-base=/tmp/pybuild/foo-1.0 - -(Or you could do this permanently with a directive in your system or personal -Distutils configuration file; see section :ref:`inst-config-files`.) Normally, this -isn't necessary. - -The default layout for the build tree is as follows:: - - --- build/ --- lib/ - or - --- build/ --- lib./ - temp./ - -where ```` expands to a brief description of the current OS/hardware -platform and Python version. The first form, with just a :file:`lib` directory, -is used for "pure module distributions"---that is, module distributions that -include only pure Python modules. If a module distribution contains any -extensions (modules written in C/C++), then the second form, with two ```` -directories, is used. In that case, the :file:`temp.{plat}` directory holds -temporary files generated by the compile/link process that don't actually get -installed. In either case, the :file:`lib` (or :file:`lib.{plat}`) directory -contains all Python modules (pure Python and extensions) that will be installed. - -In the future, more directories will be added to handle Python scripts, -documentation, binary executables, and whatever else is needed to handle the job -of installing Python modules and applications. - - -.. _inst-how-install-works: - -How installation works ----------------------- - -After the :command:`build` command runs (whether you run it explicitly, or the -:command:`install` command does it for you), the work of the :command:`install` -command is relatively simple: all it has to do is copy everything under -:file:`build/lib` (or :file:`build/lib.{plat}`) to your chosen installation -directory. - -If you don't choose an installation directory---i.e., if you just run ``setup.py -install``\ ---then the :command:`install` command installs to the standard -location for third-party Python modules. This location varies by platform and -by how you built/installed Python itself. On Unix (and Mac OS X, which is also -Unix-based), it also depends on whether the module distribution being installed -is pure Python or contains extensions ("non-pure"): - -+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ -| Platform | Standard installation location | Default value | Notes | -+=================+=====================================================+==================================================+=======+ -| Unix (pure) | :file:`{prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | -+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ -| Unix (non-pure) | :file:`{exec-prefix}/lib/python{X.Y}/site-packages` | :file:`/usr/local/lib/python{X.Y}/site-packages` | \(1) | -+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ -| Windows | :file:`{prefix}\\Lib\\site-packages` | :file:`C:\\Python{XY}\\Lib\\site-packages` | \(2) | -+-----------------+-----------------------------------------------------+--------------------------------------------------+-------+ - -Notes: - -(1) - Most Linux distributions include Python as a standard part of the system, so - :file:`{prefix}` and :file:`{exec-prefix}` are usually both :file:`/usr` on - Linux. If you build Python yourself on Linux (or any Unix-like system), the - default :file:`{prefix}` and :file:`{exec-prefix}` are :file:`/usr/local`. - -(2) - The default installation directory on Windows was :file:`C:\\Program - Files\\Python` under Python 1.6a1, 1.5.2, and earlier. - -:file:`{prefix}` and :file:`{exec-prefix}` stand for the directories that Python -is installed to, and where it finds its libraries at run-time. They are always -the same under Windows, and very often the same under Unix and Mac OS X. You -can find out what your Python installation uses for :file:`{prefix}` and -:file:`{exec-prefix}` by running Python in interactive mode and typing a few -simple commands. Under Unix, just type ``python`` at the shell prompt. Under -Windows, choose :menuselection:`Start --> Programs --> Python X.Y --> -Python (command line)`. Once the interpreter is started, you type Python code -at the prompt. For example, on my Linux system, I type the three Python -statements shown below, and get the output as shown, to find out my -:file:`{prefix}` and :file:`{exec-prefix}`:: - - Python 2.4 (#26, Aug 7 2004, 17:19:02) - Type "help", "copyright", "credits" or "license" for more information. - >>> import sys - >>> sys.prefix - '/usr' - >>> sys.exec_prefix - '/usr' - -A few other placeholders are used in this document: :file:`{X.Y}` stands for the -version of Python, for example ``3.2``; :file:`{abiflags}` will be replaced by -the value of :data:`sys.abiflags` or the empty string for platforms which don't -define ABI flags; :file:`{distname}` will be replaced by the name of the module -distribution being installed. Dots and capitalization are important in the -paths; for example, a value that uses ``python3.2`` on UNIX will typically use -``Python32`` on Windows. - -If you don't want to install modules to the standard location, or if you don't -have permission to write there, then you need to read about alternate -installations in section :ref:`inst-alt-install`. If you want to customize your -installation directories more heavily, see section :ref:`inst-custom-install` on -custom installations. - - -.. _inst-alt-install: - -Alternate Installation -====================== - -Often, it is necessary or desirable to install modules to a location other than -the standard location for third-party Python modules. For example, on a Unix -system you might not have permission to write to the standard third-party module -directory. Or you might wish to try out a module before making it a standard -part of your local Python installation. This is especially true when upgrading -a distribution already present: you want to make sure your existing base of -scripts still works with the new version before actually upgrading. - -The Distutils :command:`install` command is designed to make installing module -distributions to an alternate location simple and painless. The basic idea is -that you supply a base directory for the installation, and the -:command:`install` command picks a set of directories (called an *installation -scheme*) under this base directory in which to install files. The details -differ across platforms, so read whichever of the following sections applies to -you. - -Note that the various alternate installation schemes are mutually exclusive: you -can pass ``--user``, or ``--home``, or ``--prefix`` and ``--exec-prefix``, or -``--install-base`` and ``--install-platbase``, but you can't mix from these -groups. - - -.. _inst-alt-install-user: - -Alternate installation: the user scheme ---------------------------------------- - -This scheme is designed to be the most convenient solution for users that don't -have write permission to the global site-packages directory or don't want to -install into it. It is enabled with a simple option:: - - python setup.py install --user - -Files will be installed into subdirectories of :data:`site.USER_BASE` (written -as :file:`{userbase}` hereafter). This scheme installs pure Python modules and -extension modules in the same location (also known as :data:`site.USER_SITE`). -Here are the values for UNIX, including Mac OS X: - -=============== =========================================================== -Type of file Installation directory -=============== =========================================================== -modules :file:`{userbase}/lib/python{X.Y}/site-packages` -scripts :file:`{userbase}/bin` -data :file:`{userbase}` -C headers :file:`{userbase}/include/python{X.Y}{abiflags}/{distname}` -=============== =========================================================== - -And here are the values used on Windows: - -=============== =========================================================== -Type of file Installation directory -=============== =========================================================== -modules :file:`{userbase}\\Python{XY}\\site-packages` -scripts :file:`{userbase}\\Scripts` -data :file:`{userbase}` -C headers :file:`{userbase}\\Python{XY}\\Include\\{distname}` -=============== =========================================================== - -The advantage of using this scheme compared to the other ones described below is -that the user site-packages directory is under normal conditions always included -in :data:`sys.path` (see :mod:`site` for more information), which means that -there is no additional step to perform after running the :file:`setup.py` script -to finalize the installation. - -The :command:`build_ext` command also has a ``--user`` option to add -:file:`{userbase}/include` to the compiler search path for header files and -:file:`{userbase}/lib` to the compiler search path for libraries as well as to -the runtime search path for shared C libraries (rpath). - - -.. _inst-alt-install-home: - -Alternate installation: the home scheme ---------------------------------------- - -The idea behind the "home scheme" is that you build and maintain a personal -stash of Python modules. This scheme's name is derived from the idea of a -"home" directory on Unix, since it's not unusual for a Unix user to make their -home directory have a layout similar to :file:`/usr/` or :file:`/usr/local/`. -This scheme can be used by anyone, regardless of the operating system they -are installing for. - -Installing a new module distribution is as simple as :: - - python setup.py install --home= - -where you can supply any directory you like for the :option:`--home` option. On -Unix, lazy typists can just type a tilde (``~``); the :command:`install` command -will expand this to your home directory:: - - python setup.py install --home=~ - -To make Python find the distributions installed with this scheme, you may have -to :ref:`modify Python's search path ` or edit -:mod:`sitecustomize` (see :mod:`site`) to call :func:`site.addsitedir` or edit -:data:`sys.path`. - -The :option:`--home` option defines the installation base directory. Files are -installed to the following directories under the installation base as follows: - -=============== =========================================================== -Type of file Installation directory -=============== =========================================================== -modules :file:`{home}/lib/python` -scripts :file:`{home}/bin` -data :file:`{home}` -C headers :file:`{home}/include/python/{distname}` -=============== =========================================================== - -(Mentally replace slashes with backslashes if you're on Windows.) - - -.. _inst-alt-install-prefix-unix: - -Alternate installation: Unix (the prefix scheme) ------------------------------------------------- - -The "prefix scheme" is useful when you wish to use one Python installation to -perform the build/install (i.e., to run the setup script), but install modules -into the third-party module directory of a different Python installation (or -something that looks like a different Python installation). If this sounds a -trifle unusual, it is---that's why the user and home schemes come before. However, -there are at least two known cases where the prefix scheme will be useful. - -First, consider that many Linux distributions put Python in :file:`/usr`, rather -than the more traditional :file:`/usr/local`. This is entirely appropriate, -since in those cases Python is part of "the system" rather than a local add-on. -However, if you are installing Python modules from source, you probably want -them to go in :file:`/usr/local/lib/python2.{X}` rather than -:file:`/usr/lib/python2.{X}`. This can be done with :: - - /usr/bin/python setup.py install --prefix=/usr/local - -Another possibility is a network filesystem where the name used to write to a -remote directory is different from the name used to read it: for example, the -Python interpreter accessed as :file:`/usr/local/bin/python` might search for -modules in :file:`/usr/local/lib/python2.{X}`, but those modules would have to -be installed to, say, :file:`/mnt/{@server}/export/lib/python2.{X}`. This could -be done with :: - - /usr/local/bin/python setup.py install --prefix=/mnt/@server/export - -In either case, the :option:`--prefix` option defines the installation base, and -the :option:`--exec-prefix` option defines the platform-specific installation -base, which is used for platform-specific files. (Currently, this just means -non-pure module distributions, but could be expanded to C libraries, binary -executables, etc.) If :option:`--exec-prefix` is not supplied, it defaults to -:option:`--prefix`. Files are installed as follows: - -================= ========================================================== -Type of file Installation directory -================= ========================================================== -Python modules :file:`{prefix}/lib/python{X.Y}/site-packages` -extension modules :file:`{exec-prefix}/lib/python{X.Y}/site-packages` -scripts :file:`{prefix}/bin` -data :file:`{prefix}` -C headers :file:`{prefix}/include/python{X.Y}{abiflags}/{distname}` -================= ========================================================== - -There is no requirement that :option:`--prefix` or :option:`--exec-prefix` -actually point to an alternate Python installation; if the directories listed -above do not already exist, they are created at installation time. - -Incidentally, the real reason the prefix scheme is important is simply that a -standard Unix installation uses the prefix scheme, but with :option:`--prefix` -and :option:`--exec-prefix` supplied by Python itself as ``sys.prefix`` and -``sys.exec_prefix``. Thus, you might think you'll never use the prefix scheme, -but every time you run ``python setup.py install`` without any other options, -you're using it. - -Note that installing extensions to an alternate Python installation has no -effect on how those extensions are built: in particular, the Python header files -(:file:`Python.h` and friends) installed with the Python interpreter used to run -the setup script will be used in compiling extensions. It is your -responsibility to ensure that the interpreter used to run extensions installed -in this way is compatible with the interpreter used to build them. The best way -to do this is to ensure that the two interpreters are the same version of Python -(possibly different builds, or possibly copies of the same build). (Of course, -if your :option:`--prefix` and :option:`--exec-prefix` don't even point to an -alternate Python installation, this is immaterial.) - - -.. _inst-alt-install-prefix-windows: - -Alternate installation: Windows (the prefix scheme) ---------------------------------------------------- - -Windows has no concept of a user's home directory, and since the standard Python -installation under Windows is simpler than under Unix, the :option:`--prefix` -option has traditionally been used to install additional packages in separate -locations on Windows. :: - - python setup.py install --prefix="\Temp\Python" - -to install modules to the :file:`\\Temp\\Python` directory on the current drive. - -The installation base is defined by the :option:`--prefix` option; the -:option:`--exec-prefix` option is not supported under Windows, which means that -pure Python modules and extension modules are installed into the same location. -Files are installed as follows: - -=============== ========================================================== -Type of file Installation directory -=============== ========================================================== -modules :file:`{prefix}\\Lib\\site-packages` -scripts :file:`{prefix}\\Scripts` -data :file:`{prefix}` -C headers :file:`{prefix}\\Include\\{distname}` -=============== ========================================================== - - -.. _inst-custom-install: - -Custom Installation -=================== - -Sometimes, the alternate installation schemes described in section -:ref:`inst-alt-install` just don't do what you want. You might want to tweak just -one or two directories while keeping everything under the same base directory, -or you might want to completely redefine the installation scheme. In either -case, you're creating a *custom installation scheme*. - -To create a custom installation scheme, you start with one of the alternate -schemes and override some of the installation directories used for the various -types of files, using these options: - -====================== ======================= -Type of file Override option -====================== ======================= -Python modules ``--install-purelib`` -extension modules ``--install-platlib`` -all modules ``--install-lib`` -scripts ``--install-scripts`` -data ``--install-data`` -C headers ``--install-headers`` -====================== ======================= - -These override options can be relative, absolute, -or explicitly defined in terms of one of the installation base directories. -(There are two installation base directories, and they are normally the same--- -they only differ when you use the Unix "prefix scheme" and supply different -``--prefix`` and ``--exec-prefix`` options; using ``--install-lib`` will -override values computed or given for ``--install-purelib`` and -``--install-platlib``, and is recommended for schemes that don't make a -difference between Python and extension modules.) - -For example, say you're installing a module distribution to your home directory -under Unix---but you want scripts to go in :file:`~/scripts` rather than -:file:`~/bin`. As you might expect, you can override this directory with the -:option:`--install-scripts` option; in this case, it makes most sense to supply -a relative path, which will be interpreted relative to the installation base -directory (your home directory, in this case):: - - python setup.py install --home=~ --install-scripts=scripts - -Another Unix example: suppose your Python installation was built and installed -with a prefix of :file:`/usr/local/python`, so under a standard installation -scripts will wind up in :file:`/usr/local/python/bin`. If you want them in -:file:`/usr/local/bin` instead, you would supply this absolute directory for the -:option:`--install-scripts` option:: - - python setup.py install --install-scripts=/usr/local/bin - -(This performs an installation using the "prefix scheme," where the prefix is -whatever your Python interpreter was installed with--- :file:`/usr/local/python` -in this case.) - -If you maintain Python on Windows, you might want third-party modules to live in -a subdirectory of :file:`{prefix}`, rather than right in :file:`{prefix}` -itself. This is almost as easy as customizing the script installation directory ----you just have to remember that there are two types of modules to worry about, -Python and extension modules, which can conveniently be both controlled by one -option:: - - python setup.py install --install-lib=Site - -The specified installation directory is relative to :file:`{prefix}`. Of -course, you also have to ensure that this directory is in Python's module -search path, such as by putting a :file:`.pth` file in a site directory (see -:mod:`site`). See section :ref:`inst-search-path` to find out how to modify -Python's search path. - -If you want to define an entire installation scheme, you just have to supply all -of the installation directory options. The recommended way to do this is to -supply relative paths; for example, if you want to maintain all Python -module-related files under :file:`python` in your home directory, and you want a -separate directory for each platform that you use your home directory from, you -might define the following installation scheme:: - - python setup.py install --home=~ \ - --install-purelib=python/lib \ - --install-platlib=python/lib.$PLAT \ - --install-scripts=python/scripts - --install-data=python/data - -or, equivalently, :: - - python setup.py install --home=~/python \ - --install-purelib=lib \ - --install-platlib='lib.$PLAT' \ - --install-scripts=scripts - --install-data=data - -``$PLAT`` is not (necessarily) an environment variable---it will be expanded by -the Distutils as it parses your command line options, just as it does when -parsing your configuration file(s). - -Obviously, specifying the entire installation scheme every time you install a -new module distribution would be very tedious. Thus, you can put these options -into your Distutils config file (see section :ref:`inst-config-files`):: - - [install] - install-base=$HOME - install-purelib=python/lib - install-platlib=python/lib.$PLAT - install-scripts=python/scripts - install-data=python/data - -or, equivalently, :: - - [install] - install-base=$HOME/python - install-purelib=lib - install-platlib=lib.$PLAT - install-scripts=scripts - install-data=data - -Note that these two are *not* equivalent if you supply a different installation -base directory when you run the setup script. For example, :: - - python setup.py install --install-base=/tmp - -would install pure modules to :file:`/tmp/python/lib` in the first case, and -to :file:`/tmp/lib` in the second case. (For the second case, you probably -want to supply an installation base of :file:`/tmp/python`.) - -You probably noticed the use of ``$HOME`` and ``$PLAT`` in the sample -configuration file input. These are Distutils configuration variables, which -bear a strong resemblance to environment variables. In fact, you can use -environment variables in config files on platforms that have such a notion but -the Distutils additionally define a few extra variables that may not be in your -environment, such as ``$PLAT``. (And of course, on systems that don't have -environment variables, such as Mac OS 9, the configuration variables supplied by -the Distutils are the only ones you can use.) See section :ref:`inst-config-files` -for details. - -.. XXX need some Windows examples---when would custom installation schemes be - needed on those platforms? - - -.. XXX Move this to Doc/using - -.. _inst-search-path: - -Modifying Python's Search Path ------------------------------- - -When the Python interpreter executes an :keyword:`import` statement, it searches -for both Python code and extension modules along a search path. A default value -for the path is configured into the Python binary when the interpreter is built. -You can determine the path by importing the :mod:`sys` module and printing the -value of ``sys.path``. :: - - $ python - Python 2.2 (#11, Oct 3 2002, 13:31:27) - [GCC 2.96 20000731 (Red Hat Linux 7.3 2.96-112)] on linux2 - Type "help", "copyright", "credits" or "license" for more information. - >>> import sys - >>> sys.path - ['', '/usr/local/lib/python2.3', '/usr/local/lib/python2.3/plat-linux2', - '/usr/local/lib/python2.3/lib-tk', '/usr/local/lib/python2.3/lib-dynload', - '/usr/local/lib/python2.3/site-packages'] - >>> - -The null string in ``sys.path`` represents the current working directory. - -The expected convention for locally installed packages is to put them in the -:file:`{...}/site-packages/` directory, but you may want to install Python -modules into some arbitrary directory. For example, your site may have a -convention of keeping all software related to the web server under :file:`/www`. -Add-on Python modules might then belong in :file:`/www/python`, and in order to -import them, this directory must be added to ``sys.path``. There are several -different ways to add the directory. - -The most convenient way is to add a path configuration file to a directory -that's already on Python's path, usually to the :file:`.../site-packages/` -directory. Path configuration files have an extension of :file:`.pth`, and each -line must contain a single path that will be appended to ``sys.path``. (Because -the new paths are appended to ``sys.path``, modules in the added directories -will not override standard modules. This means you can't use this mechanism for -installing fixed versions of standard modules.) - -Paths can be absolute or relative, in which case they're relative to the -directory containing the :file:`.pth` file. See the documentation of -the :mod:`site` module for more information. - -A slightly less convenient way is to edit the :file:`site.py` file in Python's -standard library, and modify ``sys.path``. :file:`site.py` is automatically -imported when the Python interpreter is executed, unless the :option:`-S` switch -is supplied to suppress this behaviour. So you could simply edit -:file:`site.py` and add two lines to it:: - - import sys - sys.path.append('/www/python/') - -However, if you reinstall the same major version of Python (perhaps when -upgrading from 2.2 to 2.2.2, for example) :file:`site.py` will be overwritten by -the stock version. You'd have to remember that it was modified and save a copy -before doing the installation. - -There are two environment variables that can modify ``sys.path``. -:envvar:`PYTHONHOME` sets an alternate value for the prefix of the Python -installation. For example, if :envvar:`PYTHONHOME` is set to ``/www/python``, -the search path will be set to ``['', '/www/python/lib/pythonX.Y/', -'/www/python/lib/pythonX.Y/plat-linux2', ...]``. - -The :envvar:`PYTHONPATH` variable can be set to a list of paths that will be -added to the beginning of ``sys.path``. For example, if :envvar:`PYTHONPATH` is -set to ``/www/python:/opt/py``, the search path will begin with -``['/www/python', '/opt/py']``. (Note that directories must exist in order to -be added to ``sys.path``; the :mod:`site` module removes paths that don't -exist.) - -Finally, ``sys.path`` is just a regular Python list, so any Python application -can modify it by adding or removing entries. - - -.. _inst-config-files: - -Distutils Configuration Files -============================= - -As mentioned above, you can use Distutils configuration files to record personal -or site preferences for any Distutils options. That is, any option to any -command can be stored in one of two or three (depending on your platform) -configuration files, which will be consulted before the command-line is parsed. -This means that configuration files will override default values, and the -command-line will in turn override configuration files. Furthermore, if -multiple configuration files apply, values from "earlier" files are overridden -by "later" files. - - -.. _inst-config-filenames: - -Location and names of config files ----------------------------------- - -The names and locations of the configuration files vary slightly across -platforms. On Unix and Mac OS X, the three configuration files (in the order -they are processed) are: - -+--------------+----------------------------------------------------------+-------+ -| Type of file | Location and filename | Notes | -+==============+==========================================================+=======+ -| system | :file:`{prefix}/lib/python{ver}/distutils/distutils.cfg` | \(1) | -+--------------+----------------------------------------------------------+-------+ -| personal | :file:`$HOME/.pydistutils.cfg` | \(2) | -+--------------+----------------------------------------------------------+-------+ -| local | :file:`setup.cfg` | \(3) | -+--------------+----------------------------------------------------------+-------+ - -And on Windows, the configuration files are: - -+--------------+-------------------------------------------------+-------+ -| Type of file | Location and filename | Notes | -+==============+=================================================+=======+ -| system | :file:`{prefix}\\Lib\\distutils\\distutils.cfg` | \(4) | -+--------------+-------------------------------------------------+-------+ -| personal | :file:`%HOME%\\pydistutils.cfg` | \(5) | -+--------------+-------------------------------------------------+-------+ -| local | :file:`setup.cfg` | \(3) | -+--------------+-------------------------------------------------+-------+ - -On all platforms, the "personal" file can be temporarily disabled by -passing the `--no-user-cfg` option. - -Notes: - -(1) - Strictly speaking, the system-wide configuration file lives in the directory - where the Distutils are installed; under Python 1.6 and later on Unix, this is - as shown. For Python 1.5.2, the Distutils will normally be installed to - :file:`{prefix}/lib/python1.5/site-packages/distutils`, so the system - configuration file should be put there under Python 1.5.2. - -(2) - On Unix, if the :envvar:`HOME` environment variable is not defined, the user's - home directory will be determined with the :func:`getpwuid` function from the - standard :mod:`pwd` module. This is done by the :func:`os.path.expanduser` - function used by Distutils. - -(3) - I.e., in the current directory (usually the location of the setup script). - -(4) - (See also note (1).) Under Python 1.6 and later, Python's default "installation - prefix" is :file:`C:\\Python`, so the system configuration file is normally - :file:`C:\\Python\\Lib\\distutils\\distutils.cfg`. Under Python 1.5.2, the - default prefix was :file:`C:\\Program Files\\Python`, and the Distutils were not - part of the standard library---so the system configuration file would be - :file:`C:\\Program Files\\Python\\distutils\\distutils.cfg` in a standard Python - 1.5.2 installation under Windows. - -(5) - On Windows, if the :envvar:`HOME` environment variable is not defined, - :envvar:`USERPROFILE` then :envvar:`HOMEDRIVE` and :envvar:`HOMEPATH` will - be tried. This is done by the :func:`os.path.expanduser` function used - by Distutils. - - -.. _inst-config-syntax: - -Syntax of config files ----------------------- - -The Distutils configuration files all have the same syntax. The config files -are grouped into sections. There is one section for each Distutils command, -plus a ``global`` section for global options that affect every command. Each -section consists of one option per line, specified as ``option=value``. - -For example, the following is a complete config file that just forces all -commands to run quietly by default:: - - [global] - verbose=0 - -If this is installed as the system config file, it will affect all processing of -any Python module distribution by any user on the current system. If it is -installed as your personal config file (on systems that support them), it will -affect only module distributions processed by you. And if it is used as the -:file:`setup.cfg` for a particular module distribution, it affects only that -distribution. - -You could override the default "build base" directory and make the -:command:`build\*` commands always forcibly rebuild all files with the -following:: - - [build] - build-base=blib - force=1 - -which corresponds to the command-line arguments :: - - python setup.py build --build-base=blib --force - -except that including the :command:`build` command on the command-line means -that command will be run. Including a particular command in config files has no -such implication; it only means that if the command is run, the options in the -config file will apply. (Or if other commands that derive values from it are -run, they will use the values in the config file.) - -You can find out the complete list of options for any command using the -:option:`--help` option, e.g.:: - - python setup.py build --help - -and you can find out the complete list of global options by using -:option:`--help` without a command:: - - python setup.py --help - -See also the "Reference" section of the "Distributing Python Modules" manual. - - -.. _inst-building-ext: - -Building Extensions: Tips and Tricks -==================================== - -Whenever possible, the Distutils try to use the configuration information made -available by the Python interpreter used to run the :file:`setup.py` script. -For example, the same compiler and linker flags used to compile Python will also -be used for compiling extensions. Usually this will work well, but in -complicated situations this might be inappropriate. This section discusses how -to override the usual Distutils behaviour. - - -.. _inst-tweak-flags: - -Tweaking compiler/linker flags ------------------------------- - -Compiling a Python extension written in C or C++ will sometimes require -specifying custom flags for the compiler and linker in order to use a particular -library or produce a special kind of object code. This is especially true if the -extension hasn't been tested on your platform, or if you're trying to -cross-compile Python. - -In the most general case, the extension author might have foreseen that -compiling the extensions would be complicated, and provided a :file:`Setup` file -for you to edit. This will likely only be done if the module distribution -contains many separate extension modules, or if they often require elaborate -sets of compiler flags in order to work. - -A :file:`Setup` file, if present, is parsed in order to get a list of extensions -to build. Each line in a :file:`Setup` describes a single module. Lines have -the following structure:: - - module ... [sourcefile ...] [cpparg ...] [library ...] - - -Let's examine each of the fields in turn. - -* *module* is the name of the extension module to be built, and should be a - valid Python identifier. You can't just change this in order to rename a module - (edits to the source code would also be needed), so this should be left alone. - -* *sourcefile* is anything that's likely to be a source code file, at least - judging by the filename. Filenames ending in :file:`.c` are assumed to be - written in C, filenames ending in :file:`.C`, :file:`.cc`, and :file:`.c++` are - assumed to be C++, and filenames ending in :file:`.m` or :file:`.mm` are assumed - to be in Objective C. - -* *cpparg* is an argument for the C preprocessor, and is anything starting with - :option:`-I`, :option:`-D`, :option:`-U` or :option:`-C`. - -* *library* is anything ending in :file:`.a` or beginning with :option:`-l` or - :option:`-L`. - -If a particular platform requires a special library on your platform, you can -add it by editing the :file:`Setup` file and running ``python setup.py build``. -For example, if the module defined by the line :: - - foo foomodule.c - -must be linked with the math library :file:`libm.a` on your platform, simply add -:option:`-lm` to the line:: - - foo foomodule.c -lm - -Arbitrary switches intended for the compiler or the linker can be supplied with -the :option:`-Xcompiler` *arg* and :option:`-Xlinker` *arg* options:: - - foo foomodule.c -Xcompiler -o32 -Xlinker -shared -lm - -The next option after :option:`-Xcompiler` and :option:`-Xlinker` will be -appended to the proper command line, so in the above example the compiler will -be passed the :option:`-o32` option, and the linker will be passed -:option:`-shared`. If a compiler option requires an argument, you'll have to -supply multiple :option:`-Xcompiler` options; for example, to pass ``-x c++`` -the :file:`Setup` file would have to contain ``-Xcompiler -x -Xcompiler c++``. - -Compiler flags can also be supplied through setting the :envvar:`CFLAGS` -environment variable. If set, the contents of :envvar:`CFLAGS` will be added to -the compiler flags specified in the :file:`Setup` file. - - -.. _inst-non-ms-compilers: - -Using non-Microsoft compilers on Windows ----------------------------------------- - -.. sectionauthor:: Rene Liebscher - - - -Borland/CodeGear C++ -^^^^^^^^^^^^^^^^^^^^ - -This subsection describes the necessary steps to use Distutils with the Borland -C++ compiler version 5.5. First you have to know that Borland's object file -format (OMF) is different from the format used by the Python version you can -download from the Python or ActiveState Web site. (Python is built with -Microsoft Visual C++, which uses COFF as the object file format.) For this -reason you have to convert Python's library :file:`python25.lib` into the -Borland format. You can do this as follows: - -.. Should we mention that users have to create cfg-files for the compiler? -.. see also http://community.borland.com/article/0,1410,21205,00.html - -:: - - coff2omf python25.lib python25_bcpp.lib - -The :file:`coff2omf` program comes with the Borland compiler. The file -:file:`python25.lib` is in the :file:`Libs` directory of your Python -installation. If your extension uses other libraries (zlib, ...) you have to -convert them too. - -The converted files have to reside in the same directories as the normal -libraries. - -How does Distutils manage to use these libraries with their changed names? If -the extension needs a library (eg. :file:`foo`) Distutils checks first if it -finds a library with suffix :file:`_bcpp` (eg. :file:`foo_bcpp.lib`) and then -uses this library. In the case it doesn't find such a special library it uses -the default name (:file:`foo.lib`.) [#]_ - -To let Distutils compile your extension with Borland C++ you now have to type:: - - python setup.py build --compiler=bcpp - -If you want to use the Borland C++ compiler as the default, you could specify -this in your personal or system-wide configuration file for Distutils (see -section :ref:`inst-config-files`.) - - -.. seealso:: - - `C++Builder Compiler `_ - Information about the free C++ compiler from Borland, including links to the - download pages. - - `Creating Python Extensions Using Borland's Free Compiler `_ - Document describing how to use Borland's free command-line C++ compiler to build - Python. - - -GNU C / Cygwin / MinGW -^^^^^^^^^^^^^^^^^^^^^^ - -This section describes the necessary steps to use Distutils with the GNU C/C++ -compilers in their Cygwin and MinGW distributions. [#]_ For a Python interpreter -that was built with Cygwin, everything should work without any of these -following steps. - -Not all extensions can be built with MinGW or Cygwin, but many can. Extensions -most likely to not work are those that use C++ or depend on Microsoft Visual C -extensions. - -To let Distutils compile your extension with Cygwin you have to type:: - - python setup.py build --compiler=cygwin - -and for Cygwin in no-cygwin mode [#]_ or for MinGW type:: - - python setup.py build --compiler=mingw32 - -If you want to use any of these options/compilers as default, you should -consider writing it in your personal or system-wide configuration file for -Distutils (see section :ref:`inst-config-files`.) - -Older Versions of Python and MinGW -"""""""""""""""""""""""""""""""""" -The following instructions only apply if you're using a version of Python -inferior to 2.4.1 with a MinGW inferior to 3.0.0 (with -binutils-2.13.90-20030111-1). - -These compilers require some special libraries. This task is more complex than -for Borland's C++, because there is no program to convert the library. First -you have to create a list of symbols which the Python DLL exports. (You can find -a good program for this task at -http://www.emmestech.com/software/pexports-0.43/download_pexports.html). - -.. I don't understand what the next line means. --amk -.. (inclusive the references on data structures.) - -:: - - pexports python25.dll >python25.def - -The location of an installed :file:`python25.dll` will depend on the -installation options and the version and language of Windows. In a "just for -me" installation, it will appear in the root of the installation directory. In -a shared installation, it will be located in the system directory. - -Then you can create from these information an import library for gcc. :: - - /cygwin/bin/dlltool --dllname python25.dll --def python25.def --output-lib libpython25.a - -The resulting library has to be placed in the same directory as -:file:`python25.lib`. (Should be the :file:`libs` directory under your Python -installation directory.) - -If your extension uses other libraries (zlib,...) you might have to convert -them too. The converted files have to reside in the same directories as the -normal libraries do. - - -.. seealso:: - - `Building Python modules on MS Windows platform with MinGW `_ - Information about building the required libraries for the MinGW environment. - - -.. rubric:: Footnotes - -.. [#] This also means you could replace all existing COFF-libraries with OMF-libraries - of the same name. - -.. [#] Check http://sources.redhat.com/cygwin/ and http://www.mingw.org/ for more - information - -.. [#] Then you have no POSIX emulation available, but you also don't need - :file:`cygwin1.dll`. From 48d6907c3d2dcdc29f5d3d81e67686a7d37cb730 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Mon, 2 Jul 2012 17:46:40 -0400 Subject: [PATCH 229/330] Adapt mentions of future changes in doc --- sourcedist.rst | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index a9858d01bf..b1695a2585 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -51,8 +51,7 @@ Notes: of the standard Python library since Python 1.6) (4) - requires the :program:`compress` program. Notice that this format is now - pending for deprecation and will be removed in the future versions of Python. + requires the :program:`compress` program. When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or ``tar``) under Unix, you can specify the ``owner`` and ``group`` names From 0c3f26427f11650f243b40296f238a71aeedb2ec Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Tue, 3 Jul 2012 01:12:42 -0400 Subject: [PATCH 230/330] Ignore .nfs* files in distutils (#7719). These files are created by some NFS clients a file is edited and removed concurrently (see added link in doc for more info). If such a file is removed between distutils calls listdir and copy, it will get confused. Other special files are ignored in sdist (namely VCS directories), but this has to be filtered out earlier. --- apiref.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index ba4fc9f5a5..60c0dd8fe7 100644 --- a/apiref.rst +++ b/apiref.rst @@ -973,8 +973,8 @@ directories. Copy an entire directory tree *src* to a new location *dst*. Both *src* and *dst* must be directory names. If *src* is not a directory, raise :exc:`DistutilsFileError`. If *dst* does not exist, it is created with - :func:`mkpath`. The end result of the copy is that every file in *src* is - copied to *dst*, and directories under *src* are recursively copied to *dst*. + :func:`mkpath`. The end result of the copy is that every file in *src* is + copied to *dst*, and directories under *src* are recursively copied to *dst*. Return the list of files that were copied or might have been copied, using their output name. The return value is unaffected by *update* or *dry_run*: it is simply the list of all files under *src*, with the names changed to be under @@ -987,6 +987,10 @@ directories. destination of the symlink will be copied. *update* and *verbose* are the same as for :func:`copy_file`. + Files in *src* that begin with :file:`.nfs` are skipped (more information on + these files is available in answer D2 of the `NFS FAQ page + `_. + .. function:: remove_tree(directory[, verbose=0, dry_run=0]) From 95d02d486f38c16fea5723e7454f072d95ceea7e Mon Sep 17 00:00:00 2001 From: Eli Bendersky Date: Tue, 24 Jul 2012 19:51:06 +0300 Subject: [PATCH 231/330] Issue #15321: update PyPI upload doc to say --no-raw passed to rst2html.py. Patch by Chris Jerdonek --- uploading.rst | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/uploading.rst b/uploading.rst index 1b3cb589ec..dc1025fdc0 100644 --- a/uploading.rst +++ b/uploading.rst @@ -73,4 +73,6 @@ check the ``long_description`` from the command line:: $ python setup.py --long-description | rst2html.py > output.html :mod:`docutils` will display a warning if there's something wrong with your -syntax. +syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` +to ``rst2html.py`` in the command above), running the command above without +warnings is not sufficient for PyPI to convert the content successfully. From f72e7183e7d2365b4e929462504afb48552a5817 Mon Sep 17 00:00:00 2001 From: Eli Bendersky Date: Tue, 31 Jul 2012 06:14:59 +0300 Subject: [PATCH 232/330] Issue #15231: rephrase the last paragraph slightly --- uploading.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/uploading.rst b/uploading.rst index dc1025fdc0..bfb392e3b6 100644 --- a/uploading.rst +++ b/uploading.rst @@ -74,5 +74,7 @@ check the ``long_description`` from the command line:: :mod:`docutils` will display a warning if there's something wrong with your syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` -to ``rst2html.py`` in the command above), running the command above without -warnings is not sufficient for PyPI to convert the content successfully. +to ``rst2html.py`` in the command above), being able to run the command above +without warnings does not guarantee that PyPI will convert the content +successfully. + From 2e857c403090c9427100bf90462c0dbd05c22f62 Mon Sep 17 00:00:00 2001 From: Eli Bendersky Date: Thu, 2 Aug 2012 02:56:39 +0300 Subject: [PATCH 233/330] Issue #15321: update PyPI upload doc to say --no-raw passed to rst2html.py --- uploading.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/uploading.rst b/uploading.rst index 1b3cb589ec..bfb392e3b6 100644 --- a/uploading.rst +++ b/uploading.rst @@ -73,4 +73,8 @@ check the ``long_description`` from the command line:: $ python setup.py --long-description | rst2html.py > output.html :mod:`docutils` will display a warning if there's something wrong with your -syntax. +syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` +to ``rst2html.py`` in the command above), being able to run the command above +without warnings does not guarantee that PyPI will convert the content +successfully. + From 5f644fdab8835e236cdeb880cdef011a0225239e Mon Sep 17 00:00:00 2001 From: Eli Bendersky Date: Thu, 2 Aug 2012 03:00:33 +0300 Subject: [PATCH 234/330] Issue #15231: update PyPI upload doc to say --no-raw passed to rst2html.py --- uploading.rst | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/uploading.rst b/uploading.rst index 936402b5ba..12ee32856e 100644 --- a/uploading.rst +++ b/uploading.rst @@ -74,4 +74,9 @@ and check the ``long_description`` from the command line:: $ python setup.py --long-description | rst2html.py > output.html -:mod:`docutils` will display a warning if there's something wrong with your syntax. +:mod:`docutils` will display a warning if there's something wrong with your +syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` +to ``rst2html.py`` in the command above), being able to run the command above +without warnings does not guarantee that PyPI will convert the content +successfully. + From f6a6d6c5a9882761cf58016b1caefd7905b16b17 Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Sun, 28 Oct 2012 11:08:26 -0700 Subject: [PATCH 235/330] Remove unneeded "Release" and "Date" markers from doc index pages. --- index.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/index.rst b/index.rst index ace8280894..ebb48f3377 100644 --- a/index.rst +++ b/index.rst @@ -6,8 +6,6 @@ :Authors: Greg Ward, Anthony Baxter :Email: distutils-sig@python.org -:Release: |version| -:Date: |today| This document describes the Python Distribution Utilities ("Distutils") from the module developer's point of view, describing how to use the Distutils to From 20a1edeb670de01a09140d6e367c106030cda7ea Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Sun, 28 Oct 2012 11:16:36 -0700 Subject: [PATCH 236/330] Backport from 3.2: remove "Release" and "Date" markers from index pages. --- index.rst | 2 -- 1 file changed, 2 deletions(-) diff --git a/index.rst b/index.rst index ace8280894..ebb48f3377 100644 --- a/index.rst +++ b/index.rst @@ -6,8 +6,6 @@ :Authors: Greg Ward, Anthony Baxter :Email: distutils-sig@python.org -:Release: |version| -:Date: |today| This document describes the Python Distribution Utilities ("Distutils") from the module developer's point of view, describing how to use the Distutils to From 4494dd68b941d46096f059d1f719675d0ee92b49 Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Wed, 14 Nov 2012 12:12:30 -0800 Subject: [PATCH 237/330] Update the description of which package versions PyPI displays (issue #16400). --- packageindex.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index 1498394481..9fc18c1b89 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -43,9 +43,9 @@ the web interface. They may also designate other users as Owners or Maintainers. Maintainers may edit the package information, but not designate other Owners or Maintainers. -By default PyPI will list all versions of a given package. To hide certain -versions, the Hidden property should be set to yes. This must be edited through -the web interface. +By default PyPI displays only the newest version of a given package. The web +interface lets one change this default behavior and manually select which +versions to display and hide. .. _pypirc: From e2670a23062667da7ebf2ee2d9fecb0808a7632c Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Wed, 14 Nov 2012 12:36:53 -0800 Subject: [PATCH 238/330] Backport from 3.2: update PyPI docs regarding listing versions (issue #16400). --- packageindex.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index 1498394481..9fc18c1b89 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -43,9 +43,9 @@ the web interface. They may also designate other users as Owners or Maintainers. Maintainers may edit the package information, but not designate other Owners or Maintainers. -By default PyPI will list all versions of a given package. To hide certain -versions, the Hidden property should be set to yes. This must be edited through -the web interface. +By default PyPI displays only the newest version of a given package. The web +interface lets one change this default behavior and manually select which +versions to display and hide. .. _pypirc: From d596ba93c6cf422d7d40313bb8ab6dd8564cdd07 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 8 Dec 2012 14:18:26 -0500 Subject: [PATCH 239/330] Add versionchanged note for a56cebff113a --- apiref.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/apiref.rst b/apiref.rst index 60c0dd8fe7..76567ad735 100644 --- a/apiref.rst +++ b/apiref.rst @@ -991,6 +991,9 @@ directories. these files is available in answer D2 of the `NFS FAQ page `_. + .. versionchanged:: 2.7.4 + NFS files are ignored. + .. function:: remove_tree(directory[, verbose=0, dry_run=0]) From 2837ed9ca53dd4f885106ec4603616ced142944f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Sat, 8 Dec 2012 14:21:51 -0500 Subject: [PATCH 240/330] Ignore .nfs* files in distutils (#7719). These files are created by some NFS clients a file is edited and removed concurrently (see added link in doc for more info). If such a file is removed between distutils calls listdir and copy, it will get confused. Other special files are ignored in sdist (namely VCS directories), but this has to be filtered out earlier. --- apiref.rst | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/apiref.rst b/apiref.rst index e15dc76c83..74fba4ada7 100644 --- a/apiref.rst +++ b/apiref.rst @@ -992,6 +992,12 @@ directories. destination of the symlink will be copied. *update* and *verbose* are the same as for :func:`copy_file`. + Files in *src* that begin with :file:`.nfs` are skipped (more information on + these files is available in answer D2 of the `NFS FAQ page + `_. + + .. versionchanged:: 3.2.4 + NFS files are ignored. .. function:: remove_tree(directory[, verbose=0, dry_run=0]) From bcc4ddad07400965c20e4ea5bc19fa07dfc9aaf2 Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Thu, 10 Jan 2013 22:50:40 -0800 Subject: [PATCH 241/330] Issue #16874: fix formatting of setup.py upload options in documentation. --- uploading.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/uploading.rst b/uploading.rst index 12ee32856e..89ca560a68 100644 --- a/uploading.rst +++ b/uploading.rst @@ -27,21 +27,21 @@ and if the password was entered in the prompt, :command:`upload` will reuse the entered password. This is useful if you do not want to store a clear text password in the :file:`$HOME/.pypirc` file. -You can specify another PyPI server with the :option:`--repository=*url*` option:: +You can specify another PyPI server with the ``--repository=url`` option:: python setup.py sdist bdist_wininst upload -r http://example.com/pypi See section :ref:`pypirc` for more on defining several servers. -You can use the :option:`--sign` option to tell :command:`upload` to sign each +You can use the ``--sign`` option to tell :command:`upload` to sign each uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must be available for execution on the system :envvar:`PATH`. You can also specify -which key to use for signing using the :option:`--identity=*name*` option. +which key to use for signing using the ``--identity=name`` option. -Other :command:`upload` options include :option:`--repository=` or -:option:`--repository=
` where *url* is the url of the server and +Other :command:`upload` options include ``--repository=url`` or +``--repository=section`` where *url* is the url of the server and *section* the name of the section in :file:`$HOME/.pypirc`, and -:option:`--show-response` (which displays the full response text from the PyPI +``--show-response`` (which displays the full response text from the PyPI server for help in debugging upload problems). PyPI package display From 89f1afebfa1a76cd8416fd523461497228767c0b Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Thu, 10 Jan 2013 23:01:27 -0800 Subject: [PATCH 242/330] Issue #16874 (forward-port from 2.7): fix some documentation formatting. --- uploading.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/uploading.rst b/uploading.rst index bfb392e3b6..87f4f8abfc 100644 --- a/uploading.rst +++ b/uploading.rst @@ -25,21 +25,21 @@ and if the password was entered in the prompt, :command:`upload` will reuse the entered password. This is useful if you do not want to store a clear text password in the :file:`$HOME/.pypirc` file. -You can specify another PyPI server with the :option:`--repository=*url*` option:: +You can specify another PyPI server with the ``--repository=url`` option:: python setup.py sdist bdist_wininst upload -r http://example.com/pypi See section :ref:`pypirc` for more on defining several servers. -You can use the :option:`--sign` option to tell :command:`upload` to sign each +You can use the ``--sign`` option to tell :command:`upload` to sign each uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must be available for execution on the system :envvar:`PATH`. You can also specify -which key to use for signing using the :option:`--identity=*name*` option. +which key to use for signing using the ``--identity=name`` option. -Other :command:`upload` options include :option:`--repository=` or -:option:`--repository=
` where *url* is the url of the server and +Other :command:`upload` options include ``--repository=url`` or +``--repository=section`` where *url* is the url of the server and *section* the name of the section in :file:`$HOME/.pypirc`, and -:option:`--show-response` (which displays the full response text from the PyPI +``--show-response`` (which displays the full response text from the PyPI server for help in debugging upload problems). PyPI package display From 8de498c6c1125cd27f9ac377fae980495109a67c Mon Sep 17 00:00:00 2001 From: Petri Lehtinen Date: Sat, 23 Feb 2013 21:05:27 +0100 Subject: [PATCH 243/330] Issue #16403: Document how distutils uses the maintainer field in PKG-INFO --- apiref.rst | 5 ++++- setupscript.rst | 3 ++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 76567ad735..b37e02cb68 100644 --- a/apiref.rst +++ b/apiref.rst @@ -48,7 +48,10 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and +--------------------+--------------------------------+-------------------------------------------------------------+ | *maintainer* | The name of the current | a string | | | maintainer, if different from | | - | | the author | | + | | the author. Note that if | | + | | the maintainer is provided, | | + | | distutils will use it as the | | + | | author in :file:`PKG-INFO` | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *maintainer_email* | The email address of the | a string | | | current maintainer, if | | diff --git a/setupscript.rst b/setupscript.rst index 165bfcd716..58f3149d58 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -598,7 +598,8 @@ Notes: It is recommended that versions take the form *major.minor[.patch[.sub]]*. (3) - Either the author or the maintainer must be identified. + Either the author or the maintainer must be identified. If maintainer is + provided, distutils lists it as the author in :file:`PKG-INFO`. (4) These fields should not be used if your package is to be compatible with Python From d3e2f8a19a5cb1db048321be238e0796d2b030f9 Mon Sep 17 00:00:00 2001 From: Petri Lehtinen Date: Sat, 23 Feb 2013 21:05:27 +0100 Subject: [PATCH 244/330] Issue #16403: Document how distutils uses the maintainer field in PKG-INFO --- apiref.rst | 5 ++++- setupscript.rst | 3 ++- 2 files changed, 6 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 74fba4ada7..c4127bdbbf 100644 --- a/apiref.rst +++ b/apiref.rst @@ -48,7 +48,10 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and +--------------------+--------------------------------+-------------------------------------------------------------+ | *maintainer* | The name of the current | a string | | | maintainer, if different from | | - | | the author | | + | | the author. Note that if | | + | | the maintainer is provided, | | + | | distutils will use it as the | | + | | author in :file:`PKG-INFO` | | +--------------------+--------------------------------+-------------------------------------------------------------+ | *maintainer_email* | The email address of the | a string | | | current maintainer, if | | diff --git a/setupscript.rst b/setupscript.rst index 80292432a9..ba7810715d 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -601,7 +601,8 @@ Notes: It is recommended that versions take the form *major.minor[.patch[.sub]]*. (3) - Either the author or the maintainer must be identified. + Either the author or the maintainer must be identified. If maintainer is + provided, distutils lists it as the author in :file:`PKG-INFO`. (4) These fields should not be used if your package is to be compatible with Python From bd5c16c899b4cbdc75d845820358dac0a7cefe72 Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Wed, 27 Feb 2013 09:55:39 -0800 Subject: [PATCH 245/330] Issue #16406: combine the doc pages for uploading and registering to PyPI. --- index.rst | 1 - packageindex.rst | 123 ++++++++++++++++++++++++++++++++++++++++++++--- setupscript.rst | 5 +- uploading.rst | 79 +----------------------------- 4 files changed, 122 insertions(+), 86 deletions(-) diff --git a/index.rst b/index.rst index ebb48f3377..1cd5f3c5dc 100644 --- a/index.rst +++ b/index.rst @@ -22,7 +22,6 @@ very little overhead for build/release/install mechanics. sourcedist.rst builtdist.rst packageindex.rst - uploading.rst examples.rst extending.rst commandref.rst diff --git a/packageindex.rst b/packageindex.rst index 9fc18c1b89..1d724e2c9d 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -1,12 +1,33 @@ +.. index:: + single: Python Package Index (PyPI) + single: PyPI; (see Python Package Index (PyPI)) + .. _package-index: -********************************** -Registering with the Package Index -********************************** +******************************* +The Python Package Index (PyPI) +******************************* + +The `Python Package Index (PyPI)`_ holds :ref:`meta-data ` +describing distributions packaged with distutils, as well as package data like +distribution files if the package author wishes. + +Distutils exposes two commands for submitting package data to PyPI: the +:ref:`register ` command for submitting meta-data to PyPI +and the :ref:`upload ` command for submitting distribution +files. Both commands read configuration data from a special file called the +:ref:`.pypirc file `. PyPI :ref:`displays a home page +` for each package created from the ``long_description`` +submitted by the :command:`register` command. + + +.. _package-register: -The Python Package Index (PyPI) holds meta-data describing distributions -packaged with distutils. The distutils command :command:`register` is used to -submit your distribution's meta-data to the index. It is invoked as follows:: +Registering Packages +==================== + +The distutils command :command:`register` is used to submit your distribution's +meta-data to the index. It is invoked as follows:: python setup.py register @@ -48,6 +69,54 @@ interface lets one change this default behavior and manually select which versions to display and hide. +.. _package-upload: + +Uploading Packages +================== + +.. versionadded:: 2.5 + +The distutils command :command:`upload` pushes the distribution files to PyPI. + +The command is invoked immediately after building one or more distribution +files. For example, the command :: + + python setup.py sdist bdist_wininst upload + +will cause the source distribution and the Windows installer to be uploaded to +PyPI. Note that these will be uploaded even if they are built using an earlier +invocation of :file:`setup.py`, but that only distributions named on the command +line for the invocation including the :command:`upload` command are uploaded. + +The :command:`upload` command uses the username, password, and repository URL +from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this +file). If a :command:`register` command was previously called in the same command, +and if the password was entered in the prompt, :command:`upload` will reuse the +entered password. This is useful if you do not want to store a clear text +password in the :file:`$HOME/.pypirc` file. + +You can specify another PyPI server with the ``--repository=url`` option:: + + python setup.py sdist bdist_wininst upload -r http://example.com/pypi + +See section :ref:`pypirc` for more on defining several servers. + +You can use the ``--sign`` option to tell :command:`upload` to sign each +uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must +be available for execution on the system :envvar:`PATH`. You can also specify +which key to use for signing using the ``--identity=name`` option. + +Other :command:`upload` options include ``--repository=url`` or +``--repository=section`` where *url* is the url of the server and +*section* the name of the section in :file:`$HOME/.pypirc`, and +``--show-response`` (which displays the full response text from the PyPI +server for help in debugging upload problems). + + +.. index:: + single: .pypirc file + single: Python Package Index (PyPI); .pypirc file + .. _pypirc: The .pypirc file @@ -102,3 +171,45 @@ For convenience, the name of the section that describes the repository may also be used:: python setup.py register -r other + + +.. _package-display: + +PyPI package display +==================== + +The ``long_description`` field plays a special role at PyPI. It is used by +the server to display a home page for the registered package. + +If you use the `reStructuredText `_ +syntax for this field, PyPI will parse it and display an HTML output for +the package home page. + +The ``long_description`` field can be attached to a text file located +in the package:: + + from distutils.core import setup + + with open('README.txt') as file: + long_description = file.read() + + setup(name='Distutils', + long_description=long_description) + +In that case, :file:`README.txt` is a regular reStructuredText text file located +in the root of the package besides :file:`setup.py`. + +To prevent registering broken reStructuredText content, you can use the +:program:`rst2html` program that is provided by the :mod:`docutils` package and +check the ``long_description`` from the command line:: + + $ python setup.py --long-description | rst2html.py > output.html + +:mod:`docutils` will display a warning if there's something wrong with your +syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` +to ``rst2html.py`` in the command above), being able to run the command above +without warnings does not guarantee that PyPI will convert the content +successfully. + + +.. _Python Package Index (PyPI): http://pypi.python.org/ diff --git a/setupscript.rst b/setupscript.rst index 58f3149d58..533af01f50 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -607,8 +607,9 @@ Notes: `_. (5) - The ``long_description`` field is used by PyPI when you are registering a - package, to build its home page. + The ``long_description`` field is used by PyPI when you are + :ref:`registering ` a package, to + :ref:`build its home page `. (6) The ``license`` field is a text indicating the license covering the diff --git a/uploading.rst b/uploading.rst index 89ca560a68..4bce6997f9 100644 --- a/uploading.rst +++ b/uploading.rst @@ -1,82 +1,7 @@ -.. _package-upload: +:orphan: *************************************** Uploading Packages to the Package Index *************************************** -.. versionadded:: 2.5 - -The Python Package Index (PyPI) not only stores the package info, but also the -package data if the author of the package wishes to. The distutils command -:command:`upload` pushes the distribution files to PyPI. - -The command is invoked immediately after building one or more distribution -files. For example, the command :: - - python setup.py sdist bdist_wininst upload - -will cause the source distribution and the Windows installer to be uploaded to -PyPI. Note that these will be uploaded even if they are built using an earlier -invocation of :file:`setup.py`, but that only distributions named on the command -line for the invocation including the :command:`upload` command are uploaded. - -The :command:`upload` command uses the username, password, and repository URL -from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this -file). If a :command:`register` command was previously called in the same command, -and if the password was entered in the prompt, :command:`upload` will reuse the -entered password. This is useful if you do not want to store a clear text -password in the :file:`$HOME/.pypirc` file. - -You can specify another PyPI server with the ``--repository=url`` option:: - - python setup.py sdist bdist_wininst upload -r http://example.com/pypi - -See section :ref:`pypirc` for more on defining several servers. - -You can use the ``--sign`` option to tell :command:`upload` to sign each -uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must -be available for execution on the system :envvar:`PATH`. You can also specify -which key to use for signing using the ``--identity=name`` option. - -Other :command:`upload` options include ``--repository=url`` or -``--repository=section`` where *url* is the url of the server and -*section* the name of the section in :file:`$HOME/.pypirc`, and -``--show-response`` (which displays the full response text from the PyPI -server for help in debugging upload problems). - -PyPI package display -==================== - -The ``long_description`` field plays a special role at PyPI. It is used by -the server to display a home page for the registered package. - -If you use the `reStructuredText `_ -syntax for this field, PyPI will parse it and display an HTML output for -the package home page. - -The ``long_description`` field can be attached to a text file located -in the package:: - - from distutils.core import setup - - with open('README.txt') as file: - long_description = file.read() - - setup(name='Distutils', - long_description=long_description) - -In that case, :file:`README.txt` is a regular reStructuredText text file located -in the root of the package besides :file:`setup.py`. - -To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the :mod:`docutils` package -and check the ``long_description`` from the command line:: - - $ python setup.py --long-description | rst2html.py > output.html - -:mod:`docutils` will display a warning if there's something wrong with your -syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` -to ``rst2html.py`` in the command above), being able to run the command above -without warnings does not guarantee that PyPI will convert the content -successfully. - +The contents of this page have moved to the section :ref:`package-index`. From 2f8c78e6c938e4255bef4ba7eef55d6cd01a2537 Mon Sep 17 00:00:00 2001 From: Chris Jerdonek Date: Wed, 27 Feb 2013 10:00:20 -0800 Subject: [PATCH 246/330] Issue #16406: Combine the doc pages for uploading and registering to PyPI. --- index.rst | 1 - packageindex.rst | 121 ++++++++++++++++++++++++++++++++++++++++++++--- setupscript.rst | 5 +- uploading.rst | 77 +----------------------------- 4 files changed, 120 insertions(+), 84 deletions(-) diff --git a/index.rst b/index.rst index ebb48f3377..1cd5f3c5dc 100644 --- a/index.rst +++ b/index.rst @@ -22,7 +22,6 @@ very little overhead for build/release/install mechanics. sourcedist.rst builtdist.rst packageindex.rst - uploading.rst examples.rst extending.rst commandref.rst diff --git a/packageindex.rst b/packageindex.rst index 9fc18c1b89..dae8c545d0 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -1,12 +1,33 @@ +.. index:: + single: Python Package Index (PyPI) + single: PyPI; (see Python Package Index (PyPI)) + .. _package-index: -********************************** -Registering with the Package Index -********************************** +******************************* +The Python Package Index (PyPI) +******************************* + +The `Python Package Index (PyPI)`_ holds :ref:`meta-data ` +describing distributions packaged with distutils, as well as package data like +distribution files if the package author wishes. + +Distutils exposes two commands for submitting package data to PyPI: the +:ref:`register ` command for submitting meta-data to PyPI +and the :ref:`upload ` command for submitting distribution +files. Both commands read configuration data from a special file called the +:ref:`.pypirc file `. PyPI :ref:`displays a home page +` for each package created from the ``long_description`` +submitted by the :command:`register` command. + + +.. _package-register: -The Python Package Index (PyPI) holds meta-data describing distributions -packaged with distutils. The distutils command :command:`register` is used to -submit your distribution's meta-data to the index. It is invoked as follows:: +Registering Packages +==================== + +The distutils command :command:`register` is used to submit your distribution's +meta-data to the index. It is invoked as follows:: python setup.py register @@ -48,6 +69,52 @@ interface lets one change this default behavior and manually select which versions to display and hide. +.. _package-upload: + +Uploading Packages +================== + +The distutils command :command:`upload` pushes the distribution files to PyPI. + +The command is invoked immediately after building one or more distribution +files. For example, the command :: + + python setup.py sdist bdist_wininst upload + +will cause the source distribution and the Windows installer to be uploaded to +PyPI. Note that these will be uploaded even if they are built using an earlier +invocation of :file:`setup.py`, but that only distributions named on the command +line for the invocation including the :command:`upload` command are uploaded. + +The :command:`upload` command uses the username, password, and repository URL +from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this +file). If a :command:`register` command was previously called in the same command, +and if the password was entered in the prompt, :command:`upload` will reuse the +entered password. This is useful if you do not want to store a clear text +password in the :file:`$HOME/.pypirc` file. + +You can specify another PyPI server with the ``--repository=url`` option:: + + python setup.py sdist bdist_wininst upload -r http://example.com/pypi + +See section :ref:`pypirc` for more on defining several servers. + +You can use the ``--sign`` option to tell :command:`upload` to sign each +uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must +be available for execution on the system :envvar:`PATH`. You can also specify +which key to use for signing using the ``--identity=name`` option. + +Other :command:`upload` options include ``--repository=url`` or +``--repository=section`` where *url* is the url of the server and +*section* the name of the section in :file:`$HOME/.pypirc`, and +``--show-response`` (which displays the full response text from the PyPI +server for help in debugging upload problems). + + +.. index:: + single: .pypirc file + single: Python Package Index (PyPI); .pypirc file + .. _pypirc: The .pypirc file @@ -102,3 +169,45 @@ For convenience, the name of the section that describes the repository may also be used:: python setup.py register -r other + + +.. _package-display: + +PyPI package display +==================== + +The ``long_description`` field plays a special role at PyPI. It is used by +the server to display a home page for the registered package. + +If you use the `reStructuredText `_ +syntax for this field, PyPI will parse it and display an HTML output for +the package home page. + +The ``long_description`` field can be attached to a text file located +in the package:: + + from distutils.core import setup + + with open('README.txt') as file: + long_description = file.read() + + setup(name='Distutils', + long_description=long_description) + +In that case, :file:`README.txt` is a regular reStructuredText text file located +in the root of the package besides :file:`setup.py`. + +To prevent registering broken reStructuredText content, you can use the +:program:`rst2html` program that is provided by the :mod:`docutils` package and +check the ``long_description`` from the command line:: + + $ python setup.py --long-description | rst2html.py > output.html + +:mod:`docutils` will display a warning if there's something wrong with your +syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` +to ``rst2html.py`` in the command above), being able to run the command above +without warnings does not guarantee that PyPI will convert the content +successfully. + + +.. _Python Package Index (PyPI): http://pypi.python.org/ diff --git a/setupscript.rst b/setupscript.rst index ba7810715d..6ed6fbf223 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -610,8 +610,9 @@ Notes: `_. (5) - The ``long_description`` field is used by PyPI when you are registering a - package, to build its home page. + The ``long_description`` field is used by PyPI when you are + :ref:`registering ` a package, to + :ref:`build its home page `. (6) The ``license`` field is a text indicating the license covering the diff --git a/uploading.rst b/uploading.rst index 87f4f8abfc..4bce6997f9 100644 --- a/uploading.rst +++ b/uploading.rst @@ -1,80 +1,7 @@ -.. _package-upload: +:orphan: *************************************** Uploading Packages to the Package Index *************************************** -The Python Package Index (PyPI) not only stores the package info, but also the -package data if the author of the package wishes to. The distutils command -:command:`upload` pushes the distribution files to PyPI. - -The command is invoked immediately after building one or more distribution -files. For example, the command :: - - python setup.py sdist bdist_wininst upload - -will cause the source distribution and the Windows installer to be uploaded to -PyPI. Note that these will be uploaded even if they are built using an earlier -invocation of :file:`setup.py`, but that only distributions named on the command -line for the invocation including the :command:`upload` command are uploaded. - -The :command:`upload` command uses the username, password, and repository URL -from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this -file). If a :command:`register` command was previously called in the same command, -and if the password was entered in the prompt, :command:`upload` will reuse the -entered password. This is useful if you do not want to store a clear text -password in the :file:`$HOME/.pypirc` file. - -You can specify another PyPI server with the ``--repository=url`` option:: - - python setup.py sdist bdist_wininst upload -r http://example.com/pypi - -See section :ref:`pypirc` for more on defining several servers. - -You can use the ``--sign`` option to tell :command:`upload` to sign each -uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must -be available for execution on the system :envvar:`PATH`. You can also specify -which key to use for signing using the ``--identity=name`` option. - -Other :command:`upload` options include ``--repository=url`` or -``--repository=section`` where *url* is the url of the server and -*section* the name of the section in :file:`$HOME/.pypirc`, and -``--show-response`` (which displays the full response text from the PyPI -server for help in debugging upload problems). - -PyPI package display -==================== - -The ``long_description`` field plays a special role at PyPI. It is used by -the server to display a home page for the registered package. - -If you use the `reStructuredText `_ -syntax for this field, PyPI will parse it and display an HTML output for -the package home page. - -The ``long_description`` field can be attached to a text file located -in the package:: - - from distutils.core import setup - - with open('README.txt') as file: - long_description = file.read() - - setup(name='Distutils', - long_description=long_description) - -In that case, :file:`README.txt` is a regular reStructuredText text file located -in the root of the package besides :file:`setup.py`. - -To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the :mod:`docutils` package and -check the ``long_description`` from the command line:: - - $ python setup.py --long-description | rst2html.py > output.html - -:mod:`docutils` will display a warning if there's something wrong with your -syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` -to ``rst2html.py`` in the command above), being able to run the command above -without warnings does not guarantee that PyPI will convert the content -successfully. - +The contents of this page have moved to the section :ref:`package-index`. From ef5932ba682e271fa88731a3c5bbc50f8e5b1fc9 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 28 Mar 2013 13:28:44 +0100 Subject: [PATCH 247/330] Closes #4159: add LaTeX tabular column specifications to tables that otherwise are cut off or have overlapping text. --- apiref.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/apiref.rst b/apiref.rst index 1381afc652..c323775cb4 100644 --- a/apiref.rst +++ b/apiref.rst @@ -26,6 +26,8 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and The setup function takes a large number of arguments. These are laid out in the following table. + .. tabularcolumns:: |l|L|L| + +--------------------+--------------------------------+-------------------------------------------------------------+ | argument name | value | type | +====================+================================+=============================================================+ @@ -125,6 +127,8 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and *stop_after* tells :func:`setup` when to stop processing; possible values: + .. tabularcolumns:: |l|L| + +---------------+---------------------------------------------+ | value | description | +===============+=============================================+ @@ -165,6 +169,8 @@ the full reference. The Extension class describes a single C or C++extension module in a setup script. It accepts the following keyword arguments in its constructor: + .. tabularcolumns:: |l|L|l| + +------------------------+--------------------------------+---------------------------+ | argument name | value | type | +========================+================================+===========================+ @@ -1562,6 +1568,8 @@ lines, and joining lines with backslashes. The options are all boolean, and affect the values returned by :meth:`readline` + .. tabularcolumns:: |l|L|l| + +------------------+--------------------------------+---------+ | option name | description | default | +==================+================================+=========+ From 4a7db296d8655e79527780b9c624641b55a1d156 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 6 Oct 2013 11:12:29 +0200 Subject: [PATCH 248/330] Fix missing period. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index c323775cb4..246be14019 100644 --- a/apiref.rst +++ b/apiref.rst @@ -734,7 +734,7 @@ This module provides the following functions. .. method:: CCompiler.execute(func, args[, msg=None, level=1]) - Invokes :func:`distutils.util.execute` This method invokes a Python function + Invokes :func:`distutils.util.execute`. This method invokes a Python function *func* with the given arguments *args*, after logging and taking into account the *dry_run* flag. From 7bb579ece786cd3868470f5a82ae47d78bc74304 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 9 Oct 2013 14:09:16 +0300 Subject: [PATCH 249/330] #19196: Improved cross-references in distutils documentation. --- apiref.rst | 15 ++++++++------- setupscript.rst | 16 +++++++++------- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/apiref.rst b/apiref.rst index 246be14019..54f0a4eca6 100644 --- a/apiref.rst +++ b/apiref.rst @@ -994,8 +994,9 @@ directories. simply the list of all files under *src*, with the names changed to be under *dst*. - *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in - :mod:`distutils.file_util`; note that they only apply to regular files, not to + *preserve_mode* and *preserve_times* are the same as for + :func:`distutils.file_util.copy_file`; note that they only apply to + regular files, not to directories. If *preserve_symlinks* is true, symlinks will be copied as symlinks (on platforms that support them!); otherwise (the default), the destination of the symlink will be copied. *update* and *verbose* are the same @@ -1175,7 +1176,7 @@ other utility module. Generate a useful error message from an :exc:`OSError` exception object. Handles Python 1.5.1 and later styles, and does what it can to deal with exception objects that don't have a filename (which happens when the error - is due to a two-file operation, such as :func:`rename` or :func:`link`). + is due to a two-file operation, such as :func:`~os.rename` or :func:`~os.link`). Returns the error message as a string prefixed with *prefix*. @@ -1265,8 +1266,8 @@ other utility module. built/installed/distributed -This module provides the :class:`Distribution` class, which represents the -module distribution being built/installed/distributed. +This module provides the :class:`~distutils.core.Distribution` class, which +represents the module distribution being built/installed/distributed. :mod:`distutils.extension` --- The Extension class @@ -1712,8 +1713,8 @@ This module supplies the abstract base class :class:`Command`. options, is the :meth:`run` method, which must also be implemented by every command class. - The class constructor takes a single argument *dist*, a :class:`Distribution` - instance. + The class constructor takes a single argument *dist*, a + :class:`~distutils.core.Distribution` instance. Creating a new Distutils command diff --git a/setupscript.rst b/setupscript.rst index 6ed6fbf223..ee96302ce1 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -139,7 +139,8 @@ directories, libraries to link with, etc.). All of this is done through another keyword argument to :func:`setup`, the :option:`ext_modules` option. :option:`ext_modules` is just a list of -:class:`Extension` instances, each of which describes a single extension module. +:class:`~distutils.core.Extension` instances, each of which describes a +single extension module. Suppose your distribution includes a single extension, called :mod:`foo` and implemented by :file:`foo.c`. If no additional instructions to the compiler/linker are needed, describing this extension is quite simple:: @@ -165,8 +166,8 @@ following sections. Extension names and packages ---------------------------- -The first argument to the :class:`Extension` constructor is always the name of -the extension, including any package names. For example, :: +The first argument to the :class:`~distutils.core.Extension` constructor is +always the name of the extension, including any package names. For example, :: Extension('foo', ['src/foo1.c', 'src/foo2.c']) @@ -196,7 +197,8 @@ will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to Extension source files ---------------------- -The second argument to the :class:`Extension` constructor is a list of source +The second argument to the :class:`~distutils.core.Extension` constructor is +a list of source files. Since the Distutils currently only support C, C++, and Objective-C extensions, these are normally C/C++/Objective-C source files. (Be sure to use appropriate extensions to distinguish C++\ source files: :file:`.cc` and @@ -232,9 +234,9 @@ linked into the executable. Preprocessor options -------------------- -Three optional arguments to :class:`Extension` will help if you need to specify -include directories to search or preprocessor macros to define/undefine: -``include_dirs``, ``define_macros``, and ``undef_macros``. +Three optional arguments to :class:`~distutils.core.Extension` will help if +you need to specify include directories to search or preprocessor macros to +define/undefine: ``include_dirs``, ``define_macros``, and ``undef_macros``. For example, if your extension requires header files in the :file:`include` directory under your distribution root, use the ``include_dirs`` option:: From bbbfa974d3c3ed1c5b058077feddce68c1296033 Mon Sep 17 00:00:00 2001 From: Andrew Kuchling Date: Fri, 15 Nov 2013 13:01:52 -0500 Subject: [PATCH 250/330] Issue #19544 and Issue #6516: Restore support for --user and --group parameters to sdist command as found in Python 2.7 and originally slated for Python 3.2 but accidentally rolled back as part of the distutils2 rollback. Closes Issue #6516. --- sourcedist.rst | 18 +++++++++++++----- 1 file changed, 13 insertions(+), 5 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index 1666436be0..9f7a38eda6 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -26,16 +26,16 @@ to create a gzipped tarball and a zip file. The available formats are: +===========+=========================+=========+ | ``zip`` | zip file (:file:`.zip`) | (1),(3) | +-----------+-------------------------+---------+ -| ``gztar`` | gzip'ed tar file | (2),(4) | +| ``gztar`` | gzip'ed tar file | \(2) | | | (:file:`.tar.gz`) | | +-----------+-------------------------+---------+ -| ``bztar`` | bzip2'ed tar file | \(4) | +| ``bztar`` | bzip2'ed tar file | | | | (:file:`.tar.bz2`) | | +-----------+-------------------------+---------+ | ``ztar`` | compressed tar file | \(4) | | | (:file:`.tar.Z`) | | +-----------+-------------------------+---------+ -| ``tar`` | tar file (:file:`.tar`) | \(4) | +| ``tar`` | tar file (:file:`.tar`) | | +-----------+-------------------------+---------+ Notes: @@ -51,8 +51,16 @@ Notes: of the standard Python library since Python 1.6) (4) - requires external utilities: :program:`tar` and possibly one of :program:`gzip`, - :program:`bzip2`, or :program:`compress` + requires the :program:`compress` program. Notice that this format is now + pending for deprecation and will be removed in the future versions of Python. + +When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or +``tar``), under Unix you can specify the ``owner`` and ``group`` names +that will be set for each member of the archive. + +For example, if you want all files of the archive to be owned by root:: + + python setup.py sdist --owner=root --group=root .. _manifest: From cf70f0f2fd8ff0a637a5b0ffb7610952dc92bb9e Mon Sep 17 00:00:00 2001 From: Andrew Kuchling Date: Sun, 10 Nov 2013 18:11:00 -0500 Subject: [PATCH 251/330] Issue #19544 and Issue #1180: Restore global option to ignore ~/.pydistutils.cfg in Distutils, accidentally removed in backout of distutils2 changes. --- builtdist.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index d1ab7dbce9..83c68ae20c 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -239,7 +239,8 @@ tedious and error-prone, so it's usually best to put them in the setup configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If you distribute or package many Python module distributions, you might want to put options that apply to all of them in your personal Distutils configuration -file (:file:`~/.pydistutils.cfg`). +file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable +this file, you can pass the :option:`--no-user-cfg` option to :file:`setup.py`. There are three steps to building a binary RPM package, all of which are handled automatically by the Distutils: From 21c65d6bf6bab0b382109c20dd48c45cf5438134 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 10 Nov 2013 18:15:03 -0500 Subject: [PATCH 252/330] Issue 19544 and Issue #7457: Restore the read_pkg_file method to distutils.dist.DistributionMetadata accidentally removed in the undo of distutils2. --- examples.rst | 42 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 42 insertions(+) diff --git a/examples.rst b/examples.rst index b268486398..5eb654a529 100644 --- a/examples.rst +++ b/examples.rst @@ -284,6 +284,48 @@ by using the :mod:`docutils` parser:: warning: check: Title underline too short. (line 2) warning: check: Could not finish the parsing. +Reading the metadata +===================== + +The :func:`distutils.core.setup` function provides a command-line interface +that allows you to query the metadata fields of a project through the +`setup.py` script of a given project:: + + $ python setup.py --name + distribute + +This call reads the `name` metadata by running the +:func:`distutils.core.setup` function. Although, when a source or binary +distribution is created with Distutils, the metadata fields are written +in a static file called :file:`PKG-INFO`. When a Distutils-based project is +installed in Python, the :file:`PKG-INFO` file is copied alongside the modules +and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, +where `NAME` is the name of the project, `VERSION` its version as defined +in the Metadata, and `pyX.X` the major and minor version of Python like +`2.7` or `3.2`. + +You can read back this static file, by using the +:class:`distutils.dist.DistributionMetadata` class and its +:func:`read_pkg_file` method:: + + >>> from distutils.dist import DistributionMetadata + >>> metadata = DistributionMetadata() + >>> metadata.read_pkg_file(open('distribute-0.6.8-py2.7.egg-info')) + >>> metadata.name + 'distribute' + >>> metadata.version + '0.6.8' + >>> metadata.description + 'Easily download, build, install, upgrade, and uninstall Python packages' + +Notice that the class can also be instanciated with a metadata file path to +loads its values:: + + >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info' + >>> DistributionMetadata(pkg_info_path).name + 'distribute' + + .. % \section{Multiple extension modules} .. % \label{multiple-ext} From f71ceb3f6f0353598a1741f122c6a7fb60fdfedd Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Tue, 10 Dec 2013 21:24:55 +1000 Subject: [PATCH 253/330] Issue #19407: add Python Packaging User Guide notes The stdlib docs for package distribution and building extensions are rather dated, and that isn't expected to change for 2.7 and 3.3. The Python Packaging User Guide isn't complete either, but it's already a much better road map for new users than the existing stdlib docs. --- index.rst | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/index.rst b/index.rst index 1cd5f3c5dc..1a6f04c87a 100644 --- a/index.rst +++ b/index.rst @@ -12,6 +12,16 @@ the module developer's point of view, describing how to use the Distutils to make Python modules and extensions easily available to a wider audience with very little overhead for build/release/install mechanics. +.. note:: + + This guide only covers the basic tools for building and distributing + extensions that are provided as part of this version of Python. Third + party tools offer easier to use and more secure alternatives. Refer to the + `quick recommendations section + `__ + in the Python Packaging User Guide for more information. + + .. toctree:: :maxdepth: 2 :numbered: From d28fb4623be46f73875013b098cd51be60a4320b Mon Sep 17 00:00:00 2001 From: Andrew Kuchling Date: Sat, 1 Mar 2014 07:53:28 -0500 Subject: [PATCH 254/330] #16135: remove mentions of OS/2 from the documentation --- apiref.rst | 11 ----------- 1 file changed, 11 deletions(-) diff --git a/apiref.rst b/apiref.rst index 54f0a4eca6..909f5634c4 100644 --- a/apiref.rst +++ b/apiref.rst @@ -853,17 +853,6 @@ Windows. It also contains the Mingw32CCompiler class which handles the mingw32 port of GCC (same as cygwin in no-cygwin mode). -:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler -=================================================== - -.. module:: distutils.emxccompiler - :synopsis: OS/2 EMX Compiler support - - -This module provides the EMXCCompiler class, a subclass of -:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2. - - :mod:`distutils.archive_util` --- Archiving utilities ====================================================== From 12e44f7ef0e8b39dbdc86194e56ecfa27c020aeb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Wed, 12 Mar 2014 03:34:02 -0400 Subject: [PATCH 255/330] =?UTF-8?q?Avoid=20=E2=80=9Cerror:=20None=E2=80=9D?= =?UTF-8?q?=20messages=20from=20distutils=20(#4931).?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Thanks to Amaury Forgeot d’Arc and Philip J. Eby. --- apiref.rst | 9 --------- 1 file changed, 9 deletions(-) diff --git a/apiref.rst b/apiref.rst index 54f0a4eca6..d70d13f8b8 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1171,15 +1171,6 @@ other utility module. underscore. No { } or ( ) style quoting is available. -.. function:: grok_environment_error(exc[, prefix='error: ']) - - Generate a useful error message from an :exc:`OSError` exception object. - Handles Python 1.5.1 and later styles, and does what it can to deal with - exception objects that don't have a filename (which happens when the error - is due to a two-file operation, such as :func:`~os.rename` or :func:`~os.link`). - Returns the error message as a string prefixed with *prefix*. - - .. function:: split_quoted(s) Split a string up according to Unix shell-like rules for quotes and backslashes. From 4c07de989b9454d513ab2f1c75d31ba92e80ecd7 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 13 Mar 2014 04:55:35 -0400 Subject: [PATCH 256/330] Make distutils error messages more helpful (#11599). When running external programs such as a C compiler and getting an error code, distutils only prints the program name. With this change, one can get the full command line by setting the DISTUTILS_DEBUG environment variable. This should have no compatibility issues, unless there are tools that depend on the exact format of distutils debug messages. --- setupscript.rst | 9 ++++++--- 1 file changed, 6 insertions(+), 3 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index ee96302ce1..fbe4290c64 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -685,6 +685,8 @@ include the following code fragment in your :file:`setup.py` before the DistributionMetadata.download_url = None +.. _debug-setup-script: + Debugging the setup script ========================== @@ -700,7 +702,8 @@ installation is broken because they don't read all the way down to the bottom and see that it's a permission problem. On the other hand, this doesn't help the developer to find the cause of the -failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set +failure. For this purpose, the :envvar:`DISTUTILS_DEBUG` environment variable can be set to anything except an empty string, and distutils will now print detailed -information what it is doing, and prints the full traceback in case an exception -occurs. +information about what it is doing, dump the full traceback when an exception +occurs, and print the whole command line when an external program (like a C +compiler) fails. From bdd6f5bb8d158ca5a5b98bf79b253fbb445a52bf Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Thu, 13 Mar 2014 22:13:45 +1000 Subject: [PATCH 257/330] Close #19407: New installation & distribution guides - based on pip and other PyPA tools - includes references to the new Python Packaging User Guide where appropriate (and the relevant section is at least partially filled in) - started new FAQ sections - both guides aim to introduce users to basic open source concepts if they aren't aware of them - existing guides have been relocated (now linked from the distutils docs) rather then removed, since there is some needed material that has yet to be relocated to the distutils docs as a reference for the legacy formats --- index.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/index.rst b/index.rst index 1a6f04c87a..90d1c1ab34 100644 --- a/index.rst +++ b/index.rst @@ -1,8 +1,8 @@ .. _distutils-index: -############################### - Distributing Python Modules -############################### +############################################## + Distributing Python Modules (Legacy version) +############################################## :Authors: Greg Ward, Anthony Baxter :Email: distutils-sig@python.org From 5328876b9b785b15909da186f1b02fed05f96782 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=C3=89ric=20Araujo?= Date: Thu, 13 Mar 2014 16:17:11 -0400 Subject: [PATCH 258/330] =?UTF-8?q?Clarify=20distutils=E2=80=99=20clean=20?= =?UTF-8?q?command=20(ref=20#6142)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- apiref.rst | 6 +++++- configfile.rst | 2 ++ 2 files changed, 7 insertions(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index d70d13f8b8..9853f021ea 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1934,8 +1934,12 @@ Subclasses of :class:`Command` must define the following methods. .. module:: distutils.command.clean :synopsis: Clean a package build area +This command removes the temporary files created by :command:`build` +and its subcommands, like intermediary compiled object files. With +the ``--all`` option, the complete build directory will be removed. -.. % todo +Extension modules built :ref:`in place ` +will not be cleaned, as they are not in the build directory. :mod:`distutils.command.config` --- Perform package configuration diff --git a/configfile.rst b/configfile.rst index 890047c08e..ac79671611 100644 --- a/configfile.rst +++ b/configfile.rst @@ -69,6 +69,8 @@ universal :option:`--help` option, e.g. :: Note that an option spelled :option:`--foo-bar` on the command-line is spelled :option:`foo_bar` in configuration files. +.. _distutils-build-ext-inplace: + For example, say you want your extensions to be built "in-place"---that is, you have an extension :mod:`pkg.ext`, and you want the compiled extension file (:file:`ext.so` on Unix, say) to be put in the same source directory as your From 01e5e5830b1527a54404d5a570cf91f6132b039a Mon Sep 17 00:00:00 2001 From: Larry Hastings Date: Sat, 15 Mar 2014 21:13:56 -0700 Subject: [PATCH 259/330] Merge in all documentation changes since branching 3.4.0rc1. --- apiref.rst | 26 +++++--------------------- configfile.rst | 2 ++ index.rst | 6 +++--- setupscript.rst | 9 ++++++--- 4 files changed, 16 insertions(+), 27 deletions(-) diff --git a/apiref.rst b/apiref.rst index 54f0a4eca6..36a911ebbd 100644 --- a/apiref.rst +++ b/apiref.rst @@ -853,17 +853,6 @@ Windows. It also contains the Mingw32CCompiler class which handles the mingw32 port of GCC (same as cygwin in no-cygwin mode). -:mod:`distutils.emxccompiler` --- OS/2 EMX Compiler -=================================================== - -.. module:: distutils.emxccompiler - :synopsis: OS/2 EMX Compiler support - - -This module provides the EMXCCompiler class, a subclass of -:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2. - - :mod:`distutils.archive_util` --- Archiving utilities ====================================================== @@ -1171,15 +1160,6 @@ other utility module. underscore. No { } or ( ) style quoting is available. -.. function:: grok_environment_error(exc[, prefix='error: ']) - - Generate a useful error message from an :exc:`OSError` exception object. - Handles Python 1.5.1 and later styles, and does what it can to deal with - exception objects that don't have a filename (which happens when the error - is due to a two-file operation, such as :func:`~os.rename` or :func:`~os.link`). - Returns the error message as a string prefixed with *prefix*. - - .. function:: split_quoted(s) Split a string up according to Unix shell-like rules for quotes and backslashes. @@ -1943,8 +1923,12 @@ Subclasses of :class:`Command` must define the following methods. .. module:: distutils.command.clean :synopsis: Clean a package build area +This command removes the temporary files created by :command:`build` +and its subcommands, like intermediary compiled object files. With +the ``--all`` option, the complete build directory will be removed. -.. % todo +Extension modules built :ref:`in place ` +will not be cleaned, as they are not in the build directory. :mod:`distutils.command.config` --- Perform package configuration diff --git a/configfile.rst b/configfile.rst index 890047c08e..ac79671611 100644 --- a/configfile.rst +++ b/configfile.rst @@ -69,6 +69,8 @@ universal :option:`--help` option, e.g. :: Note that an option spelled :option:`--foo-bar` on the command-line is spelled :option:`foo_bar` in configuration files. +.. _distutils-build-ext-inplace: + For example, say you want your extensions to be built "in-place"---that is, you have an extension :mod:`pkg.ext`, and you want the compiled extension file (:file:`ext.so` on Unix, say) to be put in the same source directory as your diff --git a/index.rst b/index.rst index 1a6f04c87a..90d1c1ab34 100644 --- a/index.rst +++ b/index.rst @@ -1,8 +1,8 @@ .. _distutils-index: -############################### - Distributing Python Modules -############################### +############################################## + Distributing Python Modules (Legacy version) +############################################## :Authors: Greg Ward, Anthony Baxter :Email: distutils-sig@python.org diff --git a/setupscript.rst b/setupscript.rst index ee96302ce1..fbe4290c64 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -685,6 +685,8 @@ include the following code fragment in your :file:`setup.py` before the DistributionMetadata.download_url = None +.. _debug-setup-script: + Debugging the setup script ========================== @@ -700,7 +702,8 @@ installation is broken because they don't read all the way down to the bottom and see that it's a permission problem. On the other hand, this doesn't help the developer to find the cause of the -failure. For this purpose, the DISTUTILS_DEBUG environment variable can be set +failure. For this purpose, the :envvar:`DISTUTILS_DEBUG` environment variable can be set to anything except an empty string, and distutils will now print detailed -information what it is doing, and prints the full traceback in case an exception -occurs. +information about what it is doing, dump the full traceback when an exception +occurs, and print the whole command line when an external program (like a C +compiler) fails. From 76a17a863d0221b66d696d78859e4dcc174d40f5 Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Thu, 20 Mar 2014 09:46:09 -0500 Subject: [PATCH 260/330] Add missing parenthesis. Found by cocoatomo on docs@. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 36a911ebbd..e1357fa90d 100644 --- a/apiref.rst +++ b/apiref.rst @@ -993,7 +993,7 @@ directories. Files in *src* that begin with :file:`.nfs` are skipped (more information on these files is available in answer D2 of the `NFS FAQ page - `_. + `_). .. versionchanged:: 3.3.1 NFS files are ignored. From 3c18436f0b14b4d49aa54eb0c839d89b7a71681e Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Sun, 23 Mar 2014 22:21:38 -0500 Subject: [PATCH 261/330] Remove superfluous open parenthesis. Noticed by cocoatomo on docs@. --- sourcedist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sourcedist.rst b/sourcedist.rst index 9f7a38eda6..427b7b1b2a 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -76,7 +76,7 @@ source distribution: :option:`packages` options * all C source files mentioned in the :option:`ext_modules` or - :option:`libraries` options ( + :option:`libraries` options .. XXX getting C library sources currently broken---no :meth:`get_source_files` method in :file:`build_clib.py`! From 36826f0c7c2c3c6a35f145ba625cc11494492f78 Mon Sep 17 00:00:00 2001 From: Donald Stufft Date: Tue, 20 May 2014 12:58:38 -0400 Subject: [PATCH 262/330] Fix Issue #21528 - Fix documentation typos --- apiref.rst | 4 ++-- builtdist.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index e1357fa90d..4c38a07a69 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1099,13 +1099,13 @@ other utility module. during the build of Python), not the OS version of the current system. For universal binary builds on Mac OS X the architecture value reflects - the univeral binary status instead of the architecture of the current + the universal binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is ``fat``, for 64-bit universal binaries the architecture is ``fat64``, and for 4-way universal binaries the architecture is ``universal``. Starting from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for - a univeral build with the i386 and x86_64 architectures + a universal build with the i386 and x86_64 architectures Examples of returned values on Mac OS X: diff --git a/builtdist.rst b/builtdist.rst index 83c68ae20c..a67c68e21a 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -355,7 +355,7 @@ support this option, so the command:: would create a 64bit installation executable on your 32bit version of Windows. To cross-compile, you must download the Python source code and cross-compile -Python itself for the platform you are targetting - it is not possible from a +Python itself for the platform you are targeting - it is not possible from a binary installation of Python (as the .lib etc file for other platforms are not included.) In practice, this means the user of a 32 bit operating system will need to use Visual Studio 2008 to open the From ba6f2f16228a1d9cb683e1684ae61e1ad3027f4a Mon Sep 17 00:00:00 2001 From: Terry Jan Reedy Date: Fri, 13 Jun 2014 14:57:51 -0400 Subject: [PATCH 263/330] Issue #21726: Remove unnecessary and contextually wrong line. --- examples.rst | 3 --- 1 file changed, 3 deletions(-) diff --git a/examples.rst b/examples.rst index 5eb654a529..872ecd9ff5 100644 --- a/examples.rst +++ b/examples.rst @@ -193,9 +193,6 @@ then the corresponding setup script would be :: packages=['foobar', 'foobar.subfoo'], ) -(Again, the empty string in :option:`package_dir` stands for the current -directory.) - .. _single-ext: From 4e149cfefee5a84bcd889d57fb8d8aae6720a2f0 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Sun, 21 Sep 2014 00:35:08 +0200 Subject: [PATCH 264/330] Doc: remove invalid uses of ":option:" which will emit warnings in Sphinx 1.3. --- builtdist.rst | 40 ++++++++++++++++++++-------------------- configfile.rst | 4 ++-- examples.rst | 16 ++++++++-------- extending.rst | 4 ++-- setupscript.rst | 38 +++++++++++++++++++------------------- sourcedist.rst | 12 ++++++------ 6 files changed, 57 insertions(+), 57 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 83c68ae20c..ac96c40300 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -186,21 +186,21 @@ Distutils configuration files. Various options and sections in the +------------------------------------------+----------------------------------------------+ | RPM :file:`.spec` file option or section | Distutils setup script option | +==========================================+==============================================+ -| Name | :option:`name` | +| Name | ``name`` | +------------------------------------------+----------------------------------------------+ -| Summary (in preamble) | :option:`description` | +| Summary (in preamble) | ``description`` | +------------------------------------------+----------------------------------------------+ -| Version | :option:`version` | +| Version | ``version`` | +------------------------------------------+----------------------------------------------+ -| Vendor | :option:`author` and :option:`author_email`, | -| | or --- & :option:`maintainer` and | -| | :option:`maintainer_email` | +| Vendor | ``author`` and ``author_email``, | +| | or --- & ``maintainer`` and | +| | ``maintainer_email`` | +------------------------------------------+----------------------------------------------+ -| Copyright | :option:`license` | +| Copyright | ``license`` | +------------------------------------------+----------------------------------------------+ -| Url | :option:`url` | +| Url | ``url`` | +------------------------------------------+----------------------------------------------+ -| %description (section) | :option:`long_description` | +| %description (section) | ``long_description`` | +------------------------------------------+----------------------------------------------+ Additionally, there are many options in :file:`.spec` files that don't have @@ -211,27 +211,27 @@ options to the :command:`bdist_rpm` command as follows: | RPM :file:`.spec` file option | :command:`bdist_rpm` option | default value | | or section | | | +===============================+=============================+=========================+ -| Release | :option:`release` | "1" | +| Release | ``release`` | "1" | +-------------------------------+-----------------------------+-------------------------+ -| Group | :option:`group` | "Development/Libraries" | +| Group | ``group`` | "Development/Libraries" | +-------------------------------+-----------------------------+-------------------------+ -| Vendor | :option:`vendor` | (see above) | +| Vendor | ``vendor`` | (see above) | +-------------------------------+-----------------------------+-------------------------+ -| Packager | :option:`packager` | (none) | +| Packager | ``packager`` | (none) | +-------------------------------+-----------------------------+-------------------------+ -| Provides | :option:`provides` | (none) | +| Provides | ``provides`` | (none) | +-------------------------------+-----------------------------+-------------------------+ -| Requires | :option:`requires` | (none) | +| Requires | ``requires`` | (none) | +-------------------------------+-----------------------------+-------------------------+ -| Conflicts | :option:`conflicts` | (none) | +| Conflicts | ``conflicts`` | (none) | +-------------------------------+-----------------------------+-------------------------+ -| Obsoletes | :option:`obsoletes` | (none) | +| Obsoletes | ``obsoletes`` | (none) | +-------------------------------+-----------------------------+-------------------------+ -| Distribution | :option:`distribution_name` | (none) | +| Distribution | ``distribution_name`` | (none) | +-------------------------------+-----------------------------+-------------------------+ -| BuildRequires | :option:`build_requires` | (none) | +| BuildRequires | ``build_requires`` | (none) | +-------------------------------+-----------------------------+-------------------------+ -| Icon | :option:`icon` | (none) | +| Icon | ``icon`` | (none) | +-------------------------------+-----------------------------+-------------------------+ Obviously, supplying even a few of these options on the command-line would be diff --git a/configfile.rst b/configfile.rst index ac79671611..8faffe6c20 100644 --- a/configfile.rst +++ b/configfile.rst @@ -67,7 +67,7 @@ universal :option:`--help` option, e.g. :: [...] Note that an option spelled :option:`--foo-bar` on the command-line is spelled -:option:`foo_bar` in configuration files. +``foo_bar`` in configuration files. .. _distutils-build-ext-inplace: @@ -114,7 +114,7 @@ own :file:`setup.cfg`:: doc/ examples/ -Note that the :option:`doc_files` option is simply a whitespace-separated string +Note that the ``doc_files`` option is simply a whitespace-separated string split across multiple lines for readability. diff --git a/examples.rst b/examples.rst index 872ecd9ff5..b1ecd01dab 100644 --- a/examples.rst +++ b/examples.rst @@ -22,7 +22,7 @@ Pure Python distribution (by module) If you're just distributing a couple of modules, especially if they don't live in a particular package, you can specify them individually using the -:option:`py_modules` option in the setup script. +``py_modules`` option in the setup script. In the simplest case, you'll have two files to worry about: a setup script and the single module you're distributing, :file:`foo.py` in this example:: @@ -41,12 +41,12 @@ directory.) A minimal setup script to describe this situation would be:: ) Note that the name of the distribution is specified independently with the -:option:`name` option, and there's no rule that says it has to be the same as +``name`` option, and there's no rule that says it has to be the same as the name of the sole module in the distribution (although that's probably a good convention to follow). However, the distribution name is used to generate filenames, so you should stick to letters, digits, underscores, and hyphens. -Since :option:`py_modules` is a list, you can of course specify multiple +Since ``py_modules`` is a list, you can of course specify multiple modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your setup might look like this:: @@ -130,7 +130,7 @@ requires the least work to describe in your setup script:: ) If you want to put modules in directories not named for their package, then you -need to use the :option:`package_dir` option again. For example, if the +need to use the ``package_dir`` option again. For example, if the :file:`src` directory holds modules in the :mod:`foobar` package:: / @@ -169,8 +169,8 @@ in which case your setup script would be :: (The empty string also stands for the current directory.) -If you have sub-packages, they must be explicitly listed in :option:`packages`, -but any entries in :option:`package_dir` automatically extend to sub-packages. +If you have sub-packages, they must be explicitly listed in ``packages``, +but any entries in ``package_dir`` automatically extend to sub-packages. (In other words, the Distutils does *not* scan your source tree, trying to figure out which directories correspond to Python packages by looking for :file:`__init__.py` files.) Thus, if the default layout grows a sub-package:: @@ -199,8 +199,8 @@ then the corresponding setup script would be :: Single extension module ======================= -Extension modules are specified using the :option:`ext_modules` option. -:option:`package_dir` has no effect on where extension source files are found; +Extension modules are specified using the ``ext_modules`` option. +``package_dir`` has no effect on where extension source files are found; it only affects the source for pure Python modules. The simplest case, a single extension module in a single C source file, is:: diff --git a/extending.rst b/extending.rst index 5a70d031cc..5139c6dc81 100644 --- a/extending.rst +++ b/extending.rst @@ -61,7 +61,7 @@ commands to be added which can support existing :file:`setup.py` scripts without requiring modifications to the Python installation. This is expected to allow third-party extensions to provide support for additional packaging systems, but the commands can be used for anything distutils commands can be used for. A new -configuration option, :option:`command_packages` (command-line option +configuration option, ``command_packages`` (command-line option :option:`--command-packages`), can be used to specify additional packages to be searched for modules implementing commands. Like all distutils options, this can be specified on the command line or in a configuration file. This option @@ -75,7 +75,7 @@ This new option can be used to add any number of packages to the list of packages searched for command implementations; multiple package names should be separated by commas. When not specified, the search is only performed in the :mod:`distutils.command` package. When :file:`setup.py` is run with the option -:option:`--command-packages` :option:`distcmds,buildcmds`, however, the packages +``--command-packages distcmds,buildcmds``, however, the packages :mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched in that order. New commands are expected to be implemented in modules of the same name as the command by classes sharing the same name. Given the example diff --git a/setupscript.rst b/setupscript.rst index fbe4290c64..8d89f3bf24 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -62,9 +62,9 @@ code instead of hardcoding path separators:: Listing whole packages ====================== -The :option:`packages` option tells the Distutils to process (build, distribute, +The ``packages`` option tells the Distutils to process (build, distribute, install, etc.) all pure Python modules found in each package mentioned in the -:option:`packages` list. In order to do this, of course, there has to be a +``packages`` list. In order to do this, of course, there has to be a correspondence between package names and directories in the filesystem. The default correspondence is the most obvious one, i.e. package :mod:`distutils` is found in the directory :file:`distutils` relative to the distribution root. @@ -75,7 +75,7 @@ the directory where your setup script lives. If you break this promise, the Distutils will issue a warning but still process the broken package anyway. If you use a different convention to lay out your source directory, that's no -problem: you just have to supply the :option:`package_dir` option to tell the +problem: you just have to supply the ``package_dir`` option to tell the Distutils about your convention. For example, say you keep all Python source under :file:`lib`, so that modules in the "root package" (i.e., not in any package at all) are in :file:`lib`, modules in the :mod:`foo` package are in @@ -94,13 +94,13 @@ written in the setup script as :: package_dir = {'foo': 'lib'} -A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly +A ``package: dir`` entry in the ``package_dir`` dictionary implicitly applies to all packages below *package*, so the :mod:`foo.bar` case is automatically handled here. In this example, having ``packages = ['foo', 'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and -:file:`lib/bar/__init__.py`. (Keep in mind that although :option:`package_dir` +:file:`lib/bar/__init__.py`. (Keep in mind that although ``package_dir`` applies recursively, you must explicitly list all packages in -:option:`packages`: the Distutils will *not* recursively scan your source tree +``packages``: the Distutils will *not* recursively scan your source tree looking for any directory with an :file:`__init__.py` file.) @@ -120,7 +120,7 @@ This describes two modules, one of them in the "root" package, the other in the :mod:`pkg` package. Again, the default package/directory layout implies that these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and that :file:`pkg/__init__.py` exists as well. And again, you can override the -package/directory correspondence using the :option:`package_dir` option. +package/directory correspondence using the ``package_dir`` option. .. _describing-extensions: @@ -138,7 +138,7 @@ directories, libraries to link with, etc.). .. XXX read over this section All of this is done through another keyword argument to :func:`setup`, the -:option:`ext_modules` option. :option:`ext_modules` is just a list of +``ext_modules`` option. ``ext_modules`` is just a list of :class:`~distutils.core.Extension` instances, each of which describes a single extension module. Suppose your distribution includes a single extension, called :mod:`foo` and @@ -181,7 +181,7 @@ in the filesystem (and therefore where in Python's namespace hierarchy) the resulting extension lives. If you have a number of extensions all in the same package (or all under the -same base package), use the :option:`ext_package` keyword argument to +same base package), use the ``ext_package`` keyword argument to :func:`setup`. For example, :: setup(..., @@ -336,24 +336,24 @@ Other options There are still some other options which can be used to handle special cases. -The :option:`optional` option is a boolean; if it is true, +The ``optional`` option is a boolean; if it is true, a build failure in the extension will not abort the build process, but instead simply not install the failing extension. -The :option:`extra_objects` option is a list of object files to be passed to the +The ``extra_objects`` option is a list of object files to be passed to the linker. These files must not have extensions, as the default extension for the compiler is used. -:option:`extra_compile_args` and :option:`extra_link_args` can be used to +``extra_compile_args`` and ``extra_link_args`` can be used to specify additional command line options for the respective compiler and linker command lines. -:option:`export_symbols` is only useful on Windows. It can contain a list of +``export_symbols`` is only useful on Windows. It can contain a list of symbols (functions or variables) to be exported. This option is not needed when building compiled extensions: Distutils will automatically add ``initmodule`` to the list of exported symbols. -The :option:`depends` option is a list of files that the extension depends on +The ``depends`` option is a list of files that the extension depends on (for example header files). The build command will call the compiler on the sources to rebuild extension if any on this files has been modified since the previous build. @@ -449,7 +449,7 @@ to refer to the current interpreter location. By default, it is replaced with the current interpreter location. The :option:`--executable` (or :option:`-e`) option will allow the interpreter path to be explicitly overridden. -The :option:`scripts` option simply is a list of files to be handled in this +The ``scripts`` option simply is a list of files to be handled in this way. From the PyXML setup script:: setup(..., @@ -514,11 +514,11 @@ The corresponding call to :func:`setup` might be:: Installing Additional Files =========================== -The :option:`data_files` option can be used to specify additional files needed +The ``data_files`` option can be used to specify additional files needed by the module distribution: configuration files, message catalogs, data files, anything which doesn't fit in the previous categories. -:option:`data_files` specifies a sequence of (*directory*, *files*) pairs in the +``data_files`` specifies a sequence of (*directory*, *files*) pairs in the following way:: setup(..., @@ -539,7 +539,7 @@ modules). Each file name in *files* is interpreted relative to the directory information from *files* is used to determine the final location of the installed file; only the name of the file is used. -You can specify the :option:`data_files` options as a simple sequence of files +You can specify the ``data_files`` options as a simple sequence of files without specifying a target directory, but this is not recommended, and the :command:`install` command will print a warning in this case. To install data files directly in the target directory, an empty string should be given as the @@ -650,7 +650,7 @@ information is sometimes used to indicate sub-releases. These are 1.0.1a2 the second alpha release of the first patch version of 1.0 -:option:`classifiers` are specified in a Python list:: +``classifiers`` are specified in a Python list:: setup(..., classifiers=[ diff --git a/sourcedist.rst b/sourcedist.rst index 427b7b1b2a..b9f0cc863b 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -72,16 +72,16 @@ If you don't supply an explicit list of files (or instructions on how to generate one), the :command:`sdist` command puts a minimal default set into the source distribution: -* all Python source files implied by the :option:`py_modules` and - :option:`packages` options +* all Python source files implied by the ``py_modules`` and + ``packages`` options -* all C source files mentioned in the :option:`ext_modules` or - :option:`libraries` options +* all C source files mentioned in the ``ext_modules`` or + ``libraries`` options .. XXX getting C library sources currently broken---no :meth:`get_source_files` method in :file:`build_clib.py`! -* scripts identified by the :option:`scripts` option +* scripts identified by the ``scripts`` option See :ref:`distutils-installing-scripts`. * anything that looks like a test script: :file:`test/test\*.py` (currently, the @@ -167,7 +167,7 @@ source distribution: #. include all Python source files in the :file:`distutils` and :file:`distutils/command` subdirectories (because packages corresponding to - those two directories were mentioned in the :option:`packages` option in the + those two directories were mentioned in the ``packages`` option in the setup script---see section :ref:`setup-script`) #. include :file:`README.txt`, :file:`setup.py`, and :file:`setup.cfg` (standard From 26f4ac4c0853f2fde68dde8343c130340a4e378b Mon Sep 17 00:00:00 2001 From: R David Murray Date: Sun, 12 Oct 2014 13:14:12 -0400 Subject: [PATCH 265/330] #17325: Improve distutils PyPI documentation. Patch by Chris Jerdonek. --- packageindex.rst | 146 +++++++++++++++++++++++++++++------------------ 1 file changed, 90 insertions(+), 56 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index dae8c545d0..59d27bca86 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -8,26 +8,57 @@ The Python Package Index (PyPI) ******************************* -The `Python Package Index (PyPI)`_ holds :ref:`meta-data ` +The `Python Package Index (PyPI)`_ stores :ref:`meta-data ` describing distributions packaged with distutils, as well as package data like -distribution files if the package author wishes. +distribution files if a package author wishes. + +Distutils provides the :command:`register` and :command:`upload` commands for +pushing meta-data and distribution files to PyPI, respectively. See +:ref:`package-commands` for information on these commands. + + +PyPI overview +============= + +PyPI lets you submit any number of versions of your distribution to the index. +If you alter the meta-data for a particular version, you can submit it again +and the index will be updated. + +PyPI holds a record for each (name, version) combination submitted. The first +user to submit information for a given name is designated the Owner of that +name. Changes can be submitted through the :command:`register` command or +through the web interface. Owners can designate other users as Owners or +Maintainers. Maintainers can edit the package information, but not designate +new Owners or Maintainers. + +By default PyPI displays only the newest version of a given package. The web +interface lets one change this default behavior and manually select which +versions to display and hide. + +For each version, PyPI displays a home page. The home page is created from +the ``long_description`` which can be submitted via the :command:`register` +command. See :ref:`package-display` for more information. + + +.. _package-commands: + +Distutils commands +================== Distutils exposes two commands for submitting package data to PyPI: the :ref:`register ` command for submitting meta-data to PyPI and the :ref:`upload ` command for submitting distribution -files. Both commands read configuration data from a special file called the -:ref:`.pypirc file `. PyPI :ref:`displays a home page -` for each package created from the ``long_description`` -submitted by the :command:`register` command. +files. Both commands read configuration data from a special file called a +:ref:`.pypirc file `. .. _package-register: -Registering Packages -==================== +The ``register`` command +------------------------ The distutils command :command:`register` is used to submit your distribution's -meta-data to the index. It is invoked as follows:: +meta-data to an index server. It is invoked as follows:: python setup.py register @@ -42,7 +73,8 @@ Distutils will respond with the following prompt:: Your selection [default 1]: Note: if your username and password are saved locally, you will not see this -menu. +menu. Also, refer to :ref:`pypirc` for how to store your credentials in a +:file:`.pypirc` file. If you have not registered with PyPI, then you will need to do so now. You should choose option 2, and enter your details as required. Soon after @@ -53,26 +85,13 @@ Once you are registered, you may choose option 1 from the menu. You will be prompted for your PyPI username and password, and :command:`register` will then submit your meta-data to the index. -You may submit any number of versions of your distribution to the index. If you -alter the meta-data for a particular version, you may submit it again and the -index will be updated. - -PyPI holds a record for each (name, version) combination submitted. The first -user to submit information for a given name is designated the Owner of that -name. They may submit changes through the :command:`register` command or through -the web interface. They may also designate other users as Owners or Maintainers. -Maintainers may edit the package information, but not designate other Owners or -Maintainers. - -By default PyPI displays only the newest version of a given package. The web -interface lets one change this default behavior and manually select which -versions to display and hide. +See :ref:`package-cmdoptions` for options to the :command:`register` command. .. _package-upload: -Uploading Packages -================== +The ``upload`` command +---------------------- The distutils command :command:`upload` pushes the distribution files to PyPI. @@ -86,29 +105,42 @@ PyPI. Note that these will be uploaded even if they are built using an earlier invocation of :file:`setup.py`, but that only distributions named on the command line for the invocation including the :command:`upload` command are uploaded. -The :command:`upload` command uses the username, password, and repository URL -from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this -file). If a :command:`register` command was previously called in the same command, +If a :command:`register` command was previously called in the same command, and if the password was entered in the prompt, :command:`upload` will reuse the -entered password. This is useful if you do not want to store a clear text -password in the :file:`$HOME/.pypirc` file. - -You can specify another PyPI server with the ``--repository=url`` option:: - - python setup.py sdist bdist_wininst upload -r http://example.com/pypi - -See section :ref:`pypirc` for more on defining several servers. +entered password. This is useful if you do not want to store a password in +clear text in a :file:`.pypirc` file. You can use the ``--sign`` option to tell :command:`upload` to sign each uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must be available for execution on the system :envvar:`PATH`. You can also specify which key to use for signing using the ``--identity=name`` option. -Other :command:`upload` options include ``--repository=url`` or -``--repository=section`` where *url* is the url of the server and -*section* the name of the section in :file:`$HOME/.pypirc`, and -``--show-response`` (which displays the full response text from the PyPI -server for help in debugging upload problems). +See :ref:`package-cmdoptions` for additional options to the :command:`upload` +command. + + +.. _package-cmdoptions: + +Additional command options +-------------------------- + +This section describes options common to both the :command:`register` and +:command:`upload` commands. + +The ``--repository`` or ``-r`` option lets you specify a PyPI server +different from the default. For example:: + + python setup.py sdist bdist_wininst upload -r https://example.com/pypi + +For convenience, a name can be used in place of the URL when the +:file:`.pypirc` file is configured to do so. For example:: + + python setup.py register -r other + +See :ref:`pypirc` for more information on defining alternate servers. + +The ``--show-response`` option displays the full response text from the PyPI +server, which is useful when debugging problems with registering and uploading. .. index:: @@ -117,10 +149,14 @@ server for help in debugging upload problems). .. _pypirc: -The .pypirc file -================ +The ``.pypirc`` file +-------------------- -The format of the :file:`.pypirc` file is as follows:: +The :command:`register` and :command:`upload` commands both check for the +existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`. +If this file exists, the command uses the username, password, and repository +URL configured in the file. The format of a :file:`.pypirc` file is as +follows:: [distutils] index-servers = @@ -137,7 +173,7 @@ name of all sections describing a repository. Each section describing a repository defines three variables: - *repository*, that defines the url of the PyPI server. Defaults to - ``http://www.python.org/pypi``. + ``https://www.python.org/pypi``. - *username*, which is the registered username on the PyPI server. - *password*, that will be used to authenticate. If omitted the user will be prompt to type it when needed. @@ -156,19 +192,17 @@ listed in the *index-servers* variable:: password: [other] - repository: http://example.com/pypi + repository: https://example.com/pypi username: password: -:command:`register` can then be called with the -r option to point the -repository to work with:: - - python setup.py register -r http://example.com/pypi +This allows the :command:`register` and :command:`upload` commands to be +called with the ``--repository`` option as described in +:ref:`package-cmdoptions`. -For convenience, the name of the section that describes the repository -may also be used:: - - python setup.py register -r other +Specifically, you might want to add the `PyPI Test Repository +`_ to your ``.pypirc`` to facilitate +testing before doing your first upload to ``PyPI`` itself. .. _package-display: @@ -210,4 +244,4 @@ without warnings does not guarantee that PyPI will convert the content successfully. -.. _Python Package Index (PyPI): http://pypi.python.org/ +.. _Python Package Index (PyPI): https://pypi.python.org/ From 7499bd179ce23b91d7d28b072d5ecbb90f1a2c85 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 29 Oct 2014 08:36:35 +0100 Subject: [PATCH 266/330] Use https:// URLs when referring to python.org hosts. --- apiref.rst | 2 +- examples.rst | 2 +- setupscript.rst | 4 ++-- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/apiref.rst b/apiref.rst index e1357fa90d..fff06416b2 100644 --- a/apiref.rst +++ b/apiref.rst @@ -78,7 +78,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | | be built | :class:`distutils.core.Extension` | +--------------------+--------------------------------+-------------------------------------------------------------+ | *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI | - | | package | `_. | + | | package | `_. | +--------------------+--------------------------------+-------------------------------------------------------------+ | *distclass* | the :class:`Distribution` | a subclass of | | | class to use | :class:`distutils.core.Distribution` | diff --git a/examples.rst b/examples.rst index b1ecd01dab..b08e023859 100644 --- a/examples.rst +++ b/examples.rst @@ -11,7 +11,7 @@ Distutils Cookbook. .. seealso:: - `Distutils Cookbook `_ + `Distutils Cookbook `_ Collection of recipes showing how to achieve more control over distutils. diff --git a/setupscript.rst b/setupscript.rst index 8d89f3bf24..7fe73b9255 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -28,7 +28,7 @@ the package into Python 1.5.2.) :: description='Python Distribution Utilities', author='Greg Ward', author_email='gward@python.net', - url='http://www.python.org/sigs/distutils-sig/', + url='https://www.python.org/sigs/distutils-sig/', packages=['distutils', 'distutils.command'], ) @@ -609,7 +609,7 @@ Notes: (4) These fields should not be used if your package is to be compatible with Python versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website - `_. + `_. (5) The ``long_description`` field is used by PyPI when you are From 137cd9042de75054550b8453af4a3bfb53bde3ef Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 29 Oct 2014 09:24:54 +0100 Subject: [PATCH 267/330] Fixing broken links in doc, part 1: faq/ --- packageindex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packageindex.rst b/packageindex.rst index 59d27bca86..daf9345264 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -244,4 +244,4 @@ without warnings does not guarantee that PyPI will convert the content successfully. -.. _Python Package Index (PyPI): https://pypi.python.org/ +.. _Python Package Index (PyPI): https://pypi.python.org/pypi From 8854bbdb07b276b84c44b8c8814ba0c720798539 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Wed, 29 Oct 2014 10:57:37 +0100 Subject: [PATCH 268/330] Fixing broken links in doc, part 4: some more breaks and redirects --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index 7fe73b9255..3edcf878c7 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -628,7 +628,7 @@ Notes: 'long string' Multiple lines of plain text in reStructuredText format (see - http://docutils.sf.net/). + http://docutils.sourceforge.net/). 'list of strings' See below. From c2be7de3f0752aeb29eb7bce596b14ad3049574c Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 30 Oct 2014 22:25:41 +0100 Subject: [PATCH 269/330] Doc: fix default role usage (except in unittest mock docs) --- examples.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/examples.rst b/examples.rst index b08e023859..2ca76a096e 100644 --- a/examples.rst +++ b/examples.rst @@ -286,20 +286,20 @@ Reading the metadata The :func:`distutils.core.setup` function provides a command-line interface that allows you to query the metadata fields of a project through the -`setup.py` script of a given project:: +``setup.py`` script of a given project:: $ python setup.py --name distribute -This call reads the `name` metadata by running the +This call reads the ``name`` metadata by running the :func:`distutils.core.setup` function. Although, when a source or binary distribution is created with Distutils, the metadata fields are written in a static file called :file:`PKG-INFO`. When a Distutils-based project is installed in Python, the :file:`PKG-INFO` file is copied alongside the modules and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, -where `NAME` is the name of the project, `VERSION` its version as defined -in the Metadata, and `pyX.X` the major and minor version of Python like -`2.7` or `3.2`. +where ``NAME`` is the name of the project, ``VERSION`` its version as defined +in the Metadata, and ``pyX.X`` the major and minor version of Python like +``2.7`` or ``3.2``. You can read back this static file, by using the :class:`distutils.dist.DistributionMetadata` class and its From cb4aa18fc42a6d5a10b466ca5da7019d63b9b522 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 30 Oct 2014 22:26:26 +0100 Subject: [PATCH 270/330] Doc: fix default role usage (except in unittest mock docs) --- examples.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/examples.rst b/examples.rst index b08e023859..2ca76a096e 100644 --- a/examples.rst +++ b/examples.rst @@ -286,20 +286,20 @@ Reading the metadata The :func:`distutils.core.setup` function provides a command-line interface that allows you to query the metadata fields of a project through the -`setup.py` script of a given project:: +``setup.py`` script of a given project:: $ python setup.py --name distribute -This call reads the `name` metadata by running the +This call reads the ``name`` metadata by running the :func:`distutils.core.setup` function. Although, when a source or binary distribution is created with Distutils, the metadata fields are written in a static file called :file:`PKG-INFO`. When a Distutils-based project is installed in Python, the :file:`PKG-INFO` file is copied alongside the modules and packages of the distribution under :file:`NAME-VERSION-pyX.X.egg-info`, -where `NAME` is the name of the project, `VERSION` its version as defined -in the Metadata, and `pyX.X` the major and minor version of Python like -`2.7` or `3.2`. +where ``NAME`` is the name of the project, ``VERSION`` its version as defined +in the Metadata, and ``pyX.X`` the major and minor version of Python like +``2.7`` or ``3.2``. You can read back this static file, by using the :class:`distutils.dist.DistributionMetadata` class and its From 0835a8e8305d623541500507e084f0b0323baffe Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 30 Oct 2014 22:50:46 +0100 Subject: [PATCH 271/330] distutils example: fix invalid rst in description string --- examples.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples.rst b/examples.rst index 2ca76a096e..af9125a7b3 100644 --- a/examples.rst +++ b/examples.rst @@ -264,7 +264,7 @@ For example, if the :file:`setup.py` script is changed like this:: desc = """\ My description - ============= + ============== This is the description of the ``foobar`` package. """ From 4878d3777194535b1849a3ef6c6372cf7f5b7717 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Tue, 13 Jan 2015 09:17:24 -0500 Subject: [PATCH 272/330] fix instances of consecutive articles (closes #23221) Patch by Karan Goel. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index fff06416b2..82bed24983 100644 --- a/apiref.rst +++ b/apiref.rst @@ -964,7 +964,7 @@ directories. .. function:: create_tree(base_dir, files[, mode=0o777, verbose=0, dry_run=0]) Create all the empty directories under *base_dir* needed to put *files* there. - *base_dir* is just the a name of a directory which doesn't necessarily exist + *base_dir* is just the name of a directory which doesn't necessarily exist yet; *files* is a list of filenames to be interpreted relative to *base_dir*. *base_dir* + the directory portion of every file in *files* will be created if it doesn't already exist. *mode*, *verbose* and *dry_run* flags are as for From ac5e667e4d644a2917bfb77e5a2cb1ff44aeb0f3 Mon Sep 17 00:00:00 2001 From: Berker Peksag Date: Tue, 17 Mar 2015 06:55:48 +0200 Subject: [PATCH 273/330] Issue #23682: Delete Python 2.2 mention from distutils documentation. Patch by Thomas Kluyver. --- setupscript.rst | 14 -------------- 1 file changed, 14 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 3edcf878c7..914a34f1c8 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -671,20 +671,6 @@ information is sometimes used to indicate sub-releases. These are ], ) -If you wish to include classifiers in your :file:`setup.py` file and also wish -to remain backwards-compatible with Python releases prior to 2.2.3, then you can -include the following code fragment in your :file:`setup.py` before the -:func:`setup` call. :: - - # patch distutils if it can't cope with the "classifiers" or - # "download_url" keywords - from sys import version - if version < '2.2.3': - from distutils.dist import DistributionMetadata - DistributionMetadata.classifiers = None - DistributionMetadata.download_url = None - - .. _debug-setup-script: Debugging the setup script From ab8064d8fb8a10b29c41c3acde86c910773cb179 Mon Sep 17 00:00:00 2001 From: Brett Cannon Date: Mon, 13 Apr 2015 14:21:02 -0400 Subject: [PATCH 274/330] Issue #23731: Implement PEP 488. The concept of .pyo files no longer exists. Now .pyc files have an optional `opt-` tag which specifies if any extra optimizations beyond the peepholer were applied. --- apiref.rst | 11 +++++++---- introduction.rst | 6 ++---- 2 files changed, 9 insertions(+), 8 deletions(-) diff --git a/apiref.rst b/apiref.rst index 53d7527c65..087c6715ce 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1193,12 +1193,12 @@ other utility module. .. function:: byte_compile(py_files[, optimize=0, force=0, prefix=None, base_dir=None, verbose=1, dry_run=0, direct=None]) - Byte-compile a collection of Python source files to either :file:`.pyc` or - :file:`.pyo` files in a :file:`__pycache__` subdirectory (see :pep:`3147`). + Byte-compile a collection of Python source files to :file:`.pyc` files in a + :file:`__pycache__` subdirectory (see :pep:`3147` and :pep:`488`). *py_files* is a list of files to compile; any files that don't end in :file:`.py` are silently skipped. *optimize* must be one of the following: - * ``0`` - don't optimize (generate :file:`.pyc`) + * ``0`` - don't optimize * ``1`` - normal optimization (like ``python -O``) * ``2`` - extra optimization (like ``python -OO``) @@ -1222,10 +1222,13 @@ other utility module. doing, leave it set to ``None``. .. versionchanged:: 3.2.3 - Create ``.pyc`` or ``.pyo`` files with an :func:`import magic tag + Create ``.pyc`` files with an :func:`import magic tag ` in their name, in a :file:`__pycache__` subdirectory instead of files without tag in the current directory. + .. versionchanged: 3.5 + Create ``.pyc`` files according to :pep:`488`. + .. function:: rfc822_escape(header) diff --git a/introduction.rst b/introduction.rst index 0ece646c34..8f46bd74c5 100644 --- a/introduction.rst +++ b/introduction.rst @@ -156,8 +156,8 @@ module pure Python module a module written in Python and contained in a single :file:`.py` file (and - possibly associated :file:`.pyc` and/or :file:`.pyo` files). Sometimes referred - to as a "pure module." + possibly associated :file:`.pyc` files). Sometimes referred to as a + "pure module." extension module a module written in the low-level language of the Python implementation: C/C++ @@ -210,5 +210,3 @@ distribution root the top-level directory of your source tree (or source distribution); the directory where :file:`setup.py` exists. Generally :file:`setup.py` will be run from this directory. - - From 6474391624b295d0b820f6ed0129a9c906fad519 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sat, 16 May 2015 22:13:27 +0300 Subject: [PATCH 275/330] Issue #16314: Added support for the LZMA compression in distutils. --- apiref.rst | 32 ++++++++++++++++++++------------ builtdist.rst | 47 ++++++++++++++++++++++++++++------------------- sourcedist.rst | 8 +++++++- 3 files changed, 55 insertions(+), 32 deletions(-) diff --git a/apiref.rst b/apiref.rst index 087c6715ce..d0f89471f8 100644 --- a/apiref.rst +++ b/apiref.rst @@ -868,23 +868,31 @@ tarballs or zipfiles. Create an archive file (eg. ``zip`` or ``tar``). *base_name* is the name of the file to create, minus any format-specific extension; *format* is the - archive format: one of ``zip``, ``tar``, ``ztar``, or ``gztar``. *root_dir* is - a directory that will be the root directory of the archive; ie. we typically - ``chdir`` into *root_dir* before creating the archive. *base_dir* is the - directory where we start archiving from; ie. *base_dir* will be the common - prefix of all files and directories in the archive. *root_dir* and *base_dir* - both default to the current directory. Returns the name of the archive file. + archive format: one of ``zip``, ``tar``, ``gztar``, ``bztar``, ``xztar``, or + ``ztar``. *root_dir* is a directory that will be the root directory of the + archive; ie. we typically ``chdir`` into *root_dir* before creating the + archive. *base_dir* is the directory where we start archiving from; ie. + *base_dir* will be the common prefix of all files and directories in the + archive. *root_dir* and *base_dir* both default to the current directory. + Returns the name of the archive file. + + .. versionchanged: 3.5 + Added support for the ``xztar`` format. .. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0]) 'Create an (optional compressed) archive as a tar file from all files in and - under *base_dir*. *compress* must be ``'gzip'`` (the default), ``'compress'``, - ``'bzip2'``, or ``None``. Both :program:`tar` and the compression utility named - by *compress* must be on the default program search path, so this is probably - Unix-specific. The output tar file will be named :file:`base_dir.tar`, - possibly plus the appropriate compression extension (:file:`.gz`, :file:`.bz2` - or :file:`.Z`). Return the output filename. + under *base_dir*. *compress* must be ``'gzip'`` (the default), + ``'bzip2'``, ``'xz'``, ``'compress'``, or ``None``. For the ``'compress'`` + method the compression utility named by :program:`compress` must be on the + default program search path, so this is probably Unix-specific. The output + tar file will be named :file:`base_dir.tar`, possibly plus the appropriate + compression extension (``.gz``, ``.bz2``, ``.xz`` or ``.Z``). Return the + output filename. + + .. versionchanged: 3.5 + Added support for the ``xz`` compression. .. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0]) diff --git a/builtdist.rst b/builtdist.rst index c5827b63cf..144619b41b 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -72,13 +72,19 @@ The available formats for built distributions are: +-------------+------------------------------+---------+ | Format | Description | Notes | +=============+==============================+=========+ -| ``gztar`` | gzipped tar file | (1),(3) | +| ``gztar`` | gzipped tar file | \(1) | | | (:file:`.tar.gz`) | | +-------------+------------------------------+---------+ +| ``bztar`` | bzipped tar file | | +| | (:file:`.tar.bz2`) | | ++-------------+------------------------------+---------+ +| ``xztar`` | xzipped tar file | | +| | (:file:`.tar.xz`) | | ++-------------+------------------------------+---------+ | ``ztar`` | compressed tar file | \(3) | | | (:file:`.tar.Z`) | | +-------------+------------------------------+---------+ -| ``tar`` | tar file (:file:`.tar`) | \(3) | +| ``tar`` | tar file (:file:`.tar`) | | +-------------+------------------------------+---------+ | ``zip`` | zip file (:file:`.zip`) | (2),(4) | +-------------+------------------------------+---------+ @@ -94,6 +100,9 @@ The available formats for built distributions are: | ``msi`` | Microsoft Installer. | | +-------------+------------------------------+---------+ +.. versionchanged: 3.5 + Added support for the ``xztar`` format. + Notes: @@ -104,8 +113,7 @@ Notes: default on Windows (3) - requires external utilities: :program:`tar` and possibly one of :program:`gzip`, - :program:`bzip2`, or :program:`compress` + requires external :program:`compress` utility. (4) requires either external :program:`zip` utility or :mod:`zipfile` module (part @@ -119,21 +127,22 @@ You don't have to use the :command:`bdist` command with the :option:`--formats` option; you can also use the command that directly implements the format you're interested in. Some of these :command:`bdist` "sub-commands" actually generate several similar formats; for instance, the :command:`bdist_dumb` command -generates all the "dumb" archive formats (``tar``, ``ztar``, ``gztar``, and -``zip``), and :command:`bdist_rpm` generates both binary and source RPMs. The -:command:`bdist` sub-commands, and the formats generated by each, are: - -+--------------------------+-----------------------+ -| Command | Formats | -+==========================+=======================+ -| :command:`bdist_dumb` | tar, ztar, gztar, zip | -+--------------------------+-----------------------+ -| :command:`bdist_rpm` | rpm, srpm | -+--------------------------+-----------------------+ -| :command:`bdist_wininst` | wininst | -+--------------------------+-----------------------+ -| :command:`bdist_msi` | msi | -+--------------------------+-----------------------+ +generates all the "dumb" archive formats (``tar``, ``gztar``, ``bztar``, +``xztar``, ``ztar``, and ``zip``), and :command:`bdist_rpm` generates both +binary and source RPMs. The :command:`bdist` sub-commands, and the formats +generated by each, are: + ++--------------------------+-------------------------------------+ +| Command | Formats | ++==========================+=====================================+ +| :command:`bdist_dumb` | tar, gztar, bztar, xztar, ztar, zip | ++--------------------------+-------------------------------------+ +| :command:`bdist_rpm` | rpm, srpm | ++--------------------------+-------------------------------------+ +| :command:`bdist_wininst` | wininst | ++--------------------------+-------------------------------------+ +| :command:`bdist_msi` | msi | ++--------------------------+-------------------------------------+ The following sections give details on the individual :command:`bdist_\*` commands. diff --git a/sourcedist.rst b/sourcedist.rst index b9f0cc863b..d79f00d62f 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -32,12 +32,18 @@ to create a gzipped tarball and a zip file. The available formats are: | ``bztar`` | bzip2'ed tar file | | | | (:file:`.tar.bz2`) | | +-----------+-------------------------+---------+ +| ``xztar`` | xz'ed tar file | | +| | (:file:`.tar.xz`) | | ++-----------+-------------------------+---------+ | ``ztar`` | compressed tar file | \(4) | | | (:file:`.tar.Z`) | | +-----------+-------------------------+---------+ | ``tar`` | tar file (:file:`.tar`) | | +-----------+-------------------------+---------+ +.. versionchanged: 3.5 + Added support for the ``xztar`` format. + Notes: (1) @@ -54,7 +60,7 @@ Notes: requires the :program:`compress` program. Notice that this format is now pending for deprecation and will be removed in the future versions of Python. -When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or +When using any ``tar`` format (``gztar``, ``bztar``, ``xztar``, ``ztar`` or ``tar``), under Unix you can specify the ``owner`` and ``group`` names that will be set for each member of the archive. From 762d61581289ad8f015e68906a73096dff908c19 Mon Sep 17 00:00:00 2001 From: Senthil Kumaran Date: Sun, 14 Jun 2015 17:35:37 -0700 Subject: [PATCH 276/330] Back porting changeset db302b88fdb6 to 3.4 branch, which fixed multiple documentation typos. Related Issues: #issue21528 #issue24453 --- apiref.rst | 4 ++-- builtdist.rst | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 82bed24983..53d7527c65 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1099,13 +1099,13 @@ other utility module. during the build of Python), not the OS version of the current system. For universal binary builds on Mac OS X the architecture value reflects - the univeral binary status instead of the architecture of the current + the universal binary status instead of the architecture of the current processor. For 32-bit universal binaries the architecture is ``fat``, for 64-bit universal binaries the architecture is ``fat64``, and for 4-way universal binaries the architecture is ``universal``. Starting from Python 2.7 and Python 3.2 the architecture ``fat3`` is used for a 3-way universal build (ppc, i386, x86_64) and ``intel`` is used for - a univeral build with the i386 and x86_64 architectures + a universal build with the i386 and x86_64 architectures Examples of returned values on Mac OS X: diff --git a/builtdist.rst b/builtdist.rst index ac96c40300..c5827b63cf 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -355,7 +355,7 @@ support this option, so the command:: would create a 64bit installation executable on your 32bit version of Windows. To cross-compile, you must download the Python source code and cross-compile -Python itself for the platform you are targetting - it is not possible from a +Python itself for the platform you are targeting - it is not possible from a binary installation of Python (as the .lib etc file for other platforms are not included.) In practice, this means the user of a 32 bit operating system will need to use Visual Studio 2008 to open the From fd199a1cad0e839012ffa3c3420b66b73f7028c8 Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Tue, 7 Jul 2015 00:11:36 -0500 Subject: [PATCH 277/330] Fix versionchanged directives --- builtdist.rst | 2 +- sourcedist.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index 144619b41b..523d1e0fff 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -100,7 +100,7 @@ The available formats for built distributions are: | ``msi`` | Microsoft Installer. | | +-------------+------------------------------+---------+ -.. versionchanged: 3.5 +.. versionchanged:: 3.5 Added support for the ``xztar`` format. diff --git a/sourcedist.rst b/sourcedist.rst index d79f00d62f..fb70514b79 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -41,7 +41,7 @@ to create a gzipped tarball and a zip file. The available formats are: | ``tar`` | tar file (:file:`.tar`) | | +-----------+-------------------------+---------+ -.. versionchanged: 3.5 +.. versionchanged:: 3.5 Added support for the ``xztar`` format. Notes: From 6a02b767957236bbc35c1a2e4c2350a5d8b7d7ed Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Sat, 12 Sep 2015 17:20:47 -0700 Subject: [PATCH 278/330] fix name of argument in docstring and the docs (closes #25076) Patch by TAKASE Arihiro. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 53d7527c65..6eb87cb2f7 100644 --- a/apiref.rst +++ b/apiref.rst @@ -521,7 +521,7 @@ This module provides the following functions. .. method:: CCompiler.library_option(lib) - Return the compiler option to add *dir* to the list of libraries linked into the + Return the compiler option to add *lib* to the list of libraries linked into the shared library or executable. From ce40227d19256f0c57fbc2c1d6ba7f8e2cd20b3d Mon Sep 17 00:00:00 2001 From: Martin Panter Date: Sat, 10 Oct 2015 10:36:22 +0000 Subject: [PATCH 279/330] Issue #25161: Add full stops in documentation; patch by Takase Arihiro --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 6eb87cb2f7..f67fc5ae25 100644 --- a/apiref.rst +++ b/apiref.rst @@ -920,7 +920,7 @@ timestamp dependency analysis. Walk two filename lists in parallel, testing if each source is newer than its corresponding target. Return a pair of lists (*sources*, *targets*) where - source is newer than target, according to the semantics of :func:`newer` + source is newer than target, according to the semantics of :func:`newer`. .. % % equivalent to a listcomp... From 1d59f2e2bd4f085345291116210f09c37d69c287 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Mon, 2 Nov 2015 14:10:23 +0200 Subject: [PATCH 280/330] Issue #25523: Further a-to-an corrections. --- packageindex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packageindex.rst b/packageindex.rst index daf9345264..2d7daef784 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -167,7 +167,7 @@ follows:: username: password: -The *distutils* section defines a *index-servers* variable that lists the +The *distutils* section defines an *index-servers* variable that lists the name of all sections describing a repository. Each section describing a repository defines three variables: From d478d81e7883cdc561c1783d7a78a959d09dd5c3 Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Tue, 3 Nov 2015 22:42:02 -0800 Subject: [PATCH 281/330] link to modern PUG url --- index.rst | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/index.rst b/index.rst index 90d1c1ab34..335f804d42 100644 --- a/index.rst +++ b/index.rst @@ -15,10 +15,9 @@ very little overhead for build/release/install mechanics. .. note:: This guide only covers the basic tools for building and distributing - extensions that are provided as part of this version of Python. Third - party tools offer easier to use and more secure alternatives. Refer to the - `quick recommendations section - `__ + extensions that are provided as part of this version of Python. Third party + tools offer easier to use and more secure alternatives. Refer to the `quick + recommendations section `__ in the Python Packaging User Guide for more information. From fe0cbdad21ed687f454e0ca1f86435ae037ee619 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Thu, 25 Feb 2016 20:17:45 +0100 Subject: [PATCH 282/330] Closes #26435: fix syntax in directives. Thanks to Jakub Stasiak. --- apiref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 554d2c878d..6b2d5cb099 100644 --- a/apiref.rst +++ b/apiref.rst @@ -876,7 +876,7 @@ tarballs or zipfiles. archive. *root_dir* and *base_dir* both default to the current directory. Returns the name of the archive file. - .. versionchanged: 3.5 + .. versionchanged:: 3.5 Added support for the ``xztar`` format. @@ -891,7 +891,7 @@ tarballs or zipfiles. compression extension (``.gz``, ``.bz2``, ``.xz`` or ``.Z``). Return the output filename. - .. versionchanged: 3.5 + .. versionchanged:: 3.5 Added support for the ``xz`` compression. @@ -1234,7 +1234,7 @@ other utility module. ` in their name, in a :file:`__pycache__` subdirectory instead of files without tag in the current directory. - .. versionchanged: 3.5 + .. versionchanged:: 3.5 Create ``.pyc`` files according to :pep:`488`. From d8941f454f55ad3e91b3274b74899cfaa9848307 Mon Sep 17 00:00:00 2001 From: Georg Brandl Date: Fri, 26 Feb 2016 19:37:12 +0100 Subject: [PATCH 283/330] Closes #25910: fix dead and permanently redirected links in the docs. Thanks to SilentGhost for the patch. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index 6b2d5cb099..7e2cfe379c 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1822,7 +1822,7 @@ Subclasses of :class:`Command` must define the following methods. Builds a `Windows Installer`_ (.msi) binary package. - .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx + .. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx In most cases, the ``bdist_msi`` installer is a better choice than the ``bdist_wininst`` installer, because it provides better support for From 7f1f4685be800092b6d550a8dbbb8a3029636aec Mon Sep 17 00:00:00 2001 From: Martin Panter Date: Sat, 16 Apr 2016 04:59:38 +0000 Subject: [PATCH 284/330] Issue #26638: Fix links to some CLI options and section headings * Disable inappropriate links to Python interpreter options * Correct link to CLI section in zipapp * Make CLI section label in timeit less ambiguous --- apiref.rst | 8 ++++---- configfile.rst | 2 +- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/apiref.rst b/apiref.rst index 7e2cfe379c..e66835a811 100644 --- a/apiref.rst +++ b/apiref.rst @@ -319,12 +319,12 @@ This module provides the following functions. .. function:: gen_preprocess_options(macros, include_dirs) - Generate C pre-processor options (:option:`-D`, :option:`-U`, :option:`-I`) as + Generate C pre-processor options (:option:`-D`, :option:`!-U`, :option:`!-I`) as used by at least two types of compilers: the typical Unix compiler and Visual C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)`` - means undefine (:option:`-U`) macro *name*, and ``(name, value)`` means define + means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define (:option:`-D`) macro *name* to *value*. *include_dirs* is just a list of - directory names to be added to the header file search path (:option:`-I`). + directory names to be added to the header file search path (:option:`!-I`). Returns a list of command-line options suitable for either Unix compilers or Visual C++. @@ -799,7 +799,7 @@ This module provides the :class:`UnixCCompiler` class, a subclass of * library search directories specified with :option:`-Ldir` -* compile handled by :program:`cc` (or similar) executable with :option:`-c` +* compile handled by :program:`cc` (or similar) executable with :option:`!-c` option: compiles :file:`.c` to :file:`.o` * link static library handled by :program:`ar` command (possibly with diff --git a/configfile.rst b/configfile.rst index 8faffe6c20..51d88971a4 100644 --- a/configfile.rst +++ b/configfile.rst @@ -51,7 +51,7 @@ option values can be split across multiple lines simply by indenting the continuation lines. You can find out the list of options supported by a particular command with the -universal :option:`--help` option, e.g. :: +universal :option:`!--help` option, e.g. :: > python setup.py --help build_ext [...] From a5df731635f16d52271c2062015bf6753799826f Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sun, 17 Apr 2016 08:32:47 +0300 Subject: [PATCH 285/330] Issue #26778: Fixed "a/an/and" typos in code comment and documentation. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index e66835a811..7d6a84e159 100644 --- a/apiref.rst +++ b/apiref.rst @@ -837,7 +837,7 @@ selection by :class:`MSVCCompiler`. .. module:: distutils.bcppcompiler -This module provides :class:`BorlandCCompiler`, an subclass of the abstract +This module provides :class:`BorlandCCompiler`, a subclass of the abstract :class:`CCompiler` class for the Borland C++ compiler. From bc2bc7a000a346b4b3384ffe772cc3c1b5d364bc Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Tue, 10 May 2016 12:01:23 +0300 Subject: [PATCH 286/330] Issue #23921: Standardized documentation whitespace formatting. Original patch by James Edwards. --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 7d6a84e159..0672253471 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1907,9 +1907,9 @@ Subclasses of :class:`Command` must define the following methods. that is designed to run with both Python 2.x and 3.x, add:: try: - from distutils.command.build_py import build_py_2to3 as build_py + from distutils.command.build_py import build_py_2to3 as build_py except ImportError: - from distutils.command.build_py import build_py + from distutils.command.build_py import build_py to your setup.py, and later:: From da6d254478a3c573541dfe1b7dde025f3c749389 Mon Sep 17 00:00:00 2001 From: Ned Deily Date: Sun, 5 Jun 2016 17:38:48 -0700 Subject: [PATCH 287/330] Issue #26014: Update 3.x packaging documentation: - "See also" links to the new docs are now provided in the legacy pages - links to setuptools documentation have been updated (original patch by Susan Sun) --- index.rst | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/index.rst b/index.rst index 335f804d42..c565bcc562 100644 --- a/index.rst +++ b/index.rst @@ -7,6 +7,11 @@ :Authors: Greg Ward, Anthony Baxter :Email: distutils-sig@python.org +.. seealso:: + + :ref:`distributing-index` + The up to date module distribution documentations + This document describes the Python Distribution Utilities ("Distutils") from the module developer's point of view, describing how to use the Distutils to make Python modules and extensions easily available to a wider audience with @@ -20,7 +25,6 @@ very little overhead for build/release/install mechanics. recommendations section `__ in the Python Packaging User Guide for more information. - .. toctree:: :maxdepth: 2 :numbered: From cc725e5bf71257d88e7f18230e70bbcf0bc0fb06 Mon Sep 17 00:00:00 2001 From: Martin Panter Date: Tue, 26 Jul 2016 11:18:21 +0200 Subject: [PATCH 288/330] Issue #26462: Doc: reduce literal_block warnings, fix syntax highlighting. Patch by Julien Palard. --- examples.rst | 12 +++++++++--- packageindex.rst | 4 +++- sourcedist.rst | 4 +++- 3 files changed, 15 insertions(+), 5 deletions(-) diff --git a/examples.rst b/examples.rst index af9125a7b3..1f5be9cdb2 100644 --- a/examples.rst +++ b/examples.rst @@ -245,7 +245,9 @@ Let's take an example with a simple script:: setup(name='foobar') -Running the ``check`` command will display some warnings:: +Running the ``check`` command will display some warnings: + +.. code-block:: shell-session $ python setup.py check running check @@ -274,7 +276,9 @@ For example, if the :file:`setup.py` script is changed like this:: url='http://example.com', long_description=desc) Where the long description is broken, ``check`` will be able to detect it -by using the :mod:`docutils` parser:: +by using the :mod:`docutils` parser: + +.. code-block:: shell-session $ python setup.py check --restructuredtext running check @@ -286,7 +290,9 @@ Reading the metadata The :func:`distutils.core.setup` function provides a command-line interface that allows you to query the metadata fields of a project through the -``setup.py`` script of a given project:: +``setup.py`` script of a given project: + +.. code-block:: shell-session $ python setup.py --name distribute diff --git a/packageindex.rst b/packageindex.rst index 2d7daef784..28ad1289ee 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -233,7 +233,9 @@ in the root of the package besides :file:`setup.py`. To prevent registering broken reStructuredText content, you can use the :program:`rst2html` program that is provided by the :mod:`docutils` package and -check the ``long_description`` from the command line:: +check the ``long_description`` from the command line: + +.. code-block:: shell-session $ python setup.py --long-description | rst2html.py > output.html diff --git a/sourcedist.rst b/sourcedist.rst index fb70514b79..35aea1e39a 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -133,7 +133,9 @@ described above does not apply in this case. The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an -example, again we turn to the Distutils' own manifest template:: +example, again we turn to the Distutils' own manifest template: + +.. code-block:: none include *.txt recursive-include examples *.txt *.py From 753d4468c5922fc4502c5fae447719e52b629d31 Mon Sep 17 00:00:00 2001 From: Martin Panter Date: Sun, 30 Oct 2016 04:20:17 +0000 Subject: [PATCH 289/330] Issue #26638: Mask undefined CLI options to defeat new Sphinx warnings --- apiref.rst | 24 ++++++++++++------------ builtdist.rst | 32 ++++++++++++++++---------------- configfile.rst | 6 +++--- extending.rst | 2 +- setupscript.rst | 2 +- sourcedist.rst | 12 ++++++------ 6 files changed, 39 insertions(+), 39 deletions(-) diff --git a/apiref.rst b/apiref.rst index 0672253471..be0e89a85c 100644 --- a/apiref.rst +++ b/apiref.rst @@ -205,7 +205,7 @@ the full reference. | | to or ``None`` to define it | | | | without a particular value | | | | (equivalent of ``#define FOO`` | | - | | in source or :option:`-DFOO` | | + | | in source or :option:`!-DFOO` | | | | on Unix C compiler command | | | | line) | | +------------------------+--------------------------------+---------------------------+ @@ -319,11 +319,11 @@ This module provides the following functions. .. function:: gen_preprocess_options(macros, include_dirs) - Generate C pre-processor options (:option:`-D`, :option:`!-U`, :option:`!-I`) as + Generate C pre-processor options (:option:`!-D`, :option:`!-U`, :option:`!-I`) as used by at least two types of compilers: the typical Unix compiler and Visual C++. *macros* is the usual thing, a list of 1- or 2-tuples, where ``(name,)`` means undefine (:option:`!-U`) macro *name*, and ``(name, value)`` means define - (:option:`-D`) macro *name* to *value*. *include_dirs* is just a list of + (:option:`!-D`) macro *name* to *value*. *include_dirs* is just a list of directory names to be added to the header file search path (:option:`!-I`). Returns a list of command-line options suitable for either Unix compilers or Visual C++. @@ -359,7 +359,7 @@ This module provides the following functions. .. function:: show_compilers() - Print list of available compilers (used by the :option:`--help-compiler` options + Print list of available compilers (used by the :option:`!--help-compiler` options to :command:`build`, :command:`build_ext`, :command:`build_clib`). @@ -789,15 +789,15 @@ This module provides the following functions. This module provides the :class:`UnixCCompiler` class, a subclass of :class:`CCompiler` that handles the typical Unix-style command-line C compiler: -* macros defined with :option:`-Dname[=value]` +* macros defined with :option:`!-Dname[=value]` -* macros undefined with :option:`-Uname` +* macros undefined with :option:`!-Uname` -* include search directories specified with :option:`-Idir` +* include search directories specified with :option:`!-Idir` -* libraries specified with :option:`-llib` +* libraries specified with :option:`!-llib` -* library search directories specified with :option:`-Ldir` +* library search directories specified with :option:`!-Ldir` * compile handled by :program:`cc` (or similar) executable with :option:`!-c` option: compiles :file:`.c` to :file:`.o` @@ -805,7 +805,7 @@ This module provides the :class:`UnixCCompiler` class, a subclass of * link static library handled by :program:`ar` command (possibly with :program:`ranlib`) -* link shared library handled by :program:`cc` :option:`-shared` +* link shared library handled by :program:`cc` :option:`!-shared` :mod:`distutils.msvccompiler` --- Microsoft Compiler @@ -1318,8 +1318,8 @@ provides the following additional features: * options set attributes of a passed-in object -* boolean options can have "negative aliases" --- eg. if :option:`--quiet` is - the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the +* boolean options can have "negative aliases" --- eg. if :option:`!--quiet` is + the "negative alias" of :option:`!--verbose`, then :option:`!--quiet` on the command line sets *verbose* to false. .. function:: fancy_getopt(options, negative_opt, object, args) diff --git a/builtdist.rst b/builtdist.rst index 523d1e0fff..bbd2a8ce83 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -57,7 +57,7 @@ built distributions, such as an RPM package or an executable installer for Windows, is far more convenient for users even if your distribution doesn't include any extensions. -The :command:`bdist` command has a :option:`--formats` option, similar to the +The :command:`bdist` command has a :option:`!--formats` option, similar to the :command:`sdist` command, which you can use to select the types of built distribution to generate: for example, :: @@ -123,7 +123,7 @@ Notes: requires external :program:`rpm` utility, version 3.0.4 or better (use ``rpm --version`` to find out which version you have) -You don't have to use the :command:`bdist` command with the :option:`--formats` +You don't have to use the :command:`bdist` command with the :option:`!--formats` option; you can also use the command that directly implements the format you're interested in. Some of these :command:`bdist` "sub-commands" actually generate several similar formats; for instance, the :command:`bdist_dumb` command @@ -174,7 +174,7 @@ The usual way to create an RPM of your module distribution is to run the python setup.py bdist_rpm -or the :command:`bdist` command with the :option:`--format` option:: +or the :command:`bdist` command with the :option:`!--format` option:: python setup.py bdist --formats=rpm @@ -249,7 +249,7 @@ configuration file, :file:`setup.cfg`\ ---see section :ref:`setup-config`. If you distribute or package many Python module distributions, you might want to put options that apply to all of them in your personal Distutils configuration file (:file:`~/.pydistutils.cfg`). If you want to temporarily disable -this file, you can pass the :option:`--no-user-cfg` option to :file:`setup.py`. +this file, you can pass the :option:`!--no-user-cfg` option to :file:`setup.py`. There are three steps to building a binary RPM package, all of which are handled automatically by the Distutils: @@ -267,10 +267,10 @@ Normally, RPM bundles the last two steps together; when you use the Distutils, all three steps are typically bundled together. If you wish, you can separate these three steps. You can use the -:option:`--spec-only` option to make :command:`bdist_rpm` just create the +:option:`!--spec-only` option to make :command:`bdist_rpm` just create the :file:`.spec` file and exit; in this case, the :file:`.spec` file will be written to the "distribution directory"---normally :file:`dist/`, but -customizable with the :option:`--dist-dir` option. (Normally, the :file:`.spec` +customizable with the :option:`!--dist-dir` option. (Normally, the :file:`.spec` file winds up deep in the "build tree," in a temporary directory created by :command:`bdist_rpm`.) @@ -307,7 +307,7 @@ is usually as easy as running:: python setup.py bdist_wininst -or the :command:`bdist` command with the :option:`--formats` option:: +or the :command:`bdist` command with the :option:`!--formats` option:: python setup.py bdist --formats=wininst @@ -325,20 +325,20 @@ support. The installer will try to compile pure modules into :term:`bytecode` after installation on the target system in normal and optimizing mode. If you don't want this to happen for some reason, you can run the :command:`bdist_wininst` command with -the :option:`--no-target-compile` and/or the :option:`--no-target-optimize` +the :option:`!--no-target-compile` and/or the :option:`!--no-target-optimize` option. By default the installer will display the cool "Python Powered" logo when it is run, but you can also supply your own 152x261 bitmap which must be a Windows -:file:`.bmp` file with the :option:`--bitmap` option. +:file:`.bmp` file with the :option:`!--bitmap` option. The installer will also display a large title on the desktop background window when it is run, which is constructed from the name of your distribution and the version number. This can be changed to another text by using the -:option:`--title` option. +:option:`!--title` option. The installer file will be written to the "distribution directory" --- normally -:file:`dist/`, but customizable with the :option:`--dist-dir` option. +:file:`dist/`, but customizable with the :option:`!--dist-dir` option. .. _cross-compile-windows: @@ -350,7 +350,7 @@ Windows platforms. In practice, this means that with the correct tools installed, you can use a 32bit version of Windows to create 64bit extensions and vice-versa. -To build for an alternate platform, specify the :option:`--plat-name` option +To build for an alternate platform, specify the :option:`!--plat-name` option to the build command. Valid values are currently 'win32', 'win-amd64' and 'win-ia64'. For example, on a 32bit version of Windows, you could execute:: @@ -383,14 +383,14 @@ The Postinstallation script --------------------------- Starting with Python 2.3, a postinstallation script can be specified with the -:option:`--install-script` option. The basename of the script must be +:option:`!--install-script` option. The basename of the script must be specified, and the script filename must also be listed in the scripts argument to the setup function. This script will be run at installation time on the target system after all the -files have been copied, with ``argv[1]`` set to :option:`-install`, and again at +files have been copied, with ``argv[1]`` set to :option:`!-install`, and again at uninstallation time before the files are removed with ``argv[1]`` set to -:option:`-remove`. +:option:`!-remove`. The installation script runs embedded in the windows installer, every output (``sys.stdout``, ``sys.stderr``) is redirected into a buffer and will be @@ -453,7 +453,7 @@ built-in functions in the installation script. Vista User Access Control (UAC) =============================== -Starting with Python 2.6, bdist_wininst supports a :option:`--user-access-control` +Starting with Python 2.6, bdist_wininst supports a :option:`!--user-access-control` option. The default is 'none' (meaning no UAC handling is done), and other valid values are 'auto' (meaning prompt for UAC elevation if Python was installed for all users) and 'force' (meaning always prompt for elevation). diff --git a/configfile.rst b/configfile.rst index 51d88971a4..21f1acdace 100644 --- a/configfile.rst +++ b/configfile.rst @@ -66,7 +66,7 @@ universal :option:`!--help` option, e.g. :: --swig-opts list of SWIG command line options [...] -Note that an option spelled :option:`--foo-bar` on the command-line is spelled +Note that an option spelled :option:`!--foo-bar` on the command-line is spelled ``foo_bar`` in configuration files. .. _distutils-build-ext-inplace: @@ -75,12 +75,12 @@ For example, say you want your extensions to be built "in-place"---that is, you have an extension :mod:`pkg.ext`, and you want the compiled extension file (:file:`ext.so` on Unix, say) to be put in the same source directory as your pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the -:option:`--inplace` option on the command-line to ensure this:: +:option:`!--inplace` option on the command-line to ensure this:: python setup.py build_ext --inplace But this requires that you always specify the :command:`build_ext` command -explicitly, and remember to provide :option:`--inplace`. An easier way is to +explicitly, and remember to provide :option:`!--inplace`. An easier way is to "set and forget" this option, by encoding it in :file:`setup.cfg`, the configuration file for this distribution:: diff --git a/extending.rst b/extending.rst index 5139c6dc81..501fd7c564 100644 --- a/extending.rst +++ b/extending.rst @@ -62,7 +62,7 @@ requiring modifications to the Python installation. This is expected to allow third-party extensions to provide support for additional packaging systems, but the commands can be used for anything distutils commands can be used for. A new configuration option, ``command_packages`` (command-line option -:option:`--command-packages`), can be used to specify additional packages to be +:option:`!--command-packages`), can be used to specify additional packages to be searched for modules implementing commands. Like all distutils options, this can be specified on the command line or in a configuration file. This option can only be set in the ``[global]`` section of a configuration file, or before diff --git a/setupscript.rst b/setupscript.rst index 914a34f1c8..9c4a9d59dd 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -446,7 +446,7 @@ command line. Scripts don't require Distutils to do anything very complicated. The only clever feature is that if the first line of the script starts with ``#!`` and contains the word "python", the Distutils will adjust the first line to refer to the current interpreter location. By default, it is replaced with -the current interpreter location. The :option:`--executable` (or :option:`-e`) +the current interpreter location. The :option:`!--executable` (or :option:`!-e`) option will allow the interpreter path to be explicitly overridden. The ``scripts`` option simply is a list of files to be handled in this diff --git a/sourcedist.rst b/sourcedist.rst index 35aea1e39a..cc289c9b25 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -14,7 +14,7 @@ or config file), :command:`sdist` creates the archive of the default format for the current platform. The default format is a gzip'ed tar file (:file:`.tar.gz`) on Unix, and ZIP file on Windows. -You can specify as many formats as you like using the :option:`--formats` +You can specify as many formats as you like using the :option:`!--formats` option, for example:: python setup.py sdist --formats=gztar,zip @@ -147,7 +147,7 @@ matching :file:`\*.txt` or :file:`\*.py`, and exclude all directories matching :file:`examples/sample?/build`. All of this is done *after* the standard include set, so you can exclude files from the standard set with explicit instructions in the manifest template. (Or, you can use the -:option:`--no-defaults` option to disable the standard set entirely.) There are +:option:`!--no-defaults` option to disable the standard set entirely.) There are several other commands available in the manifest template mini-language; see section :ref:`sdist-cmd`. @@ -166,8 +166,8 @@ Now we have our complete list of files, which is written to the manifest for future reference, and then used to build the source distribution archive(s). You can disable the default set of included files with the -:option:`--no-defaults` option, and you can disable the standard exclude set -with :option:`--no-prune`. +:option:`!--no-defaults` option, and you can disable the standard exclude set +with :option:`!--no-prune`. Following the Distutils' own manifest template, let's trace how the :command:`sdist` command builds the list of files to include in the Distutils @@ -225,7 +225,7 @@ The normal course of operations for the :command:`sdist` command is as follows: in) to create the source distribution archive(s) There are a couple of options that modify this behaviour. First, use the -:option:`--no-defaults` and :option:`--no-prune` to disable the standard +:option:`!--no-defaults` and :option:`!--no-prune` to disable the standard "include" and "exclude" sets. Second, you might just want to (re)generate the manifest, but not create a source @@ -233,4 +233,4 @@ distribution:: python setup.py sdist --manifest-only -:option:`-o` is a shortcut for :option:`--manifest-only`. +:option:`!-o` is a shortcut for :option:`!--manifest-only`. From 2436e5fbab394e625f2bc1d29b766bf0bdb589d9 Mon Sep 17 00:00:00 2001 From: Martin Panter Date: Sat, 5 Nov 2016 02:40:31 +0000 Subject: [PATCH 290/330] Fix spacing after C++ in documentation --- apiref.rst | 2 +- setupscript.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index be0e89a85c..b5b7731074 100644 --- a/apiref.rst +++ b/apiref.rst @@ -166,7 +166,7 @@ the full reference. .. class:: Extension - The Extension class describes a single C or C++extension module in a setup + The Extension class describes a single C or C++ extension module in a setup script. It accepts the following keyword arguments in its constructor: .. tabularcolumns:: |l|L|l| diff --git a/setupscript.rst b/setupscript.rst index 9c4a9d59dd..38e0202e4a 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -201,7 +201,7 @@ The second argument to the :class:`~distutils.core.Extension` constructor is a list of source files. Since the Distutils currently only support C, C++, and Objective-C extensions, these are normally C/C++/Objective-C source files. (Be sure to use -appropriate extensions to distinguish C++\ source files: :file:`.cc` and +appropriate extensions to distinguish C++ source files: :file:`.cc` and :file:`.cpp` seem to be recognized by both Unix and Windows compilers.) However, you can also include SWIG interface (:file:`.i`) files in the list; the From 0ea6937188a253e11e244bd619dd1cbdfa332810 Mon Sep 17 00:00:00 2001 From: Berker Peksag Date: Tue, 27 Dec 2016 15:16:25 +0300 Subject: [PATCH 291/330] Issue #29069: Update the default URL of PyPI server Patch by paka. --- packageindex.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packageindex.rst b/packageindex.rst index 28ad1289ee..44556e3df9 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -173,7 +173,7 @@ name of all sections describing a repository. Each section describing a repository defines three variables: - *repository*, that defines the url of the PyPI server. Defaults to - ``https://www.python.org/pypi``. + ``https://upload.pypi.org/legacy/``. - *username*, which is the registered username on the PyPI server. - *password*, that will be used to authenticate. If omitted the user will be prompt to type it when needed. From c2250ca5ff84cb061ee35d4af629353ccd5f2e54 Mon Sep 17 00:00:00 2001 From: Mariatta Date: Sat, 4 Mar 2017 16:41:06 -0800 Subject: [PATCH 292/330] distutils docs: Fix a typo (GH-470) instanciated -> instantiated --- examples.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples.rst b/examples.rst index 1f5be9cdb2..4e2761d8a7 100644 --- a/examples.rst +++ b/examples.rst @@ -321,7 +321,7 @@ You can read back this static file, by using the >>> metadata.description 'Easily download, build, install, upgrade, and uninstall Python packages' -Notice that the class can also be instanciated with a metadata file path to +Notice that the class can also be instantiated with a metadata file path to loads its values:: >>> pkg_info_path = 'distribute-0.6.8-py2.7.egg-info' From e9f6164db755b35d44eabb46cd578f90feab9a01 Mon Sep 17 00:00:00 2001 From: Ryan Gonzalez Date: Fri, 14 Apr 2017 04:00:25 -0500 Subject: [PATCH 293/330] bpo-11913: Add README.rst to the distutils standard READMEs list (#563) --- sourcedist.rst | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/sourcedist.rst b/sourcedist.rst index cc289c9b25..0ac8ef41dd 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -95,8 +95,9 @@ source distribution: distributions, but in the future there will be a standard for testing Python module distributions) -* :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever you - called your setup script), and :file:`setup.cfg` +* Any of the standard README files (:file:`README`, :file:`README.txt`, + or :file:`README.rst`), :file:`setup.py` (or whatever you called your setup + script), and :file:`setup.cfg`. * all files that matches the ``package_data`` metadata. See :ref:`distutils-installing-package-data`. @@ -130,6 +131,9 @@ described above does not apply in this case. :command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in` exists, like it used to do. +.. versionchanged:: 3.7 + :file:`README.rst` is now included in the list of distutils standard READMEs. + The manifest template has one command per line, where each command specifies a set of files to include or exclude from the source distribution. For an From 5284514970cadef01417a855140818a86b55a45f Mon Sep 17 00:00:00 2001 From: Benjamin Peterson Date: Mon, 4 Sep 2017 16:36:05 -0700 Subject: [PATCH 294/330] remove IRIX support (closes bpo-31341) (#3310) See PEP 11. --- apiref.rst | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/apiref.rst b/apiref.rst index b5b7731074..622c7d1708 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1086,19 +1086,16 @@ other utility module. Return a string that identifies the current platform. This is used mainly to distinguish platform-specific build directories and platform-specific built - distributions. Typically includes the OS name and version and the architecture - (as supplied by 'os.uname()'), although the exact information included depends - on the OS; eg. for IRIX the architecture isn't particularly important (IRIX only - runs on SGI hardware), but for Linux the kernel version isn't particularly - important. + distributions. Typically includes the OS name and version and the + architecture (as supplied by 'os.uname()'), although the exact information + included depends on the OS; e.g., on Linux, the kernel version isn't + particularly important. Examples of returned values: * ``linux-i586`` * ``linux-alpha`` * ``solaris-2.6-sun4u`` - * ``irix-5.3`` - * ``irix64-6.2`` For non-POSIX platforms, currently just returns ``sys.platform``. From ca33b76e8d990fd9c4113642c3a4ec01874f08e4 Mon Sep 17 00:00:00 2001 From: Zachary Ware Date: Wed, 6 Sep 2017 15:45:25 -0700 Subject: [PATCH 295/330] Remove all mention of Windows IA-64 support (GH-3389) It was mostly removed long ago. --- apiref.rst | 4 ++-- builtdist.rst | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/apiref.rst b/apiref.rst index 622c7d1708..7cde1a0701 100644 --- a/apiref.rst +++ b/apiref.rst @@ -814,13 +814,13 @@ This module provides the :class:`UnixCCompiler` class, a subclass of .. module:: distutils.msvccompiler :synopsis: Microsoft Compiler +.. XXX: This is *waaaaay* out of date! This module provides :class:`MSVCCompiler`, an implementation of the abstract :class:`CCompiler` class for Microsoft Visual Studio. Typically, extension modules need to be compiled with the same compiler that was used to compile Python. For Python 2.3 and earlier, the compiler was Visual Studio 6. For Python -2.4 and 2.5, the compiler is Visual Studio .NET 2003. The AMD64 and Itanium -binaries are created using the Platform SDK. +2.4 and 2.5, the compiler is Visual Studio .NET 2003. :class:`MSVCCompiler` will normally choose the right compiler, linker etc. on its own. To override this choice, the environment variables *DISTUTILS_USE_SDK* diff --git a/builtdist.rst b/builtdist.rst index bbd2a8ce83..dc3a50cb03 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -351,8 +351,8 @@ installed, you can use a 32bit version of Windows to create 64bit extensions and vice-versa. To build for an alternate platform, specify the :option:`!--plat-name` option -to the build command. Valid values are currently 'win32', 'win-amd64' and -'win-ia64'. For example, on a 32bit version of Windows, you could execute:: +to the build command. Valid values are currently 'win32', and 'win-amd64'. +For example, on a 32bit version of Windows, you could execute:: python setup.py build --plat-name=win-amd64 From b129d052b64bf21e6ffd6c20898b6948edbafc94 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stefan=20Gr=C3=B6nke?= Date: Mon, 25 Sep 2017 18:58:10 +0200 Subject: [PATCH 296/330] bpo-31569: correct PCBuild/ case to PCbuild/ in build scripts and docs (GH-3711) --- builtdist.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/builtdist.rst b/builtdist.rst index dc3a50cb03..f523a67234 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -368,7 +368,7 @@ Python itself for the platform you are targeting - it is not possible from a binary installation of Python (as the .lib etc file for other platforms are not included.) In practice, this means the user of a 32 bit operating system will need to use Visual Studio 2008 to open the -:file:`PCBuild/PCbuild.sln` solution in the Python source tree and build the +:file:`PCbuild/PCbuild.sln` solution in the Python source tree and build the "x64" configuration of the 'pythoncore' project before cross-compiling extensions is possible. From 2ed774f1a428d543b52cc7c0dc5ae9b30b2f8058 Mon Sep 17 00:00:00 2001 From: Berker Peksag Date: Thu, 23 Nov 2017 21:34:20 +0300 Subject: [PATCH 297/330] bpo-19610: setup() now raises TypeError for invalid types (GH-4519) The Distribution class now explicitly raises an exception when 'classifiers', 'keywords' and 'platforms' fields are not specified as a list. --- apiref.rst | 4 ++++ setupscript.rst | 39 +++++++++++++++++++++++++++------------ 2 files changed, 31 insertions(+), 12 deletions(-) diff --git a/apiref.rst b/apiref.rst index 7cde1a0701..ced8837d37 100644 --- a/apiref.rst +++ b/apiref.rst @@ -285,6 +285,10 @@ the full reference. See the :func:`setup` function for a list of keyword arguments accepted by the Distribution constructor. :func:`setup` creates a Distribution instance. + .. versionchanged:: 3.7 + :class:`~distutils.core.Distribution` now raises a :exc:`TypeError` if + ``classifiers``, ``keywords`` and ``platforms`` fields are not specified + as a list. .. class:: Command diff --git a/setupscript.rst b/setupscript.rst index 38e0202e4a..542ad54484 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -581,17 +581,19 @@ This information includes: | | description of the | | | | | package | | | +----------------------+---------------------------+-----------------+--------+ -| ``long_description`` | longer description of the | long string | \(5) | +| ``long_description`` | longer description of the | long string | \(4) | | | package | | | +----------------------+---------------------------+-----------------+--------+ -| ``download_url`` | location where the | URL | \(4) | +| ``download_url`` | location where the | URL | | | | package may be downloaded | | | +----------------------+---------------------------+-----------------+--------+ -| ``classifiers`` | a list of classifiers | list of strings | \(4) | +| ``classifiers`` | a list of classifiers | list of strings | (6)(7) | +----------------------+---------------------------+-----------------+--------+ -| ``platforms`` | a list of platforms | list of strings | | +| ``platforms`` | a list of platforms | list of strings | (6)(8) | +----------------------+---------------------------+-----------------+--------+ -| ``license`` | license for the package | short string | \(6) | +| ``keywords`` | a list of keywords | list of strings | (6)(8) | ++----------------------+---------------------------+-----------------+--------+ +| ``license`` | license for the package | short string | \(5) | +----------------------+---------------------------+-----------------+--------+ Notes: @@ -607,22 +609,30 @@ Notes: provided, distutils lists it as the author in :file:`PKG-INFO`. (4) - These fields should not be used if your package is to be compatible with Python - versions prior to 2.2.3 or 2.3. The list is available from the `PyPI website - `_. - -(5) The ``long_description`` field is used by PyPI when you are :ref:`registering ` a package, to :ref:`build its home page `. -(6) +(5) The ``license`` field is a text indicating the license covering the package where the license is not a selection from the "License" Trove classifiers. See the ``Classifier`` field. Notice that there's a ``licence`` distribution option which is deprecated but still acts as an alias for ``license``. +(6) + This field must be a list. + +(7) + The valid classifiers are listed on + `PyPI `_. + +(8) + To preserve backward compatibility, this field also accepts a string. If + you pass a comma-separated string ``'foo, bar'``, it will be converted to + ``['foo', 'bar']``, Otherwise, it will be converted to a list of one + string. + 'short string' A single line of text, not more than 200 characters. @@ -650,7 +660,7 @@ information is sometimes used to indicate sub-releases. These are 1.0.1a2 the second alpha release of the first patch version of 1.0 -``classifiers`` are specified in a Python list:: +``classifiers`` must be specified in a list:: setup(..., classifiers=[ @@ -671,6 +681,11 @@ information is sometimes used to indicate sub-releases. These are ], ) +.. versionchanged:: 3.7 + :class:`~distutils.core.setup` now raises a :exc:`TypeError` if + ``classifiers``, ``keywords`` and ``platforms`` fields are not specified + as a list. + .. _debug-setup-script: Debugging the setup script From 48df7805a95cab49db77d3ca2534b67d4d759490 Mon Sep 17 00:00:00 2001 From: Neil Schemenauer Date: Mon, 4 Dec 2017 18:58:12 -0800 Subject: [PATCH 298/330] bpo-19610: Warn if distutils is provided something other than a list to some fields (#4685) * Rather than raise TypeError, warn and call list() on the value. * Fix tests, revise NEWS and whatsnew text. * Revise documentation, a string is okay as well. * Ensure 'requires' and 'obsoletes' are real lists. * Test that requires and obsoletes are turned to lists. --- apiref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index ced8837d37..9fce46ad26 100644 --- a/apiref.rst +++ b/apiref.rst @@ -286,9 +286,9 @@ the full reference. Distribution constructor. :func:`setup` creates a Distribution instance. .. versionchanged:: 3.7 - :class:`~distutils.core.Distribution` now raises a :exc:`TypeError` if - ``classifiers``, ``keywords`` and ``platforms`` fields are not specified - as a list. + :class:`~distutils.core.Distribution` now warns if ``classifiers``, + ``keywords`` and ``platforms`` fields are not specified as a list or + a string. .. class:: Command From b62b9d8791eb4eeb0ecf1ff674717faca9fa4db3 Mon Sep 17 00:00:00 2001 From: Sanyam Khurana <8039608+CuriousLearner@users.noreply.github.com> Date: Sat, 20 Jan 2018 05:55:37 +0530 Subject: [PATCH 299/330] bpo-25910: Link redirections in docs (#1933) Fixes some redirection links in docs. --- index.rst | 2 +- setupscript.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/index.rst b/index.rst index c565bcc562..d6f7640fcb 100644 --- a/index.rst +++ b/index.rst @@ -22,7 +22,7 @@ very little overhead for build/release/install mechanics. This guide only covers the basic tools for building and distributing extensions that are provided as part of this version of Python. Third party tools offer easier to use and more secure alternatives. Refer to the `quick - recommendations section `__ + recommendations section `__ in the Python Packaging User Guide for more information. .. toctree:: diff --git a/setupscript.rst b/setupscript.rst index 542ad54484..952607a407 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -625,7 +625,7 @@ Notes: (7) The valid classifiers are listed on - `PyPI `_. + `PyPI `_. (8) To preserve backward compatibility, this field also accepts a string. If From 0319207c4c8818b8e6981cd94de5dc1fc686f284 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Sun, 8 Apr 2018 19:18:04 +0300 Subject: [PATCH 300/330] Improve highlighting of some code blocks. (GH-6401) --- configfile.rst | 22 ++++++++++++++++------ packageindex.rst | 8 ++++++-- 2 files changed, 22 insertions(+), 8 deletions(-) diff --git a/configfile.rst b/configfile.rst index 21f1acdace..cd10a7fdf3 100644 --- a/configfile.rst +++ b/configfile.rst @@ -36,7 +36,9 @@ consequences: * installers can override anything in :file:`setup.cfg` using the command-line options to :file:`setup.py` -The basic syntax of the configuration file is simple:: +The basic syntax of the configuration file is simple: + +.. code-block:: ini [command] option=value @@ -51,9 +53,11 @@ option values can be split across multiple lines simply by indenting the continuation lines. You can find out the list of options supported by a particular command with the -universal :option:`!--help` option, e.g. :: +universal :option:`!--help` option, e.g. + +.. code-block:: shell-session - > python setup.py --help build_ext + $ python setup.py --help build_ext [...] Options for 'build_ext' command: --build-lib (-b) directory for compiled extension modules @@ -75,14 +79,18 @@ For example, say you want your extensions to be built "in-place"---that is, you have an extension :mod:`pkg.ext`, and you want the compiled extension file (:file:`ext.so` on Unix, say) to be put in the same source directory as your pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the -:option:`!--inplace` option on the command-line to ensure this:: +:option:`!--inplace` option on the command-line to ensure this: + +.. code-block:: sh python setup.py build_ext --inplace But this requires that you always specify the :command:`build_ext` command explicitly, and remember to provide :option:`!--inplace`. An easier way is to "set and forget" this option, by encoding it in :file:`setup.cfg`, the -configuration file for this distribution:: +configuration file for this distribution: + +.. code-block:: ini [build_ext] inplace=1 @@ -103,7 +111,9 @@ information comes from the setup script, and some is automatically generated by the Distutils (such as the list of files installed). But some of it has to be supplied as options to :command:`bdist_rpm`, which would be very tedious to do on the command-line for every run. Hence, here is a snippet from the Distutils' -own :file:`setup.cfg`:: +own :file:`setup.cfg`: + +.. code-block:: ini [bdist_rpm] release = 1 diff --git a/packageindex.rst b/packageindex.rst index 44556e3df9..086e14eb25 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -156,7 +156,9 @@ The :command:`register` and :command:`upload` commands both check for the existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`. If this file exists, the command uses the username, password, and repository URL configured in the file. The format of a :file:`.pypirc` file is as -follows:: +follows: + +.. code-block:: ini [distutils] index-servers = @@ -179,7 +181,9 @@ Each section describing a repository defines three variables: will be prompt to type it when needed. If you want to define another server a new section can be created and -listed in the *index-servers* variable:: +listed in the *index-servers* variable: + +.. code-block:: ini [distutils] index-servers = From 64329821ad029e37ee00cce55f71162501c4182e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Delfino?= <34587441+andresdelfino@users.noreply.github.com> Date: Sat, 21 Apr 2018 09:17:26 -0300 Subject: [PATCH 301/330] bpo-33297: Mention Pillow to work with more image formats. (#6505) Also update PIL doc references to Pillow. --- introduction.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/introduction.rst b/introduction.rst index 8f46bd74c5..a385559103 100644 --- a/introduction.rst +++ b/introduction.rst @@ -193,8 +193,8 @@ modules using the Distutils: module distribution a collection of Python modules distributed together as a single downloadable resource and meant to be installed *en masse*. Examples of some well-known - module distributions are NumPy, SciPy, PIL (the Python Imaging - Library), or mxBase. (This would be called a *package*, except that term is + module distributions are NumPy, SciPy, Pillow, + or mxBase. (This would be called a *package*, except that term is already taken in the Python context: a single module distribution may contain zero, one, or many Python packages.) From bb152195abb863fd53811d6c96c1a23b6ca5a012 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Wirtel?= Date: Tue, 15 May 2018 20:58:35 +0200 Subject: [PATCH 302/330] bpo-33503: Fix the broken pypi link in the source and the documentation (GH-6814) --- apiref.rst | 2 +- packageindex.rst | 2 +- setupscript.rst | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 9fce46ad26..3c89468220 100644 --- a/apiref.rst +++ b/apiref.rst @@ -78,7 +78,7 @@ setup script). Indirectly provides the :class:`distutils.dist.Distribution` and | | be built | :class:`distutils.core.Extension` | +--------------------+--------------------------------+-------------------------------------------------------------+ | *classifiers* | A list of categories for the | a list of strings; valid classifiers are listed on `PyPI | - | | package | `_. | + | | package | `_. | +--------------------+--------------------------------+-------------------------------------------------------------+ | *distclass* | the :class:`Distribution` | a subclass of | | | class to use | :class:`distutils.core.Distribution` | diff --git a/packageindex.rst b/packageindex.rst index 086e14eb25..50cb74f2b6 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -250,4 +250,4 @@ without warnings does not guarantee that PyPI will convert the content successfully. -.. _Python Package Index (PyPI): https://pypi.python.org/pypi +.. _Python Package Index (PyPI): https://pypi.org diff --git a/setupscript.rst b/setupscript.rst index 952607a407..1d96acbe98 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -625,7 +625,7 @@ Notes: (7) The valid classifiers are listed on - `PyPI `_. + `PyPI `_. (8) To preserve backward compatibility, this field also accepts a string. If From 9c2a778cfd38fa474ccfdf23bc7c5946f9caf660 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Andr=C3=A9s=20Delfino?= Date: Mon, 18 Jun 2018 01:34:30 -0300 Subject: [PATCH 303/330] bpo-33892: Doc: Use gender neutral words (GH-7770) --- builtdist.rst | 2 +- introduction.rst | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index f523a67234..758bd141ac 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -21,7 +21,7 @@ specialty---writing code and creating source distributions---while an intermediary species called *packagers* springs up to turn source distributions into built distributions for as many platforms as there are packagers. -Of course, the module developer could be his own packager; or the packager could +Of course, the module developer could be their own packager; or the packager could be a volunteer "out there" somewhere who has access to a platform which the original developer does not; or it could be software periodically grabbing new source distributions and turning them into built distributions for as many diff --git a/introduction.rst b/introduction.rst index a385559103..7721484fe7 100644 --- a/introduction.rst +++ b/introduction.rst @@ -94,7 +94,7 @@ containing your setup script :file:`setup.py`, and your module :file:`foo.py`. The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and will unpack into a directory :file:`foo-1.0`. -If an end-user wishes to install your :mod:`foo` module, all she has to do is +If an end-user wishes to install your :mod:`foo` module, all they have to do is download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the :file:`foo-1.0` directory---run :: From d4bb873a9908a56c93ac10299fd2f08aeeff90e9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Wirtel?= Date: Fri, 12 Oct 2018 09:51:05 +0200 Subject: [PATCH 304/330] bpo-34962: make doctest in Doc/ now passes, and is enforced in CI (GH-9806) --- examples.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples.rst b/examples.rst index 4e2761d8a7..f81e06b5e6 100644 --- a/examples.rst +++ b/examples.rst @@ -1,4 +1,4 @@ -.. _examples: +.. _distutils_examples: ******** Examples From c6e09732d9888e4ec293f085f7263e9e17f5fca4 Mon Sep 17 00:00:00 2001 From: TilmanK Date: Thu, 25 Oct 2018 00:50:25 +0200 Subject: [PATCH 305/330] bpo-35027, distutils doc: Correct note on setup.py change in Python 3.7 (GH-10032) --- setupscript.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index 1d96acbe98..c1051d2e80 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -682,9 +682,8 @@ information is sometimes used to indicate sub-releases. These are ) .. versionchanged:: 3.7 - :class:`~distutils.core.setup` now raises a :exc:`TypeError` if - ``classifiers``, ``keywords`` and ``platforms`` fields are not specified - as a list. + :class:`~distutils.core.setup` now warns when ``classifiers``, ``keywords`` + or ``platforms`` fields are not specified as a list or a string. .. _debug-setup-script: From 8dcc595723fb0116da274af83f590f6fa3313d3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?St=C3=A9phane=20Wirtel?= Date: Sat, 27 Oct 2018 00:58:26 +0200 Subject: [PATCH 306/330] bpo-35042: Use the :pep: role where a PEP is specified (#10036) --- apiref.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/apiref.rst b/apiref.rst index 3c89468220..9d5c2ab696 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1393,11 +1393,11 @@ This module provides the :class:`FileList` class, used for poking about the filesystem and building lists of files. -:mod:`distutils.log` --- Simple PEP 282-style logging -===================================================== +:mod:`distutils.log` --- Simple :pep:`282`-style logging +======================================================== .. module:: distutils.log - :synopsis: A simple logging mechanism, 282-style + :synopsis: A simple logging mechanism, :pep:`282`-style :mod:`distutils.spawn` --- Spawn a sub-process From bf2fc82eafbf68cf5eec7fb2c4d2fccbe0fc1868 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 31 Oct 2018 02:26:06 +0200 Subject: [PATCH 307/330] bpo-35110: Fix unintentional spaces around hyphens and dashes. (GH-10231) --- apiref.rst | 9 +++++---- builtdist.rst | 6 +++--- 2 files changed, 8 insertions(+), 7 deletions(-) diff --git a/apiref.rst b/apiref.rst index 9d5c2ab696..b10b39ae22 100644 --- a/apiref.rst +++ b/apiref.rst @@ -183,8 +183,9 @@ the full reference. | *sources* | list of source filenames, | a list of strings | | | relative to the distribution | | | | root (where the setup script | | - | | lives), in Unix form (slash- | | - | | separated) for portability. | | + | | lives), in Unix form | | + | | (slash-separated) for | | + | | portability. | | | | Source files may be C, C++, | | | | SWIG (.i), platform-specific | | | | resource files, or whatever | | @@ -1566,8 +1567,8 @@ lines, and joining lines with backslashes. +------------------+--------------------------------+---------+ | option name | description | default | +==================+================================+=========+ - | *strip_comments* | strip from ``'#'`` to end-of- | true | - | | line, as well as any | | + | *strip_comments* | strip from ``'#'`` to | true | + | | end-of-line, as well as any | | | | whitespace leading up to the | | | | ``'#'``\ ---unless it is | | | | escaped by a backslash | | diff --git a/builtdist.rst b/builtdist.rst index 758bd141ac..f1f3471261 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -63,9 +63,9 @@ distribution to generate: for example, :: python setup.py bdist --format=zip -would, when run on a Unix system, create :file:`Distutils-1.0.{plat}.zip`\ ----again, this archive would be unpacked from the root directory to install the -Distutils. +would, when run on a Unix system, create +:file:`Distutils-1.0.{plat}.zip`\ ---again, this archive would be unpacked +from the root directory to install the Distutils. The available formats for built distributions are: From 90912c9659d790d61831fc8737a8d2fcb5f52f91 Mon Sep 17 00:00:00 2001 From: Serhiy Storchaka Date: Wed, 31 Oct 2018 11:14:38 +0200 Subject: [PATCH 308/330] bpo-35110: Fix yet few spaces before dashes. (GH-10255) --- configfile.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/configfile.rst b/configfile.rst index cd10a7fdf3..0874d05fe7 100644 --- a/configfile.rst +++ b/configfile.rst @@ -13,8 +13,8 @@ edit is a cheap and easy way to solicit it. Configuration files also let you provide default values for any command option, which the installer can then override either on the command-line or by editing the config file. -The setup configuration file is a useful middle-ground between the setup script ----which, ideally, would be opaque to installers [#]_---and the command-line to +The setup configuration file is a useful middle-ground between the setup +script---which, ideally, would be opaque to installers [#]_---and the command-line to the setup script, which is outside of your control and entirely up to the installer. In fact, :file:`setup.cfg` (and any other Distutils configuration files present on the target system) are processed after the contents of the From 96864af2249ade2f5a237696e01a4eff23568be0 Mon Sep 17 00:00:00 2001 From: Andre Delfino Date: Thu, 6 Dec 2018 18:06:55 -0300 Subject: [PATCH 309/330] Add missing period in distutils.dep_util.newer_group doc (GH-11003) --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index b10b39ae22..a825efc1a6 100644 --- a/apiref.rst +++ b/apiref.rst @@ -941,7 +941,7 @@ timestamp dependency analysis. .. function:: newer_group(sources, target[, missing='error']) Return true if *target* is out-of-date with respect to any file listed in - *sources* In other words, if *target* exists and is newer than every file in + *sources*. In other words, if *target* exists and is newer than every file in *sources*, return false; otherwise return true. *missing* controls what we do when a source file is missing; the default (``'error'``) is to blow up with an :exc:`OSError` from inside :func:`os.stat`; if it is ``'ignore'``, we silently From f35f5d85471cbe974eee8ba64a91a96eed08e0b2 Mon Sep 17 00:00:00 2001 From: jdemeyer Date: Wed, 30 Jan 2019 16:49:39 +0100 Subject: [PATCH 310/330] bpo-25592: Improve documentation of distutils data_files (GH-9767) --- setupscript.rst | 25 ++++++++++++++----------- 1 file changed, 14 insertions(+), 11 deletions(-) diff --git a/setupscript.rst b/setupscript.rst index c1051d2e80..54ed1aebc2 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -524,20 +524,23 @@ following way:: setup(..., data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), ('config', ['cfg/data.cfg']), - ('/etc/init.d', ['init-script'])] ) -Note that you can specify the directory names where the data files will be -installed, but you cannot rename the data files themselves. - Each (*directory*, *files*) pair in the sequence specifies the installation -directory and the files to install there. If *directory* is a relative path, it -is interpreted relative to the installation prefix (Python's ``sys.prefix`` for -pure-Python packages, ``sys.exec_prefix`` for packages that contain extension -modules). Each file name in *files* is interpreted relative to the -:file:`setup.py` script at the top of the package source distribution. No -directory information from *files* is used to determine the final location of -the installed file; only the name of the file is used. +directory and the files to install there. + +Each file name in *files* is interpreted relative to the :file:`setup.py` +script at the top of the package source distribution. Note that you can +specify the directory where the data files will be installed, but you cannot +rename the data files themselves. + +The *directory* should be a relative path. It is interpreted relative to the +installation prefix (Python's ``sys.prefix`` for system installations; +``site.USER_BASE`` for user installations). Distutils allows *directory* to be +an absolute installation path, but this is discouraged since it is +incompatible with the wheel packaging format. No directory information from +*files* is used to determine the final location of the installed file; only +the name of the file is used. You can specify the ``data_files`` options as a simple sequence of files without specifying a target directory, but this is not recommended, and the From 601692efb21a93e28ac0d300de1610c1e89ea1d0 Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Thu, 25 Apr 2019 20:13:10 +0200 Subject: [PATCH 311/330] bpo-21536: C extensions are no longer linked to libpython (GH-12946) On Unix, C extensions are no longer linked to libpython. It is now possible to load a C extension built using a shared library Python with a statically linked Python. When Python is embedded, libpython must not be loaded with RTLD_LOCAL, but RTLD_GLOBAL instead. Previously, using RTLD_LOCAL, it was already not possible to load C extensions which were not linked to libpython, like C extensions of the standard library built by the "*shared*" section of Modules/Setup. distutils, python-config and python-config.py have been modified. --- apiref.rst | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/apiref.rst b/apiref.rst index a825efc1a6..c3cdfc8a0a 100644 --- a/apiref.rst +++ b/apiref.rst @@ -277,6 +277,10 @@ the full reference. | | simply skip the extension. | | +------------------------+--------------------------------+---------------------------+ + .. versionchanged:: 3.8 + + On Unix, C extensions are no longer linked to libpython. + .. class:: Distribution From 77d2f47e4a9c16ebe05246d02cc0eedc871236f0 Mon Sep 17 00:00:00 2001 From: xdegaye Date: Mon, 29 Apr 2019 09:27:40 +0200 Subject: [PATCH 312/330] bpo-21536: On Android, C extensions are linked to libpython (GH-12989) --- apiref.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index c3cdfc8a0a..1facc0408d 100644 --- a/apiref.rst +++ b/apiref.rst @@ -279,7 +279,8 @@ the full reference. .. versionchanged:: 3.8 - On Unix, C extensions are no longer linked to libpython. + On Unix, C extensions are no longer linked to libpython except on + Android. .. class:: Distribution From 8ace7cd6f5ce887748ce1f49e9c99efd832ffd0f Mon Sep 17 00:00:00 2001 From: Zhaorong Ma Date: Wed, 8 May 2019 09:44:01 -0400 Subject: [PATCH 313/330] Doc: Fix missing bracket (GH-13163) --- setupscript.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/setupscript.rst b/setupscript.rst index 54ed1aebc2..a65a26ac57 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -523,7 +523,7 @@ following way:: setup(..., data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']), - ('config', ['cfg/data.cfg']), + ('config', ['cfg/data.cfg'])], ) Each (*directory*, *files*) pair in the sequence specifies the installation From 9ec0041082ecc13950d266313d2c05623da2c61e Mon Sep 17 00:00:00 2001 From: Kojo Idrissa Date: Fri, 10 May 2019 03:45:09 -0500 Subject: [PATCH 314/330] bpo-33071: remove outdated PyPI docs (GH-13087) Patch by Kojo Idrissa. --- packageindex.rst | 244 +---------------------------------------------- setupscript.rst | 5 +- 2 files changed, 6 insertions(+), 243 deletions(-) diff --git a/packageindex.rst b/packageindex.rst index 50cb74f2b6..f74c4396e5 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -8,246 +8,10 @@ The Python Package Index (PyPI) ******************************* -The `Python Package Index (PyPI)`_ stores :ref:`meta-data ` -describing distributions packaged with distutils, as well as package data like -distribution files if a package author wishes. - -Distutils provides the :command:`register` and :command:`upload` commands for -pushing meta-data and distribution files to PyPI, respectively. See -:ref:`package-commands` for information on these commands. - - -PyPI overview -============= - -PyPI lets you submit any number of versions of your distribution to the index. -If you alter the meta-data for a particular version, you can submit it again -and the index will be updated. - -PyPI holds a record for each (name, version) combination submitted. The first -user to submit information for a given name is designated the Owner of that -name. Changes can be submitted through the :command:`register` command or -through the web interface. Owners can designate other users as Owners or -Maintainers. Maintainers can edit the package information, but not designate -new Owners or Maintainers. - -By default PyPI displays only the newest version of a given package. The web -interface lets one change this default behavior and manually select which -versions to display and hide. - -For each version, PyPI displays a home page. The home page is created from -the ``long_description`` which can be submitted via the :command:`register` -command. See :ref:`package-display` for more information. - - -.. _package-commands: - -Distutils commands -================== - -Distutils exposes two commands for submitting package data to PyPI: the -:ref:`register ` command for submitting meta-data to PyPI -and the :ref:`upload ` command for submitting distribution -files. Both commands read configuration data from a special file called a -:ref:`.pypirc file `. - - -.. _package-register: - -The ``register`` command ------------------------- - -The distutils command :command:`register` is used to submit your distribution's -meta-data to an index server. It is invoked as follows:: - - python setup.py register - -Distutils will respond with the following prompt:: - - running register - We need to know who you are, so please choose either: - 1. use your existing login, - 2. register as a new user, - 3. have the server generate a new password for you (and email it to you), or - 4. quit - Your selection [default 1]: - -Note: if your username and password are saved locally, you will not see this -menu. Also, refer to :ref:`pypirc` for how to store your credentials in a -:file:`.pypirc` file. - -If you have not registered with PyPI, then you will need to do so now. You -should choose option 2, and enter your details as required. Soon after -submitting your details, you will receive an email which will be used to confirm -your registration. - -Once you are registered, you may choose option 1 from the menu. You will be -prompted for your PyPI username and password, and :command:`register` will then -submit your meta-data to the index. - -See :ref:`package-cmdoptions` for options to the :command:`register` command. - - -.. _package-upload: - -The ``upload`` command ----------------------- - -The distutils command :command:`upload` pushes the distribution files to PyPI. - -The command is invoked immediately after building one or more distribution -files. For example, the command :: - - python setup.py sdist bdist_wininst upload - -will cause the source distribution and the Windows installer to be uploaded to -PyPI. Note that these will be uploaded even if they are built using an earlier -invocation of :file:`setup.py`, but that only distributions named on the command -line for the invocation including the :command:`upload` command are uploaded. - -If a :command:`register` command was previously called in the same command, -and if the password was entered in the prompt, :command:`upload` will reuse the -entered password. This is useful if you do not want to store a password in -clear text in a :file:`.pypirc` file. - -You can use the ``--sign`` option to tell :command:`upload` to sign each -uploaded file using GPG (GNU Privacy Guard). The :program:`gpg` program must -be available for execution on the system :envvar:`PATH`. You can also specify -which key to use for signing using the ``--identity=name`` option. - -See :ref:`package-cmdoptions` for additional options to the :command:`upload` -command. - - -.. _package-cmdoptions: - -Additional command options --------------------------- - -This section describes options common to both the :command:`register` and -:command:`upload` commands. - -The ``--repository`` or ``-r`` option lets you specify a PyPI server -different from the default. For example:: - - python setup.py sdist bdist_wininst upload -r https://example.com/pypi - -For convenience, a name can be used in place of the URL when the -:file:`.pypirc` file is configured to do so. For example:: - - python setup.py register -r other - -See :ref:`pypirc` for more information on defining alternate servers. - -The ``--show-response`` option displays the full response text from the PyPI -server, which is useful when debugging problems with registering and uploading. - - -.. index:: - single: .pypirc file - single: Python Package Index (PyPI); .pypirc file - -.. _pypirc: - -The ``.pypirc`` file --------------------- - -The :command:`register` and :command:`upload` commands both check for the -existence of a :file:`.pypirc` file at the location :file:`$HOME/.pypirc`. -If this file exists, the command uses the username, password, and repository -URL configured in the file. The format of a :file:`.pypirc` file is as -follows: - -.. code-block:: ini - - [distutils] - index-servers = - pypi - - [pypi] - repository: - username: - password: - -The *distutils* section defines an *index-servers* variable that lists the -name of all sections describing a repository. - -Each section describing a repository defines three variables: - -- *repository*, that defines the url of the PyPI server. Defaults to - ``https://upload.pypi.org/legacy/``. -- *username*, which is the registered username on the PyPI server. -- *password*, that will be used to authenticate. If omitted the user - will be prompt to type it when needed. - -If you want to define another server a new section can be created and -listed in the *index-servers* variable: - -.. code-block:: ini - - [distutils] - index-servers = - pypi - other - - [pypi] - repository: - username: - password: - - [other] - repository: https://example.com/pypi - username: - password: - -This allows the :command:`register` and :command:`upload` commands to be -called with the ``--repository`` option as described in -:ref:`package-cmdoptions`. - -Specifically, you might want to add the `PyPI Test Repository -`_ to your ``.pypirc`` to facilitate -testing before doing your first upload to ``PyPI`` itself. - - -.. _package-display: - -PyPI package display -==================== - -The ``long_description`` field plays a special role at PyPI. It is used by -the server to display a home page for the registered package. - -If you use the `reStructuredText `_ -syntax for this field, PyPI will parse it and display an HTML output for -the package home page. - -The ``long_description`` field can be attached to a text file located -in the package:: - - from distutils.core import setup - - with open('README.txt') as file: - long_description = file.read() - - setup(name='Distutils', - long_description=long_description) - -In that case, :file:`README.txt` is a regular reStructuredText text file located -in the root of the package besides :file:`setup.py`. - -To prevent registering broken reStructuredText content, you can use the -:program:`rst2html` program that is provided by the :mod:`docutils` package and -check the ``long_description`` from the command line: - -.. code-block:: shell-session - - $ python setup.py --long-description | rst2html.py > output.html - -:mod:`docutils` will display a warning if there's something wrong with your -syntax. Because PyPI applies additional checks (e.g. by passing ``--no-raw`` -to ``rst2html.py`` in the command above), being able to run the command above -without warnings does not guarantee that PyPI will convert the content -successfully. +The `Python Package Index (PyPI)`_ stores metadata describing distributions +packaged with distutils and other publishing tools, as well the distribution +archives themselves. +Detailed instructions on using PyPI at :ref:`distributing-index`. .. _Python Package Index (PyPI): https://pypi.org diff --git a/setupscript.rst b/setupscript.rst index a65a26ac57..1f99f62f6a 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -612,9 +612,8 @@ Notes: provided, distutils lists it as the author in :file:`PKG-INFO`. (4) - The ``long_description`` field is used by PyPI when you are - :ref:`registering ` a package, to - :ref:`build its home page `. + The ``long_description`` field is used by PyPI when you publish a package, + to build its project page. (5) The ``license`` field is a text indicating the license covering the From 6e93c3658a45e91c95b1376a61da10bfc9d7e443 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Tue, 14 May 2019 22:04:30 +1000 Subject: [PATCH 315/330] bpo-36797: Prune more legacy distutils documentation (GH-13092) Removes more legacy distutils documentation, and more clearly marks what is left as potentially outdated, with references to setuptools as a replacement. --- _setuptools_disclaimer.rst | 5 +++++ apiref.rst | 10 ++++++++++ builtdist.rst | 2 ++ commandref.rst | 2 ++ configfile.rst | 2 ++ examples.rst | 2 ++ extending.rst | 2 ++ index.rst | 10 ++++++---- introduction.rst | 2 ++ setupscript.rst | 2 ++ sourcedist.rst | 2 ++ 11 files changed, 37 insertions(+), 4 deletions(-) create mode 100644 _setuptools_disclaimer.rst diff --git a/_setuptools_disclaimer.rst b/_setuptools_disclaimer.rst new file mode 100644 index 0000000000..cc75858326 --- /dev/null +++ b/_setuptools_disclaimer.rst @@ -0,0 +1,5 @@ +.. note:: + + This document is being retained solely until the ``setuptools`` documentation + at https://setuptools.readthedocs.io/en/latest/setuptools.html + independently covers all of the relevant information currently included here. diff --git a/apiref.rst b/apiref.rst index 1facc0408d..cbeedab5bb 100644 --- a/apiref.rst +++ b/apiref.rst @@ -4,6 +4,16 @@ API Reference ************* +.. seealso:: + + `New and changed setup.py arguments in setuptools `_ + The ``setuptools`` project adds new capabilities to the ``setup`` function + and other APIs, makes the API consistent across different Python versions, + and is hence recommended over using ``distutils`` directly. + +.. _setuptools-setup-py: https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords + +.. include:: ./_setuptools_disclaimer.rst :mod:`distutils.core` --- Core Distutils functionality ====================================================== diff --git a/builtdist.rst b/builtdist.rst index f1f3471261..f44d0d039f 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -4,6 +4,8 @@ Creating Built Distributions **************************** +.. include:: ./_setuptools_disclaimer.rst + A "built distribution" is what you're probably used to thinking of either as a "binary package" or an "installer" (depending on your background). It's not necessarily binary, though, because it might contain only Python source code diff --git a/commandref.rst b/commandref.rst index 6a2ac960f1..0f6fe2aba8 100644 --- a/commandref.rst +++ b/commandref.rst @@ -4,6 +4,8 @@ Command Reference ***************** +.. include:: ./_setuptools_disclaimer.rst + .. % \section{Building modules: the \protect\command{build} command family} .. % \label{build-cmds} .. % \subsubsection{\protect\command{build}} diff --git a/configfile.rst b/configfile.rst index 0874d05fe7..2a5c8329e3 100644 --- a/configfile.rst +++ b/configfile.rst @@ -4,6 +4,8 @@ Writing the Setup Configuration File ************************************ +.. include:: ./_setuptools_disclaimer.rst + Often, it's not possible to write down everything needed to build a distribution *a priori*: you may need to get some information from the user, or from the user's system, in order to proceed. As long as that information is fairly diff --git a/examples.rst b/examples.rst index f81e06b5e6..4ac552c7c6 100644 --- a/examples.rst +++ b/examples.rst @@ -4,6 +4,8 @@ Examples ******** +.. include:: ./_setuptools_disclaimer.rst + This chapter provides a number of basic examples to help get started with distutils. Additional information about using distutils can be found in the Distutils Cookbook. diff --git a/extending.rst b/extending.rst index 501fd7c564..1075e81779 100644 --- a/extending.rst +++ b/extending.rst @@ -4,6 +4,8 @@ Extending Distutils ******************* +.. include:: ./_setuptools_disclaimer.rst + Distutils can be extended in various ways. Most extensions take the form of new commands or replacements for existing commands. New commands may be written to support new types of platform-specific packaging, for example, while diff --git a/index.rst b/index.rst index d6f7640fcb..c56fafd68d 100644 --- a/index.rst +++ b/index.rst @@ -12,10 +12,7 @@ :ref:`distributing-index` The up to date module distribution documentations -This document describes the Python Distribution Utilities ("Distutils") from -the module developer's point of view, describing how to use the Distutils to -make Python modules and extensions easily available to a wider audience with -very little overhead for build/release/install mechanics. +.. include:: ./_setuptools_disclaimer.rst .. note:: @@ -25,6 +22,11 @@ very little overhead for build/release/install mechanics. recommendations section `__ in the Python Packaging User Guide for more information. +This document describes the Python Distribution Utilities ("Distutils") from +the module developer's point of view, describing the underlying capabilities +that ``setuptools`` builds on to allow Python developers to make Python modules +and extensions readily available to a wider audience. + .. toctree:: :maxdepth: 2 :numbered: diff --git a/introduction.rst b/introduction.rst index 7721484fe7..1f8a560e13 100644 --- a/introduction.rst +++ b/introduction.rst @@ -4,6 +4,8 @@ An Introduction to Distutils **************************** +.. include:: ./_setuptools_disclaimer.rst + This document covers using the Distutils to distribute your Python modules, concentrating on the role of developer/distributor: if you're looking for information on installing Python modules, you should refer to the diff --git a/setupscript.rst b/setupscript.rst index 1f99f62f6a..4386a60b66 100644 --- a/setupscript.rst +++ b/setupscript.rst @@ -4,6 +4,8 @@ Writing the Setup Script ************************ +.. include:: ./_setuptools_disclaimer.rst + The setup script is the centre of all activity in building, distributing, and installing modules using the Distutils. The main purpose of the setup script is to describe your module distribution to the Distutils, so that the various diff --git a/sourcedist.rst b/sourcedist.rst index 0ac8ef41dd..0600663d00 100644 --- a/sourcedist.rst +++ b/sourcedist.rst @@ -4,6 +4,8 @@ Creating a Source Distribution ****************************** +.. include:: ./_setuptools_disclaimer.rst + As shown in section :ref:`distutils-simple-example`, you use the :command:`sdist` command to create a source distribution. In the simplest case, :: From a2dc28765c62c6bcb08162a32c1ea5078d8d399d Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Fri, 24 May 2019 00:06:39 +1000 Subject: [PATCH 316/330] bpo-36797: Reduce levels of indirection in outdated distutils docs (#13462) --- index.rst | 1 - packageindex.rst | 7 +++---- uploading.rst | 3 ++- 3 files changed, 5 insertions(+), 6 deletions(-) diff --git a/index.rst b/index.rst index c56fafd68d..1f72a25542 100644 --- a/index.rst +++ b/index.rst @@ -36,7 +36,6 @@ and extensions readily available to a wider audience. configfile.rst sourcedist.rst builtdist.rst - packageindex.rst examples.rst extending.rst commandref.rst diff --git a/packageindex.rst b/packageindex.rst index f74c4396e5..ccb9a598b2 100644 --- a/packageindex.rst +++ b/packageindex.rst @@ -1,6 +1,4 @@ -.. index:: - single: Python Package Index (PyPI) - single: PyPI; (see Python Package Index (PyPI)) +:orphan: .. _package-index: @@ -12,6 +10,7 @@ The `Python Package Index (PyPI)`_ stores metadata describing distributions packaged with distutils and other publishing tools, as well the distribution archives themselves. -Detailed instructions on using PyPI at :ref:`distributing-index`. +References to up to date PyPI documentation can be found at +:ref:`publishing-python-packages`. .. _Python Package Index (PyPI): https://pypi.org diff --git a/uploading.rst b/uploading.rst index 4bce6997f9..4c391cab07 100644 --- a/uploading.rst +++ b/uploading.rst @@ -4,4 +4,5 @@ Uploading Packages to the Package Index *************************************** -The contents of this page have moved to the section :ref:`package-index`. +References to up to date PyPI documentation can be found at +:ref:`publishing-python-packages`. From 0d3ecffd07cf475c21c493695700871e84c1ede2 Mon Sep 17 00:00:00 2001 From: "E. M. Bray" Date: Fri, 24 May 2019 17:33:47 +0200 Subject: [PATCH 317/330] bpo-21536: On Cygwin, C extensions must be linked with libpython (GH-13549) It is also possible to link against a library or executable with a statically linked libpython, but not both with the same DLL. In fact building a statically linked python is currently broken on Cygwin for other (related) reasons. The same problem applies to other POSIX-like layers over Windows (MinGW, MSYS) but Python's build system does not seem to attempt to support those platforms at the moment. --- apiref.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apiref.rst b/apiref.rst index cbeedab5bb..2601d30f63 100644 --- a/apiref.rst +++ b/apiref.rst @@ -290,7 +290,7 @@ the full reference. .. versionchanged:: 3.8 On Unix, C extensions are no longer linked to libpython except on - Android. + Android and Cygwin. .. class:: Distribution From ceeaa6a19a32764fe34b718ca7a9265428ea54c1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miro=20Hron=C4=8Dok?= Date: Mon, 1 Jul 2019 14:12:40 +0200 Subject: [PATCH 318/330] bpo-10945: Drop support for bdist_wininst on non-Windows systems (GH-14506) bdist_wininst depends on MBCS codec, unavailable on non-Windows, and bdist_wininst have not worked since at least Python 3.2, possibly never on Python 3. Here we document that bdist_wininst is only supported on Windows, and we mark it unsupported otherwise to skip tests. Distributors of Python 3 can now safely drop the bdist_wininst .exe files without the need to skip bdist_wininst related tests. --- builtdist.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/builtdist.rst b/builtdist.rst index f44d0d039f..8c65d9d591 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -315,8 +315,8 @@ or the :command:`bdist` command with the :option:`!--formats` option:: If you have a pure module distribution (only containing pure Python modules and packages), the resulting installer will be version independent and have a name -like :file:`foo-1.0.win32.exe`. These installers can even be created on Unix -platforms or Mac OS X. +like :file:`foo-1.0.win32.exe`. Note that creating ``wininst`` binary +distributions in only supported on Windows systems. If you have a non-pure distribution, the extensions can only be created on a Windows platform, and will be Python version dependent. The installer filename From 4686db0f9ec4dc948f2ff9f671cff2a33d2e788d Mon Sep 17 00:00:00 2001 From: Victor Stinner Date: Fri, 5 Jul 2019 10:44:12 +0200 Subject: [PATCH 319/330] bpo-37481: Deprecate distutils bdist_wininst command (GH-14553) The distutils bdist_wininst command is now deprecated, use bdist_wheel (wheel packages) instead. --- apiref.rst | 3 +++ builtdist.rst | 9 +++++++++ 2 files changed, 12 insertions(+) diff --git a/apiref.rst b/apiref.rst index 2601d30f63..937f19f57b 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1863,6 +1863,9 @@ Subclasses of :class:`Command` must define the following methods. .. module:: distutils.command.bdist_wininst :synopsis: Build a Windows installer +.. deprecated:: 3.8 + Use bdist_wheel (wheel packages) instead. + .. % todo diff --git a/builtdist.rst b/builtdist.rst index 8c65d9d591..b814f2e950 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -146,6 +146,9 @@ generated by each, are: | :command:`bdist_msi` | msi | +--------------------------+-------------------------------------+ +.. note:: + bdist_wininst is deprecated since Python 3.8. + The following sections give details on the individual :command:`bdist_\*` commands. @@ -298,6 +301,9 @@ file winds up deep in the "build tree," in a temporary directory created by Creating Windows Installers =========================== +.. warning:: + bdist_wininst is deprecated since Python 3.8. + Executable installers are the natural format for binary distributions on Windows. They display a nice graphical user interface, display some information about the module distribution to be installed taken from the metadata in the @@ -459,3 +465,6 @@ Starting with Python 2.6, bdist_wininst supports a :option:`!--user-access-contr option. The default is 'none' (meaning no UAC handling is done), and other valid values are 'auto' (meaning prompt for UAC elevation if Python was installed for all users) and 'force' (meaning always prompt for elevation). + +.. note:: + bdist_wininst is deprecated since Python 3.8. From 7f891f2e69b82cdee48b2611529e0fc85941d2de Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Miro=20Hron=C4=8Dok?= Date: Thu, 5 Sep 2019 17:06:45 +0200 Subject: [PATCH 320/330] bpo-36797: Fix a dead link in Doc/distutils/apiref (GH-15700) https://bugs.python.org/issue36797 --- apiref.rst | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/apiref.rst b/apiref.rst index 937f19f57b..a42d2d3559 100644 --- a/apiref.rst +++ b/apiref.rst @@ -6,12 +6,12 @@ API Reference .. seealso:: - `New and changed setup.py arguments in setuptools `_ + `New and changed setup.py arguments in setuptools`_ The ``setuptools`` project adds new capabilities to the ``setup`` function and other APIs, makes the API consistent across different Python versions, and is hence recommended over using ``distutils`` directly. -.. _setuptools-setup-py: https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords +.. _New and changed setup.py arguments in setuptools: https://setuptools.readthedocs.io/en/latest/setuptools.html#new-and-changed-setup-keywords .. include:: ./_setuptools_disclaimer.rst From a9a584ff3ff91e5e5b5bfe7b1e123fdeb70ce399 Mon Sep 17 00:00:00 2001 From: Ezio Melotti Date: Wed, 11 Sep 2019 11:57:59 +0100 Subject: [PATCH 321/330] bpo-38103: fix conflicting labels in the docs. (GH-15906) --- examples.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/examples.rst b/examples.rst index 4ac552c7c6..44f70831d0 100644 --- a/examples.rst +++ b/examples.rst @@ -1,8 +1,8 @@ .. _distutils_examples: -******** -Examples -******** +****************** +Distutils Examples +****************** .. include:: ./_setuptools_disclaimer.rst From a831d3aff473637e761bda61c807c2c3b7f6eaa4 Mon Sep 17 00:00:00 2001 From: Sanchit Khurana <54467174+GeniusLearner@users.noreply.github.com> Date: Tue, 26 Nov 2019 03:47:59 +0530 Subject: [PATCH 322/330] bpo-21063: Improve module synopsis for distutils (GH-17363) --- apiref.rst | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/apiref.rst b/apiref.rst index a42d2d3559..80136b8a6b 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1545,7 +1545,7 @@ Python's own build procedures. ================================================= .. module:: distutils.text_file - :synopsis: provides the TextFile class, a simple interface to text files + :synopsis: Provides the TextFile class, a simple interface to text files This module provides the :class:`TextFile` class, which gives an interface to @@ -1684,7 +1684,7 @@ lines, and joining lines with backslashes. =================================================== .. module:: distutils.version - :synopsis: implements classes that represent module version numbers. + :synopsis: Implements classes that represent module version numbers. .. % todo @@ -1699,7 +1699,7 @@ lines, and joining lines with backslashes. =================================================================== .. module:: distutils.cmd - :synopsis: This module provides the abstract base class Command. This class + :synopsis: Provides the abstract base class :class:`~distutils.cmd.Command`. This class is subclassed by the modules in the distutils.command subpackage. @@ -1792,7 +1792,7 @@ Subclasses of :class:`Command` must define the following methods. ========================================================== .. module:: distutils.command - :synopsis: This subpackage contains one module for each standard Distutils command. + :synopsis: Contains one module for each standard Distutils command. .. % \subsubsection{Individual Distutils commands} @@ -2039,7 +2039,7 @@ This is described in more detail in :pep:`301`. =================================================================== .. module:: distutils.command.check - :synopsis: Check the metadata of a package + :synopsis: Check the meta-data of a package The ``check`` command performs some tests on the meta-data of a package. From fb4296cfd231785430ea174b44df5c7d21dff3d6 Mon Sep 17 00:00:00 2001 From: Michael Felt Date: Sun, 15 Dec 2019 15:17:53 +0100 Subject: [PATCH 323/330] bpo-38021: Modify AIX platform_tag so it covers PEP 425 needs (GH-17303) Provides a richer platform tag for AIX that we expect to be sufficient for PEP 425 binary distribution identification. Any backports to earlier Python versions will be handled via setuptools. Patch by Michael Felt. --- apiref.rst | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/apiref.rst b/apiref.rst index 80136b8a6b..12e0c0b2c9 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1142,6 +1142,24 @@ other utility module. * ``macosx-10.6-intel`` + For AIX, Python 3.9 and later return a string starting with "aix", followed + by additional fields (separated by ``'-'``) that represent the combined + values of AIX Version, Release and Technology Level (first field), Build Date + (second field), and bit-size (third field). Python 3.8 and earlier returned + only a single additional field with the AIX Version and Release. + + Examples of returned values on AIX: + + * ``aix-5307-0747-32`` # 32-bit build on AIX ``oslevel -s``: 5300-07-00-0000 + + * ``aix-7105-1731-64`` # 64-bit build on AIX ``oslevel -s``: 7100-05-01-1731 + + * ``aix-7.2`` # Legacy form reported in Python 3.8 and earlier + + .. versionchanged:: 3.9 + The AIX platform string format now also includes the technology level, + build date, and ABI bit-size. + .. function:: convert_path(pathname) From 9c8d213361e714fc29fb239df7cabf195c498fbb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?J=C3=BCrgen=20Gmach?= Date: Mon, 23 Dec 2019 15:53:18 +0100 Subject: [PATCH 324/330] bpo-38914 Do not require email field in setup.py. (GH-17388) When checking `setup.py` and when the `author` field was provided, but the `author_email` field was missing, erroneously a warning message was displayed that the `author_email` field is required. The specs do not require the `author_email`field: https://packaging.python.org/specifications/core-metadata/#author The same is valid for `maintainer` and `maintainer_email`. The warning message has been adjusted. modified: Doc/distutils/examples.rst modified: Lib/distutils/command/check.py https://bugs.python.org/issue38914 --- examples.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples.rst b/examples.rst index 44f70831d0..e492b7f605 100644 --- a/examples.rst +++ b/examples.rst @@ -255,7 +255,7 @@ Running the ``check`` command will display some warnings: running check warning: check: missing required meta-data: version, url warning: check: missing meta-data: either (author and author_email) or - (maintainer and maintainer_email) must be supplied + (maintainer and maintainer_email) should be supplied If you use the reStructuredText syntax in the ``long_description`` field and From 261f346dcc53dd5a22e3af9096679d17dbbecfcc Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Mon, 10 Feb 2020 15:26:40 +0200 Subject: [PATCH 325/330] bpo-39586: Deprecate distutils bdist_msi command (GH-18415) --- apiref.rst | 3 +++ builtdist.rst | 9 +++++++++ 2 files changed, 12 insertions(+) diff --git a/apiref.rst b/apiref.rst index 12e0c0b2c9..b14197c2f9 100644 --- a/apiref.rst +++ b/apiref.rst @@ -1855,6 +1855,9 @@ Subclasses of :class:`Command` must define the following methods. .. class:: bdist_msi +.. deprecated:: 3.9 + Use bdist_wheel (wheel packages) instead. + Builds a `Windows Installer`_ (.msi) binary package. .. _Windows Installer: https://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx diff --git a/builtdist.rst b/builtdist.rst index b814f2e950..e032c03e22 100644 --- a/builtdist.rst +++ b/builtdist.rst @@ -149,6 +149,9 @@ generated by each, are: .. note:: bdist_wininst is deprecated since Python 3.8. +.. note:: + bdist_msi is deprecated since Python 3.9. + The following sections give details on the individual :command:`bdist_\*` commands. @@ -304,6 +307,9 @@ Creating Windows Installers .. warning:: bdist_wininst is deprecated since Python 3.8. +.. warning:: + bdist_msi is deprecated since Python 3.9. + Executable installers are the natural format for binary distributions on Windows. They display a nice graphical user interface, display some information about the module distribution to be installed taken from the metadata in the @@ -468,3 +474,6 @@ installed for all users) and 'force' (meaning always prompt for elevation). .. note:: bdist_wininst is deprecated since Python 3.8. + +.. note:: + bdist_msi is deprecated since Python 3.9. From 1bfb4ba5347cf3f0fa8e1e8d4b19aa056f28a16b Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Wed, 23 Sep 2020 15:28:50 -0400 Subject: [PATCH 326/330] Move docs to docs/distutils --- .../distutils/_setuptools_disclaimer.rst | 0 apiref.rst => docs/distutils/apiref.rst | 0 builtdist.rst => docs/distutils/builtdist.rst | 0 commandref.rst => docs/distutils/commandref.rst | 0 configfile.rst => docs/distutils/configfile.rst | 0 examples.rst => docs/distutils/examples.rst | 0 extending.rst => docs/distutils/extending.rst | 0 index.rst => docs/distutils/index.rst | 0 introduction.rst => docs/distutils/introduction.rst | 0 packageindex.rst => docs/distutils/packageindex.rst | 0 setupscript.rst => docs/distutils/setupscript.rst | 0 sourcedist.rst => docs/distutils/sourcedist.rst | 0 uploading.rst => docs/distutils/uploading.rst | 0 13 files changed, 0 insertions(+), 0 deletions(-) rename _setuptools_disclaimer.rst => docs/distutils/_setuptools_disclaimer.rst (100%) rename apiref.rst => docs/distutils/apiref.rst (100%) rename builtdist.rst => docs/distutils/builtdist.rst (100%) rename commandref.rst => docs/distutils/commandref.rst (100%) rename configfile.rst => docs/distutils/configfile.rst (100%) rename examples.rst => docs/distutils/examples.rst (100%) rename extending.rst => docs/distutils/extending.rst (100%) rename index.rst => docs/distutils/index.rst (100%) rename introduction.rst => docs/distutils/introduction.rst (100%) rename packageindex.rst => docs/distutils/packageindex.rst (100%) rename setupscript.rst => docs/distutils/setupscript.rst (100%) rename sourcedist.rst => docs/distutils/sourcedist.rst (100%) rename uploading.rst => docs/distutils/uploading.rst (100%) diff --git a/_setuptools_disclaimer.rst b/docs/distutils/_setuptools_disclaimer.rst similarity index 100% rename from _setuptools_disclaimer.rst rename to docs/distutils/_setuptools_disclaimer.rst diff --git a/apiref.rst b/docs/distutils/apiref.rst similarity index 100% rename from apiref.rst rename to docs/distutils/apiref.rst diff --git a/builtdist.rst b/docs/distutils/builtdist.rst similarity index 100% rename from builtdist.rst rename to docs/distutils/builtdist.rst diff --git a/commandref.rst b/docs/distutils/commandref.rst similarity index 100% rename from commandref.rst rename to docs/distutils/commandref.rst diff --git a/configfile.rst b/docs/distutils/configfile.rst similarity index 100% rename from configfile.rst rename to docs/distutils/configfile.rst diff --git a/examples.rst b/docs/distutils/examples.rst similarity index 100% rename from examples.rst rename to docs/distutils/examples.rst diff --git a/extending.rst b/docs/distutils/extending.rst similarity index 100% rename from extending.rst rename to docs/distutils/extending.rst diff --git a/index.rst b/docs/distutils/index.rst similarity index 100% rename from index.rst rename to docs/distutils/index.rst diff --git a/introduction.rst b/docs/distutils/introduction.rst similarity index 100% rename from introduction.rst rename to docs/distutils/introduction.rst diff --git a/packageindex.rst b/docs/distutils/packageindex.rst similarity index 100% rename from packageindex.rst rename to docs/distutils/packageindex.rst diff --git a/setupscript.rst b/docs/distutils/setupscript.rst similarity index 100% rename from setupscript.rst rename to docs/distutils/setupscript.rst diff --git a/sourcedist.rst b/docs/distutils/sourcedist.rst similarity index 100% rename from sourcedist.rst rename to docs/distutils/sourcedist.rst diff --git a/uploading.rst b/docs/distutils/uploading.rst similarity index 100% rename from uploading.rst rename to docs/distutils/uploading.rst From 109bde8883ed07092443ae51fe1f5fe732300a13 Mon Sep 17 00:00:00 2001 From: "Jason R. Coombs" Date: Sun, 18 Oct 2020 13:26:05 -0400 Subject: [PATCH 327/330] Move distutils docs into 'deprecated' section and link them from that section. --- docs/{ => deprecated}/distutils/_setuptools_disclaimer.rst | 0 docs/{ => deprecated}/distutils/apiref.rst | 0 docs/{ => deprecated}/distutils/builtdist.rst | 0 docs/{ => deprecated}/distutils/commandref.rst | 0 docs/{ => deprecated}/distutils/configfile.rst | 0 docs/{ => deprecated}/distutils/examples.rst | 0 docs/{ => deprecated}/distutils/extending.rst | 0 docs/{ => deprecated}/distutils/index.rst | 0 docs/{ => deprecated}/distutils/introduction.rst | 0 docs/{ => deprecated}/distutils/packageindex.rst | 0 docs/{ => deprecated}/distutils/setupscript.rst | 0 docs/{ => deprecated}/distutils/sourcedist.rst | 0 docs/{ => deprecated}/distutils/uploading.rst | 0 docs/deprecated/index.rst | 1 + 14 files changed, 1 insertion(+) rename docs/{ => deprecated}/distutils/_setuptools_disclaimer.rst (100%) rename docs/{ => deprecated}/distutils/apiref.rst (100%) rename docs/{ => deprecated}/distutils/builtdist.rst (100%) rename docs/{ => deprecated}/distutils/commandref.rst (100%) rename docs/{ => deprecated}/distutils/configfile.rst (100%) rename docs/{ => deprecated}/distutils/examples.rst (100%) rename docs/{ => deprecated}/distutils/extending.rst (100%) rename docs/{ => deprecated}/distutils/index.rst (100%) rename docs/{ => deprecated}/distutils/introduction.rst (100%) rename docs/{ => deprecated}/distutils/packageindex.rst (100%) rename docs/{ => deprecated}/distutils/setupscript.rst (100%) rename docs/{ => deprecated}/distutils/sourcedist.rst (100%) rename docs/{ => deprecated}/distutils/uploading.rst (100%) diff --git a/docs/distutils/_setuptools_disclaimer.rst b/docs/deprecated/distutils/_setuptools_disclaimer.rst similarity index 100% rename from docs/distutils/_setuptools_disclaimer.rst rename to docs/deprecated/distutils/_setuptools_disclaimer.rst diff --git a/docs/distutils/apiref.rst b/docs/deprecated/distutils/apiref.rst similarity index 100% rename from docs/distutils/apiref.rst rename to docs/deprecated/distutils/apiref.rst diff --git a/docs/distutils/builtdist.rst b/docs/deprecated/distutils/builtdist.rst similarity index 100% rename from docs/distutils/builtdist.rst rename to docs/deprecated/distutils/builtdist.rst diff --git a/docs/distutils/commandref.rst b/docs/deprecated/distutils/commandref.rst similarity index 100% rename from docs/distutils/commandref.rst rename to docs/deprecated/distutils/commandref.rst diff --git a/docs/distutils/configfile.rst b/docs/deprecated/distutils/configfile.rst similarity index 100% rename from docs/distutils/configfile.rst rename to docs/deprecated/distutils/configfile.rst diff --git a/docs/distutils/examples.rst b/docs/deprecated/distutils/examples.rst similarity index 100% rename from docs/distutils/examples.rst rename to docs/deprecated/distutils/examples.rst diff --git a/docs/distutils/extending.rst b/docs/deprecated/distutils/extending.rst similarity index 100% rename from docs/distutils/extending.rst rename to docs/deprecated/distutils/extending.rst diff --git a/docs/distutils/index.rst b/docs/deprecated/distutils/index.rst similarity index 100% rename from docs/distutils/index.rst rename to docs/deprecated/distutils/index.rst diff --git a/docs/distutils/introduction.rst b/docs/deprecated/distutils/introduction.rst similarity index 100% rename from docs/distutils/introduction.rst rename to docs/deprecated/distutils/introduction.rst diff --git a/docs/distutils/packageindex.rst b/docs/deprecated/distutils/packageindex.rst similarity index 100% rename from docs/distutils/packageindex.rst rename to docs/deprecated/distutils/packageindex.rst diff --git a/docs/distutils/setupscript.rst b/docs/deprecated/distutils/setupscript.rst similarity index 100% rename from docs/distutils/setupscript.rst rename to docs/deprecated/distutils/setupscript.rst diff --git a/docs/distutils/sourcedist.rst b/docs/deprecated/distutils/sourcedist.rst similarity index 100% rename from docs/distutils/sourcedist.rst rename to docs/deprecated/distutils/sourcedist.rst diff --git a/docs/distutils/uploading.rst b/docs/deprecated/distutils/uploading.rst similarity index 100% rename from docs/distutils/uploading.rst rename to docs/deprecated/distutils/uploading.rst diff --git a/docs/deprecated/index.rst b/docs/deprecated/index.rst index ca80767a77..ce2ac006e1 100644 --- a/docs/deprecated/index.rst +++ b/docs/deprecated/index.rst @@ -16,5 +16,6 @@ objectives. python3 python_eggs easy_install + distutils/index distutils-legacy functionalities From 68b6847767c5f6914efd1891df957f7db0efdc1e Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Mon, 19 Oct 2020 00:34:58 +0200 Subject: [PATCH 328/330] Enable intersphinx to link against CPython docs --- docs/conf.py | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index 982f5e6212..a0449699b0 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -19,6 +19,7 @@ extensions = [ 'sphinx.ext.extlinks', # allows to create custom roles easily + 'sphinx.ext.intersphinx', # allows interlinking external docs sites 'jaraco.packaging.sphinx', 'rst.linker', ] @@ -155,3 +156,10 @@ # Ref: https://github.com/python-attrs/attrs/pull/571/files\ # #diff-85987f48f1258d9ee486e3191495582dR82 default_role = 'any' + + +# Allow linking objects on other Sphinx sites seamlessly: +intersphinx_mapping = { + 'python': ('https://docs.python.org/3', None), + 'python2': ('https://docs.python.org/2', None), +} From 8848933c2a6830b91461e356f4af3117813d96f7 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Mon, 19 Oct 2020 00:35:32 +0200 Subject: [PATCH 329/330] Correct broken refs in distutils docs --- docs/deprecated/distutils/apiref.rst | 29 +++++++------- docs/deprecated/distutils/configfile.rst | 4 +- docs/deprecated/distutils/examples.rst | 16 ++++---- docs/deprecated/distutils/extending.rst | 10 ++--- docs/deprecated/distutils/introduction.rst | 6 +-- docs/deprecated/distutils/setupscript.rst | 44 +++++++++++----------- 6 files changed, 56 insertions(+), 53 deletions(-) diff --git a/docs/deprecated/distutils/apiref.rst b/docs/deprecated/distutils/apiref.rst index b14197c2f9..40a360ddf2 100644 --- a/docs/deprecated/distutils/apiref.rst +++ b/docs/deprecated/distutils/apiref.rst @@ -513,7 +513,7 @@ This module provides the following functions. .. method:: CCompiler.detect_language(sources) Detect the language of a given file, or list of files. Uses the instance - attributes :attr:`language_map` (a dictionary), and :attr:`language_order` (a + attributes :attr:`~CCompiler.language_map` (a dictionary), and :attr:`~CCompiler.language_order` (a list) to do the job. @@ -761,7 +761,7 @@ This module provides the following functions. .. method:: CCompiler.spawn(cmd) - Invokes :func:`distutils.util.spawn`. This invokes an external process to run + Invokes :func:`distutils.spawn.spawn`. This invokes an external process to run the given command. @@ -861,8 +861,8 @@ This module provides :class:`BorlandCCompiler`, a subclass of the abstract :class:`CCompiler` class for the Borland C++ compiler. -:mod:`distutils.cygwincompiler` --- Cygwin Compiler -=================================================== +:mod:`distutils.cygwinccompiler` --- Cygwin Compiler +==================================================== .. module:: distutils.cygwinccompiler @@ -1017,7 +1017,7 @@ directories. directories. If *preserve_symlinks* is true, symlinks will be copied as symlinks (on platforms that support them!); otherwise (the default), the destination of the symlink will be copied. *update* and *verbose* are the same - as for :func:`copy_file`. + as for :func:`~distutils.file_util.copy_file`. Files in *src* that begin with :file:`.nfs` are skipped (more information on these files is available in answer D2 of the `NFS FAQ page @@ -1058,7 +1058,7 @@ This module contains some utility functions for operating on individual files. (using :func:`os.symlink`) instead of copying: set it to ``'hard'`` or ``'sym'``; if it is ``None`` (the default), files are copied. Don't set *link* on systems that don't support it: :func:`copy_file` doesn't check if hard or - symbolic linking is available. It uses :func:`_copy_file_contents` to copy file + symbolic linking is available. It uses :func:`~distutils.file_util._copy_file_contents` to copy file contents. Return a tuple ``(dest_name, copied)``: *dest_name* is the actual name of the @@ -1304,8 +1304,8 @@ represents the module distribution being built/installed/distributed. scripts -This module provides the :class:`Extension` class, used to describe C/C++ -extension modules in setup scripts. +This module provides the :class:`~distutils.extension.Extension` class, +used to describe C/C++ extension modules in setup scripts. .. % \subsection{Ungrouped modules} .. % The following haven't been moved into a more appropriate section yet. @@ -1363,7 +1363,7 @@ provides the following additional features: help_string)`` 3-tuples as described in the constructor for :class:`FancyGetopt`. *negative_opt* should be a dictionary mapping option names to option names, both the key and value should be in the *options* list. - *object* is an object which will be used to store values (see the :meth:`getopt` + *object* is an object which will be used to store values (see the :meth:`~FancyGetopt.getopt` method of the :class:`FancyGetopt` class). *args* is the argument list. Will use ``sys.argv[1:]`` if you pass ``None`` as *args*. @@ -1441,9 +1441,10 @@ filesystem and building lists of files. :synopsis: Provides the spawn() function -This module provides the :func:`spawn` function, a front-end to various -platform-specific functions for launching another program in a sub-process. -Also provides :func:`find_executable` to search the path for a given executable +This module provides the :func:`~distutils.spawn.spawn` function, a +front-end to various platform-specific functions for launching another +program in a sub-process. +Also provides :func:`~distutils.spawn.find_executable` to search the path for a given executable name. @@ -1755,7 +1756,7 @@ implementing. This module should implement a class with the same name as the module (and the command). So, for instance, to create the command ``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy :file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit -it so that it's implementing the class :class:`peel_banana`, a subclass of +it so that it's implementing the class ``peel_banana``, a subclass of :class:`distutils.cmd.Command`. Subclasses of :class:`Command` must define the following methods. @@ -2065,6 +2066,6 @@ This is described in more detail in :pep:`301`. The ``check`` command performs some tests on the meta-data of a package. For example, it verifies that all required meta-data are provided as -the arguments passed to the :func:`setup` function. +the arguments passed to the :func:`~distutils.core.setup` function. .. % todo diff --git a/docs/deprecated/distutils/configfile.rst b/docs/deprecated/distutils/configfile.rst index 2a5c8329e3..328936fb40 100644 --- a/docs/deprecated/distutils/configfile.rst +++ b/docs/deprecated/distutils/configfile.rst @@ -78,9 +78,9 @@ Note that an option spelled :option:`!--foo-bar` on the command-line is spelled .. _distutils-build-ext-inplace: For example, say you want your extensions to be built "in-place"---that is, you -have an extension :mod:`pkg.ext`, and you want the compiled extension file +have an extension ``pkg.ext``, and you want the compiled extension file (:file:`ext.so` on Unix, say) to be put in the same source directory as your -pure Python modules :mod:`pkg.mod1` and :mod:`pkg.mod2`. You can always use the +pure Python modules ``pkg.mod1`` and ``pkg.mod2``. You can always use the :option:`!--inplace` option on the command-line to ensure this: .. code-block:: sh diff --git a/docs/deprecated/distutils/examples.rst b/docs/deprecated/distutils/examples.rst index e492b7f605..d0984655df 100644 --- a/docs/deprecated/distutils/examples.rst +++ b/docs/deprecated/distutils/examples.rst @@ -49,7 +49,7 @@ convention to follow). However, the distribution name is used to generate filenames, so you should stick to letters, digits, underscores, and hyphens. Since ``py_modules`` is a list, you can of course specify multiple -modules, eg. if you're distributing modules :mod:`foo` and :mod:`bar`, your +modules, eg. if you're distributing modules ``foo`` and ``bar``, your setup might look like this:: / @@ -111,8 +111,8 @@ Distutils where source files in the root package live:: ) More typically, though, you will want to distribute multiple modules in the same -package (or in sub-packages). For example, if the :mod:`foo` and :mod:`bar` -modules belong in package :mod:`foobar`, one way to layout your source tree is +package (or in sub-packages). For example, if the ``foo`` and ``bar`` +modules belong in package ``foobar``, one way to layout your source tree is :: / @@ -133,7 +133,7 @@ requires the least work to describe in your setup script:: If you want to put modules in directories not named for their package, then you need to use the ``package_dir`` option again. For example, if the -:file:`src` directory holds modules in the :mod:`foobar` package:: +:file:`src` directory holds modules in the ``foobar`` package:: / setup.py @@ -210,7 +210,7 @@ single extension module in a single C source file, is:: setup.py foo.c -If the :mod:`foo` extension belongs in the root package, the setup script for +If the ``foo`` extension belongs in the root package, the setup script for this could be :: from distutils.core import setup @@ -220,10 +220,10 @@ this could be :: ext_modules=[Extension('foo', ['foo.c'])], ) -If the extension actually belongs in a package, say :mod:`foopkg`, then +If the extension actually belongs in a package, say ``foopkg``, then With exactly the same source tree layout, this extension can be put in the -:mod:`foopkg` package simply by changing the name of the extension:: +``foopkg`` package simply by changing the name of the extension:: from distutils.core import setup from distutils.extension import Extension @@ -311,7 +311,7 @@ in the Metadata, and ``pyX.X`` the major and minor version of Python like You can read back this static file, by using the :class:`distutils.dist.DistributionMetadata` class and its -:func:`read_pkg_file` method:: +:func:`~distutils.dist.DistributionMetadata.read_pkg_file` method:: >>> from distutils.dist import DistributionMetadata >>> metadata = DistributionMetadata() diff --git a/docs/deprecated/distutils/extending.rst b/docs/deprecated/distutils/extending.rst index 1075e81779..c99d3c791f 100644 --- a/docs/deprecated/distutils/extending.rst +++ b/docs/deprecated/distutils/extending.rst @@ -19,9 +19,9 @@ convenience. Most distutils command implementations are subclasses of the :class:`distutils.cmd.Command` class. New commands may directly inherit from -:class:`Command`, while replacements often derive from :class:`Command` +:class:`~distutils.cmd.Command`, while replacements often derive from :class:`~distutils.cmd.Command` indirectly, directly subclassing the command they are replacing. Commands are -required to derive from :class:`Command`. +required to derive from :class:`~distutils.cmd.Command`. .. % \section{Extending existing commands} .. % \label{extend-existing} @@ -78,12 +78,12 @@ packages searched for command implementations; multiple package names should be separated by commas. When not specified, the search is only performed in the :mod:`distutils.command` package. When :file:`setup.py` is run with the option ``--command-packages distcmds,buildcmds``, however, the packages -:mod:`distutils.command`, :mod:`distcmds`, and :mod:`buildcmds` will be searched +:mod:`distutils.command`, ``distcmds``, and ``buildcmds`` will be searched in that order. New commands are expected to be implemented in modules of the same name as the command by classes sharing the same name. Given the example command line option above, the command :command:`bdist_openpkg` could be -implemented by the class :class:`distcmds.bdist_openpkg.bdist_openpkg` or -:class:`buildcmds.bdist_openpkg.bdist_openpkg`. +implemented by the class ``distcmds.bdist_openpkg.bdist_openpkg`` or +``buildcmds.bdist_openpkg.bdist_openpkg``. Adding new distribution types diff --git a/docs/deprecated/distutils/introduction.rst b/docs/deprecated/distutils/introduction.rst index 1f8a560e13..7491b965a5 100644 --- a/docs/deprecated/distutils/introduction.rst +++ b/docs/deprecated/distutils/introduction.rst @@ -55,7 +55,7 @@ Unlike, say, Autoconf-style configure scripts, the setup script may be run multiple times in the course of building and installing your module distribution. -If all you want to do is distribute a module called :mod:`foo`, contained in a +If all you want to do is distribute a module called ``foo``, contained in a file :file:`foo.py`, then your setup script can be as simple as this:: from distutils.core import setup @@ -67,7 +67,7 @@ file :file:`foo.py`, then your setup script can be as simple as this:: Some observations: * most information that you supply to the Distutils is supplied as keyword - arguments to the :func:`setup` function + arguments to the :func:`~distutils.core.setup` function * those keyword arguments fall into two categories: package metadata (name, version number) and information about what's in the package (a list of pure @@ -96,7 +96,7 @@ containing your setup script :file:`setup.py`, and your module :file:`foo.py`. The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and will unpack into a directory :file:`foo-1.0`. -If an end-user wishes to install your :mod:`foo` module, all they have to do is +If an end-user wishes to install your ``foo`` module, all they have to do is download :file:`foo-1.0.tar.gz` (or :file:`.zip`), unpack it, and---from the :file:`foo-1.0` directory---run :: diff --git a/docs/deprecated/distutils/setupscript.rst b/docs/deprecated/distutils/setupscript.rst index 4386a60b66..f49c4f893f 100644 --- a/docs/deprecated/distutils/setupscript.rst +++ b/docs/deprecated/distutils/setupscript.rst @@ -10,9 +10,9 @@ The setup script is the centre of all activity in building, distributing, and installing modules using the Distutils. The main purpose of the setup script is to describe your module distribution to the Distutils, so that the various commands that operate on your modules do the right thing. As we saw in section -:ref:`distutils-simple-example` above, the setup script consists mainly of a call to -:func:`setup`, and most information supplied to the Distutils by the module -developer is supplied as keyword arguments to :func:`setup`. +:ref:`distutils-simple-example` above, the setup script consists mainly of a call to :func:`~distutils.core.setup`, and most information +supplied to the Distutils by the module developer is supplied as keyword +arguments to :func:`~distutils.core.setup`. Here's a slightly more involved example, which we'll follow for the next couple of sections: the Distutils' own setup script. (Keep in mind that although the @@ -80,7 +80,7 @@ If you use a different convention to lay out your source directory, that's no problem: you just have to supply the ``package_dir`` option to tell the Distutils about your convention. For example, say you keep all Python source under :file:`lib`, so that modules in the "root package" (i.e., not in any -package at all) are in :file:`lib`, modules in the :mod:`foo` package are in +package at all) are in :file:`lib`, modules in the ``foo`` package are in :file:`lib/foo`, and so forth. Then you would put :: package_dir = {'': 'lib'} @@ -90,14 +90,14 @@ empty package name stands for the root package. The values are directory names relative to your distribution root. In this case, when you say ``packages = ['foo']``, you are promising that the file :file:`lib/foo/__init__.py` exists. -Another possible convention is to put the :mod:`foo` package right in -:file:`lib`, the :mod:`foo.bar` package in :file:`lib/bar`, etc. This would be +Another possible convention is to put the ``foo`` package right in +:file:`lib`, the ``foo.bar`` package in :file:`lib/bar`, etc. This would be written in the setup script as :: package_dir = {'foo': 'lib'} A ``package: dir`` entry in the ``package_dir`` dictionary implicitly -applies to all packages below *package*, so the :mod:`foo.bar` case is +applies to all packages below *package*, so the ``foo.bar`` case is automatically handled here. In this example, having ``packages = ['foo', 'foo.bar']`` tells the Distutils to look for :file:`lib/__init__.py` and :file:`lib/bar/__init__.py`. (Keep in mind that although ``package_dir`` @@ -119,7 +119,7 @@ section :ref:`distutils-simple-example`; here is a slightly more involved exampl py_modules = ['mod1', 'pkg.mod2'] This describes two modules, one of them in the "root" package, the other in the -:mod:`pkg` package. Again, the default package/directory layout implies that +``pkg`` package. Again, the default package/directory layout implies that these two modules can be found in :file:`mod1.py` and :file:`pkg/mod2.py`, and that :file:`pkg/__init__.py` exists as well. And again, you can override the package/directory correspondence using the ``package_dir`` option. @@ -139,18 +139,19 @@ directories, libraries to link with, etc.). .. XXX read over this section -All of this is done through another keyword argument to :func:`setup`, the +All of this is done through another keyword argument to +:func:`~distutils.core.setup`, the ``ext_modules`` option. ``ext_modules`` is just a list of :class:`~distutils.core.Extension` instances, each of which describes a single extension module. -Suppose your distribution includes a single extension, called :mod:`foo` and +Suppose your distribution includes a single extension, called ``foo`` and implemented by :file:`foo.c`. If no additional instructions to the compiler/linker are needed, describing this extension is quite simple:: Extension('foo', ['foo.c']) -The :class:`Extension` class can be imported from :mod:`distutils.core` along -with :func:`setup`. Thus, the setup script for a module distribution that +The :class:`~distutils.extension.Extension` class can be imported from :mod:`distutils.core` along +with :func:`~distutils.core.setup`. Thus, the setup script for a module distribution that contains only this one extension and nothing else might be:: from distutils.core import setup, Extension @@ -159,7 +160,7 @@ contains only this one extension and nothing else might be:: ext_modules=[Extension('foo', ['foo.c'])], ) -The :class:`Extension` class (actually, the underlying extension-building +The :class:`~distutils.extension.Extension` class (actually, the underlying extension-building machinery implemented by the :command:`build_ext` command) supports a great deal of flexibility in describing Python extensions, which is explained in the following sections. @@ -177,14 +178,14 @@ describes an extension that lives in the root package, while :: Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c']) -describes the same extension in the :mod:`pkg` package. The source files and +describes the same extension in the ``pkg`` package. The source files and resulting object code are identical in both cases; the only difference is where in the filesystem (and therefore where in Python's namespace hierarchy) the resulting extension lives. If you have a number of extensions all in the same package (or all under the same base package), use the ``ext_package`` keyword argument to -:func:`setup`. For example, :: +:func:`~distutils.core.setup`. For example, :: setup(..., ext_package='pkg', @@ -192,8 +193,8 @@ same base package), use the ``ext_package`` keyword argument to Extension('subpkg.bar', ['bar.c'])], ) -will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to -:mod:`pkg.subpkg.bar`. +will compile :file:`foo.c` to the extension ``pkg.foo``, and +:file:`bar.c` to ``pkg.subpkg.bar``. Extension source files @@ -375,7 +376,8 @@ These relationships can be specified using keyword arguments to the :func:`distutils.core.setup` function. Dependencies on other Python modules and packages can be specified by supplying -the *requires* keyword argument to :func:`setup`. The value must be a list of +the *requires* keyword argument to :func:`~distutils.core.setup`. The +value must be a list of strings. Each string specifies a package that is required, and optionally what versions are sufficient. @@ -407,7 +409,7 @@ Let's look at a bunch of examples: Now that we can specify dependencies, we also need to be able to specify what we provide that other distributions can require. This is done using the *provides* -keyword argument to :func:`setup`. The value for this keyword is a list of +keyword argument to :func:`~distutils.core.setup`. The value for this keyword is a list of strings, each of which names a Python module or package, and optionally identifies the version. If the version is not specified, it is assumed to match that of the distribution. @@ -474,7 +476,7 @@ containing documentation that might be of interest to programmers using the package. These files are called :dfn:`package data`. Package data can be added to packages using the ``package_data`` keyword -argument to the :func:`setup` function. The value must be a mapping from +argument to the :func:`~distutils.core.setup` function. The value must be a mapping from package name to a list of relative path names that should be copied into the package. The paths are interpreted as relative to the directory containing the package (information from the ``package_dir`` mapping is used if appropriate); @@ -497,7 +499,7 @@ the files can be arranged like this in the source tree:: spoons.dat forks.dat -The corresponding call to :func:`setup` might be:: +The corresponding call to :func:`~distutils.core.setup` might be:: setup(..., packages=['mypkg'], From 18b7a3e77aa81e9d22cd0a52061a2c8e3a640cc8 Mon Sep 17 00:00:00 2001 From: Sviatoslav Sydorenko Date: Mon, 19 Oct 2020 00:36:03 +0200 Subject: [PATCH 330/330] Allow some refs to undocumented/undeclared objects --- docs/conf.py | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) diff --git a/docs/conf.py b/docs/conf.py index a0449699b0..de9fe3f892 100644 --- a/docs/conf.py +++ b/docs/conf.py @@ -152,6 +152,42 @@ # Be strict about any broken references: nitpicky = True +# Ref: https://stackoverflow.com/a/30624034/595220 +nitpick_ignore = [ + ('c:func', 'SHGetSpecialFolderPath'), # ref to MS docs + ('envvar', 'DISTUTILS_DEBUG'), # undocumented + ('envvar', 'HOME'), # undocumented + ('envvar', 'PLAT'), # undocumented + ('py:attr', 'CCompiler.language_map'), # undocumented + ('py:attr', 'CCompiler.language_order'), # undocumented + ('py:class', 'distutils.dist.Distribution'), # undocumented + ('py:class', 'distutils.extension.Extension'), # undocumented + ('py:class', 'BorlandCCompiler'), # undocumented + ('py:class', 'CCompiler'), # undocumented + ('py:class', 'CygwinCCompiler'), # undocumented + ('py:class', 'distutils.dist.DistributionMetadata'), # undocumented + ('py:class', 'FileList'), # undocumented + ('py:class', 'IShellLink'), # ref to MS docs + ('py:class', 'MSVCCompiler'), # undocumented + ('py:class', 'OptionDummy'), # undocumented + ('py:class', 'UnixCCompiler'), # undocumented + ('py:exc', 'CompileError'), # undocumented + ('py:exc', 'DistutilsExecError'), # undocumented + ('py:exc', 'DistutilsFileError'), # undocumented + ('py:exc', 'LibError'), # undocumented + ('py:exc', 'LinkError'), # undocumented + ('py:exc', 'PreprocessError'), # undocumented + ('py:func', 'distutils.CCompiler.new_compiler'), # undocumented + # undocumented: + ('py:func', 'distutils.dist.DistributionMetadata.read_pkg_file'), + ('py:func', 'distutils.file_util._copy_file_contents'), # undocumented + ('py:func', 'distutils.log.debug'), # undocumented + ('py:func', 'distutils.spawn.find_executable'), # undocumented + ('py:func', 'distutils.spawn.spawn'), # undocumented + # TODO: check https://docutils.rtfd.io in the future + ('py:mod', 'docutils'), # there's no Sphinx site documenting this +] + # Ref: https://github.com/python-attrs/attrs/pull/571/files\ # #diff-85987f48f1258d9ee486e3191495582dR82