[Distutils] New draft of PEP 426

[Donald Stufft]

On Sunday, February 3, 2013 at 8:32 AM, Nick Coghlan wrote:
> 
> Keywords (optional)
> -------------------
> 
> A list of additional whitespace separated keywords to be used to assist
> searching for the distribution in a larger catalog.
> 
> Example::
> 
> Keywords: dog puppy voting election
I wonder if it makes sense to make this a multi use field instead of
a whitespace separated field. It always felt really dirty to me that
this was essentially a list but wasn't treat as one. Not a requirement
but just a thought.

> 
> Version Scheme
> ==============
> 
> Version numbers must comply with the following scheme::
> 
> N.N[.N]+[{a|b|c|rc}N][.postN][.devN]
> 
> Parser implementations should be aware that versions of the Metadata
> specification prior to v1.2 (PEP 345) do not specify a standard version
> numbering scheme. For metadata v1.2, it is recommended that implementations
> use the sorting scheme defined below rather than the one defined in PEP 386.
> 
> 
> Suffixes and Ordering
> ---------------------
> 
> The following suffixes are the only ones allowed at the given level of the
> version hierarchy and they are ordered as listed.
> 
> Within a numeric release (``1.0``, ``2.7.3``)::
> 
> .devN, aN, bN, cN, rcN, <no suffix>, .postN
> 
> Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate
> (``1.0c1``, ``1.0rc1``)::
> 
> .devN, <no suffix>, .postN
> 
> Within a post release (``1.0.post1``)::
> 
> devN, <no suffix>
> 
> Note that ``devN`` and ``postN`` must always be preceded by a dot, even
> when used immediately following a numeric version (e.g. ``1.0.dev456``,
> ``1.0.post1``).
> 
> Within a given suffix, ordering is by the value of the numeric component.
> 
> Note that `rc` will always sort after `c` (regardless of the numeric
> component) although they are semantically equivalent. It is suggested
> that within a particular project you do not mix `c` and `rc`, especially
> within the same numeric version.
> 
> 
> Example Version Order
> ---------------------
> 
> ::
> 
> 1.0.dev456
> 1.0a1
> 1.0a2.dev456
> 1.0a12.dev456
> 1.0a12
> 1.0b1.dev456
> 1.0b2
> 1.0b2.post345
> 1.0c1.dev456
> 1.0c1
> 1.0
> 1.0.post456.dev34
> 1.0.post456
> 1.1.dev1

Just to point out that this a minor departure from PEP386 (on purpose) and
a simplification of the rules. The major point being to enable backwards
compatibility with setuptools/distribute.

In [1]: import pkg_resources
In [2]: import distutils2.version
In [3]: versions = ["1.0.dev456", "1.0a1", "1.0a2.dev456", "1.0a12.dev456", "1.0a12", "1.0b1.dev456", "1.0b2", "1.0b2.post345", "1.0c1.dev456", "1.0c1", "1.0", "1.0.post456.dev34", "1.0.post456", "1.1.dev1"]
In [4]: versions2 = sorted(versions, key=pkg_resources.parse_version)
In [5]: versions == versions2
Out[5]: True

In [6]: versions3 = sorted(versions, key=distutils2.version.NormalizedVersion)
In [7]: versions == versions3
Out[7]: False



> Version Specifiers
> ==================
> 
> A version specifier consists of a series of version clauses, separated by
> commas. Each version clause consists of an optional comparison operator
> followed by a version number. For example::
> 
> 0.9, >= 1.0, != 1.3.4, < 2.0
> 
> Each version number must be in the standard format described in
> `Version Scheme`_.

So what happens when I'm writing a package and want to depend on
something that does not use the Version Scheme? Do we just
say "You can't do that?". 
> 
> Comparison operators must be one of ``<``, ``>``, ``<=``, ``>=``, ``==``
> and ``!=``.
> 
> When no comparison operator is provided, it is equivalent to using the
> following pair of version clauses::
> 
> >= V, < V+1
> 
> where ``V+1`` is the "next version" after ``V``, as determined by
> incrementing the last numeric component in ``V`` (for example, if
> ``V == 1.0a3``, then ``V+1 == 1.0a4``, while if ``V == 1.0``, then
> ``V+1 == 1.1``).
> 
> The comma (",") is equivalent to a logical **and** operator.
> 
> Whitespace between a conditional operator and the following version number
> is optional, as is the whitespace around the commas.
> 
> Pre-releases of any kind (indicated by the presence of ``dev``, ``a``,
> ``b``, ``c`` or ``rc`` in the version number) are implicitly excluded
> from all version specifiers, *unless* a pre-release version is explicitly
> mentioned in one of the clauses. For example, this specifier implicitly
> excludes all pre-releases of later versions::
> 
> >= 1.0
> 
> While these specifiers would include them::
> 
> >= 1.0a1
> >= 1.0c1
> >= 1.0, != 1.0b2
> >= 1.0, < 2.0.dev123
> 
> Dependency resolution tools should use the above rules by default, but may
> also allow users to request the following alternative behaviours:
> 
> * accept already installed pre-releases for all version specifiers
> * retrieve and install available pre-releases for all version specifiers
> 
> Post releases and purely numeric releases receive no special treatment -
> they are always included unless explicitly excluded.
> 
> Given the above rules, projects which include the ``.0`` suffix for the
> first release in a series, such as ``2.5.0``, can easily refer specifically
> to that version with the clause ``2.5.0``, while the clause ``2.5`` refers
> to that entire series. Projects which omit the ".0" suffix for the first
> release of a series, by using a version string like ``2.5`` rather than
> ``2.5.0``, will need to use an explicit clause like ``2.5, < 2.5.1`` to
> refer specifically to that initial release.

Should replace this to be ==2.5 instead of 2.5, < 2.5.1 as that's
not guaranteed to  be the same as ==2.5. Also -==2.5.0 really. A
bare clause should not be expected to match exactly
anything.

> 
> - ``Requires-Python`` (explicitly flagged as multiple use)
What's the use case for a multiple use Requires-Python? Are Multiple
uses OR'd while single use but comma seperated AND'd? 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://mail.python.org/pipermail/distutils-sig/attachments/20130203/ac2e06fc/attachment-0001.html>