[Python-checkins] peps: PEP 440: Patch from Donald to address distutils-sig feedback

[nick.coghlan]

http://hg.python.org/peps/rev/73580fd4a2d6
changeset:   5523:73580fd4a2d6
user:        Nick Coghlan <ncoghlan at gmail.com>
date:        Fri Aug 22 19:53:21 2014 +1000
summary:
  PEP 440: Patch from Donald to address distutils-sig feedback

files:
  pep-0440.txt |  71 ++++++++++++++++++++++++++++++++++++---
  1 files changed, 64 insertions(+), 7 deletions(-)


diff --git a/pep-0440.txt b/pep-0440.txt
--- a/pep-0440.txt
+++ b/pep-0440.txt
@@ -12,6 +12,7 @@
 Created: 18 Mar 2013
 Post-History: 30 Mar 2013, 27 May 2013, 20 Jun 2013,
               21 Dec 2013, 28 Jan 2014, 08 Aug 2014
+              22 Aug 2014
 Replaces: 386
 
 
@@ -150,12 +151,18 @@
 segments, as long as the shorter local version's segments match the beginning
 of the longer local version's segments exactly.
 
-Local version identifiers may be used in most locations where a public
-version identifier is expected, with the exception of any version specifiers
-that explicitly rely on being able to unambiguously order candidate versions.
+An "upstream project" is a project that defines its own public versions. A
+"downstream project" is one which tracks and redistributes an upstream project,
+potentially backporting security and bug fixes from later versions of the
+upstream project.
 
-Public index servers SHOULD NOT allow the use of local version identifiers
-for uploaded distributions.
+Local version identifiers SHOULD NOT be used for upstream projects. Local
+version identifiers SHOULD be used by dowstream projects when releasing a
+version that is API compatible with the version of the upstream project
+identified by the public version identifier, but contains additional changes
+(such as bug fixes). As the Python Package Index is intended solely for
+indexing and hosting upstream projects, it MUST NOT allow the use of local
+version identifiers.
 
 Source distributions using a local version identifier SHOULD provide the
 ``python.integrator`` extension metadata (as defined in :pep:`459`).
@@ -1126,6 +1133,27 @@
     pip @ git+https://github.com/pypa/pip.git@1.3.1#7921be1537eac1e97bc40179a57f0349c2aee67d
 
 
+File URLs
+---------
+
+File URLs take the form of ``file://<host>/<path>``. If the ``<host>`` is
+omitted it is assumed to be ``localhost`` and even if the ``<host>`` is omitted
+the third slash MUST still exist. The ``<path>`` defines what the file path on
+the filesystem that is to be accessed.
+
+On the various \*nix operating systems the only allowed values for ``<host>``
+is for it to be ommitted, ``localhost``, or another FQDN that the current
+machine believes matches its own host. In other words on \*nix the ``file://``
+scheme can only be used to access paths on the local machine.
+
+On Windows the file format should include the drive letter if applicable as
+part of the ``<path>`` (e.g. ``file:///c:/path/to/a/file``). Unlike \*nix on
+Windows the ``<host>`` parameter may be used to specify a file residing on a
+network share. In other words in order to translate ``\\machine\volume\file``
+to a ``file://`` url, it would end up as ``file://machine/volume/file``. For
+more information on ``file://`` URLs on Windows see MSDN [4]_.
+
+
 
 Updating the versioning specification
 =====================================
@@ -1137,6 +1165,22 @@
 versioning scheme and metadata version defined in new PEPs.
 
 
+Summary of differences from pkg_resources.parse_version
+=======================================================
+
+* Local versions sort differently, this PEP requires that they sort as greater
+  than the same version without a local version, whereas
+  ``pkg_resources.parse_version`` considers it a pre-release marker.
+
+* This PEP purposely restricts the syntax which constitutes a valid version
+  while ``pkg_resources.parse_version`` attempts to provide some meaning from
+  *any* arbitrary string.
+
+* ``pkg_resources.parse_version`` allows arbitrarily deeply nested version
+  signifiers like ``1.0.dev1.post1.dev5``. This PEP however allows only a
+  single use of each type and they must exist in a certain order.
+
+
 Summary of differences from \PEP 386
 ====================================
 
@@ -1425,7 +1469,17 @@
 increase the likelihood of ambiguous or "junk" versions.
 
 For an extended discussion on the various types of normalizations that were
-considered, please see the proof of concept for PEP 440 within pip [4]_.
+considered, please see the proof of concept for PEP 440 within pip [5]_.
+
+
+Allowing Underscore in Normalization
+------------------------------------
+
+There are not a lot of projects on PyPI which utilize a ``_`` in the version
+string. However this PEP allows its use anywhere that ``-`` is acceptable. The
+reason for this is that the Wheel normalization scheme specifies that ``-``
+gets normalized to a ``_`` to enable easier parsing of the filename.
+
 
 
 References
@@ -1443,7 +1497,10 @@
 .. [3] Pessimistic version constraint
    http://docs.rubygems.org/read/chapter/16
 
-.. [4] Proof of Concept: PEP 440 within pip
+.. [4] File URIs in Windows
+   http://blogs.msdn.com/b/ie/archive/2006/12/06/file-uris-in-windows.aspx
+
+.. [5] Proof of Concept: PEP 440 within pip
     https://github.com/pypa/pip/pull/1894
 
 

-- 
Repository URL: http://hg.python.org/peps