Branch merge

Doc/library/abc.rst

@@ -20,7 +20,7 @@ regarding a type hierarchy for numbers based on ABCs.)
 
 The :mod:`collections` module has some concrete classes that derive from
 ABCs; these can, of course, be further derived. In addition the
-:mod:`collections` module has some ABCs that can be used to test whether
+:mod:`collections.abc` submodule has some ABCs that can be used to test whether
 a class or instance provides a particular interface, for example, is it
 hashable or a mapping.
 

Doc/packaging/commandhooks.rst

@@ -1,3 +1,5 @@
+.. TODO integrate this in commandref and configfile
+
 =============
 Command hooks
 =============
@@ -9,6 +11,9 @@ The pre-hooks are run after the command is finalized (its options are
 processed), but before it is run. The post-hooks are run after the command
 itself. Both types of hooks receive an instance of the command object.
 
+See also global setup hooks in :ref:`packaging-setupcfg`.
+
+
 Sample usage of hooks
 =====================
 

Doc/packaging/setupcfg.rst

@@ -1,14 +1,119 @@
 .. highlightlang:: cfg
 
+.. _packaging-setupcfg:
+
 *******************************************
 Specification of the :file:`setup.cfg` file
 *******************************************
 
-.. :version: 1.0
+:version: 0.9
 
 This document describes the :file:`setup.cfg`, an ini-style configuration file
-(compatible with :class:`configparser.RawConfigParser`) configuration file used
-by Packaging to replace the :file:`setup.py` file.
+(compatible with :class:`configparser.RawConfigParser`) used by Packaging to
+replace the :file:`setup.py` file.
+
+
+Syntax
+======
+
+The configuration file is an ini-based file. Variables name can be
+assigned values, and grouped into sections. A line that starts with "#" is
+commented out. Empty lines are also removed.
+
+Example::
+
+   [section1]
+   # comment
+   name = value
+   name2 = "other value"
+
+   [section2]
+   foo = bar
+
+
+Values conversion
+-----------------
+
+Here are a set of rules for converting values:
+
+- If value is quoted with " chars, it's a string. This notation is useful to
+  include "=" characters in the value. In case the value contains a "
+  character, it must be escaped with a "\" character.
+- If the value is "true" or "false" --no matter what the case is--, it's
+  converted to a boolean, or 0 and 1 when the language does not have a
+  boolean type.
+- A value can contains multiple lines. When read, lines are converted into a
+  sequence of values. Each new line for a multiple lines value must start with
+  a least one space or tab character. These indentation characters will be
+  stripped.
+- all other values are considered as strings
+
+Examples::
+
+   [section]
+   foo = one
+         two
+         three
+
+   bar = false
+   baz = 1.3
+   boo = "ok"
+   beee = "wqdqw pojpj w\"ddq"
+
+
+Extending files
+---------------
+
+An INI file can extend another file. For this, a "DEFAULT" section must contain
+an "extends" variable that can point to one or several INI files which will be
+merged to the current file by adding new sections and values.
+
+If the file pointed in "extends" contains section/variable names that already
+exist in the original file, they will not override existing ones.
+
+file_one.ini::
+
+    [section1]
+    name2 = "other value"
+
+    [section2]
+    foo = baz
+    bas = bar
+
+file_two.ini::
+
+    [DEFAULT]
+    extends = file_one.ini
+
+    [section2]
+    foo = bar
+
+Result::
+
+    [section1]
+    name2 = "other value"
+
+    [section2]
+    foo = bar
+    bas = bar
+
+To point several files, the multi-line notation can be used::
+
+    [DEFAULT]
+    extends = file_one.ini
+              file_two.ini
+
+When several files are provided, they are processed sequentially. So if the
+first one has a value that is also present in the second, the second one will
+be ignored. This means that the configuration goes from the most specialized to
+the most common.
+
+**Tools will need to provide a way to produce a canonical version of the
+file**. This will be useful to publish a single file.
+
+
+Description of sections and fields
+==================================
 
 Each section contains a description of its options.
 
@@ -646,3 +751,57 @@ section named after the command.  Example::
 
 Option values given in the configuration file can be overriden on the command
 line.  See :ref:`packaging-setup-config` for more information.
+
+
+Extensibility
+=============
+
+Every section can define new variables that are not part of the specification.
+They are called **extensions**.
+
+An extension field starts with *X-*.
+
+Example::
+
+   [metadata]
+   ...
+   X-Debian-Name = python-distribute
+
+
+Changes in the specification
+============================
+
+The version scheme for this specification is **MAJOR.MINOR**.
+Changes in the specification will increment the version.
+
+- minor version changes (1.x): backwards compatible
+
+ - new fields and sections (both optional and mandatory) can be added
+ - optional fields can be removed
+
+- major channges (2.X): backwards-incompatible
+
+ - mandatory fields/sections are removed
+ - fields change their meaning
+
+As a consequence, a tool written to consume 1.X (say, X=5) has these
+properties:
+
+- reading 1.Y, Y<X (e.g. 1.1) is possible, since the tool knows what
+  optional fields weren't there
+- reading 1.Y, Y>X is also possible. The tool will just ignore the new
+  fields (even if they are mandatory in that version)
+  If optional fields were removed, the tool will just consider them absent.
+- reading 2.X is not possible; the tool should refuse to interpret
+  the file.
+
+A tool written to produce 1.X should have these properties:
+
+- it will write all mandatory fields
+- it may write optional fields
+
+
+Acks
+====
+
+XXX

Lib/packaging/compiler/cygwinccompiler.py

@@ -48,7 +48,6 @@ of GCC (same as cygwin in no-cygwin mode).
 
 import os
 import sys
-import copy
 
 from packaging import logger
 from packaging.compiler.unixccompiler import UnixCCompiler
@@ -172,9 +171,9 @@ class CygwinCCompiler(UnixCCompiler):
              extra_postargs=None, build_temp=None, target_lang=None):
         """Link the objects."""
         # use separate copies, so we can modify the lists
-        extra_preargs = copy.copy(extra_preargs or [])
-        libraries = copy.copy(libraries or [])
-        objects = copy.copy(objects or [])
+        extra_preargs = list(extra_preargs or [])
+        libraries = list(libraries or [])
+        objects = list(objects or [])
 
         # Additional libraries
         libraries.extend(self.dll_libraries)

Lib/packaging/run.py

@@ -5,7 +5,6 @@ import re
 import sys
 import getopt
 import logging
-from copy import copy
 
 from packaging import logger
 from packaging.dist import Distribution
@@ -673,7 +672,7 @@ class Dispatcher:
 
 def main(args=None):
     old_level = logger.level
-    old_handlers = copy(logger.handlers)
+    old_handlers = list(logger.handlers)
     try:
         dispatcher = Dispatcher(args)
         if dispatcher.action is None:

Lib/packaging/util.py

@@ -14,7 +14,6 @@ import zipfile
 import posixpath
 import sysconfig
 import subprocess
-from copy import copy
 from glob import iglob as std_iglob
 from fnmatch import fnmatchcase
 from inspect import getsource
@@ -384,7 +383,7 @@ byte_compile(files, optimize=%r, force=%r,
         elif optimize == 2:
             cmd.insert(1, "-OO")
 
-        env = copy(os.environ)
+        env = os.environ.copy()
         env['PYTHONPATH'] = os.path.pathsep.join(sys.path)
         try:
             spawn(cmd, env=env)