http://hg.python.org/peps/rev/a561f851473c changeset: 4916:a561f851473c user: Nick Coghlan <ncoghlan@gmail.com> date: Thu May 30 00:15:30 2013 +1000 summary: Update based on distutils-sig feedback files: pep-0426.txt | 232 ++++++++++++++++++++++++-------------- pep-0440.txt | 110 +++++++---------- 2 files changed, 192 insertions(+), 150 deletions(-) diff --git a/pep-0426.txt b/pep-0426.txt --- a/pep-0426.txt +++ b/pep-0426.txt @@ -310,11 +310,11 @@ * ``version_url`` * ``extras`` * ``requires`` -* ``may-require`` -* ``build-requires`` -* ``build-may-require`` -* ``dev-requires`` -* ``dev-may-require`` +* ``may_require`` +* ``build_requires`` +* ``build_may_require`` +* ``dev_requires`` +* ``dev_may_require`` * ``provides`` * ``obsoleted_by`` * ``supports_environments`` @@ -474,49 +474,49 @@ "version": "1.0a2" -Additional identifying metadata -=============================== - -This section specifies fields that provide other identifying details -that are unique to this distribution. +Source code metadata +==================== + +This section specifies fields that provide identifying details for the +source code used to produce this distribution. All of these fields are optional. Automated tools MUST operate correctly if a distribution does not provide them, including failing cleanly when an operation depending on one of these fields is requested. -Build label ------------ - -A constrained identifying text string, as defined in PEP 440. Build labels +Source label +------------ + +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 an exact version (see PEP 440 for details). Examples:: - "build_label": "1.0.0-alpha.1" - - "build_label": "1.3.7+build.11.e0f985a" - - "build_label": "v1.8.1.301.ga0df26f" - - "build_label": "2013.02.17.dev123" - - -Version URL ------------ - -A string containing a full URL where this specific version of the -distribution can be downloaded. (This means that the URL can't be + "source_label": "1.0.0-alpha.1" + + "source_label": "1.3.7+build.11.e0f985a" + + "source_label": "v1.8.1.301.ga0df26f" + + "source_label": "2013.02.17.dev123" + + +Source URL +---------- + +A string containing a full URL where the source for this specific version of +the distribution can be downloaded. (This means that the URL can't be something like ``"https://github.com/pypa/pip/archive/master.zip"``, but 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 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 URL for verification purposes. If an insecure transport is specified without any hash information (or with hash information that the tool doesn't @@ -542,9 +542,9 @@ Example:: - "version_url": "https://github.com/pypa/pip/archive/1.3.1.zip" - "version_url": "http://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6..." - "version_url": "git+https://github.com/pypa/pip.git@1.3.1" + "source_url": "https://github.com/pypa/pip/archive/1.3.1.zip" + "source_url": "http://github.com/pypa/pip/archive/1.3.1.zip#sha1=da9234ee9982d4bbb3c72346a6..." + "source_url": "git+https://github.com/pypa/pip.git@1.3.1" .. note:: @@ -709,10 +709,10 @@ ] -Contact metadata -================ - -Contact metadata for a distribution is provided to allow users to get +Contributor metadata +==================== + +Contributor metadata for a distribution is provided to allow users to get access to more information about the distribution and its maintainers. These details are recorded as mappings with the following subfields: @@ -720,42 +720,39 @@ * ``name``: the name of an individual or group * ``email``: an email address (this may be a mailing list) * ``url``: a URL (such as a profile page on a source code hosting service) -* ``type``: one of ``"author"``, ``"maintainer"``, ``"organization"`` - or ``"individual"`` +* ``role``: one of ``"author"``, ``"maintainer"`` or ``"contributor"`` The ``name`` subfield is required, the other subfields are optional. -If no specific contact type is stated, the default is ``individual``. - -The different contact types are as follows: +If no specific role is stated, the default is ``contributor``. + +The defined contributor roles are as follows: * ``author``: the original creator of a distribution * ``maintainer``: the current lead contributor for a distribution, when they are not the original creator -* ``individual``: any other individuals involved in the creation of the - distribution -* ``organization``: indicates that these contact details are for an - organization (formal or informal) rather than for a specific individual +* ``contributor``: any other individuals or organizations involved in the + creation of the distribution .. 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 1.2 in a way that allows those distinctions to be fully represented for lossless translation, while allowing future distributions to pretty much ignore everything other than the contact/contributor distinction if they so choose. -Contact metadata is optional. Automated tools MUST operate correctly if -a distribution does not provide them, including failing cleanly when an -operation depending on one of these fields is requested. +Contact and contributor metadata is optional. Automated tools MUST operate +correctly if a distribution does not provide it, including failing cleanly +when an operation depending on one of these fields is requested. Contacts -------- -A list of contact entries giving the recommended contact points for getting -more information about the project. +A list of contributor entries giving the recommended contact points for +getting more information about the project. 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 @@ -766,18 +763,17 @@ "contacts": [ { "name": "Python Packaging Authority/Distutils-SIG", - "type": "organization", "email": "distutils-sig@python.org", "url": "https://bitbucket.org/pypa/" }, { "name": "Samantha C.", - "type": "maintainer", + "role": "maintainer", "email": "dontblameme@example.org" }, { "name": "Charlotte C.", - "type": "author", + "role": "author", "email": "iambecomingasketchcomedian@example.com" } ] @@ -786,7 +782,7 @@ 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 are the same as those for the main contact field. @@ -821,7 +817,7 @@ "project_urls": { "Documentation": "https://distlib.readthedocs.org" "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" } @@ -842,9 +838,10 @@ model in metadata 1.2 (which was in turn derived from the setuptools dependency parameters). The translation is that ``dev_requires`` and ``build_requires`` both map to ``Setup-Requires-Dist`` - in 1.2, while ``requires`` maps to ``Requires-Dist``. To go the other - way, ``Setup-Requires-Dist`` maps to ``build_requires`` and - ``Requires-Dist`` maps to ``requires``. + in 1.2, while ``requires`` and ``distributes`` map to ``Requires-Dist``. + To go the other way, ``Setup-Requires-Dist`` maps to ``build_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 a distribution does not provide them, by assuming that a missing field @@ -923,6 +920,7 @@ * Deployment dependencies: + * ``distributes`` * ``requires`` * ``may_require`` * Request the ``test`` extra to also install @@ -937,6 +935,7 @@ * Development dependencies: + * ``distributes`` * ``requires`` * ``may_require`` * ``build_requires`` @@ -946,6 +945,7 @@ * ``dev_requires`` * ``dev_may_require`` + To ease compatibility with existing two phase setup/deployment toolchains, installation tools MAY treat ``dev_requires`` and ``dev_may_require`` as additions to ``build_requires`` and ``build_may_require`` rather than @@ -958,6 +958,8 @@ * Install just the build dependencies without installing the distribution * Install just the development dependencies without installing 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 request additional optional dependencies when installing deployment @@ -973,10 +975,10 @@ example project without any extras defined is split into 2 RPMs in a SPEC file: example and example-devel - The ``requires`` and applicable ``may_require`` dependencies would be - mapped to the Requires dependencies for the "example" RPM (a mapping from - environment markers to SPEC file conditions would also allow those to - be handled correctly) + The ``distributes``, ``requires`` and applicable ``may_require`` + dependencies would be mapped to the Requires dependencies for the + "example" RPM (a mapping from environment markers to SPEC file + conditions would also allow those to be handled correctly) The ``build_requires`` and ``build_may_require`` dependencies would be mapped to the BuildRequires dependencies for the "example" RPM. @@ -997,11 +999,29 @@ 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 -------- 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:: "requires": ["SciPy", "PasteDeploy", "zope.interface (>3.5.0)"] @@ -1032,6 +1052,9 @@ 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:: "may_require": [ @@ -1052,6 +1075,9 @@ for this distribution, either during development or when running the ``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:: "test_requires": ["unittest2"] @@ -1067,6 +1093,9 @@ 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:: "test_may_require": [ @@ -1090,6 +1119,9 @@ Note that while these are build dependencies for the distribution being 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:: "build_requires": ["setuptools (>= 0.7)"] @@ -1110,6 +1142,9 @@ Automated tools MAY assume that all extras are implicitly requested when 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:: "build_may_require": [ @@ -1141,6 +1176,9 @@ example, tests that require a local database server and web server and 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:: "dev_requires": ["hgtools", "sphinx (>= 1.0)"] @@ -1161,6 +1199,9 @@ Automated tools MAY assume that all extras are implicitly requested when 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:: "dev_may_require": [ @@ -1295,7 +1336,7 @@ "metabuild_hooks": { "postinstall": "myproject.build_hooks:postinstall", "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 @@ -1484,7 +1525,8 @@ The pseudo-grammar is :: 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 ``'win32'``) or one of the following marker variables: @@ -1493,17 +1535,18 @@ * ``python_full_version``: see definition below * ``os_name````: ``os.name`` * ``sys_platform````: ``sys.platform`` +* ``platform_release``: ``platform.release()`` * ``platform_version``: ``platform.version()`` * ``platform_machine``: ``platform.machine()`` * ``platform_python_implementation``: ``platform.python_implementation()`` Note that all subexpressions are restricted to strings or one of the -marker variable names, meaning that it is not possible to use other -sequences like tuples or lists on the right side of the ``in`` and -``not in`` operators. - -Unlike Python, chaining of comparison operations is NOT permitted in -environment markers. +marker variable names (which refer to string values), meaning that it is +not possible to use other sequences like tuples or lists on the right +side of the ``in`` and ``not in`` operators. + +Chaining of comparison operations is permitted using the normal Python +semantics of an implied ``and``. The ``python_full_version`` marker variable is derived from ``sys.version_info()`` in accordance with the following algorithm:: @@ -1516,7 +1559,6 @@ version += kind[0] + str(info.serial) return version - Updating the metadata specification =================================== @@ -1653,7 +1695,7 @@ ---------------------------------------------- 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. As distribution metadata improves, this should allow much greater control @@ -1696,7 +1738,7 @@ --------------------------- 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. Falling back to invoking ``setup.py`` directly rather than using a @@ -1704,23 +1746,35 @@ and is also used as the interim solution for installation from source archives. -The ``test_installed_dist`` metabuild hook is included as a complement to -the ability to explicitly specify test dependencies. +The ``test_installed_dist`` metabuild hook is included in order to integrate +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 ------------------------------ -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. The arbitrariness of the choice of ``.`` and ``_`` in the different -variables was addressed by standardising on ``_`` (as these are predefined -variables rather than live references into the Python module namespace) - -The use of parentheses for grouping and the disallowance of chained -comparisons were added to address some underspecified behaviour in the -previous version of the specification. +variables was addressed by standardising on ``_`` (as these are all +predefined variables rather than live references into the Python module +namespace) + +The use of parentheses for grouping was explicitly noted to address some +underspecified behaviour in the previous version of the specification. Updated contact information @@ -1854,7 +1908,7 @@ tarball and sdist based installation to use the existing ``setup.py`` 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: * ``python setup.py dist_info`` @@ -1870,8 +1924,7 @@ archive Tentative signatures have been designed for those hooks, but they will -not be pursued further until 2.1 (note that the current signatures for -the hooks do *not* adequately handle the "extras" concept):: +not be pursued further until 2.1:: def make_dist_info(source_dir, info_dir): """Generate the contents of dist_info for an sdist archive @@ -1912,6 +1965,11 @@ 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 ================= diff --git a/pep-0440.txt b/pep-0440.txt --- a/pep-0440.txt +++ b/pep-0440.txt @@ -99,18 +99,18 @@ 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, 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. @@ -444,7 +444,7 @@ Some projects may choose to use a version scheme which requires 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 translated public version is published in the version field. @@ -488,7 +488,7 @@ permitted in the public version field. 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. @@ -496,7 +496,7 @@ ~~~~~~~~~~~~~~~~~~~ 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 label, with the date based version number as the remaining components in the release segment. @@ -521,7 +521,7 @@ * ``~=``: `Compatible release`_ clause * ``==``: `Version matching`_ clause * ``!=``: `Version exclusion`_ clause -* ``is``: `Build reference`_ clause +* ``is``: `Source reference`_ clause * ``<=``, ``>=``: `Inclusive ordered comparison`_ clause * ``<``, ``>``: `Exclusive ordered comparison`_ clause @@ -626,10 +626,6 @@ dependencies for repeatable *deployments of applications* while using 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 ----------------- @@ -649,43 +645,44 @@ != 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 build label or a build URL. +A source reference includes the source reference operator ``is`` and +a source label or a source URL. -Publication tools and public index servers SHOULD NOT permit build -references in dependency specifications. +Installation tools MAY also permit direct references to a platform +appropriate binary archive in a source reference clause. -Installation tools SHOULD support the use of build references to identify -dependencies. +Publication tools and public index servers SHOULD NOT permit direct +references to a platform appropriate binary archive in a source +reference clause. -Build label matching works solely on strict equality comparisons: the -candidate build label must be exactly the same as the build label in the +Source label matching works solely on strict equality comparisons: 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. -For example, a build reference could be used to depend on a ``hashdist`` -generated build of ``zlib`` with the ``hashdist`` hash used as a build -label:: +For example, a source reference could be used to depend directly on a +version control hash based identifier rather than the translated public +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 -``:`` and ``/`` characters in the build reference. As these characters -are not permitted in build labels, they indicate that the reference uses -a build URL. +A source URL is distinguished from a source label by the presence of +``:`` and ``/`` characters in the source reference. As these characters +are not permitted in source labels, they indicate that the reference uses +a source URL. -Some appropriate targets for a build URL are a binary archive, a -source tarball, an sdist archive or a direct reference to a tag or -specific commit in an online version control system. The exact URLs and +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 +version control system. The exact URLs and 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 value in the URL for verification purposes. If an insecure network transport is specified without any hash information (or with hash @@ -698,7 +695,7 @@ ``'md5'``, ``'sha1'``, ``'sha224'``, ``'sha256'``, ``'sha384'``, and ``'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 the URL fragment. @@ -711,7 +708,7 @@ The use of ``is`` when defining dependencies for published distributions 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 applications* while using a shared distribution index, as well as to reference dependencies which are not published through an index server. @@ -823,31 +820,18 @@ 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 ==================================== * 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 on DVCS hashes * 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 and exclusion @@ -869,10 +853,10 @@ 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 the creation of reliable automated dependency analysis tools. Projects are free to use whatever versioning scheme they like internally, so long @@ -1041,12 +1025,12 @@ and the desired pre-release handling semantics for ``<`` and ``>`` ordered comparison clauses. -Build references are added for two purposes. In conjunction with build -labels, they allow hash based references, such as those employed by -`hashdist <http://hashdist.readthedocs.org/en/latest/build_spec.html>`__, -or generated from version control. In conjunction with build URLs, they -allow the new metadata standard to natively support an existing feature of -``pip``, which allows arbitrary URLs like +Source references are added for two purposes. In conjunction with source +labels, they allow hash based references to exact versions that aren't +compliant with the fully ordered public version scheme, such as those +generated from version control. In combination with source URLs, they +also allow the new metadata standard to natively support an existing +feature of ``pip``, which allows arbitrary URLs like ``file:///localbuilds/exampledist-1.0-py33-none-any.whl``. -- Repository URL: http://hg.python.org/peps