Ignore:
Timestamp:
Mar 19, 2014, 11:11:30 AM (11 years ago)
Author:
dmik
Message:

python: Update vendor to 2.7.6.

Location:
python/vendor/current/Doc/distutils
Files:
10 edited

Legend:

Unmodified
Added
Removed

  • python/vendor/current/Doc/distutils/apiref.rst

    r2 r388  
    2222
    2323   The basic do-everything function that does most everything you could ever ask
    24    for from a Distutils method. See XXXXX
     24   for from a Distutils method.
    2525
    2626   The setup function takes a large number of arguments. These are laid out in the
    2727   following table.
     28
     29   .. tabularcolumns:: |l|L|L|
    2830
    2931   +--------------------+--------------------------------+-------------------------------------------------------------+
    … …  
    3234   | *name*             | The name of the package        | a string                                                    |
    3335   +--------------------+--------------------------------+-------------------------------------------------------------+
    34    | *version*          | The version number of the      | See :mod:`distutils.version`                                |
    35    |                    | package                        |                                                             |
     36   | *version*          | The version number of the      | a string                                                    |
     37   |                    | package; see                   |                                                             |
     38   |                    | :mod:`distutils.version`       |                                                             |
    3639   +--------------------+--------------------------------+-------------------------------------------------------------+
    3740   | *description*      | A single line describing the   | a string                                                    |
    … …  
    4851   | *maintainer*       | The name of the current        | a string                                                    |
    4952   |                    | maintainer, if different from  |                                                             |
    50    |                    | the author                     |                                                             |
    51    +--------------------+--------------------------------+-------------------------------------------------------------+
    52    | *maintainer_email* | The email address of the       |                                                             |
     53   |                    | the author. Note that if       |                                                             |
     54   |                    | the maintainer is provided,    |                                                             |
     55   |                    | distutils will use it as the   |                                                             |
     56   |                    | author in :file:`PKG-INFO`     |                                                             |
     57   +--------------------+--------------------------------+-------------------------------------------------------------+
     58   | *maintainer_email* | The email address of the       | a string                                                    |
    5359   |                    | current maintainer, if         |                                                             |
    5460   |                    | different from the author      |                                                             |
    5561   +--------------------+--------------------------------+-------------------------------------------------------------+
    56    | *url*              | A URL for the package          | a URL                                                       |
     62   | *url*              | A URL for the package          | a string                                                    |
    5763   |                    | (homepage)                     |                                                             |
    5864   +--------------------+--------------------------------+-------------------------------------------------------------+
    59    | *download_url*     | A URL to download the package  | a URL                                                       |
     65   | *download_url*     | A URL to download the package  | a string                                                    |
    6066   +--------------------+--------------------------------+-------------------------------------------------------------+
    6167   | *packages*         | A list of Python packages that | a list of strings                                           |
    … …  
    6975   |                    | installed                      |                                                             |
    7076   +--------------------+--------------------------------+-------------------------------------------------------------+
    71    | *ext_modules*      | A list of Python extensions to | A list of  instances of                                     |
     77   | *ext_modules*      | A list of Python extensions to | a list of instances of                                      |
    7278   |                    | be built                       | :class:`distutils.core.Extension`                           |
    7379   +--------------------+--------------------------------+-------------------------------------------------------------+
    74    | *classifiers*      | A list of categories for the   | The list of available                                       |
    75    |                    | package                        | categorizations is at                                       |
    76    |                    |                                | http://pypi.python.org/pypi?:action=list_classifiers.       |
    77    +--------------------+--------------------------------+-------------------------------------------------------------+
    78    | *distclass*        | the :class:`Distribution`      | A subclass of                                               |
     80   | *classifiers*      | A list of categories for the   | a list of strings; valid classifiers are listed on `PyPI    |
     81   |                    | package                        | <http://pypi.python.org/pypi?:action=list_classifiers>`_.   |
     82   +--------------------+--------------------------------+-------------------------------------------------------------+
     83   | *distclass*        | the :class:`Distribution`      | a subclass of                                               |
    7984   |                    | class to use                   | :class:`distutils.core.Distribution`                        |
    8085   +--------------------+--------------------------------+-------------------------------------------------------------+
    … …  
    8691   |                    | setup script                   |                                                             |
    8792   +--------------------+--------------------------------+-------------------------------------------------------------+
    88    | *options*          | default options for the setup  | a string                                                    |
     93   | *options*          | default options for the setup  | a dictionary                                                |
    8994   |                    | script                         |                                                             |
    9095   +--------------------+--------------------------------+-------------------------------------------------------------+
    9196   | *license*          | The license for the package    | a string                                                    |
    9297   +--------------------+--------------------------------+-------------------------------------------------------------+
    93    | *keywords*         | Descriptive meta-data, see     |                                                             |
     98   | *keywords*         | Descriptive meta-data, see     | a list of strings or a comma-separated string               |
    9499   |                    | :pep:`314`                     |                                                             |
    95100   +--------------------+--------------------------------+-------------------------------------------------------------+
    96    | *platforms*        |                                |                                                             |
     101   | *platforms*        |                                | a list of strings or a comma-separated string               |
    97102   +--------------------+--------------------------------+-------------------------------------------------------------+
    98103   | *cmdclass*         | A mapping of command names to  | a dictionary                                                |
    … …  
    122127
    123128   *stop_after* tells :func:`setup` when to stop processing; possible  values:
     129
     130   .. tabularcolumns:: |l|L|
    124131
    125132   +---------------+---------------------------------------------+
    … …  
    148155live elsewhere.
    149156
    150 * :class:`Extension` from :mod:`distutils.extension`
    151 
    152 * :class:`Command` from :mod:`distutils.cmd`
    153 
    154 * :class:`Distribution` from :mod:`distutils.dist`
     157* :class:`~distutils.extension.Extension` from :mod:`distutils.extension`
     158
     159* :class:`~distutils.cmd.Command` from :mod:`distutils.cmd`
     160
     161* :class:`~distutils.dist.Distribution` from :mod:`distutils.dist`
    155162
    156163A short description of each of these follows, but see the relevant module for
    … …  
    162169   The Extension class describes a single C or C++extension module in a setup
    163170   script. It accepts the following keyword arguments in its constructor
     171
     172   .. tabularcolumns:: |l|L|l|
    164173
    165174   +------------------------+--------------------------------+---------------------------+
    166175   | argument name          | value                          | type                      |
    167176   +========================+================================+===========================+
    168    | *name*                 | the full name of the           | string                    |
     177   | *name*                 | the full name of the           | a string                  |
    169178   |                        | extension, including any       |                           |
    170179   |                        | packages --- ie. *not* a       |                           |
    … …  
    172181   |                        | Python dotted name             |                           |
    173182   +------------------------+--------------------------------+---------------------------+
    174    | *sources*              | list of source filenames,      | string                    |
     183   | *sources*              | list of source filenames,      | a list of strings         |
    175184   |                        | relative to the distribution   |                           |
    176185   |                        | root (where the setup script   |                           |
    … …  
    185194   |                        | extension.                     |                           |
    186195   +------------------------+--------------------------------+---------------------------+
    187    | *include_dirs*         | list of directories to search  | string                    |
     196   | *include_dirs*         | list of directories to search  | a list of strings         |
    188197   |                        | for C/C++ header files (in     |                           |
    189198   |                        | Unix form for portability)     |                           |
    190199   +------------------------+--------------------------------+---------------------------+
    191    | *define_macros*        | list of macros to define; each | (string, string) tuple or |
    192    |                        | macro is defined using a       | (name, ``None``)          |
     200   | *define_macros*        | list of macros to define; each | a list of tuples          |
     201   |                        | macro is defined using a       |                           |
    193202   |                        | 2-tuple ``(name, value)``,     |                           |
    194203   |                        | where *value* is               |                           |
    … …  
    201210   |                        | line)                          |                           |
    202211   +------------------------+--------------------------------+---------------------------+
    203    | *undef_macros*         | list of macros to undefine     | string                    |
     212   | *undef_macros*         | list of macros to undefine     | a list of strings         |
    204213   |                        | explicitly                     |                           |
    205214   +------------------------+--------------------------------+---------------------------+
    206    | *library_dirs*         | list of directories to search  | string                    |
     215   | *library_dirs*         | list of directories to search  | a list of strings         |
    207216   |                        | for C/C++ libraries at link    |                           |
    208217   |                        | time                           |                           |
    209218   +------------------------+--------------------------------+---------------------------+
    210    | *libraries*            | list of library names (not     | string                    |
     219   | *libraries*            | list of library names (not     | a list of strings         |
    211220   |                        | filenames or paths) to link    |                           |
    212221   |                        | against                        |                           |
    213222   +------------------------+--------------------------------+---------------------------+
    214    | *runtime_library_dirs* | list of directories to search  | string                    |
     223   | *runtime_library_dirs* | list of directories to search  | a list of strings         |
    215224   |                        | for C/C++ libraries at run     |                           |
    216225   |                        | time (for shared extensions,   |                           |
    … …  
    218227   |                        | loaded)                        |                           |
    219228   +------------------------+--------------------------------+---------------------------+
    220    | *extra_objects*        | list of extra files to link    | string                    |
     229   | *extra_objects*        | list of extra files to link    | a list of strings         |
    221230   |                        | with (eg. object files not     |                           |
    222231   |                        | implied by 'sources', static   |                           |
    … …  
    225234   |                        | resource files, etc.)          |                           |
    226235   +------------------------+--------------------------------+---------------------------+
    227    | *extra_compile_args*   | any extra platform- and        | string                    |
     236   | *extra_compile_args*   | any extra platform- and        | a list of strings         |
    228237   |                        | compiler-specific information  |                           |
    229238   |                        | to use when compiling the      |                           |
    … …  
    236245   |                        | be anything.                   |                           |
    237246   +------------------------+--------------------------------+---------------------------+
    238    | *extra_link_args*      | any extra platform- and        | string                    |
     247   | *extra_link_args*      | any extra platform- and        | a list of strings         |
    239248   |                        | compiler-specific information  |                           |
    240249   |                        | to use when linking object     |                           |
    … …  
    245254   |                        | 'extra_compile_args'.          |                           |
    246255   +------------------------+--------------------------------+---------------------------+
    247    | *export_symbols*       | list of symbols to be exported | string                    |
     256   | *export_symbols*       | list of symbols to be exported | a list of strings         |
    248257   |                        | from a shared extension. Not   |                           |
    249258   |                        | used on all platforms, and not |                           |
    … …  
    253262   |                        | ``init`` + extension_name.     |                           |
    254263   +------------------------+--------------------------------+---------------------------+
    255    | *depends*              | list of files that the         | string                    |
     264   | *depends*              | list of files that the         | a list of strings         |
    256265   |                        | extension depends on           |                           |
    257266   +------------------------+--------------------------------+---------------------------+
    258    | *language*             | extension language (i.e.       | string                    |
     267   | *language*             | extension language (i.e.       | a string                  |
    259268   |                        | ``'c'``, ``'c++'``,            |                           |
    260269   |                        | ``'objc'``). Will be detected  |                           |
    … …  
    445454      The optional parameter *value* should be a string; if it is not supplied, then
    446455      the macro will be defined without an explicit value and the exact outcome
    447       depends on the compiler used (XXX true? does ANSI say anything about this?)
     456      depends on the compiler used.
     457
     458      .. XXX true? does ANSI say anything about this?
    448459
    449460
    … …  
    599610      *output_libname* should be a library name, not a filename; the filename will be
    600611      inferred from the library name.  *output_dir* is the directory where the library
    601       file will be put. XXX defaults to what?
     612      file will be put.
     613
     614      .. XXX defaults to what?
    602615
    603616      *debug* is a boolean; if true, debugging information will be included in the
    … …  
    717730   .. method:: CCompiler.execute(func, args[, msg=None, level=1])
    718731
    719       Invokes :func:`distutils.util.execute` This method invokes a  Python function
     732      Invokes :func:`distutils.util.execute`. This method invokes a  Python function
    720733      *func* with the given arguments *args*, after  logging and taking into account
    721       the *dry_run* flag. XXX see also.
     734      the *dry_run* flag.
    722735
    723736
    … …  
    725738
    726739      Invokes :func:`distutils.util.spawn`. This invokes an external  process to run
    727       the given command. XXX see also.
     740      the given command.
    728741
    729742
    … …  
    731744
    732745      Invokes :func:`distutils.dir_util.mkpath`. This creates a directory  and any
    733       missing ancestor directories. XXX see also.
     746      missing ancestor directories.
    734747
    735748
    736749   .. method:: CCompiler.move_file(src, dst)
    737750
    738       Invokes :meth:`distutils.file_util.move_file`. Renames *src* to  *dst*.  XXX see
    739       also.
     751      Invokes :meth:`distutils.file_util.move_file`. Renames *src* to  *dst*.
    740752
    741753
    742754   .. method:: CCompiler.announce(msg[, level=1])
    743755
    744       Write a message using :func:`distutils.log.debug`. XXX see also.
     756      Write a message using :func:`distutils.log.debug`.
    745757
    746758
    … …  
    846858This module provides the EMXCCompiler class, a subclass of
    847859:class:`UnixCCompiler` that handles the EMX port of the GNU C compiler to OS/2.
    848 
    849 
    850 :mod:`distutils.mwerkscompiler` --- Metrowerks CodeWarrior support
    851 ==================================================================
    852 
    853 .. module:: distutils.mwerkscompiler
    854    :synopsis: Metrowerks CodeWarrior support
    855 
    856 
    857 Contains :class:`MWerksCompiler`, an implementation of the abstract
    858 :class:`CCompiler` class for MetroWerks CodeWarrior on the pre-Mac OS X
    859 Macintosh. Needs work to support CW on Windows or Mac OS X.
    860 
    861 .. % \subsection{Utility modules}
    862 .. %
    863 .. % The following modules all provide general utility functions. They haven't
    864 .. % all been documented yet.
    865860
    866861
    … …  
    887882   both default to the current directory.  Returns the name of the archive file.
    888883
    889    .. XXX This should be changed to support bz2 files.
    890 
    891884
    892885.. function:: make_tarball(base_name, base_dir[, compress='gzip', verbose=0, dry_run=0])
    … …  
    900893   or :file:`.Z`).  Return the output filename.
    901894
    902    .. XXX This should be replaced with calls to the :mod:`tarfile` module.
    903 
    904895
    905896.. function:: make_zipfile(base_name, base_dir[, verbose=0, dry_run=0])
    906897
    907898   Create a zip file from all files in and under *base_dir*.  The output zip file
    908    will be named *base_dir* + :file:`.zip`.  Uses either the  :mod:`zipfile` Python
     899   will be named *base_name* + :file:`.zip`.  Uses either the  :mod:`zipfile` Python
    909900   module (if available) or the InfoZIP :file:`zip`  utility (if installed and
    910901   found on the default search path).  If neither  tool is available, raises
    … …  
    992983   *dst* must be directory names.  If *src* is not a directory, raise
    993984   :exc:`DistutilsFileError`.  If *dst* does  not exist, it is created with
    994    :func:`mkpath`.  The end result of the  copy is that every file in *src* is
    995    copied to *dst*, and  directories under *src* are recursively copied to *dst*.
     985   :func:`mkpath`.  The end result of the copy is that every file in *src* is
     986   copied to *dst*, and directories under *src* are recursively copied to *dst*.
    996987   Return the list of files that were copied or might have been copied, using their
    997988   output name. The return value is unaffected by *update* or *dry_run*: it is
    … …  
    999990   *dst*.
    1000991
    1001    *preserve_mode* and *preserve_times* are the same as for :func:`copy_file` in
    1002    :mod:`distutils.file_util`; note that they only apply to regular files, not to
     992   *preserve_mode* and *preserve_times* are the same as for
     993   :func:`distutils.file_util.copy_file`; note that they only apply to
     994   regular files, not to
    1003995   directories.  If *preserve_symlinks* is true, symlinks will be copied as
    1004996   symlinks (on platforms that support them!); otherwise (the default), the
    … …  
    1006998   as for :func:`copy_file`.
    1007999
     1000   Files in *src* that begin with :file:`.nfs` are skipped (more information on
     1001   these files is available in answer D2 of the `NFS FAQ page
     1002   <http://nfs.sourceforge.net/#section_d>`_.
     1003
     1004   .. versionchanged:: 2.7.4
     1005      NFS files are ignored.
     1006
    10081007
    10091008.. function:: remove_tree(directory[, verbose=0, dry_run=0])
    … …  
    10121011   errors are ignored (apart from being reported to ``sys.stdout`` if *verbose* is
    10131012   true).
    1014 
    1015 **\*\*** Some of this could be replaced with the shutil module? **\*\***
    10161013
    10171014
    … …  
    11281125   * ``macosx-10.6-intel``
    11291126
    1130    .. % XXX isn't this also provided by some other non-distutils module?
    1131 
    11321127
    11331128.. function:: convert_path(pathname)
    … …  
    11791174   and does what it can to deal with  exception objects that don't have a filename
    11801175   (which happens when the error  is due to a two-file operation, such as
    1181    :func:`rename` or  :func:`link`).  Returns the error message as a string
    1182    prefixed  with *prefix*.
     1176   :func:`~os.rename` or  :func:`~os.link`).  Returns the error message as a
     1177   string prefixed  with *prefix*.
    11831178
    11841179
    … …  
    12641259
    12651260
    1266 This module provides the :class:`Distribution` class, which represents the
    1267 module distribution being built/installed/distributed.
     1261This module provides the :class:`~distutils.core.Distribution` class, which
     1262represents the module distribution being built/installed/distributed.
    12681263
    12691264
    … …  
    13281323  the "negative alias" of :option:`--verbose`, then :option:`--quiet` on the
    13291324  command line sets *verbose* to false.
    1330 
    1331 **\*\*** Should be replaced with :mod:`optik` (which is also now known as
    1332 :mod:`optparse` in Python 2.3 and later). **\*\***
    13331325
    13341326
    … …  
    13481340   Wraps *text* to less than *width* wide.
    13491341
    1350    .. XXX Should be replaced with :mod:`textwrap` (which is available in Python
    1351       2.3 and later).
    13521342
    13531343
    … …  
    14111401.. module:: distutils.log
    14121402   :synopsis: A simple logging mechanism, 282-style
    1413 
    1414 
    1415 .. XXX Should be replaced with standard :mod:`logging` module.
    1416 
    14171403
    14181404
    … …  
    15771563
    15781564   The options are all boolean, and affect the values returned by :meth:`readline`
     1565
     1566   .. tabularcolumns:: |l|L|l|
    15791567
    15801568   +------------------+--------------------------------+---------+
    … …  
    16981686
    16991687.. module:: distutils.cmd
    1700    :synopsis: This module provides the abstract base class Command. This class is subclassed
    1701               by the modules in the distutils.command subpackage.
     1688   :synopsis: This module provides the abstract base class Command. This class
     1689              is subclassed by the modules in the distutils.command subpackage.
    17021690
    17031691
    … …  
    17091697   Abstract base class for defining command classes, the "worker bees" of the
    17101698   Distutils.  A useful analogy for command classes is to think of them as
    1711    subroutines with local variables called *options*.  The options are declared in
    1712    :meth:`initialize_options` and defined (given their final values) in
    1713    :meth:`finalize_options`, both of which must be defined by every command class.
    1714    The distinction between the two is necessary because option values might come
    1715    from the outside world (command line, config file, ...), and any options
    1716    dependent on other options must be computed after these outside influences have
    1717    been processed --- hence :meth:`finalize_options`.  The body of the subroutine,
    1718    where it does all its work based on the values of its options, is the
    1719    :meth:`run` method, which must also be implemented by every command class.
    1720 
    1721    The class constructor takes a single argument *dist*, a  :class:`Distribution`
    1722    instance.
    1723 
    1724 
    1725 :mod:`distutils.command` --- Individual Distutils commands
    1726 ==========================================================
    1727 
    1728 .. module:: distutils.command
    1729    :synopsis: This subpackage contains one module for each standard Distutils command.
    1730 
    1731 
    1732 .. % \subsubsection{Individual Distutils commands}
    1733 .. % todo
    1734 
    1735 
    1736 :mod:`distutils.command.bdist` --- Build a binary installer
    1737 ===========================================================
    1738 
    1739 .. module:: distutils.command.bdist
    1740    :synopsis: Build a binary installer for a package
    1741 
    1742 
    1743 .. % todo
    1744 
    1745 
    1746 :mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
    1747 =============================================================================
    1748 
    1749 .. module:: distutils.command.bdist_packager
    1750    :synopsis: Abstract base class for packagers
    1751 
    1752 
    1753 .. % todo
    1754 
    1755 
    1756 :mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
    1757 ================================================================
    1758 
    1759 .. module:: distutils.command.bdist_dumb
    1760    :synopsis: Build a "dumb" installer - a simple archive of files
    1761 
    1762 
    1763 .. % todo
    1764 
    1765 
    1766 :mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
    1767 =================================================================================
    1768 
    1769 .. module:: distutils.command.bdist_msi
    1770    :synopsis: Build a binary distribution as a Windows MSI file
    1771 
    1772 .. class:: bdist_msi(Command)
    1773 
    1774    Builds a `Windows Installer`_ (.msi) binary package.
    1775 
    1776    .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
    1777 
    1778    In most cases, the ``bdist_msi`` installer is a better choice than the
    1779    ``bdist_wininst`` installer, because it provides better support for
    1780    Win64 platforms, allows administrators to perform non-interactive
    1781    installations, and allows installation through group policies.
    1782 
    1783 
    1784 :mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
    1785 ===========================================================================================
    1786 
    1787 .. module:: distutils.command.bdist_rpm
    1788    :synopsis: Build a binary distribution as a Redhat RPM and SRPM
    1789 
    1790 
    1791 .. % todo
    1792 
    1793 
    1794 :mod:`distutils.command.bdist_wininst` --- Build a Windows installer
    1795 ====================================================================
    1796 
    1797 .. module:: distutils.command.bdist_wininst
    1798    :synopsis: Build a Windows installer
    1799 
    1800 
    1801 .. % todo
    1802 
    1803 
    1804 :mod:`distutils.command.sdist` --- Build a source distribution
    1805 ==============================================================
    1806 
    1807 .. module:: distutils.command.sdist
    1808    :synopsis: Build a source distribution
    1809 
    1810 
    1811 .. % todo
    1812 
    1813 
    1814 :mod:`distutils.command.build` --- Build all files of a package
    1815 ===============================================================
    1816 
    1817 .. module:: distutils.command.build
    1818    :synopsis: Build all files of a package
    1819 
    1820 
    1821 .. % todo
    1822 
    1823 
    1824 :mod:`distutils.command.build_clib` --- Build any C libraries in a package
    1825 ==========================================================================
    1826 
    1827 .. module:: distutils.command.build_clib
    1828    :synopsis: Build any C libraries in a package
    1829 
    1830 
    1831 .. % todo
    1832 
    1833 
    1834 :mod:`distutils.command.build_ext` --- Build any extensions in a package
    1835 ========================================================================
    1836 
    1837 .. module:: distutils.command.build_ext
    1838    :synopsis: Build any extensions in a package
    1839 
    1840 
    1841 .. % todo
    1842 
    1843 
    1844 :mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
    1845 ===========================================================================
    1846 
    1847 .. module:: distutils.command.build_py
    1848    :synopsis: Build the .py/.pyc files of a package
    1849 
    1850 
    1851 .. % todo
    1852 
    1853 
    1854 :mod:`distutils.command.build_scripts` --- Build the scripts of a package
    1855 =========================================================================
    1856 
    1857 .. module:: distutils.command.build_scripts
    1858    :synopsis: Build the scripts of a package
    1859 
    1860 
    1861 .. % todo
    1862 
    1863 
    1864 :mod:`distutils.command.clean` --- Clean a package build area
    1865 =============================================================
    1866 
    1867 .. module:: distutils.command.clean
    1868    :synopsis: Clean a package build area
    1869 
    1870 
    1871 .. % todo
    1872 
    1873 
    1874 :mod:`distutils.command.config` --- Perform package configuration
    1875 =================================================================
    1876 
    1877 .. module:: distutils.command.config
    1878    :synopsis: Perform package configuration
    1879 
    1880 
    1881 .. % todo
    1882 
    1883 
    1884 :mod:`distutils.command.install` --- Install a package
    1885 ======================================================
    1886 
    1887 .. module:: distutils.command.install
    1888    :synopsis: Install a package
    1889 
    1890 
    1891 .. % todo
    1892 
    1893 
    1894 :mod:`distutils.command.install_data` --- Install data files from a package
    1895 ===========================================================================
    1896 
    1897 .. module:: distutils.command.install_data
    1898    :synopsis: Install data files from a package
    1899 
    1900 
    1901 .. % todo
    1902 
    1903 
    1904 :mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
    1905 ======================================================================================
    1906 
    1907 .. module:: distutils.command.install_headers
    1908    :synopsis: Install C/C++ header files from a package
    1909 
    1910 
    1911 .. % todo
    1912 
    1913 
    1914 :mod:`distutils.command.install_lib` --- Install library files from a package
    1915 =============================================================================
    1916 
    1917 .. module:: distutils.command.install_lib
    1918    :synopsis: Install library files from a package
    1919 
    1920 
    1921 .. % todo
    1922 
    1923 
    1924 :mod:`distutils.command.install_scripts` --- Install script files from a package
    1925 ================================================================================
    1926 
    1927 .. module:: distutils.command.install_scripts
    1928    :synopsis: Install script files from a package
    1929 
    1930 
    1931 .. % todo
    1932 
    1933 
    1934 :mod:`distutils.command.register` --- Register a module with the Python Package Index
    1935 =====================================================================================
    1936 
    1937 .. module:: distutils.command.register
    1938    :synopsis: Register a module with the Python Package Index
    1939 
    1940 
    1941 The ``register`` command registers the package with the Python Package  Index.
    1942 This is described in more detail in :pep:`301`.
    1943 
    1944 .. % todo
     1699   subroutines with local variables called *options*.  The options are declared
     1700   in :meth:`initialize_options` and defined (given their final values) in
     1701   :meth:`finalize_options`, both of which must be defined by every command
     1702   class.  The distinction between the two is necessary because option values
     1703   might come from the outside world (command line, config file, ...), and any
     1704   options dependent on other options must be computed after these outside
     1705   influences have been processed --- hence :meth:`finalize_options`.  The body
     1706   of the subroutine, where it does all its work based on the values of its
     1707   options, is the :meth:`run` method, which must also be implemented by every
     1708   command class.
     1709
     1710   The class constructor takes a single argument *dist*, a
     1711   :class:`~distutils.core.Distribution` instance.
    19451712
    19461713
    … …  
    19511718
    19521719A new command lives in a module in the :mod:`distutils.command` package. There
    1953 is a sample template in that directory called  :file:`command_template`. Copy
     1720is a sample template in that directory called :file:`command_template`. Copy
    19541721this file to a new module with the same name as the new command you're
    1955 implementing. This module should implement a class with the same name as the
    1956 module (and the command). So, for instance, to create the command
     1722implementing.  This module should implement a class with the same name as the
     1723module (and the command).  So, for instance, to create the command
    19571724``peel_banana`` (so that users can run ``setup.py peel_banana``), you'd copy
    1958 :file:`command_template`  to :file:`distutils/command/peel_banana.py`, then edit
     1725:file:`command_template` to :file:`distutils/command/peel_banana.py`, then edit
    19591726it so that it's implementing the class :class:`peel_banana`, a subclass of
    19601727:class:`distutils.cmd.Command`.
    19611728
    19621729Subclasses of :class:`Command` must define the following methods.
    1963 
    19641730
    19651731.. method:: Command.initialize_options()
    … …  
    19771743   always called as late as possible, ie.  after any option assignments from the
    19781744   command-line or from other commands have been done.  Thus, this is the place
    1979    to to code option dependencies: if *foo* depends on *bar*, then it is safe to
     1745   to code option dependencies: if *foo* depends on *bar*, then it is safe to
    19801746   set *foo* from *bar* as long as *foo* still has the same value it was
    19811747   assigned in :meth:`initialize_options`.
    … …  
    19901756   be done by :meth:`run`.
    19911757
    1992 *sub_commands* formalizes the notion of a "family" of commands, eg. ``install``
    1993 as the parent with sub-commands ``install_lib``, ``install_headers``, etc.  The
    1994 parent of a family of commands defines *sub_commands* as a class attribute; it's
    1995 a list of 2-tuples ``(command_name, predicate)``, with *command_name* a string
    1996 and *predicate* an unbound method, a string or None. *predicate* is a method of
    1997 the parent command that determines whether the corresponding command is
    1998 applicable in the current situation.  (Eg. we ``install_headers`` is only
    1999 applicable if we have any C header files to install.)  If *predicate* is None,
    2000 that command is always applicable.
    2001 
    2002 *sub_commands* is usually defined at the \*end\* of a class, because predicates
    2003 can be unbound methods, so they must already have been defined.  The canonical
    2004 example is the :command:`install` command.
     1758
     1759.. attribute:: Command.sub_commands
     1760
     1761   *sub_commands* formalizes the notion of a "family" of commands,
     1762   e.g. ``install`` as the parent with sub-commands ``install_lib``,
     1763   ``install_headers``, etc.  The parent of a family of commands defines
     1764   *sub_commands* as a class attribute; it's a list of 2-tuples ``(command_name,
     1765   predicate)``, with *command_name* a string and *predicate* a function, a
     1766   string or ``None``.  *predicate* is a method of the parent command that
     1767   determines whether the corresponding command is applicable in the current
     1768   situation.  (E.g. ``install_headers`` is only applicable if we have any C
     1769   header files to install.)  If *predicate* is ``None``, that command is always
     1770   applicable.
     1771
     1772   *sub_commands* is usually defined at the *end* of a class, because
     1773   predicates can be methods of the class, so they must already have been
     1774   defined.  The canonical example is the :command:`install` command.
     1775
     1776
     1777:mod:`distutils.command` --- Individual Distutils commands
     1778==========================================================
     1779
     1780.. module:: distutils.command
     1781   :synopsis: This subpackage contains one module for each standard Distutils command.
     1782
     1783
     1784.. % \subsubsection{Individual Distutils commands}
     1785.. % todo
     1786
     1787
     1788:mod:`distutils.command.bdist` --- Build a binary installer
     1789===========================================================
     1790
     1791.. module:: distutils.command.bdist
     1792   :synopsis: Build a binary installer for a package
     1793
     1794
     1795.. % todo
     1796
     1797
     1798:mod:`distutils.command.bdist_packager` --- Abstract base class for packagers
     1799=============================================================================
     1800
     1801.. module:: distutils.command.bdist_packager
     1802   :synopsis: Abstract base class for packagers
     1803
     1804
     1805.. % todo
     1806
     1807
     1808:mod:`distutils.command.bdist_dumb` --- Build a "dumb" installer
     1809================================================================
     1810
     1811.. module:: distutils.command.bdist_dumb
     1812   :synopsis: Build a "dumb" installer - a simple archive of files
     1813
     1814
     1815.. % todo
     1816
     1817
     1818:mod:`distutils.command.bdist_msi` --- Build a Microsoft Installer binary package
     1819=================================================================================
     1820
     1821.. module:: distutils.command.bdist_msi
     1822   :synopsis: Build a binary distribution as a Windows MSI file
     1823
     1824.. class:: bdist_msi
     1825
     1826   Builds a `Windows Installer`_ (.msi) binary package.
     1827
     1828   .. _Windows Installer: http://msdn.microsoft.com/en-us/library/cc185688(VS.85).aspx
     1829
     1830   In most cases, the ``bdist_msi`` installer is a better choice than the
     1831   ``bdist_wininst`` installer, because it provides better support for
     1832   Win64 platforms, allows administrators to perform non-interactive
     1833   installations, and allows installation through group policies.
     1834
     1835
     1836:mod:`distutils.command.bdist_rpm` --- Build a binary distribution as a Redhat RPM and SRPM
     1837===========================================================================================
     1838
     1839.. module:: distutils.command.bdist_rpm
     1840   :synopsis: Build a binary distribution as a Redhat RPM and SRPM
     1841
     1842
     1843.. % todo
     1844
     1845
     1846:mod:`distutils.command.bdist_wininst` --- Build a Windows installer
     1847====================================================================
     1848
     1849.. module:: distutils.command.bdist_wininst
     1850   :synopsis: Build a Windows installer
     1851
     1852
     1853.. % todo
     1854
     1855
     1856:mod:`distutils.command.sdist` --- Build a source distribution
     1857==============================================================
     1858
     1859.. module:: distutils.command.sdist
     1860   :synopsis: Build a source distribution
     1861
     1862
     1863.. % todo
     1864
     1865
     1866:mod:`distutils.command.build` --- Build all files of a package
     1867===============================================================
     1868
     1869.. module:: distutils.command.build
     1870   :synopsis: Build all files of a package
     1871
     1872
     1873.. % todo
     1874
     1875
     1876:mod:`distutils.command.build_clib` --- Build any C libraries in a package
     1877==========================================================================
     1878
     1879.. module:: distutils.command.build_clib
     1880   :synopsis: Build any C libraries in a package
     1881
     1882
     1883.. % todo
     1884
     1885
     1886:mod:`distutils.command.build_ext` --- Build any extensions in a package
     1887========================================================================
     1888
     1889.. module:: distutils.command.build_ext
     1890   :synopsis: Build any extensions in a package
     1891
     1892
     1893.. % todo
     1894
     1895
     1896:mod:`distutils.command.build_py` --- Build the .py/.pyc files of a package
     1897===========================================================================
     1898
     1899.. module:: distutils.command.build_py
     1900   :synopsis: Build the .py/.pyc files of a package
     1901
     1902
     1903:mod:`distutils.command.build_scripts` --- Build the scripts of a package
     1904=========================================================================
     1905
     1906.. module:: distutils.command.build_scripts
     1907   :synopsis: Build the scripts of a package
     1908
     1909
     1910.. % todo
     1911
     1912
     1913:mod:`distutils.command.clean` --- Clean a package build area
     1914=============================================================
     1915
     1916.. module:: distutils.command.clean
     1917   :synopsis: Clean a package build area
     1918
     1919
     1920.. % todo
     1921
     1922
     1923:mod:`distutils.command.config` --- Perform package configuration
     1924=================================================================
     1925
     1926.. module:: distutils.command.config
     1927   :synopsis: Perform package configuration
     1928
     1929
     1930.. % todo
     1931
     1932
     1933:mod:`distutils.command.install` --- Install a package
     1934======================================================
     1935
     1936.. module:: distutils.command.install
     1937   :synopsis: Install a package
     1938
     1939
     1940.. % todo
     1941
     1942
     1943:mod:`distutils.command.install_data` --- Install data files from a package
     1944===========================================================================
     1945
     1946.. module:: distutils.command.install_data
     1947   :synopsis: Install data files from a package
     1948
     1949
     1950.. % todo
     1951
     1952
     1953:mod:`distutils.command.install_headers` --- Install C/C++ header files from a package
     1954======================================================================================
     1955
     1956.. module:: distutils.command.install_headers
     1957   :synopsis: Install C/C++ header files from a package
     1958
     1959
     1960.. % todo
     1961
     1962
     1963:mod:`distutils.command.install_lib` --- Install library files from a package
     1964=============================================================================
     1965
     1966.. module:: distutils.command.install_lib
     1967   :synopsis: Install library files from a package
     1968
     1969
     1970.. % todo
     1971
     1972
     1973:mod:`distutils.command.install_scripts` --- Install script files from a package
     1974================================================================================
     1975
     1976.. module:: distutils.command.install_scripts
     1977   :synopsis: Install script files from a package
     1978
     1979
     1980.. % todo
     1981
     1982
     1983:mod:`distutils.command.register` --- Register a module with the Python Package Index
     1984=====================================================================================
     1985
     1986.. module:: distutils.command.register
     1987   :synopsis: Register a module with the Python Package Index
     1988
     1989
     1990The ``register`` command registers the package with the Python Package  Index.
     1991This is described in more detail in :pep:`301`.
     1992
     1993.. % todo
     1994
     1995
     1996:mod:`distutils.command.check` --- Check the meta-data of a package
     1997===================================================================
     1998
     1999.. module:: distutils.command.check
     2000   :synopsis: Check the metadata of a package
     2001
     2002
     2003The ``check`` command performs some tests on the meta-data of a package.
     2004For example, it verifies that all required meta-data are provided as
     2005the arguments passed to the :func:`setup` function.
     2006
     2007.. % todo

  • python/vendor/current/Doc/distutils/builtdist.rst

    r2 r388  
    8181| ``tar``     | tar file (:file:`.tar`)      | \(3)    |
    8282+-------------+------------------------------+---------+
    83 | ``zip``     | zip file (:file:`.zip`)      | \(4)    |
     83| ``zip``     | zip file (:file:`.zip`)      | (2),(4) |
    8484+-------------+------------------------------+---------+
    8585| ``rpm``     | RPM                          | \(5)    |
    … …  
    8989| ``sdux``    | HP-UX :program:`swinstall`   |         |
    9090+-------------+------------------------------+---------+
    91 | ``rpm``     | RPM                          | \(5)    |
    92 +-------------+------------------------------+---------+
    93 | ``wininst`` | self-extracting ZIP file for | (2),(4) |
     91| ``wininst`` | self-extracting ZIP file for | \(4)    |
    9492|             | Windows                      |         |
    9593+-------------+------------------------------+---------+
     94| ``msi``     | Microsoft Installer.         |         |
     95+-------------+------------------------------+---------+
     96
    9697
    9798Notes:
    … …  
    102103(2)
    103104   default on Windows
    104 
    105    **\*\*** to-do! **\*\***
    106105
    107106(3)
    … …  
    134133| :command:`bdist_wininst` | wininst               |
    135134+--------------------------+-----------------------+
     135| :command:`bdist_msi`     | msi                   |
     136+--------------------------+-----------------------+
    136137
    137138The following sections give details on the individual :command:`bdist_\*`
    … …  
    144145=================================
    145146
    146 **\*\*** Need to document absolute vs. prefix-relative packages here, but first
    147 I have to implement it! **\*\***
     147.. XXX Need to document absolute vs. prefix-relative packages here, but first
     148       I have to implement it!
    148149
    149150
    … …  
    174175
    175176   python setup.py bdist_rpm --packager="John Doe <jdoe@example.org>" \
    176                    bdist_wininst --target_version="2.0"
     177                   bdist_wininst --target-version="2.0"
    177178
    178179Creating RPM packages is driven by a :file:`.spec` file, much as using the
    … …  
    239240you distribute or package many Python module distributions, you might want to
    240241put options that apply to all of them in your personal Distutils configuration
    241 file (:file:`~/.pydistutils.cfg`).
     242file (:file:`~/.pydistutils.cfg`).  If you want to temporarily disable
     243this file, you can pass the --no-user-cfg option to setup.py.
    242244
    243245There are three steps to building a binary RPM package, all of which are
    … …  
    319321
    320322By default the installer will display the cool "Python Powered" logo when it is
    321 run, but you can also supply your own bitmap which must be a Windows
     323run, but you can also supply your own 152x261 bitmap which must be a Windows
    322324:file:`.bmp` file with the :option:`--bitmap` option.
    323325
    … …  
    355357To cross-compile, you must download the Python source code and cross-compile
    356358Python itself for the platform you are targetting - it is not possible from a
    357 binary installtion of Python (as the .lib etc file for other platforms are
     359binary installation of Python (as the .lib etc file for other platforms are
    358360not included.)  In practice, this means the user of a 32 bit operating
    359361system will need to use Visual Studio 2008 to open the
    … …  
    372374---------------------------
    373375
    374 Starting with Python 2.3, a postinstallation script can be specified which the
     376Starting with Python 2.3, a postinstallation script can be specified with the
    375377:option:`--install-script` option.  The basename of the script must be
    376378specified, and the script filename must also be listed in the scripts argument
    … …  
    425427   Which folders are available depends on the exact Windows version, and probably
    426428   also the configuration.  For details refer to Microsoft's documentation of the
    427    :cfunc:`SHGetSpecialFolderPath` function.
     429   :c:func:`SHGetSpecialFolderPath` function.
    428430
    429431

  • python/vendor/current/Doc/distutils/commandref.rst

    r2 r388  
    4949
    5050
    51 .. _sdist-cmd:
    52 
    53 Creating a source distribution: the :command:`sdist` command
    54 ============================================================
    55 
    56 **\*\*** fragment moved down from above: needs context! **\*\***
    57 
    58 The manifest template commands are:
    59 
    60 +-------------------------------------------+-----------------------------------------------+
    61 | Command                                   | Description                                   |
    62 +===========================================+===============================================+
    63 | :command:`include pat1 pat2 ...`          | include all files matching any of the listed  |
    64 |                                           | patterns                                      |
    65 +-------------------------------------------+-----------------------------------------------+
    66 | :command:`exclude pat1 pat2 ...`          | exclude all files matching any of the listed  |
    67 |                                           | patterns                                      |
    68 +-------------------------------------------+-----------------------------------------------+
    69 | :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
    70 | ...`                                      | the listed patterns                           |
    71 +-------------------------------------------+-----------------------------------------------+
    72 | :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
    73 | ...`                                      | the listed patterns                           |
    74 +-------------------------------------------+-----------------------------------------------+
    75 | :command:`global-include pat1 pat2 ...`   | include all files anywhere in the source tree |
    76 |                                           | matching --- & any of the listed patterns     |
    77 +-------------------------------------------+-----------------------------------------------+
    78 | :command:`global-exclude pat1 pat2 ...`   | exclude all files anywhere in the source tree |
    79 |                                           | matching --- & any of the listed patterns     |
    80 +-------------------------------------------+-----------------------------------------------+
    81 | :command:`prune dir`                      | exclude all files under *dir*                 |
    82 +-------------------------------------------+-----------------------------------------------+
    83 | :command:`graft dir`                      | include all files under *dir*                 |
    84 +-------------------------------------------+-----------------------------------------------+
    85 
    86 The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
    87 regular filename characters, ``?`` matches any single regular filename
    88 character, and ``[range]`` matches any of the characters in *range* (e.g.,
    89 ``a-z``, ``a-zA-Z``, ``a-f0-9_.``).  The definition of "regular filename
    90 character" is platform-specific: on Unix it is anything except slash; on Windows
    91 anything except backslash or colon.
    92 
    93 **\*\*** Windows support not there yet **\*\***
    94 
    9551.. % \section{Creating a built distribution: the
    9652.. % \protect\command{bdist} command family}

  • python/vendor/current/Doc/distutils/extending.rst

    r2 r388  
    1616convenience.
    1717
    18 Most distutils command implementations are subclasses of the :class:`Command`
    19 class from :mod:`distutils.cmd`.  New commands may directly inherit from
     18Most distutils command implementations are subclasses of the
     19:class:`distutils.cmd.Command` class.  New commands may directly inherit from
    2020:class:`Command`, while replacements often derive from :class:`Command`
    2121indirectly, directly subclassing the command they are replacing.  Commands are

  • python/vendor/current/Doc/distutils/index.rst

    r2 r388  
    77:Authors: Greg Ward, Anthony Baxter
    88:Email: distutils-sig@python.org
    9 :Release: |version|
    10 :Date: |today|
    119
    1210This document describes the Python Distribution Utilities ("Distutils") from
    … …  
    2523   builtdist.rst
    2624   packageindex.rst
    27    uploading.rst
    2825   examples.rst
    2926   extending.rst

  • python/vendor/current/Doc/distutils/introduction.rst

    r2 r388  
    8080
    8181To create a source distribution for this module, you would create a setup
    82 script, :file:`setup.py`, containing the above code, and run::
     82script, :file:`setup.py`, containing the above code, and run this command from a
     83terminal::
    8384
    8485   python setup.py sdist
    8586
    86 which will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
     87For Windows, open a command prompt windows (:menuselection:`Start -->
     88Accessories`) and change the command to::
     89
     90   setup.py sdist
     91
     92:command:`sdist` will create an archive file (e.g., tarball on Unix, ZIP file on Windows)
    8793containing your setup script :file:`setup.py`, and your module :file:`foo.py`.
    8894The archive file will be named :file:`foo-1.0.tar.gz` (or :file:`.zip`), and

  • python/vendor/current/Doc/distutils/packageindex.rst

    r2 r388  
     1.. index::
     2   single: Python Package Index (PyPI)
     3   single: PyPI; (see Python Package Index (PyPI))
     4
    15.. _package-index:
    26
    3 **********************************
    4 Registering with the Package Index
    5 **********************************
    6 
    7 The Python Package Index (PyPI) holds meta-data describing distributions
    8 packaged with distutils. The distutils command :command:`register` is used to
    9 submit your distribution's meta-data to the index. It is invoked as follows::
    10 
    11    python setup.py register
     7*******************************
     8The Python Package Index (PyPI)
     9*******************************
     10
     11The `Python Package Index (PyPI)`_ holds :ref:`meta-data <meta-data>`
     12describing distributions packaged with distutils, as well as package data like
     13distribution files if the package author wishes.
     14
     15Distutils exposes two commands for submitting package data to PyPI: the
     16:ref:`register <package-register>` command for submitting meta-data to PyPI
     17and the :ref:`upload <package-upload>` command for submitting distribution
     18files.  Both commands read configuration data from a special file called the
     19:ref:`.pypirc file <pypirc>`.  PyPI :ref:`displays a home page
     20<package-display>` for each package created from the ``long_description``
     21submitted by the :command:`register` command.
     22
     23
     24.. _package-register:
     25
     26Registering Packages
     27====================
     28
     29The distutils command :command:`register` is used to submit your distribution's
     30meta-data to the index. It is invoked as follows::
     31
     32    python setup.py register
    1233
    1334Distutils will respond with the following prompt::
    1435
    15    running register
    16    We need to know who you are, so please choose either:
    17     1. use your existing login,
    18     2. register as a new user,
    19     3. have the server generate a new password for you (and email it to you), or
    20     4. quit
    21    Your selection [default 1]:
     36    running register
     37    We need to know who you are, so please choose either:
     38        1. use your existing login,
     39        2. register as a new user,
     40        3. have the server generate a new password for you (and email it to you), or
     41        4. quit
     42    Your selection [default 1]:
    2243
    2344Note: if your username and password are saved locally, you will not see this
    … …  
    4465Maintainers.
    4566
    46 By default PyPI will list all versions of a given package. To hide certain
    47 versions, the Hidden property should be set to yes. This must be edited through
    48 the web interface.
    49 
     67By default PyPI displays only the newest version of a given package. The web
     68interface lets one change this default behavior and manually select which
     69versions to display and hide.
     70
     71
     72.. _package-upload:
     73
     74Uploading Packages
     75==================
     76
     77.. versionadded:: 2.5
     78
     79The distutils command :command:`upload` pushes the distribution files to PyPI.
     80
     81The command is invoked immediately after building one or more distribution
     82files.  For example, the command ::
     83
     84    python setup.py sdist bdist_wininst upload
     85
     86will cause the source distribution and the Windows installer to be uploaded to
     87PyPI.  Note that these will be uploaded even if they are built using an earlier
     88invocation of :file:`setup.py`, but that only distributions named on the command
     89line for the invocation including the :command:`upload` command are uploaded.
     90
     91The :command:`upload` command uses the username, password, and repository URL
     92from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this
     93file). If a :command:`register` command was previously called in the same command,
     94and if the password was entered in the prompt, :command:`upload` will reuse the
     95entered password. This is useful if you do not want to store a clear text
     96password in the :file:`$HOME/.pypirc` file.
     97
     98You can specify another PyPI server with the ``--repository=url`` option::
     99
     100    python setup.py sdist bdist_wininst upload -r http://example.com/pypi
     101
     102See section :ref:`pypirc` for more on defining several servers.
     103
     104You can use the ``--sign`` option to tell :command:`upload` to sign each
     105uploaded file using GPG (GNU Privacy Guard).  The  :program:`gpg` program must
     106be available for execution on the system :envvar:`PATH`.  You can also specify
     107which key to use for signing using the ``--identity=name`` option.
     108
     109Other :command:`upload` options include ``--repository=url`` or
     110``--repository=section`` where *url* is the url of the server and
     111*section* the name of the section in :file:`$HOME/.pypirc`, and
     112``--show-response`` (which displays the full response text from the PyPI
     113server for help in debugging upload problems).
     114
     115
     116.. index::
     117   single: .pypirc file
     118   single: Python Package Index (PyPI); .pypirc file
    50119
    51120.. _pypirc:
    … …  
    56125The format of the :file:`.pypirc` file is as follows::
    57126
    58    [distutils]
    59    index-servers =
    60      pypi
    61 
    62    [pypi]
    63    repository: <repository-url>
    64    username: <username>
    65    password: <password>
    66 
    67 *repository* can be omitted and defaults to ``http://www.python.org/pypi``.
    68 
    69 If you want to define another server a new section can be created::
    70 
    71    [distutils]
    72    index-servers =
    73      pypi
    74      other
    75 
    76    [pypi]
    77    repository: <repository-url>
    78    username: <username>
    79    password: <password>
    80 
    81    [other]
    82    repository: http://example.com/pypi
    83    username: <username>
    84    password: <password>
    85 
    86 The command can then be called with the -r option::
    87 
    88    python setup.py register -r http://example.com/pypi
    89 
    90 Or even with the section name::
    91 
    92    python setup.py register -r other
    93 
     127    [distutils]
     128    index-servers =
     129        pypi
     130
     131    [pypi]
     132    repository: <repository-url>
     133    username: <username>
     134    password: <password>
     135
     136The *distutils* section defines a *index-servers* variable that lists the
     137name of all sections describing a repository.
     138
     139Each section describing a repository defines three variables:
     140
     141- *repository*, that defines the url of the PyPI server. Defaults to
     142    ``http://www.python.org/pypi``.
     143- *username*, which is the registered username on the PyPI server.
     144- *password*, that will be used to authenticate. If omitted the user
     145    will be prompt to type it when needed.
     146
     147If you want to define another server a new section can be created and
     148listed in the *index-servers* variable::
     149
     150    [distutils]
     151    index-servers =
     152        pypi
     153        other
     154
     155    [pypi]
     156    repository: <repository-url>
     157    username: <username>
     158    password: <password>
     159
     160    [other]
     161    repository: http://example.com/pypi
     162    username: <username>
     163    password: <password>
     164
     165:command:`register` can then be called with the -r option to point the
     166repository to work with::
     167
     168    python setup.py register -r http://example.com/pypi
     169
     170For convenience, the name of the section that describes the repository
     171may also be used::
     172
     173    python setup.py register -r other
     174
     175
     176.. _package-display:
     177
     178PyPI package display
     179====================
     180
     181The ``long_description`` field plays a special role at PyPI. It is used by
     182the server to display a home page for the registered package.
     183
     184If you use the `reStructuredText <http://docutils.sourceforge.net/rst.html>`_
     185syntax for this field, PyPI will parse it and display an HTML output for
     186the package home page.
     187
     188The ``long_description`` field can be attached to a text file located
     189in the package::
     190
     191    from distutils.core import setup
     192
     193    with open('README.txt') as file:
     194        long_description = file.read()
     195
     196    setup(name='Distutils',
     197          long_description=long_description)
     198
     199In that case, :file:`README.txt` is a regular reStructuredText text file located
     200in the root of the package besides :file:`setup.py`.
     201
     202To prevent registering broken reStructuredText content, you can use the
     203:program:`rst2html` program that is provided by the :mod:`docutils` package and
     204check the ``long_description`` from the command line::
     205
     206    $ python setup.py --long-description | rst2html.py > output.html
     207
     208:mod:`docutils` will display a warning if there's something wrong with your
     209syntax.  Because PyPI applies additional checks (e.g. by passing ``--no-raw``
     210to ``rst2html.py`` in the command above), being able to run the command above
     211without warnings does not guarantee that PyPI will convert the content
     212successfully.
     213
     214
     215.. _Python Package Index (PyPI): http://pypi.python.org/

  • python/vendor/current/Doc/distutils/setupscript.rst

    r2 r388  
    2020the package into Python 1.5.2.) ::
    2121
    22    #!/usr/bin/env python
    23 
    24    from distutils.core import setup
    25 
    26    setup(name='Distutils',
    27          version='1.0',
    28          description='Python Distribution Utilities',
    29          author='Greg Ward',
    30          author_email='gward@python.net',
    31          url='http://www.python.org/sigs/distutils-sig/',
    32          packages=['distutils', 'distutils.command'],
    33         )
     22    #!/usr/bin/env python
     23
     24    from distutils.core import setup
     25
     26    setup(name='Distutils',
     27          version='1.0',
     28          description='Python Distribution Utilities',
     29          author='Greg Ward',
     30          author_email='gward@python.net',
     31          url='http://www.python.org/sigs/distutils-sig/',
     32          packages=['distutils', 'distutils.command'],
     33         )
    3434
    3535There are only two differences between this and the trivial one-file
    … …  
    5454code instead of hardcoding path separators::
    5555
    56    glob.glob(os.path.join('mydir', 'subdir', '*.html'))
    57    os.listdir(os.path.join('mydir', 'subdir'))
     56    glob.glob(os.path.join('mydir', 'subdir', '*.html'))
     57    os.listdir(os.path.join('mydir', 'subdir'))
    5858
    5959
    … …  
    7373might be spelled differently on your system, but you get the idea) relative to
    7474the directory where your setup script lives.  If you break this promise, the
    75 Distutils will issue a warning but still process the broken package anyways.
     75Distutils will issue a warning but still process the broken package anyway.
    7676
    7777If you use a different convention to lay out your source directory, that's no
    … …  
    8282:file:`lib/foo`, and so forth.  Then you would put ::
    8383
    84    package_dir = {'': 'lib'}
     84    package_dir = {'': 'lib'}
    8585
    8686in your setup script.  The keys to this dictionary are package names, and an
    … …  
    9393written in the setup script as ::
    9494
    95    package_dir = {'foo': 'lib'}
     95    package_dir = {'foo': 'lib'}
    9696
    9797A ``package: dir`` entry in the :option:`package_dir` dictionary implicitly
    … …  
    115115section :ref:`distutils-simple-example`; here is a slightly more involved example::
    116116
    117    py_modules = ['mod1', 'pkg.mod2']
     117    py_modules = ['mod1', 'pkg.mod2']
    118118
    119119This describes two modules, one of them in the "root" package, the other in the
    … …  
    140140All of this is done through another keyword argument to :func:`setup`, the
    141141:option:`ext_modules` option.  :option:`ext_modules` is just a list of
    142 :class:`Extension` instances, each of which describes a single extension module.
     142:class:`~distutils.core.Extension` instances, each of which describes a
     143single extension module.
    143144Suppose your distribution includes a single extension, called :mod:`foo` and
    144145implemented by :file:`foo.c`.  If no additional instructions to the
    145146compiler/linker are needed, describing this extension is quite simple::
    146147
    147    Extension('foo', ['foo.c'])
     148    Extension('foo', ['foo.c'])
    148149
    149150The :class:`Extension` class can be imported from :mod:`distutils.core` along
    … …  
    151152contains only this one extension and nothing else might be::
    152153
    153    from distutils.core import setup, Extension
    154    setup(name='foo',
    155          version='1.0',
    156          ext_modules=[Extension('foo', ['foo.c'])],
    157          )
     154    from distutils.core import setup, Extension
     155    setup(name='foo',
     156          version='1.0',
     157          ext_modules=[Extension('foo', ['foo.c'])],
     158          )
    158159
    159160The :class:`Extension` class (actually, the underlying extension-building
    … …  
    166167----------------------------
    167168
    168 The first argument to the :class:`Extension` constructor is always the name of
    169 the extension, including any package names.  For example, ::
    170 
    171    Extension('foo', ['src/foo1.c', 'src/foo2.c'])
     169The first argument to the :class:`~distutils.core.Extension` constructor is
     170always the name of the extension, including any package names.  For example, ::
     171
     172    Extension('foo', ['src/foo1.c', 'src/foo2.c'])
    172173
    173174describes an extension that lives in the root package, while ::
    174175
    175    Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
     176    Extension('pkg.foo', ['src/foo1.c', 'src/foo2.c'])
    176177
    177178describes the same extension in the :mod:`pkg` package.  The source files and
    … …  
    184185:func:`setup`.  For example, ::
    185186
    186    setup(...,
    187          ext_package='pkg',
    188          ext_modules=[Extension('foo', ['foo.c']),
    189                       Extension('subpkg.bar', ['bar.c'])],
    190         )
     187    setup(...,
     188          ext_package='pkg',
     189          ext_modules=[Extension('foo', ['foo.c']),
     190                       Extension('subpkg.bar', ['bar.c'])],
     191         )
    191192
    192193will compile :file:`foo.c` to the extension :mod:`pkg.foo`, and :file:`bar.c` to
    … …  
    197198----------------------
    198199
    199 The second argument to the :class:`Extension` constructor is a list of source
     200The second argument to the :class:`~distutils.core.Extension` constructor is
     201a list of source
    200202files.  Since the Distutils currently only support C, C++, and Objective-C
    201203extensions, these are normally C/C++/Objective-C source files.  (Be sure to use
    … …  
    208210extension.
    209211
    210 **\*\*** SWIG support is rough around the edges and largely untested! **\*\***
     212.. XXX SWIG support is rough around the edges and largely untested!
    211213
    212214This warning notwithstanding, options to SWIG can be currently passed like
    213215this::
    214216
    215    setup(...,
    216          ext_modules=[Extension('_foo', ['foo.i'],
    217                                 swig_opts=['-modern', '-I../include'])],
    218          py_modules=['foo'],
    219         )
     217    setup(...,
     218          ext_modules=[Extension('_foo', ['foo.i'],
     219                                 swig_opts=['-modern', '-I../include'])],
     220          py_modules=['foo'],
     221         )
    220222
    221223Or on the commandline like this::
    222224
    223    > python setup.py build_ext --swig-opts="-modern -I../include"
     225    > python setup.py build_ext --swig-opts="-modern -I../include"
    224226
    225227On some platforms, you can include non-source files that are processed by the
    … …  
    233235--------------------
    234236
    235 Three optional arguments to :class:`Extension` will help if you need to specify
    236 include directories to search or preprocessor macros to define/undefine:
    237 ``include_dirs``, ``define_macros``, and ``undef_macros``.
     237Three optional arguments to :class:`~distutils.core.Extension` will help if
     238you need to specify include directories to search or preprocessor macros to
     239define/undefine: ``include_dirs``, ``define_macros``, and ``undef_macros``.
    238240
    239241For example, if your extension requires header files in the :file:`include`
    240242directory under your distribution root, use the ``include_dirs`` option::
    241243
    242    Extension('foo', ['foo.c'], include_dirs=['include'])
     244    Extension('foo', ['foo.c'], include_dirs=['include'])
    243245
    244246You can specify absolute directories there; if you know that your extension will
    … …  
    246248away with ::
    247249
    248    Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
     250    Extension('foo', ['foo.c'], include_dirs=['/usr/include/X11'])
    249251
    250252You should avoid this sort of non-portable usage if you plan to distribute your
    251253code: it's probably better to write C code like  ::
    252254
    253    #include <X11/Xlib.h>
     255    #include <X11/Xlib.h>
    254256
    255257If you need to include header files from some other Python extension, you can
    256258take advantage of the fact that header files are installed in a consistent way
    257 by the Distutils :command:`install_header` command.  For example, the Numerical
     259by the Distutils :command:`install_headers` command.  For example, the Numerical
    258260Python header files are installed (on a standard Unix installation) to
    259261:file:`/usr/local/include/python1.5/Numerical`. (The exact location will differ
    … …  
    263265is to write C code like  ::
    264266
    265    #include <Numerical/arrayobject.h>
     267    #include <Numerical/arrayobject.h>
    266268
    267269If you must put the :file:`Numerical` include directory right into your header
    … …  
    269271:mod:`distutils.sysconfig` module::
    270272
    271    from distutils.sysconfig import get_python_inc
    272    incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
    273    setup(...,
    274          Extension(..., include_dirs=[incdir]),
    275          )
     273    from distutils.sysconfig import get_python_inc
     274    incdir = os.path.join(get_python_inc(plat_specific=1), 'Numerical')
     275    setup(...,
     276          Extension(..., include_dirs=[incdir]),
     277          )
    276278
    277279Even though this is quite portable---it will work on any Python installation,
    … …  
    289291For example::
    290292
    291    Extension(...,
    292              define_macros=[('NDEBUG', '1'),
    293                             ('HAVE_STRFTIME', None)],
    294              undef_macros=['HAVE_FOO', 'HAVE_BAR'])
     293    Extension(...,
     294              define_macros=[('NDEBUG', '1'),
     295                             ('HAVE_STRFTIME', None)],
     296              undef_macros=['HAVE_FOO', 'HAVE_BAR'])
    295297
    296298is the equivalent of having this at the top of every C source file::
    297299
    298    #define NDEBUG 1
    299    #define HAVE_STRFTIME
    300    #undef HAVE_FOO
    301    #undef HAVE_BAR
     300    #define NDEBUG 1
     301    #define HAVE_STRFTIME
     302    #undef HAVE_FOO
     303    #undef HAVE_BAR
    302304
    303305
    … …  
    314316library search path on target systems ::
    315317
    316    Extension(...,
    317              libraries=['gdbm', 'readline'])
     318    Extension(...,
     319              libraries=['gdbm', 'readline'])
    318320
    319321If you need to link with libraries in a non-standard location, you'll have to
    320322include the location in ``library_dirs``::
    321323
    322    Extension(...,
    323              library_dirs=['/usr/X11R6/lib'],
    324              libraries=['X11', 'Xt'])
     324    Extension(...,
     325              library_dirs=['/usr/X11R6/lib'],
     326              libraries=['X11', 'Xt'])
    325327
    326328(Again, this sort of non-portable construct should be avoided if you intend to
    327329distribute your code.)
    328330
    329 **\*\*** Should mention clib libraries here or somewhere else! **\*\***
     331.. XXX Should mention clib libraries here or somewhere else!
    330332
    331333
    … …  
    348350to the list of exported symbols.
    349351
     352The :option:`depends` option is a list of files that the extension depends on
     353(for example header files). The build command will call the compiler on the
     354sources to rebuild extension if any on this files has been modified since the
     355previous build.
    350356
    351357Relationships between Distributions and Packages
    … …  
    376382number.  The accepted comparison operators are::
    377383
    378    <    >    ==
    379    <=   >=   !=
     384    <    >    ==
     385    <=   >=   !=
    380386
    381387These can be combined by using multiple qualifiers separated by commas (and
    … …  
    424430named module or package are understood to be obsoleted.
    425431
     432.. _distutils-installing-scripts:
    426433
    427434Installing Scripts
    … …  
    442449way.  From the PyXML setup script::
    443450
    444    setup(...,
    445          scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
    446          )
    447 
     451    setup(...,
     452          scripts=['scripts/xmlproc_parse', 'scripts/xmlproc_val']
     453          )
     454
     455.. versionchanged:: 2.7
     456    All the scripts will also be added to the ``MANIFEST``
     457    file if no template is provided. See :ref:`manifest`.
     458
     459.. _distutils-installing-package-data:
    448460
    449461Installing Package Data
    … …  
    469481the files can be arranged like this in the source tree::
    470482
    471    setup.py
    472    src/
    473        mypkg/
    474            __init__.py
    475            module.py
    476            data/
    477                tables.dat
    478                spoons.dat
    479                forks.dat
     483    setup.py
     484    src/
     485        mypkg/
     486            __init__.py
     487            module.py
     488            data/
     489                tables.dat
     490                spoons.dat
     491                forks.dat
    480492
    481493The corresponding call to :func:`setup` might be::
    482494
    483    setup(...,
    484          packages=['mypkg'],
    485          package_dir={'mypkg': 'src/mypkg'},
    486          package_data={'mypkg': ['data/*.dat']},
    487          )
     495    setup(...,
     496          packages=['mypkg'],
     497          package_dir={'mypkg': 'src/mypkg'},
     498          package_data={'mypkg': ['data/*.dat']},
     499          )
    488500
    489501.. versionadded:: 2.4
    490502
     503.. versionchanged:: 2.7
     504    All the files that match ``package_data`` will be added to the ``MANIFEST``
     505    file if no template is provided. See :ref:`manifest`.
     506
     507
     508.. _distutils-additional-files:
    491509
    492510Installing Additional Files
    … …  
    500518following way::
    501519
    502    setup(...,
    503          data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
    504                      ('config', ['cfg/data.cfg']),
    505                      ('/etc/init.d', ['init-script'])]
    506         )
     520    setup(...,
     521          data_files=[('bitmaps', ['bm/b1.gif', 'bm/b2.gif']),
     522                      ('config', ['cfg/data.cfg']),
     523                      ('/etc/init.d', ['init-script'])]
     524         )
    507525
    508526Note that you can specify the directory names where the data files will be
    … …  
    524542directory.
    525543
     544.. versionchanged:: 2.7
     545    All the files that match ``data_files`` will be added to the ``MANIFEST``
     546    file if no template is provided. See :ref:`manifest`.
     547
     548
    526549
    527550.. _meta-data:
    … …  
    556579|                      | package                   |                 |        |
    557580+----------------------+---------------------------+-----------------+--------+
    558 | ``long_description`` | longer description of the | long string     |        |
     581| ``long_description`` | longer description of the | long string     | \(5)   |
    559582|                      | package                   |                 |        |
    560583+----------------------+---------------------------+-----------------+--------+
    … …  
    572595
    573596(1)
    574    These fields are required.
     597    These fields are required.
    575598
    576599(2)
    577    It is recommended that versions take the form *major.minor[.patch[.sub]]*.
     600    It is recommended that versions take the form *major.minor[.patch[.sub]]*.
    578601
    579602(3)
    580    Either the author or the maintainer must be identified.
     603    Either the author or the maintainer must be identified. If maintainer is
     604    provided, distutils lists it as the author in :file:`PKG-INFO`.
    581605
    582606(4)
    583    These fields should not be used if your package is to be compatible with Python
    584    versions prior to 2.2.3 or 2.3.  The list is available from the `PyPI website
    585    <http://pypi.python.org/pypi>`_.
     607    These fields should not be used if your package is to be compatible with Python
     608    versions prior to 2.2.3 or 2.3.  The list is available from the `PyPI website
     609    <http://pypi.python.org/pypi>`_.
     610
     611(5)
     612    The ``long_description`` field is used by PyPI when you are
     613    :ref:`registering <package-register>` a package, to
     614    :ref:`build its home page <package-display>`.
    586615
    587616(6)
    … …  
    593622
    594623'short string'
    595    A single line of text, not more than 200 characters.
     624    A single line of text, not more than 200 characters.
    596625
    597626'long string'
    598    Multiple lines of plain text in reStructuredText format (see
    599    http://docutils.sf.net/).
     627    Multiple lines of plain text in reStructuredText format (see
     628    http://docutils.sf.net/).
    600629
    601630'list of strings'
    602    See below.
     631    See below.
    603632
    604633None of the string values may be Unicode.
    … …  
    616645
    6176460.1.0
    618    the first, experimental release of a package
     647    the first, experimental release of a package
    619648
    6206491.0.1a2
    621    the second alpha release of the first patch version of 1.0
     650    the second alpha release of the first patch version of 1.0
    622651
    623652:option:`classifiers` are specified in a Python list::
    624653
    625    setup(...,
    626          classifiers=[
    627              'Development Status :: 4 - Beta',
    628              'Environment :: Console',
    629              'Environment :: Web Environment',
    630              'Intended Audience :: End Users/Desktop',
    631              'Intended Audience :: Developers',
    632              'Intended Audience :: System Administrators',
    633              'License :: OSI Approved :: Python Software Foundation License',
    634              'Operating System :: MacOS :: MacOS X',
    635              'Operating System :: Microsoft :: Windows',
    636              'Operating System :: POSIX',
    637              'Programming Language :: Python',
    638              'Topic :: Communications :: Email',
    639              'Topic :: Office/Business',
    640              'Topic :: Software Development :: Bug Tracking',
    641              ],
    642          )
     654    setup(...,
     655          classifiers=[
     656              'Development Status :: 4 - Beta',
     657              'Environment :: Console',
     658              'Environment :: Web Environment',
     659              'Intended Audience :: End Users/Desktop',
     660              'Intended Audience :: Developers',
     661              'Intended Audience :: System Administrators',
     662              'License :: OSI Approved :: Python Software Foundation License',
     663              'Operating System :: MacOS :: MacOS X',
     664              'Operating System :: Microsoft :: Windows',
     665              'Operating System :: POSIX',
     666              'Programming Language :: Python',
     667              'Topic :: Communications :: Email',
     668              'Topic :: Office/Business',
     669              'Topic :: Software Development :: Bug Tracking',
     670              ],
     671          )
    643672
    644673If you wish to include classifiers in your :file:`setup.py` file and also wish
    … …  
    647676:func:`setup` call. ::
    648677
    649    # patch distutils if it can't cope with the "classifiers" or
    650    # "download_url" keywords
    651    from sys import version
    652    if version < '2.2.3':
    653        from distutils.dist import DistributionMetadata
    654        DistributionMetadata.classifiers = None
    655        DistributionMetadata.download_url = None
     678    # patch distutils if it can't cope with the "classifiers" or
     679    # "download_url" keywords
     680    from sys import version
     681    if version < '2.2.3':
     682        from distutils.dist import DistributionMetadata
     683        DistributionMetadata.classifiers = None
     684        DistributionMetadata.download_url = None
    656685
    657686
    … …  
    675704information what it is doing, and prints the full traceback in case an exception
    676705occurs.
    677 
    678 

  • python/vendor/current/Doc/distutils/sourcedist.rst

    r2 r388  
    2727| ``zip``   | zip file (:file:`.zip`) | (1),(3) |
    2828+-----------+-------------------------+---------+
    29 | ``gztar`` | gzip'ed tar file        | (2),(4) |
     29| ``gztar`` | gzip'ed tar file        | \(2)    |
    3030|           | (:file:`.tar.gz`)       |         |
    3131+-----------+-------------------------+---------+
    32 | ``bztar`` | bzip2'ed tar file       | \(4)    |
     32| ``bztar`` | bzip2'ed tar file       |         |
    3333|           | (:file:`.tar.bz2`)      |         |
    3434+-----------+-------------------------+---------+
    … …  
    3636|           | (:file:`.tar.Z`)        |         |
    3737+-----------+-------------------------+---------+
    38 | ``tar``   | tar file (:file:`.tar`) | \(4)    |
     38| ``tar``   | tar file (:file:`.tar`) |         |
    3939+-----------+-------------------------+---------+
    4040
    … …  
    5252
    5353(4)
    54    requires external utilities: :program:`tar` and possibly one of :program:`gzip`,
    55    :program:`bzip2`, or :program:`compress`
     54   requires the :program:`compress` program.
     55
     56When using any ``tar`` format (``gztar``, ``bztar``, ``ztar`` or
     57``tar``) under Unix, you can specify the ``owner`` and ``group`` names
     58that will be set for each member of the archive.
     59
     60For example, if you want all files of the archive to be owned by root::
     61
     62    python setup.py sdist --owner=root --group=root
    5663
    5764
    … …  
    6976
    7077* all C source files mentioned in the :option:`ext_modules` or
    71   :option:`libraries` options (
    72 
    73   **\*\*** getting C library sources currently broken---no
    74   :meth:`get_source_files` method in :file:`build_clib.py`! **\*\***)
     78  :option:`libraries` options
     79
     80  .. XXX Getting C library sources is currently broken -- no
     81     :meth:`get_source_files` method in :file:`build_clib.py`!
    7582
    7683* scripts identified by the :option:`scripts` option
     84  See :ref:`distutils-installing-scripts`.
    7785
    7886* anything that looks like a test script: :file:`test/test\*.py` (currently, the
    … …  
    8391* :file:`README.txt` (or :file:`README`), :file:`setup.py` (or whatever  you
    8492  called your setup script), and :file:`setup.cfg`
     93
     94* all files that matches the ``package_data`` metadata.
     95  See :ref:`distutils-installing-package-data`.
     96
     97* all files that matches the ``data_files`` metadata.
     98  See :ref:`distutils-additional-files`.
    8599
    86100Sometimes this is enough, but usually you will want to specify additional files
    … …  
    97111described above does not apply in this case.
    98112
     113.. versionchanged:: 2.7
     114   An existing generated :file:`MANIFEST` will be regenerated without
     115   :command:`sdist` comparing its modification time to the one of
     116   :file:`MANIFEST.in` or :file:`setup.py`.
     117
     118.. versionchanged:: 2.7.1
     119   :file:`MANIFEST` files start with a comment indicating they are generated.
     120   Files without this comment are not overwritten or removed.
     121
     122.. versionchanged:: 2.7.3
     123   :command:`sdist` will read a :file:`MANIFEST` file if no :file:`MANIFEST.in`
     124   exists, like it did before 2.7.
     125
     126See :ref:`manifest_template` section for a syntax reference.
     127
     128
     129.. _manifest-options:
     130
     131Manifest-related options
     132========================
     133
     134The normal course of operations for the :command:`sdist` command is as follows:
     135
     136* if the manifest file (:file:`MANIFEST` by default) exists and the first line
     137  does not have a comment indicating it is generated from :file:`MANIFEST.in`,
     138  then it is used as is, unaltered
     139
     140* if the manifest file doesn't exist or has been previously automatically
     141  generated, read :file:`MANIFEST.in` and create the manifest
     142
     143* if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
     144  with just the default file set
     145
     146* use the list of files now in :file:`MANIFEST` (either just generated or read
     147  in) to create the source distribution archive(s)
     148
     149There are a couple of options that modify this behaviour.  First, use the
     150:option:`--no-defaults` and :option:`--no-prune` to disable the standard
     151"include" and "exclude" sets.
     152
     153Second, you might just want to (re)generate the manifest, but not create a
     154source distribution::
     155
     156   python setup.py sdist --manifest-only
     157
     158:option:`-o` is a shortcut for :option:`--manifest-only`.
     159
     160.. _manifest_template:
     161
     162The MANIFEST.in template
     163========================
     164
     165A :file:`MANIFEST.in` file can be added in a project to define the list of
     166files to include in the distribution built by the :command:`sdist` command.
     167
     168When :command:`sdist` is run, it will look for the :file:`MANIFEST.in` file
     169and interpret it to generate the :file:`MANIFEST` file that contains the
     170list of files that will be included in the package.
     171
     172This mechanism can be used when the default list of files is not enough.
     173(See :ref:`manifest`).
     174
     175Principle
     176---------
     177
    99178The manifest template has one command per line, where each command specifies a
    100179set of files to include or exclude from the source distribution.  For an
    101 example, again we turn to the Distutils' own manifest template::
     180example, let's look at the Distutils' own manifest template::
    102181
    103182   include *.txt
    … …  
    111190include set, so you can exclude files from the standard set with explicit
    112191instructions in the manifest template.  (Or, you can use the
    113 :option:`--no-defaults` option to disable the standard set entirely.)  There are
    114 several other commands available in the manifest template mini-language; see
    115 section :ref:`sdist-cmd`.
     192:option:`--no-defaults` option to disable the standard set entirely.)
    116193
    117194The order of commands in the manifest template matters: initially, we have the
    … …  
    167244template is portable across operating systems.
    168245
    169 
    170 .. _manifest-options:
    171 
    172 Manifest-related options
    173 ========================
    174 
    175 The normal course of operations for the :command:`sdist` command is as follows:
    176 
    177 * if the manifest file, :file:`MANIFEST` doesn't exist, read :file:`MANIFEST.in`
    178   and create the manifest
    179 
    180 * if neither :file:`MANIFEST` nor :file:`MANIFEST.in` exist, create a manifest
    181   with just the default file set
    182 
    183 * if either :file:`MANIFEST.in` or the setup script (:file:`setup.py`) are more
    184   recent than :file:`MANIFEST`, recreate :file:`MANIFEST` by reading
    185   :file:`MANIFEST.in`
    186 
    187 * use the list of files now in :file:`MANIFEST` (either just generated or read
    188   in) to create the source distribution archive(s)
    189 
    190 There are a couple of options that modify this behaviour.  First, use the
    191 :option:`--no-defaults` and :option:`--no-prune` to disable the standard
    192 "include" and "exclude" sets.
    193 
    194 Second, you might want to force the manifest to be regenerated---for example, if
    195 you have added or removed files or directories that match an existing pattern in
    196 the manifest template, you should regenerate the manifest::
    197 
    198    python setup.py sdist --force-manifest
    199 
    200 Or, you might just want to (re)generate the manifest, but not create a source
    201 distribution::
    202 
    203    python setup.py sdist --manifest-only
    204 
    205 :option:`--manifest-only` implies :option:`--force-manifest`. :option:`-o` is a
    206 shortcut for :option:`--manifest-only`, and :option:`-f` for
    207 :option:`--force-manifest`.
    208 
    209 
     246Commands
     247--------
     248
     249The manifest template commands are:
     250
     251+-------------------------------------------+-----------------------------------------------+
     252| Command                                   | Description                                   |
     253+===========================================+===============================================+
     254| :command:`include pat1 pat2 ...`          | include all files matching any of the listed  |
     255|                                           | patterns                                      |
     256+-------------------------------------------+-----------------------------------------------+
     257| :command:`exclude pat1 pat2 ...`          | exclude all files matching any of the listed  |
     258|                                           | patterns                                      |
     259+-------------------------------------------+-----------------------------------------------+
     260| :command:`recursive-include dir pat1 pat2 | include all files under *dir* matching any of |
     261| ...`                                      | the listed patterns                           |
     262+-------------------------------------------+-----------------------------------------------+
     263| :command:`recursive-exclude dir pat1 pat2 | exclude all files under *dir* matching any of |
     264| ...`                                      | the listed patterns                           |
     265+-------------------------------------------+-----------------------------------------------+
     266| :command:`global-include pat1 pat2 ...`   | include all files anywhere in the source tree |
     267|                                           | matching --- & any of the listed patterns     |
     268+-------------------------------------------+-----------------------------------------------+
     269| :command:`global-exclude pat1 pat2 ...`   | exclude all files anywhere in the source tree |
     270|                                           | matching --- & any of the listed patterns     |
     271+-------------------------------------------+-----------------------------------------------+
     272| :command:`prune dir`                      | exclude all files under *dir*                 |
     273+-------------------------------------------+-----------------------------------------------+
     274| :command:`graft dir`                      | include all files under *dir*                 |
     275+-------------------------------------------+-----------------------------------------------+
     276
     277The patterns here are Unix-style "glob" patterns: ``*`` matches any sequence of
     278regular filename characters, ``?`` matches any single regular filename
     279character, and ``[range]`` matches any of the characters in *range* (e.g.,
     280``a-z``, ``a-zA-Z``, ``a-f0-9_.``).  The definition of "regular filename
     281character" is platform-specific: on Unix it is anything except slash; on Windows
     282anything except backslash or colon.

  • python/vendor/current/Doc/distutils/uploading.rst

    r2 r388  
    1 .. _package-upload:
     1:orphan:
    22
    33***************************************
    … …  
    55***************************************
    66
    7 .. versionadded:: 2.5
    8 
    9 The Python Package Index (PyPI) not only stores the package info, but also  the
    10 package data if the author of the package wishes to. The distutils command
    11 :command:`upload` pushes the distribution files to PyPI.
    12 
    13 The command is invoked immediately after building one or more distribution
    14 files.  For example, the command ::
    15 
    16    python setup.py sdist bdist_wininst upload
    17 
    18 will cause the source distribution and the Windows installer to be uploaded to
    19 PyPI.  Note that these will be uploaded even if they are built using an earlier
    20 invocation of :file:`setup.py`, but that only distributions named on the command
    21 line for the invocation including the :command:`upload` command are uploaded.
    22 
    23 The :command:`upload` command uses the username, password, and repository URL
    24 from the :file:`$HOME/.pypirc` file (see section :ref:`pypirc` for more on this
    25 file).
    26 
    27 You can specify another PyPI server with the :option:`--repository=*url*` option::
    28 
    29    python setup.py sdist bdist_wininst upload -r http://example.com/pypi
    30 
    31 See section :ref:`pypirc` for more on defining several servers.
    32 
    33 You can use the :option:`--sign` option to tell :command:`upload` to sign each
    34 uploaded file using GPG (GNU Privacy Guard).  The  :program:`gpg` program must
    35 be available for execution on the system :envvar:`PATH`.  You can also specify
    36 which key to use for signing using the :option:`--identity=*name*` option.
    37 
    38 Other :command:`upload` options include :option:`--repository=<url>` or
    39 :option:`--repository=<section>` where *url* is the url of the server and
    40 *section* the name of the section in :file:`$HOME/.pypirc`, and
    41 :option:`--show-response` (which displays the full response text from the PyPI
    42 server for help in debugging upload problems).
    43 
     7The contents of this page have moved to the section :ref:`package-index`.
Note: See TracChangeset for help on using the changeset viewer.