iSharkFly-Open
/
python-peps
mirror of https://github.com/python/peps.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update based on distutils-sig feedback

This commit is contained in:
Nick Coghlan 2013-05-30 00:15:30 +10:00
parent 620f079ec8
commit e2794d830b
2 changed files with 180 additions and 138 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

208
pep-0426.txt
View File

@ -310,11 +310,11 @@ fields:
* ``version_url`` * ``version_url``
* ``extras`` * ``extras``
* ``requires`` * ``requires``
* ``may-require`` * ``may_require``
* ``build-requires`` * ``build_requires``
* ``build-may-require`` * ``build_may_require``
* ``dev-requires`` * ``dev_requires``
* ``dev-may-require`` * ``dev_may_require``
* ``provides`` * ``provides``
* ``obsoleted_by`` * ``obsoleted_by``
* ``supports_environments`` * ``supports_environments``
@ -474,49 +474,49 @@ Example::
"version": "1.0a2" "version": "1.0a2"
Additional identifying metadata Source code metadata
=============================== ====================
This section specifies fields that provide other identifying details This section specifies fields that provide identifying details for the
that are unique to this distribution. source code used to produce this distribution.
All of these fields are optional. Automated tools MUST operate correctly if All of these fields are optional. Automated tools MUST operate correctly if
a distribution does not provide them, including failing cleanly when an a distribution does not provide them, including failing cleanly when an
operation depending on one of these fields is requested. operation depending on one of these fields is requested.
Build label Source label
----------- ------------
A constrained identifying text string, as defined in PEP 440. Build labels A constrained identifying text string, as defined in PEP 440. Source labels
cannot be used in ordered version comparisons, but may be used to select cannot be used in ordered version comparisons, but may be used to select
an exact version (see PEP 440 for details). an exact version (see PEP 440 for details).
Examples:: Examples::
"build_label": "1.0.0-alpha.1" "source_label": "1.0.0-alpha.1"
"build_label": "1.3.7+build.11.e0f985a" "source_label": "1.3.7+build.11.e0f985a"
"build_label": "v1.8.1.301.ga0df26f" "source_label": "v1.8.1.301.ga0df26f"
"build_label": "2013.02.17.dev123" "source_label": "2013.02.17.dev123"
Version URL Source URL
----------- ----------
A string containing a full URL where this specific version of the A string containing a full URL where the source for this specific version of
distribution can be downloaded. (This means that the URL can't be the distribution can be downloaded. (This means that the URL can't be
something like ``"https://github.com/pypa/pip/archive/master.zip"``, but something like ``"https://github.com/pypa/pip/archive/master.zip"``, but
instead must be ``"https://github.com/pypa/pip/archive/1.3.1.zip"``.) instead must be ``"https://github.com/pypa/pip/archive/1.3.1.zip"``.)
Some appropriate targets for a version URL are a source tarball, an sdist Some appropriate targets for a source URL are a source tarball, an sdist
archive or a direct reference to a tag or specific commit in an online archive or a direct reference to a tag or specific commit in an online
version control system. version control system.
All version URL references SHOULD either specify a secure transport All source URL references SHOULD either specify a secure transport
mechanism (such as ``https``) or else include an expected hash value in the mechanism (such as ``https``) or else include an expected hash value in the
URL for verification purposes. If an insecure transport is specified without URL for verification purposes. If an insecure transport is specified without
any hash information (or with hash information that the tool doesn't any hash information (or with hash information that the tool doesn't
@ -542,9 +542,9 @@ end of the URL using the ``@<tag>`` notation.
Example:: Example::
"version_url": "https://github.com/pypa/pip/archive/1.3.1.zip" "source_url": "https://github.com/pypa/pip/archive/1.3.1.zip"
"version_url": "http://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686" "source_url": "http://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6de940a148ea686"
"version_url": "git+https://github.com/pypa/pip.git@1.3.1" "source_url": "git+https://github.com/pypa/pip.git@1.3.1"
.. note:: .. note::
@ -709,10 +709,10 @@ Example::
] ]
Contact metadata Contributor metadata
================ ====================
Contact metadata for a distribution is provided to allow users to get Contributor metadata for a distribution is provided to allow users to get
access to more information about the distribution and its maintainers. access to more information about the distribution and its maintainers.
These details are recorded as mappings with the following subfields: These details are recorded as mappings with the following subfields:
@ -720,42 +720,39 @@ These details are recorded as mappings with the following subfields:
* ``name``: the name of an individual or group * ``name``: the name of an individual or group
* ``email``: an email address (this may be a mailing list) * ``email``: an email address (this may be a mailing list)
* ``url``: a URL (such as a profile page on a source code hosting service) * ``url``: a URL (such as a profile page on a source code hosting service)
* ``type``: one of ``"author"``, ``"maintainer"``, ``"organization"`` * ``role``: one of ``"author"``, ``"maintainer"`` or ``"contributor"``
or ``"individual"``
The ``name`` subfield is required, the other subfields are optional. The ``name`` subfield is required, the other subfields are optional.
If no specific contact type is stated, the default is ``individual``. If no specific role is stated, the default is ``contributor``.
The different contact types are as follows: The defined contributor roles are as follows:
* ``author``: the original creator of a distribution * ``author``: the original creator of a distribution
* ``maintainer``: the current lead contributor for a distribution, when * ``maintainer``: the current lead contributor for a distribution, when
they are not the original creator they are not the original creator
* ``individual``: any other individuals involved in the creation of the * ``contributor``: any other individuals or organizations involved in the
distribution creation of the distribution
* ``organization``: indicates that these contact details are for an
organization (formal or informal) rather than for a specific individual
.. note:: .. note::
This is admittedly a little complicated, but it's designed to replace the The contributor role field is included primarily to replace the
Author, Author-Email, Maintainer, Maintainer-Email fields from metadata Author, Author-Email, Maintainer, Maintainer-Email fields from metadata
1.2 in a way that allows those distinctions to be fully represented for 1.2 in a way that allows those distinctions to be fully represented for
lossless translation, while allowing future distributions to pretty lossless translation, while allowing future distributions to pretty
much ignore everything other than the contact/contributor distinction much ignore everything other than the contact/contributor distinction
if they so choose. if they so choose.
Contact metadata is optional. Automated tools MUST operate correctly if Contact and contributor metadata is optional. Automated tools MUST operate
a distribution does not provide them, including failing cleanly when an correctly if a distribution does not provide it, including failing cleanly
operation depending on one of these fields is requested. when an operation depending on one of these fields is requested.
Contacts Contacts
-------- --------
A list of contact entries giving the recommended contact points for getting A list of contributor entries giving the recommended contact points for
more information about the project. getting more information about the project.
The example below would be suitable for a project that was in the process The example below would be suitable for a project that was in the process
of handing over from the original author to a new lead maintainer, while of handing over from the original author to a new lead maintainer, while
@ -766,18 +763,17 @@ Example::
"contacts": [ "contacts": [
{ {
"name": "Python Packaging Authority/Distutils-SIG", "name": "Python Packaging Authority/Distutils-SIG",
"type": "organization",
"email": "distutils-sig@python.org", "email": "distutils-sig@python.org",
"url": "https://bitbucket.org/pypa/" "url": "https://bitbucket.org/pypa/"
}, },
{ {
"name": "Samantha C.", "name": "Samantha C.",
"type": "maintainer", "role": "maintainer",
"email": "dontblameme@example.org" "email": "dontblameme@example.org"
}, },
{ {
"name": "Charlotte C.", "name": "Charlotte C.",
"type": "author", "role": "author",
"email": "iambecomingasketchcomedian@example.com" "email": "iambecomingasketchcomedian@example.com"
} }
] ]
@ -786,7 +782,7 @@ Example::
Contributors Contributors
------------ ------------
A list of contact entries for other contributors not already listed as A list of contributor entries for other contributors not already listed as
current project points of contact. The subfields within the list elements current project points of contact. The subfields within the list elements
are the same as those for the main contact field. are the same as those for the main contact field.
@ -821,7 +817,7 @@ Example::
"project_urls": { "project_urls": {
"Documentation": "https://distlib.readthedocs.org" "Documentation": "https://distlib.readthedocs.org"
"Home": "https://bitbucket.org/pypa/distlib" "Home": "https://bitbucket.org/pypa/distlib"
"Source": "https://bitbucket.org/pypa/distlib/src" "Repository": "https://bitbucket.org/pypa/distlib/src"
"Tracker": "https://bitbucket.org/pypa/distlib/issues" "Tracker": "https://bitbucket.org/pypa/distlib/issues"
} }
@ -842,9 +838,10 @@ and specification scheme defined in PEP 440.
model in metadata 1.2 (which was in turn derived from the setuptools model in metadata 1.2 (which was in turn derived from the setuptools
dependency parameters). The translation is that ``dev_requires`` and dependency parameters). The translation is that ``dev_requires`` and
``build_requires`` both map to ``Setup-Requires-Dist`` ``build_requires`` both map to ``Setup-Requires-Dist``
in 1.2, while ``requires`` maps to ``Requires-Dist``. To go the other in 1.2, while ``requires`` and ``distributes`` map to ``Requires-Dist``.
way, ``Setup-Requires-Dist`` maps to ``build_requires`` and To go the other way, ``Setup-Requires-Dist`` maps to ``build_requires``
``Requires-Dist`` maps to ``requires``. and ``Requires-Dist`` maps to ``distributes`` (for exact comparisons)
and ``requires`` (for all other version specifiers).
All of these fields are optional. Automated tools MUST operate correctly if All of these fields are optional. Automated tools MUST operate correctly if
a distribution does not provide them, by assuming that a missing field a distribution does not provide them, by assuming that a missing field
@ -923,6 +920,7 @@ should be installed for the specified activities:
* Deployment dependencies: * Deployment dependencies:
* ``distributes``
* ``requires`` * ``requires``
* ``may_require`` * ``may_require``
* Request the ``test`` extra to also install * Request the ``test`` extra to also install
@ -937,6 +935,7 @@ should be installed for the specified activities:
* Development dependencies: * Development dependencies:
* ``distributes``
* ``requires`` * ``requires``
* ``may_require`` * ``may_require``
* ``build_requires`` * ``build_requires``
@ -946,6 +945,7 @@ should be installed for the specified activities:
* ``dev_requires`` * ``dev_requires``
* ``dev_may_require`` * ``dev_may_require``
To ease compatibility with existing two phase setup/deployment toolchains, To ease compatibility with existing two phase setup/deployment toolchains,
installation tools MAY treat ``dev_requires`` and ``dev_may_require`` as installation tools MAY treat ``dev_requires`` and ``dev_may_require`` as
additions to ``build_requires`` and ``build_may_require`` rather than additions to ``build_requires`` and ``build_may_require`` rather than
@ -958,6 +958,8 @@ operations for a named distribution:
* Install just the build dependencies without installing the distribution * Install just the build dependencies without installing the distribution
* Install just the development dependencies without installing * Install just the development dependencies without installing
the distribution the distribution
* Install just the development dependencies without installing
the distribution or any dependencies listed in ``distributes``
The notation described in `Extras (optional dependencies)`_ SHOULD be used to The notation described in `Extras (optional dependencies)`_ SHOULD be used to
request additional optional dependencies when installing deployment request additional optional dependencies when installing deployment
@ -973,10 +975,10 @@ installation to proceed regardless.
example project without any extras defined is split into 2 RPMs example project without any extras defined is split into 2 RPMs
in a SPEC file: example and example-devel in a SPEC file: example and example-devel
The ``requires`` and applicable ``may_require`` dependencies would be The ``distributes``, ``requires`` and applicable ``may_require``
mapped to the Requires dependencies for the "example" RPM (a mapping from dependencies would be mapped to the Requires dependencies for the
environment markers to SPEC file conditions would also allow those to "example" RPM (a mapping from environment markers to SPEC file
be handled correctly) conditions would also allow those to be handled correctly)
The ``build_requires`` and ``build_may_require`` dependencies would be The ``build_requires`` and ``build_may_require`` dependencies would be
mapped to the BuildRequires dependencies for the "example" RPM. mapped to the BuildRequires dependencies for the "example" RPM.
@ -997,11 +999,29 @@ installation to proceed regardless.
to map it to an appropriate dependency in the spec file. to map it to an appropriate dependency in the spec file.
Distributes
-----------
A list of subdistributions that can easily be installed and used together
by depending on this metadistribution.
Automated tools MUST allow strict version matching and source reference
clauses in this field and MUST NOT allow more permissive version specifiers.
Example::
"distributes": ["ComfyUpholstery (== 1.0a2)",
"ComfySeatCushion (== 1.0a2)"]
Requires Requires
-------- --------
A list of other distributions needed when this distribution is deployed. A list of other distributions needed when this distribution is deployed.
Automated tools MAY disallow strict version matching clauses and source
references in this field and SHOULD at least emit a warning for such clauses.
Example:: Example::
"requires": ["SciPy", "PasteDeploy", "zope.interface (>3.5.0)"] "requires": ["SciPy", "PasteDeploy", "zope.interface (>3.5.0)"]
@ -1032,6 +1052,9 @@ environment.
Any extras referenced from this field MUST be named in the `Extras`_ field. Any extras referenced from this field MUST be named in the `Extras`_ field.
Automated tools MAY disallow strict version matching clauses and source
references in this field and SHOULD at least emit a warning for such clauses.
Example:: Example::
"may_require": [ "may_require": [
@ -1052,6 +1075,9 @@ A list of other distributions needed in order to run the automated tests
for this distribution, either during development or when running the for this distribution, either during development or when running the
``test_installed_dist`` metabuild when deployed. ``test_installed_dist`` metabuild when deployed.
Automated tools MAY disallow strict version matching clauses and source
references in this field and SHOULD at least emit a warning for such clauses.
Example:: Example::
"test_requires": ["unittest2"] "test_requires": ["unittest2"]
@ -1067,6 +1093,9 @@ extras requested and the target deployment environment.
Any extras referenced from this field MUST be named in the `Extras`_ field. Any extras referenced from this field MUST be named in the `Extras`_ field.
Automated tools MAY disallow strict version matching clauses and source
references in this field and SHOULD at least emit a warning for such clauses.
Example:: Example::
"test_may_require": [ "test_may_require": [
@ -1090,6 +1119,9 @@ A list of other distributions needed when this distribution is being built
Note that while these are build dependencies for the distribution being Note that while these are build dependencies for the distribution being
built, the installation is a *deployment* scenario for the dependencies. built, the installation is a *deployment* scenario for the dependencies.
Automated tools MAY disallow strict version matching clauses and source
references in this field and SHOULD at least emit a warning for such clauses.
Example:: Example::
"build_requires": ["setuptools (>= 0.7)"] "build_requires": ["setuptools (>= 0.7)"]
@ -1110,6 +1142,9 @@ Any extras referenced from this field MUST be named in the `Extras`_ field.
Automated tools MAY assume that all extras are implicitly requested when Automated tools MAY assume that all extras are implicitly requested when
installing build dependencies. installing build dependencies.
Automated tools MAY disallow strict version matching clauses and source
references in this field and SHOULD at least emit a warning for such clauses.
Example:: Example::
"build_may_require": [ "build_may_require": [
@ -1141,6 +1176,9 @@ Additional dependencies that may be listed in this field include:
example, tests that require a local database server and web server and example, tests that require a local database server and web server and
may not work when fully installed on a production system) may not work when fully installed on a production system)
Automated tools MAY disallow strict version matching clauses and source
references in this field and SHOULD at least emit a warning for such clauses.
Example:: Example::
"dev_requires": ["hgtools", "sphinx (>= 1.0)"] "dev_requires": ["hgtools", "sphinx (>= 1.0)"]
@ -1161,6 +1199,9 @@ Any extras referenced from this field MUST be named in the `Extras`_ field.
Automated tools MAY assume that all extras are implicitly requested when Automated tools MAY assume that all extras are implicitly requested when
installing development dependencies. installing development dependencies.
Automated tools MAY disallow strict version matching clauses and source
references in this field and SHOULD at least emit a warning for such clauses.
Example:: Example::
"dev_may_require": [ "dev_may_require": [
@ -1295,7 +1336,7 @@ Example metabuild hooks::
"metabuild_hooks": { "metabuild_hooks": {
"postinstall": "myproject.build_hooks:postinstall", "postinstall": "myproject.build_hooks:postinstall",
"preuininstall": "myproject.build_hooks:preuninstall", "preuininstall": "myproject.build_hooks:preuninstall",
"test_installed_dist": "some_test_harness.metabuild_hook" "test_installed_dist": "some_test_harness:metabuild_hook"
} }
Build and installation tools MAY offer additional operations beyond the Build and installation tools MAY offer additional operations beyond the
@ -1484,7 +1525,8 @@ for grouping.
The pseudo-grammar is :: The pseudo-grammar is ::
MARKER: EXPR [(and|or) EXPR]* MARKER: EXPR [(and|or) EXPR]*
EXPR: ("(" MARKER ")") | (SUBEXPR [(in|==|!=|not in) SUBEXPR]) EXPR: ("(" MARKER ")") | (SUBEXPR [CMPOP SUBEXPR])
CMPOP: (==|!=|<|>|<=|>=|in|not in)
where ``SUBEXPR`` is either a Python string (such as ``'2.4'``, or where ``SUBEXPR`` is either a Python string (such as ``'2.4'``, or
``'win32'``) or one of the following marker variables: ``'win32'``) or one of the following marker variables:
@ -1493,17 +1535,18 @@ where ``SUBEXPR`` is either a Python string (such as ``'2.4'``, or
* ``python_full_version``: see definition below * ``python_full_version``: see definition below
* ``os_name````: ``os.name`` * ``os_name````: ``os.name``
* ``sys_platform````: ``sys.platform`` * ``sys_platform````: ``sys.platform``
* ``platform_release``: ``platform.release()``
* ``platform_version``: ``platform.version()`` * ``platform_version``: ``platform.version()``
* ``platform_machine``: ``platform.machine()`` * ``platform_machine``: ``platform.machine()``
* ``platform_python_implementation``: ``platform.python_implementation()`` * ``platform_python_implementation``: ``platform.python_implementation()``
Note that all subexpressions are restricted to strings or one of the Note that all subexpressions are restricted to strings or one of the
marker variable names, meaning that it is not possible to use other marker variable names (which refer to string values), meaning that it is
sequences like tuples or lists on the right side of the ``in`` and not possible to use other sequences like tuples or lists on the right
``not in`` operators. side of the ``in`` and ``not in`` operators.
Unlike Python, chaining of comparison operations is NOT permitted in Chaining of comparison operations is permitted using the normal Python
environment markers. semantics of an implied ``and``.
The ``python_full_version`` marker variable is derived from The ``python_full_version`` marker variable is derived from
``sys.version_info()`` in accordance with the following algorithm:: ``sys.version_info()`` in accordance with the following algorithm::
@ -1516,7 +1559,6 @@ The ``python_full_version`` marker variable is derived from
version += kind[0] + str(info.serial) version += kind[0] + str(info.serial)
return version return version
Updating the metadata specification Updating the metadata specification
=================================== ===================================
@ -1653,7 +1695,7 @@ Development, build and deployment dependencies
---------------------------------------------- ----------------------------------------------
The separation of the ``requires``, ``build_requires`` and ``dev_requires`` The separation of the ``requires``, ``build_requires`` and ``dev_requires``
fields allow a distribution to indicate whether a dependency is needed fields allows a distribution to indicate whether a dependency is needed
specifically to develop, build or deploy the distribution. specifically to develop, build or deploy the distribution.
As distribution metadata improves, this should allow much greater control As distribution metadata improves, this should allow much greater control
@ -1696,7 +1738,7 @@ Support for metabuild hooks
--------------------------- ---------------------------
The new metabuild system is designed to allow the wheel format to fully The new metabuild system is designed to allow the wheel format to fully
replace direct installation on deployment targets, by allows projects like replace direct installation on deployment targets, by allowing projects like
Twisted to still execute code following installation from a wheel file. Twisted to still execute code following installation from a wheel file.
Falling back to invoking ``setup.py`` directly rather than using a Falling back to invoking ``setup.py`` directly rather than using a
@ -1704,23 +1746,35 @@ metabuild hook will remain an option when relying on version 1.x metadata,
and is also used as the interim solution for installation from source and is also used as the interim solution for installation from source
archives. archives.
The ``test_installed_dist`` metabuild hook is included as a complement to The ``test_installed_dist`` metabuild hook is included in order to integrate
the ability to explicitly specify test dependencies. with build systems that can automatically invoke test suites, and as
a complement to the ability to explicitly specify test dependencies.
Changes to environment markers Changes to environment markers
------------------------------ ------------------------------
The changes to environment markers were just clarifications and There are three substantive changes to environment markers in this version::
* ``platform_release`` was added, as it provides more useful information
than ``platform_version`` on at least Linux and Mac OS X (specifically,
it provides details of the running kernel version)
* ordered comparison of strings is allowed, as this is more useful for
setting minimum and maximum versions where conditional dependencies
are needed or where a platform is supported
* comparison chaining is explicitly allowed, as this becomes useful in the
presence of ordered comparisons
The other changes to environment markers are just clarifications and
simplifications to make them easier to use. simplifications to make them easier to use.
The arbitrariness of the choice of ``.`` and ``_`` in the different The arbitrariness of the choice of ``.`` and ``_`` in the different
variables was addressed by standardising on ``_`` (as these are predefined variables was addressed by standardising on ``_`` (as these are all
variables rather than live references into the Python module namespace) predefined variables rather than live references into the Python module
namespace)
The use of parentheses for grouping and the disallowance of chained The use of parentheses for grouping was explicitly noted to address some
comparisons were added to address some underspecified behaviour in the underspecified behaviour in the previous version of the specification.
previous version of the specification.
Updated contact information Updated contact information
@ -1854,7 +1908,7 @@ Metadata 2.0 deliberately focuses on wheel based installation, leaving
tarball and sdist based installation to use the existing ``setup.py`` tarball and sdist based installation to use the existing ``setup.py``
based ``distutils`` command interface. based ``distutils`` command interface.
In the meantime, the above four operations will continue to be handled In the meantime, the above three operations will continue to be handled
through the ``distutils``/``setuptools`` command system: through the ``distutils``/``setuptools`` command system:
* ``python setup.py dist_info`` * ``python setup.py dist_info``
@ -1870,8 +1924,7 @@ cover these operations without relying on ``setup.py``:
archive archive
Tentative signatures have been designed for those hooks, but they will Tentative signatures have been designed for those hooks, but they will
not be pursued further until 2.1 (note that the current signatures for not be pursued further until 2.1::
the hooks do *not* adequately handle the "extras" concept)::
def make_dist_info(source_dir, info_dir): def make_dist_info(source_dir, info_dir):
"""Generate the contents of dist_info for an sdist archive """Generate the contents of dist_info for an sdist archive
@ -1912,6 +1965,11 @@ the hooks do *not* adequately handle the "extras" concept)::
Returns the actual compatibility tag for the build Returns the actual compatibility tag for the build
""" """
As with the existing metabuild hooks, checking for extras would be done
using the same import based checks as are used for runtime extras. That
way it doesn't matter if the additional dependencies were requested
explicitly or just happen to be available on the system.
Rejected Features Rejected Features
================= =================

110
pep-0440.txt
View File

@ -99,18 +99,18 @@ Any given version will be a "release", "pre-release", "post-release" or
sections. sections.
Build labels Source labels
------------ -------------
Build labels are text strings with minimal defined semantics. Source labels are text strings with minimal defined semantics.
To ensure build labels can be readily incorporated as part of file names To ensure source labels can be readily incorporated as part of file names
and URLs, they MUST be comprised of only ASCII alphanumerics, plus signs, and URLs, they MUST be comprised of only ASCII alphanumerics, plus signs,
periods and hyphens. periods and hyphens.
In addition, build labels MUST be unique within a given distribution. In addition, source labels MUST be unique within a given distribution.
As with distribution names, all comparisons of build labels MUST be case As with distribution names, all comparisons of source labels MUST be case
insensitive. insensitive.
@ -444,7 +444,7 @@ Compatibility with other version schemes
Some projects may choose to use a version scheme which requires Some projects may choose to use a version scheme which requires
translation in order to comply with the public version scheme defined in translation in order to comply with the public version scheme defined in
this PEP. In such cases, the build label can be used to this PEP. In such cases, the source label can be used to
record the project specific version as an arbitrary label, while the record the project specific version as an arbitrary label, while the
translated public version is published in the version field. translated public version is published in the version field.
@ -488,7 +488,7 @@ identifier. As hashes cannot be ordered reliably such versions are not
permitted in the public version field. permitted in the public version field.
As with semantic versioning, the public ``.devN`` suffix may be used to As with semantic versioning, the public ``.devN`` suffix may be used to
uniquely identify such releases for publication, while the build label is uniquely identify such releases for publication, while the source label is
used to record the original DVCS based version label. used to record the original DVCS based version label.
@ -496,7 +496,7 @@ Date based versions
~~~~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~~~~
As with other incompatible version schemes, date based versions can be As with other incompatible version schemes, date based versions can be
stored in the build label field. Translating them to a compliant stored in the source label field. Translating them to a compliant
public version is straightforward: use a leading ``"0."`` prefix in the public version is straightforward: use a leading ``"0."`` prefix in the
public version label, with the date based version number as the remaining public version label, with the date based version number as the remaining
components in the release segment. components in the release segment.
@ -521,7 +521,7 @@ clause:
* ``~=``: `Compatible release`_ clause * ``~=``: `Compatible release`_ clause
* ``==``: `Version matching`_ clause * ``==``: `Version matching`_ clause
* ``!=``: `Version exclusion`_ clause * ``!=``: `Version exclusion`_ clause
* ``is``: `Build reference`_ clause * ``is``: `Source reference`_ clause
* ``<=``, ``>=``: `Inclusive ordered comparison`_ clause * ``<=``, ``>=``: `Inclusive ordered comparison`_ clause
* ``<``, ``>``: `Exclusive ordered comparison`_ clause * ``<``, ``>``: `Exclusive ordered comparison`_ clause
@ -626,10 +626,6 @@ comparison operator is intended primarily for use when defining
dependencies for repeatable *deployments of applications* while using dependencies for repeatable *deployments of applications* while using
a shared distribution index. a shared distribution index.
Publication tools and index servers SHOULD at least emit a warning when
dependencies are pinned in this fashion and MAY refuse to allow publication
of such overly specific dependencies.
Version exclusion Version exclusion
----------------- -----------------
@ -649,43 +645,44 @@ match or not as shown::
!= 1.1.* # Same prefix, so 1.1.post1 does not match clause != 1.1.* # Same prefix, so 1.1.post1 does not match clause
Build reference Source reference
--------------- ----------------
A build reference includes the build reference operator ``is`` and A source reference includes the source reference operator ``is`` and
a build label or a build URL. a source label or a source URL.
Publication tools and public index servers SHOULD NOT permit build Installation tools MAY also permit direct references to a platform
references in dependency specifications. appropriate binary archive in a source reference clause.
Installation tools SHOULD support the use of build references to identify Publication tools and public index servers SHOULD NOT permit direct
dependencies. references to a platform appropriate binary archive in a source
reference clause.
Build label matching works solely on strict equality comparisons: the Source label matching works solely on strict equality comparisons: the
candidate build label must be exactly the same as the build label in the candidate source label must be exactly the same as the source label in the
version clause for the clause to match the candidate distribution. version clause for the clause to match the candidate distribution.
For example, a build reference could be used to depend on a ``hashdist`` For example, a source reference could be used to depend directly on a
generated build of ``zlib`` with the ``hashdist`` hash used as a build version control hash based identifier rather than the translated public
label:: version::
zlib (is d4jwf2sb2g6glprsdqfdpcracwpzujwq) exact-dependency (is 1.3.7+build.11.e0f985a)
A build URL is distinguished from a build label by the presence of A source URL is distinguished from a source label by the presence of
``:`` and ``/`` characters in the build reference. As these characters ``:`` and ``/`` characters in the source reference. As these characters
are not permitted in build labels, they indicate that the reference uses are not permitted in source labels, they indicate that the reference uses
a build URL. a source URL.
Some appropriate targets for a build URL are a binary archive, a Some appropriate targets for a source URL are a source tarball, an sdist
source tarball, an sdist archive or a direct reference to a tag or archive or a direct reference to a tag or specific commit in an online
specific commit in an online version control system. The exact URLs and version control system. The exact URLs and
targets supported will be installation tool specific. targets supported will be installation tool specific.
For example, a local prebuilt wheel file may be referenced directly:: For example, a local source archive may be referenced directly::
exampledist (is file:///localbuilds/exampledist-1.0-py33-none-any.whl) pip (is file:///localbuilds/pip-1.3.1.zip)
All build URL references SHOULD either specify a local file URL, a secure All source URL references SHOULD either specify a local file URL, a secure
transport mechanism (such as ``https``) or else include an expected hash transport mechanism (such as ``https``) or else include an expected hash
value in the URL for verification purposes. If an insecure network value in the URL for verification purposes. If an insecure network
transport is specified without any hash information (or with hash transport is specified without any hash information (or with hash
@ -698,7 +695,7 @@ for source archive hashes. At time of writing, that list consists of
``'md5'``, ``'sha1'``, ``'sha224'``, ``'sha256'``, ``'sha384'``, and ``'md5'``, ``'sha1'``, ``'sha224'``, ``'sha256'``, ``'sha384'``, and
``'sha512'``. ``'sha512'``.
For binary or source archive references, an expected hash value may be For source archive references, an expected hash value may be
specified by including a ``<hash-algorithm>=<expected-hash>`` as part of specified by including a ``<hash-algorithm>=<expected-hash>`` as part of
the URL fragment. the URL fragment.
@ -711,7 +708,7 @@ end of the URL using the ``@<tag>`` notation.
The use of ``is`` when defining dependencies for published distributions The use of ``is`` when defining dependencies for published distributions
is strongly discouraged as it greatly complicates the deployment of is strongly discouraged as it greatly complicates the deployment of
security fixes. The build label matching operator is intended primarily security fixes. The source label matching operator is intended primarily
for use when defining dependencies for repeatable *deployments of for use when defining dependencies for repeatable *deployments of
applications* while using a shared distribution index, as well as to applications* while using a shared distribution index, as well as to
reference dependencies which are not published through an index server. reference dependencies which are not published through an index server.
@ -823,31 +820,18 @@ Actually changing the version comparison semantics still requires a new
versioning scheme and metadata version defined in new PEPs. versioning scheme and metadata version defined in new PEPs.
Open issues
===========
* The new ``is`` operator seems like a reasonable way to cleanly allow
installation tools to bring in non-published dependencies, while heavily
discouraging the practice for published libraries. It also makes
build labels more useful by allowing them to be used to pin dependencies
in the integration use case.
However, it's an early draft of the idea, so feedback is definitely
welcome.
Summary of differences from \PEP 386 Summary of differences from \PEP 386
==================================== ====================================
* Moved the description of version specifiers into the versioning PEP * Moved the description of version specifiers into the versioning PEP
* added the "build label" concept to better handle projects that wish to * added the "source label" concept to better handle projects that wish to
use a non-compliant versioning scheme internally, especially those based use a non-compliant versioning scheme internally, especially those based
on DVCS hashes on DVCS hashes
* added the "compatible release" clause * added the "compatible release" clause
* added the "build reference" clause * added the "source reference" clause
* added the trailing wildcard syntax for prefix based version matching * added the trailing wildcard syntax for prefix based version matching
and exclusion and exclusion
@ -869,10 +853,10 @@ Summary of differences from \PEP 386
The rationale for major changes is given in the following sections. The rationale for major changes is given in the following sections.
Adding build labels Adding source labels
------------------- -------------------
The new build label support is intended to make it clearer that the The new source label support is intended to make it clearer that the
constraints on public version identifiers are there primarily to aid in constraints on public version identifiers are there primarily to aid in
the creation of reliable automated dependency analysis tools. Projects the creation of reliable automated dependency analysis tools. Projects
are free to use whatever versioning scheme they like internally, so long are free to use whatever versioning scheme they like internally, so long
@ -1041,12 +1025,12 @@ added to make it possible to sensibly define both compatible release clauses
and the desired pre-release handling semantics for ``<`` and ``>`` ordered and the desired pre-release handling semantics for ``<`` and ``>`` ordered
comparison clauses. comparison clauses.
Build references are added for two purposes. In conjunction with build Source references are added for two purposes. In conjunction with source
labels, they allow hash based references, such as those employed by labels, they allow hash based references to exact versions that aren't
`hashdist <http://hashdist.readthedocs.org/en/latest/build_spec.html>`__, compliant with the fully ordered public version scheme, such as those
or generated from version control. In conjunction with build URLs, they generated from version control. In combination with source URLs, they
allow the new metadata standard to natively support an existing feature of also allow the new metadata standard to natively support an existing
``pip``, which allows arbitrary URLs like feature of ``pip``, which allows arbitrary URLs like
``file:///localbuilds/exampledist-1.0-py33-none-any.whl``. ``file:///localbuilds/exampledist-1.0-py33-none-any.whl``.