updated with latest feedback + PEP 345 changes
This commit is contained in:
Tarek Ziadé
parent
1c4110d282
commit
2b2e353c74
69
pep-0386.txt
69
pep-0386.txt
|
|
@ -19,22 +19,29 @@ Distutils.
|
|||
Motivation
|
||||
==========
|
||||
|
||||
Distutils will soon extend the metadata standard, by including the
|
||||
`install_requires` field from Setuptools [#requires]_ among other changes.
|
||||
Distutils will soon extend the metadata standard, by including an
|
||||
``install_requires``-like field from Setuptools [#requires]_ among
|
||||
other changes. This field will be called ``Requires-Dist``.
|
||||
|
||||
These changes are a work in progress in PEP 345 [#pep345]_, but validating
|
||||
the current PEP is mandatory to continue the work.
|
||||
These changes are located in PEP 345 [#pep345]_.
|
||||
|
||||
The `install_requires` field will allow a package to define a dependency on
|
||||
another package and optionally restrict this dependency to a set of
|
||||
compatible versions.
|
||||
The ``Requires-Dist`` field will allow a package to define a dependency on
|
||||
another package and optionally restrict this dependency to a set of
|
||||
compatible versions, so one may write::
|
||||
|
||||
Requires-Dist: zope.interface (>3.5.0)
|
||||
|
||||
This means that the distribution requires ``zope.interface``, as long as its
|
||||
version is superior to ``3.5.0``.
|
||||
|
||||
That's why Distutils needs to provide a robust standard and reference
|
||||
implementation to compare versions numbers.
|
||||
version scheme, and an API to provide version comparisons.
|
||||
|
||||
This will also provide to the community a convention for their package
|
||||
versioning needs.
|
||||
This PEP describes a new version scheme that will be added in Distutils.
|
||||
|
||||
Of course developers are **not** required to conform to this scheme, but
|
||||
it is suggested to use it as a standard for interoperability between the
|
||||
existing Python distributions installers.
|
||||
|
||||
Current status
|
||||
==============
|
||||
|
|
@ -246,12 +253,11 @@ The new versioning algorithm
|
|||
During Pycon, members of the Python, Ubuntu and Fedora community worked on
|
||||
a version standard that would be acceptable for everyone.
|
||||
|
||||
It's currently called `verlib` and a prototype lives here :
|
||||
http://bitbucket.org/tarek/distutilsversion/src/
|
||||
It's currently called `verlib` and a prototype lives at [#prototype]_.
|
||||
|
||||
The pseudo-format supported is::
|
||||
|
||||
N.N[.N]+[abc]N[.N]+[.postN+][.devN+]
|
||||
N.N[.N]+[abc]N[.N]+[.postN+][.devN+]
|
||||
|
||||
Some examples probably make it clearer::
|
||||
|
||||
|
|
@ -267,16 +273,19 @@ Some examples probably make it clearer::
|
|||
... < V('1.0c1')
|
||||
... < V('1.0.dev456')
|
||||
... < V('1.0')
|
||||
... < V('1.0.post623.dev456')
|
||||
... < V('1.0.post456.dev34')
|
||||
... < V('1.0.post456'))
|
||||
True
|
||||
|
||||
The trailing ".dev123" is for pre-releases. The ".post123" is for
|
||||
The trailing ``.dev123`` is for pre-releases. The ``.post123`` is for
|
||||
post-releases -- which apparently is used by a number of projects out there
|
||||
(e.g. Twisted [#twisted]_). For example *after* a "1.2.0" release there might
|
||||
be a "1.2.0-r678" release. We used "post" instead of "r" because the "r" is
|
||||
ambiguous as to whether it indicates a pre- or post-release.
|
||||
Last ".post623.dev456" is a development version of a post-release.
|
||||
(e.g. Twisted [#twisted]_). For example *after* a ``1.2.0`` release there might
|
||||
be a ``1.2.0-r678`` release. We used ``post`` instead of ``r`` because the
|
||||
``r`` is ambiguous as to whether it indicates a pre- or post-release.
|
||||
|
||||
Last, ``.post456.dev34`` indicates a dev parker for a post release, that sorts
|
||||
before a ``.post345`` marker. This can be used to do development versions
|
||||
of post releases.
|
||||
|
||||
``verlib`` provides a ``RationalVersion`` class and a
|
||||
``suggest_rational_version`` function.
|
||||
|
|
@ -310,7 +319,6 @@ Each part is a tuple and there are three parts:
|
|||
|
||||
- the main version part
|
||||
- the pre-release part
|
||||
- the `postdev` marker part
|
||||
|
||||
Examples ::
|
||||
|
||||
|
|
@ -326,10 +334,22 @@ Examples ::
|
|||
>>> str(version)
|
||||
'1.0c4.dev34'
|
||||
|
||||
|
||||
suggest_rational_version
|
||||
------------------------
|
||||
|
||||
XXX explain here suggest_rational_version
|
||||
``suggest_rational_version`` is a function that suggests a rational version
|
||||
close to the given version string. If you have a version string that isn't
|
||||
rational (i.e. ``RationalVersion`` doesn't like it) then you might be able
|
||||
to get an equivalent (or close) rational version from this function.
|
||||
|
||||
This does a number of simple normalizations to the given string, based
|
||||
on observation of versions currently in use on PyPI. Given a dump of those
|
||||
version during PyCon 2009, 4287 of them:
|
||||
|
||||
- 2312 (53.93%) match RationalVersion without change with the automatic
|
||||
suggestion
|
||||
- 3474 (81.04%) match when using this suggestion method
|
||||
|
||||
|
||||
References
|
||||
|
|
@ -365,8 +385,11 @@ References
|
|||
.. [#pep345]
|
||||
http://svn.python.org/projects/peps/branches/jim-update-345/pep-0345.txt
|
||||
|
||||
Aknowledgments
|
||||
==============
|
||||
.. [#prototype]
|
||||
http://bitbucket.org/tarek/distutilsversion/
|
||||
|
||||
Acknowledgments
|
||||
===============
|
||||
|
||||
Trent Mick, Matthias Klose, Phillip Eby, and many people at Pycon and
|
||||
Distutils-SIG.
|
||||
|
|
|
|||
Loading…
Reference in New Issue