Branch merge

6 files changed, 82 insertions, 69 deletions

diff --git a/Doc/ACKS.txt b/Doc/ACKS.txt
index bb30e6d..9180cf7 100644
--- a/Doc/ACKS.txt
+++ b/Doc/ACKS.txt
@@ -57,6 +57,7 @@ docs@python.org), and we'll be glad to correct the problem.
    * Carl Feynman
    * Dan Finnie
    * Hernán Martínez Foffani
+   * Michael Foord
    * Stefan Franke
    * Jim Fulton
    * Peter Funk
@@ -144,6 +145,7 @@ docs@python.org), and we'll be glad to correct the problem.
    * Ross Moore
    * Sjoerd Mullender
    * Dale Nagata
+   * Trent Nelson
    * Michal Nowikowski
    * Steffen Daode Nurpmeso
    * Ng Pheng Siong
@@ -186,6 +188,7 @@ docs@python.org), and we'll be glad to correct the problem.
    * Joakim Sernbrant
    * Justin Sheehy
    * Charlie Shepherd
+   * Yue Shuaijie
    * SilentGhost
    * Michael Simcich
    * Ionel Simionescu
@@ -230,5 +233,3 @@ docs@python.org), and we'll be glad to correct the problem.
    * Moshe Zadka
    * Milan Zamazal
    * Cheng Zhang
-   * Trent Nelson
-   * Michael Foord
diff --git a/Doc/distutils/apiref.rst b/Doc/distutils/apiref.rst
index 124d891..3adbc52 100644
--- a/Doc/distutils/apiref.rst
+++ b/Doc/distutils/apiref.rst
@@ -31,8 +31,9 @@ setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
    +====================+================================+=============================================================+
    | *name*             | The name of the package        | a string                                                    |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *version*          | The version number of the      | See :mod:`distutils.version`                                |
-   |                    | package                        |                                                             |
+   | *version*          | The version number of the      | a string                                                    |
+   |                    | package; see                   |                                                             |
+   |                    | :mod:`distutils.version`       |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *description*      | A single line describing the   | a string                                                    |
    |                    | package                        |                                                             |
@@ -49,14 +50,14 @@ setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
    |                    | maintainer, if different from  |                                                             |
    |                    | the author                     |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *maintainer_email* | The email address of the       |                                                             |
+   | *maintainer_email* | The email address of the       | a string                                                    |
    |                    | current maintainer, if         |                                                             |
    |                    | different from the author      |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *url*              | A URL for the package          | a URL                                                       |
+   | *url*              | A URL for the package          | a string                                                    |
    |                    | (homepage)                     |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *download_url*     | A URL to download the package  | a URL                                                       |
+   | *download_url*     | A URL to download the package  | a string                                                    |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *packages*         | A list of Python packages that | a list of strings                                           |
    |                    | distutils will manipulate      |                                                             |
@@ -68,14 +69,13 @@ setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
    |                    | files to be built and          |                                                             |
    |                    | installed                      |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *ext_modules*      | A list of Python extensions to | A list of  instances of                                     |
+   | *ext_modules*      | A list of Python extensions to | a list of instances of                                      |
    |                    | be built                       | :class:`distutils.core.Extension`                           |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *classifiers*      | A list of categories for the   | The list of available                                       |
-   |                    | package                        | categorizations is available on `PyPI                       |
-   |                    |                                | <http://pypi.python.org/pypi?:action=list_classifiers>`_.   |
+   | *classifiers*      | A list of categories for the   | a list of strings; valid classifiers are listed on `PyPI    |
+   |                    | package                        | <http://pypi.python.org/pypi?:action=list_classifiers>`_.   |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *distclass*        | the :class:`Distribution`      | A subclass of                                               |
+   | *distclass*        | the :class:`Distribution`      | a subclass of                                               |
    |                    | class to use                   | :class:`distutils.core.Distribution`                        |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *script_name*      | The name of the setup.py       | a string                                                    |
@@ -85,15 +85,15 @@ setup script). Indirectly provides the  :class:`distutils.dist.Distribution` and
    | *script_args*      | Arguments to supply to the     | a list of strings                                           |
    |                    | setup script                   |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *options*          | default options for the setup  | a string                                                    |
+   | *options*          | default options for the setup  | a dictionary                                                |
    |                    | script                         |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *license*          | The license for the package    | a string                                                    |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *keywords*         | Descriptive meta-data, see     |                                                             |
+   | *keywords*         | Descriptive meta-data, see     | a list of strings or a comma-separated string               |
    |                    | :pep:`314`                     |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *platforms*        |                                |                                                             |
+   | *platforms*        |                                | a list of strings or a comma-separated string               |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *cmdclass*         | A mapping of command names to  | a dictionary                                                |
    |                    | :class:`Command` subclasses    |                                                             |
@@ -160,18 +160,18 @@ the full reference.
 .. class:: Extension
 
    The Extension class describes a single C or C++extension module in a setup
-   script. It accepts the following keyword arguments in its constructor
+   script. It accepts the following keyword arguments in its constructor:
 
    +------------------------+--------------------------------+---------------------------+
    | argument name          | value                          | type                      |
    +========================+================================+===========================+
-   | *name*                 | the full name of the           | string                    |
+   | *name*                 | the full name of the           | a string                  |
    |                        | extension, including any       |                           |
    |                        | packages --- ie. *not* a       |                           |
    |                        | filename or pathname, but      |                           |
    |                        | Python dotted name             |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *sources*              | list of source filenames,      | string                    |
+   | *sources*              | list of source filenames,      | a list of strings         |
    |                        | relative to the distribution   |                           |
    |                        | root (where the setup script   |                           |
    |                        | lives), in Unix form (slash-   |                           |
@@ -184,12 +184,12 @@ the full reference.
    |                        | as source for a Python         |                           |
    |                        | extension.                     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *include_dirs*         | list of directories to search  | string                    |
+   | *include_dirs*         | list of directories to search  | a list of strings         |
    |                        | for C/C++ header files (in     |                           |
    |                        | Unix form for portability)     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *define_macros*        | list of macros to define; each | (string, string) tuple or |
-   |                        | macro is defined using a       | (name, ``None``)          |
+   | *define_macros*        | list of macros to define; each | a list of tuples          |
+   |                        | macro is defined using a       |                           |
    |                        | 2-tuple ``(name, value)``,     |                           |
    |                        | where *value* is               |                           |
    |                        | either the string to define it |                           |
@@ -200,31 +200,31 @@ the full reference.
    |                        | on Unix C compiler command     |                           |
    |                        | line)                          |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *undef_macros*         | list of macros to undefine     | string                    |
+   | *undef_macros*         | list of macros to undefine     | a list of strings         |
    |                        | explicitly                     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *library_dirs*         | list of directories to search  | string                    |
+   | *library_dirs*         | list of directories to search  | a list of strings         |
    |                        | for C/C++ libraries at link    |                           |
    |                        | time                           |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *libraries*            | list of library names (not     | string                    |
+   | *libraries*            | list of library names (not     | a list of strings         |
    |                        | filenames or paths) to link    |                           |
    |                        | against                        |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *runtime_library_dirs* | list of directories to search  | string                    |
+   | *runtime_library_dirs* | list of directories to search  | a list of strings         |
    |                        | for C/C++ libraries at run     |                           |
    |                        | time (for shared extensions,   |                           |
    |                        | this is when the extension is  |                           |
    |                        | loaded)                        |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *extra_objects*        | list of extra files to link    | string                    |
+   | *extra_objects*        | list of extra files to link    | a list of strings         |
    |                        | with (eg. object files not     |                           |
    |                        | implied by 'sources', static   |                           |
    |                        | library that must be           |                           |
    |                        | explicitly specified, binary   |                           |
    |                        | resource files, etc.)          |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *extra_compile_args*   | any extra platform- and        | string                    |
+   | *extra_compile_args*   | any extra platform- and        | a list of strings         |
    |                        | compiler-specific information  |                           |
    |                        | to use when compiling the      |                           |
    |                        | source files in 'sources'. For |                           |
@@ -235,7 +235,7 @@ the full reference.
    |                        | for other platforms it could   |                           |
    |                        | be anything.                   |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *extra_link_args*      | any extra platform- and        | string                    |
+   | *extra_link_args*      | any extra platform- and        | a list of strings         |
    |                        | compiler-specific information  |                           |
    |                        | to use when linking object     |                           |
    |                        | files together to create the   |                           |
@@ -244,7 +244,7 @@ the full reference.
    |                        | Similar interpretation as for  |                           |
    |                        | 'extra_compile_args'.          |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *export_symbols*       | list of symbols to be exported | string                    |
+   | *export_symbols*       | list of symbols to be exported | a list of strings         |
    |                        | from a shared extension. Not   |                           |
    |                        | used on all platforms, and not |                           |
    |                        | generally necessary for Python |                           |
@@ -252,15 +252,20 @@ the full reference.
    |                        | export exactly one symbol:     |                           |
    |                        | ``init`` + extension_name.     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *depends*              | list of files that the         | string                    |
+   | *depends*              | list of files that the         | a list of strings         |
    |                        | extension depends on           |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *language*             | extension language (i.e.       | string                    |
+   | *language*             | extension language (i.e.       | a string                  |
    |                        | ``'c'``, ``'c++'``,            |                           |
    |                        | ``'objc'``). Will be detected  |                           |
    |                        | from the source extensions if  |                           |
    |                        | not provided.                  |                           |
    +------------------------+--------------------------------+---------------------------+
+   | *optional*             | specifies that a build failure | a boolean                 |
+   |                        | in the extension should not    |                           |
+   |                        | abort the build process, but   |                           |
+   |                        | simply skip the extension.     |                           |
+   +------------------------+--------------------------------+---------------------------+
 
 
 .. class:: Distribution
diff --git a/Doc/library/packaging.compiler.rst b/Doc/library/packaging.compiler.rst
index 38e9ce5..d771972 100644
--- a/Doc/library/packaging.compiler.rst
+++ b/Doc/library/packaging.compiler.rst
@@ -572,7 +572,7 @@ extension modules.
    the following keyword arguments in its constructor:
 
    +------------------------+--------------------------------+---------------------------+
-   | argument name          | value                          | type [#]_                 |
+   | argument name          | value                          | type                      |
    +========================+================================+===========================+
    | *name*                 | the full name of the           | string                    |
    |                        | extension, including any       |                           |
@@ -580,7 +580,7 @@ extension modules.
    |                        | filename or pathname, but      |                           |
    |                        | Python dotted name             |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *sources*              | list of source filenames,      | string                    |
+   | *sources*              | list of source filenames,      | list of strings           |
    |                        | relative to the distribution   |                           |
    |                        | root (where the setup script   |                           |
    |                        | lives), in Unix form (slash-   |                           |
@@ -593,12 +593,12 @@ extension modules.
    |                        | as source for a Python         |                           |
    |                        | extension.                     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *include_dirs*         | list of directories to search  | string                    |
+   | *include_dirs*         | list of directories to search  | list of strings           |
    |                        | for C/C++ header files (in     |                           |
    |                        | Unix form for portability)     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *define_macros*        | list of macros to define; each | (string, string) tuple or |
-   |                        | macro is defined using a       | (name, ``None``)          |
+   | *define_macros*        | list of macros to define; each | list of tuples            |
+   |                        | macro is defined using a       |                           |
    |                        | 2-tuple ``(name, value)``,     |                           |
    |                        | where *value* is               |                           |
    |                        | either the string to define it |                           |
@@ -609,31 +609,31 @@ extension modules.
    |                        | on Unix C compiler command     |                           |
    |                        | line)                          |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *undef_macros*         | list of macros to undefine     | string                    |
+   | *undef_macros*         | list of macros to undefine     | list of strings           |
    |                        | explicitly                     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *library_dirs*         | list of directories to search  | string                    |
+   | *library_dirs*         | list of directories to search  | list of strings           |
    |                        | for C/C++ libraries at link    |                           |
    |                        | time                           |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *libraries*            | list of library names (not     | string                    |
+   | *libraries*            | list of library names (not     | list of strings           |
    |                        | filenames or paths) to link    |                           |
    |                        | against                        |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *runtime_library_dirs* | list of directories to search  | string                    |
+   | *runtime_library_dirs* | list of directories to search  | list of strings           |
    |                        | for C/C++ libraries at run     |                           |
    |                        | time (for shared extensions,   |                           |
    |                        | this is when the extension is  |                           |
    |                        | loaded)                        |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *extra_objects*        | list of extra files to link    | string                    |
+   | *extra_objects*        | list of extra files to link    | list of strings           |
    |                        | with (e.g. object files not    |                           |
    |                        | implied by 'sources', static   |                           |
    |                        | library that must be           |                           |
    |                        | explicitly specified, binary   |                           |
    |                        | resource files, etc.)          |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *extra_compile_args*   | any extra platform- and        | string                    |
+   | *extra_compile_args*   | any extra platform- and        | list of strings           |
    |                        | compiler-specific information  |                           |
    |                        | to use when compiling the      |                           |
    |                        | source files in 'sources'. For |                           |
@@ -644,7 +644,7 @@ extension modules.
    |                        | for other platforms it could   |                           |
    |                        | be anything.                   |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *extra_link_args*      | any extra platform- and        | string                    |
+   | *extra_link_args*      | any extra platform- and        | list of strings           |
    |                        | compiler-specific information  |                           |
    |                        | to use when linking object     |                           |
    |                        | files together to create the   |                           |
@@ -653,7 +653,7 @@ extension modules.
    |                        | Similar interpretation as for  |                           |
    |                        | 'extra_compile_args'.          |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *export_symbols*       | list of symbols to be exported | string                    |
+   | *export_symbols*       | list of symbols to be exported | list of strings           |
    |                        | from a shared extension. Not   |                           |
    |                        | used on all platforms, and not |                           |
    |                        | generally necessary for Python |                           |
@@ -661,7 +661,7 @@ extension modules.
    |                        | export exactly one symbol:     |                           |
    |                        | ``init`` + extension_name.     |                           |
    +------------------------+--------------------------------+---------------------------+
-   | *depends*              | list of files that the         | string                    |
+   | *depends*              | list of files that the         | list of strings           |
    |                        | extension depends on           |                           |
    +------------------------+--------------------------------+---------------------------+
    | *language*             | extension language (i.e.       | string                    |
@@ -670,5 +670,8 @@ extension modules.
    |                        | from the source extensions if  |                           |
    |                        | not provided.                  |                           |
    +------------------------+--------------------------------+---------------------------+
-
-.. [#] For values documented as lists, the given type is the type of each element.
+   | *optional*             | specifies that a build failure | boolean                   |
+   |                        | in the extension should not    |                           |
+   |                        | abort the build process, but   |                           |
+   |                        | simply skip the extension.     |                           |
+   +------------------------+--------------------------------+---------------------------+
diff --git a/Doc/library/packaging.dist.rst b/Doc/library/packaging.dist.rst
index 7184f7f..25cb62b 100644
--- a/Doc/library/packaging.dist.rst
+++ b/Doc/library/packaging.dist.rst
@@ -25,10 +25,11 @@ module distribution being built/packaged/distributed/installed.
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | argument name      | value                          | type                                                        |
    +====================+================================+=============================================================+
-   | *name*             | The name of the project        | string                                                      |
+   | *name*             | The name of the project        | a string                                                    |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *version*          | The version number of the      | See :mod:`packaging.version`                                |
-   |                    | release                        |                                                             |
+   | *version*          | The version number of the      | a string                                                    |
+   |                    | release; see                   |                                                             |
+   |                    | :mod:`packaging.version`       |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *summary*          | A single line describing the   | a string                                                    |
    |                    | project                        |                                                             |
@@ -45,14 +46,14 @@ module distribution being built/packaged/distributed/installed.
    |                    | maintainer, if different from  |                                                             |
    |                    | the author                     |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *maintainer_email* | The email address of the       |                                                             |
+   | *maintainer_email* | The email address of the       | a string                                                    |
    |                    | current maintainer, if         |                                                             |
    |                    | different from the author      |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *home_page*        | A URL for the proejct          | a URL                                                       |
+   | *home_page*        | A URL for the proejct          | a string                                                    |
    |                    | (homepage)                     |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *download_url*     | A URL to download the project  | a URL                                                       |
+   | *download_url*     | A URL to download the project  | a string                                                    |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *packages*         | A list of Python packages that | a list of strings                                           |
    |                    | packaging will manipulate      |                                                             |
@@ -63,14 +64,13 @@ module distribution being built/packaged/distributed/installed.
    | *scripts*          | A list of standalone scripts   | a list of strings                                           |
    |                    | to be built and installed      |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *ext_modules*      | A list of Python extensions to | A list of instances of                                      |
+   | *ext_modules*      | A list of Python extensions to | a list of instances of                                      |
    |                    | be built                       | :class:`packaging.compiler.extension.Extension`             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *classifiers*      | A list of categories for the   | The list of available                                       |
-   |                    | distribution                   | categorizations is available on `PyPI                       |
-   |                    |                                | <http://pypi.python.org/pypi?:action=list_classifiers>`_.   |
+   | *classifiers*      | A list of categories for the   | a list of strings; valid classifiers are listed on `PyPi    |
+   |                    | distribution                   | <http://pypi.python.org/pypi?:action=list_classifiers>`_.   |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *distclass*        | the :class:`Distribution`      | A subclass of                                               |
+   | *distclass*        | the :class:`Distribution`      | a subclass of                                               |
    |                    | class to use                   | :class:`packaging.dist.Distribution`                        |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *script_name*      | The name of the setup.py       | a string                                                    |
@@ -83,13 +83,19 @@ module distribution being built/packaged/distributed/installed.
    | *options*          | default options for the setup  | a string                                                    |
    |                    | script                         |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *license*          | The license for the            | a string; should be used when there is no suitable License  |
-   |                    | distribution                   | classifier, or to specify a classifier                      |
+   | *license*          | The license for the            | a string                                                    |
+   |                    | distribution; should be used   |                                                             |
+   |                    | when there is no suitable      |                                                             |
+   |                    | License classifier, or to      |                                                             |
+   |                    | refine a classifier            |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *keywords*         | Descriptive keywords           | a list of strings; used by catalogs                         |
+   | *keywords*         | Descriptive keywords; used by  | a list of strings or a comma-separated string               |
+   |                    | catalogs such as PyPI          |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
-   | *platforms*        | Platforms compatible with this | a list of strings; should be used when there is no          |
-   |                    | distribution                   | suitable Platform classifier                                |
+   | *platforms*        | Platforms compatible with this | a list of strings or a comma-separated string               |
+   |                    | distribution; should be used   |                                                             |
+   |                    | when there is no suitable      |                                                             |
+   |                    | Platform classifier            |                                                             |
    +--------------------+--------------------------------+-------------------------------------------------------------+
    | *cmdclass*         | A mapping of command names to  | a dictionary                                                |
    |                    | :class:`Command` subclasses    |                                                             |
diff --git a/Lib/distutils/tests/test_install.py b/Lib/distutils/tests/test_install.py
index 5c105af..dfc46b1 100644
--- a/Lib/distutils/tests/test_install.py
+++ b/Lib/distutils/tests/test_install.py
@@ -20,9 +20,8 @@ from distutils.tests import support
 
 
 def _make_ext_name(modname):
-    if os.name == 'nt':
-        if sys.executable.endswith('_d.exe'):
-            modname += '_d'
+    if os.name == 'nt' and sys.executable.endswith('_d.exe'):
+        modname += '_d'
     return modname + sysconfig.get_config_var('SO')
 
 
diff --git a/Lib/packaging/tests/test_command_install_dist.py b/Lib/packaging/tests/test_command_install_dist.py
index 61270af..8f90aff 100644
--- a/Lib/packaging/tests/test_command_install_dist.py
+++ b/Lib/packaging/tests/test_command_install_dist.py
@@ -18,9 +18,8 @@ _CONFIG_VARS = get_config_vars()
 
 
 def _make_ext_name(modname):
-    if os.name == 'nt':
-        if sys.executable.endswith('_d.exe'):
-            modname += '_d'
+    if os.name == 'nt' and sys.executable.endswith('_d.exe'):
+        modname += '_d'
     return modname + get_config_var('SO')