[Python-checkins] peps: PEP 440/441: reformat according to template
georg.brandl
python-checkins at python.org
Wed Apr 10 09:30:24 CEST 2013
http://hg.python.org/peps/rev/c930e4ebf844
changeset: 4847:c930e4ebf844
user: Georg Brandl <georg at python.org>
date: Wed Apr 10 09:30:46 2013 +0200
summary:
PEP 440/441: reformat according to template
files:
pep-0101.txt | 2 +-
pep-0440.txt | 853 ++++++++++++++++++++------------------
pep-0441.txt | 67 +-
3 files changed, 488 insertions(+), 434 deletions(-)
diff --git a/pep-0101.txt b/pep-0101.txt
--- a/pep-0101.txt
+++ b/pep-0101.txt
@@ -190,7 +190,7 @@
___ Check with the IE (if there is one <wink>) to be sure that
Lib/idlelib/NEWS.txt has been similarly updated.
- ___ For a final release, edit the first paragraph of
+ ___ For a final major release, edit the first paragraph of
Doc/whatsnew/X.Y.rst to include the actual release date; e.g. "Python
2.5 was released on August 1, 2003." There's no need to edit this for
alpha or beta releases. Note that Andrew Kuchling often takes care of
diff --git a/pep-0440.txt b/pep-0440.txt
--- a/pep-0440.txt
+++ b/pep-0440.txt
@@ -16,66 +16,75 @@
Abstract
========
-This PEP describes a scheme for identifying versions of Python software
-distributions, and declaring dependencies on particular versions.
+This PEP describes a scheme for identifying versions of Python
+software distributions, and declaring dependencies on particular
+versions.
-This document addresses several limitations of the previous attempt at a
-standardised approach to versioning, as described in PEP 345 and PEP 386.
+This document addresses several limitations of the previous attempt at
+a standardised approach to versioning, as described in PEP 345 and PEP
+386.
.. note::
- This PEP has been broken out of the metadata 2.0 specification in PEP 426
- and refers to some details that will be in the *next* version of PEP 426.
+ This PEP has been broken out of the metadata 2.0 specification in
+ PEP 426 and refers to some details that will be in the *next*
+ version of PEP 426.
Definitions
===========
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
-"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
+"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119.
-"Distributions" are deployable software components published through an index
-server or otherwise made available for installation.
+"Distributions" are deployable software components published through
+an index server or otherwise made available for installation.
"Versions" are uniquely identified snapshots of a distribution.
-"Distribution archives" are the packaged files which are used to publish
-and distribute the software. "Source archives" require a build system to
-be available on the target system, while "binary archives" only require that
-prebuilt files be moved to the correct location on the target system. As
-Python is a dynamically bound cross-platform language, many "binary"
-archives will contain only pure Python source code.
+"Distribution archives" are the packaged files which are used to
+publish and distribute the software. "Source archives" require a
+build system to be available on the target system, while "binary
+archives" only require that prebuilt files be moved to the correct
+location on the target system. As Python is a dynamically bound
+cross-platform language, many "binary" archives will contain only pure
+Python source code.
-"Build tools" are automated tools intended to run on development systems,
-producing source and binary distribution archives. Build tools may also be
-invoked by installation tools in order to install software distributed as
-source archives rather than prebuilt binary archives.
+"Build tools" are automated tools intended to run on development
+systems, producing source and binary distribution archives. Build
+tools may also be invoked by installation tools in order to install
+software distributed as source archives rather than prebuilt binary
+archives.
-"Index servers" are active distribution registries which publish version and
-dependency metadata and place constraints on the permitted metadata.
+"Index servers" are active distribution registries which publish
+version and dependency metadata and place constraints on the permitted
+metadata.
"Publication tools" are automated tools intended to run on development
-systems and upload source and binary distribution archives to index servers.
+systems and upload source and binary distribution archives to index
+servers.
"Installation tools" are automated tools intended to run on production
-systems, consuming source and binary distribution archives from an index
-server or other designated location and deploying them to the target system.
+systems, consuming source and binary distribution archives from an
+index server or other designated location and deploying them to the
+target system.
-"Automated tools" is a collective term covering build tools, index servers,
-publication tools, installation tools and any other software that produces
-or consumes distribution version and dependency metadata.
+"Automated tools" is a collective term covering build tools, index
+servers, publication tools, installation tools and any other software
+that produces or consumes distribution version and dependency
+metadata.
-"Projects" refers to the developers that manage the creation of a particular
-distribution.
+"Projects" refers to the developers that manage the creation of a
+particular distribution.
Version scheme
==============
-Distribution versions are identified by both a public version identifier,
-which supports all defined version comparison operations, and a build
-label, which supports only strict equality comparisons.
+Distribution versions are identified by both a public version
+identifier, which supports all defined version comparison operations,
+and a build label, which supports only strict equality comparisons.
The version scheme is used both to describe the distribution version
provided by a particular distribution archive, as well as to place
@@ -90,13 +99,14 @@
N[.N]+[{a|b|c|rc}N][.postN][.devN]
-Public version identifiers MUST NOT include leading or trailing whitespace.
+Public version identifiers MUST NOT include leading or trailing
+whitespace.
Public version identifiers MUST be unique within a given distribution.
-Installation tools SHOULD ignore any public versions which do not comply with
-this scheme. Installation tools MAY warn the user when non-compliant
-or ambiguous versions are detected.
+Installation tools SHOULD ignore any public versions which do not
+comply with this scheme. Installation tools MAY warn the user when
+non-compliant or ambiguous versions are detected.
Public version identifiers are separated into up to four segments:
@@ -105,21 +115,22 @@
* Post-release segment: ``.postN``
* Development release segment: ``.devN``
-Any given version will be a "release", "pre-release", "post-release" or
-"developmental release" as defined in the following sections.
+Any given version will be a "release", "pre-release", "post-release"
+or "developmental release" as defined in the following sections.
.. note::
- Some hard to read version identifiers are permitted by this scheme in
- order to better accommodate the wide range of versioning practices
- across existing public and private Python projects, given the
- constraint that the package index is not yet sophisticated enough to
- allow the introduction of a simpler, backwards-incompatible scheme.
+ Some hard to read version identifiers are permitted by this scheme
+ in order to better accommodate the wide range of versioning
+ practices across existing public and private Python projects, given
+ the constraint that the package index is not yet sophisticated
+ enough to allow the introduction of a simpler,
+ backwards-incompatible scheme.
Accordingly, some of the versioning practices which are technically
- permitted by the PEP are strongly discouraged for new projects. Where
- this is the case, the relevant details are noted in the following
- sections.
+ permitted by the PEP are strongly discouraged for new projects.
+ Where this is the case, the relevant details are noted in the
+ following sections.
Build labels
@@ -127,9 +138,9 @@
Build labels are text strings with minimal defined semantics.
-To ensure build labels can be readily incorporated in file names and URLs,
-they MUST be comprised of only ASCII alphanumerics, plus signs, periods
-and hyphens.
+To ensure build labels can be readily incorporated in 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.
@@ -137,31 +148,32 @@
Releases
--------
-A version identifier that consists solely of a release segment is termed
-a "release".
+A version identifier that consists solely of a release segment is
+termed a "release".
-The release segment consists of one or more non-negative integer values,
-separated by dots::
+The release segment consists of one or more non-negative integer
+values, separated by dots::
N[.N]+
Releases within a project will typically be numbered in a consistently
increasing fashion.
-Comparison and ordering of release segments considers the numeric value
-of each component of the release segment in turn. When comparing release
-segments with different numbers of components, the shorter segment is
-padded out with additional zeroes as necessary.
+Comparison and ordering of release segments considers the numeric
+value of each component of the release segment in turn. When
+comparing release segments with different numbers of components, the
+shorter segment is padded out with additional zeroes as necessary.
-Date based release numbers are technically compatible with this scheme, but
-their use is not consistent with the expected API versioning semantics
-described below. Accordingly, automated tools SHOULD at least issue a
-warning when encountering a leading release component greater than or equal
-to ``1980`` and MAY treat this case as an error.
+Date based release numbers are technically compatible with this
+scheme, but their use is not consistent with the expected API
+versioning semantics described below. Accordingly, automated tools
+SHOULD at least issue a warning when encountering a leading release
+component greater than or equal to ``1980`` and MAY treat this case as
+an error.
-While any number of additional components after the first are permitted
-under this scheme, the most common variants are to use two components
-("major.minor") or three components ("major.minor.micro").
+While any number of additional components after the first are
+permitted under this scheme, the most common variants are to use two
+components ("major.minor") or three components ("major.minor.micro").
For example::
@@ -177,26 +189,27 @@
2.0
2.0.1
-A release series is any set of release numbers that start with a common
-prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are all
-part of the ``3.3`` release series.
+A release series is any set of release numbers that start with a
+common prefix. For example, ``3.3.1``, ``3.3.5`` and ``3.3.9.45`` are
+all part of the ``3.3`` release series.
.. note::
- ``X.Y`` and ``X.Y.0`` are not considered distinct release numbers, as
- the release segment comparison rules implicit expand the two component
- form to ``X.Y.0`` when comparing it to any release segment that includes
- three components.
+ ``X.Y`` and ``X.Y.0`` are not considered distinct release numbers,
+ as the release segment comparison rules implicit expand the two
+ component form to ``X.Y.0`` when comparing it to any release
+ segment that includes three components.
Pre-releases
------------
-Some projects use an "alpha, beta, release candidate" pre-release cycle to
-support testing by their users prior to a full release.
+Some projects use an "alpha, beta, release candidate" pre-release
+cycle to support testing by their users prior to a full release.
-If used as part of a project's development cycle, these pre-releases are
-indicated by including a pre-release segment in the version identifier::
+If used as part of a project's development cycle, these pre-releases
+are indicated by including a pre-release segment in the version
+identifier::
X.YaN # Alpha release
X.YbN # Beta release
@@ -207,45 +220,47 @@
pre-release segment is termed a "pre-release".
The pre-release segment consists of an alphabetical identifier for the
-pre-release phase, along with a non-negative integer value. Pre-releases for
-a given release are ordered first by phase (alpha, beta, release candidate)
-and then by the numerical component within that phase.
+pre-release phase, along with a non-negative integer value.
+Pre-releases for a given release are ordered first by phase (alpha,
+beta, release candidate) and then by the numerical component within
+that phase.
-Build tools, publication tools and index servers SHOULD disallow the creation
-of both ``c`` and ``rc`` releases for a common release segment, but this
-may need to be tolerated in order to handle some existing legacy
-distributions.
+Build tools, publication tools and index servers SHOULD disallow the
+creation of both ``c`` and ``rc`` releases for a common release
+segment, but this may need to be tolerated in order to handle some
+existing legacy distributions.
-Installation tools SHOULD interpret all ``rc`` versions as coming after all
-``c`` versions (that is, ``rc1`` indicates a later version than ``c2``).
-Installation tools MAY warn the user when such ambiguous versions are
-detected, or even reject them entirely.
+Installation tools SHOULD interpret all ``rc`` versions as coming
+after all ``c`` versions (that is, ``rc1`` indicates a later version
+than ``c2``). Installation tools MAY warn the user when such
+ambiguous versions are detected, or even reject them entirely.
Post-releases
-------------
-Some projects use post-releases to address minor errors in a release that
-do not affect the distributed software (for example, correcting an error
-in the release notes).
+Some projects use post-releases to address minor errors in a release
+that do not affect the distributed software (for example, correcting
+an error in the release notes).
-If used as part of a project's development cycle, these post-releases are
-indicated by including a post-release segment in the version identifier::
+If used as part of a project's development cycle, these post-releases
+are indicated by including a post-release segment in the version
+identifier::
X.Y.postN # Post-release
A version identifier that includes a post-release segment without a
developmental release segment is termed a "post-release".
-The post-release segment consists of the string ``.post``, followed by a
-non-negative integer value. Post-releases are ordered by their
+The post-release segment consists of the string ``.post``, followed by
+a non-negative integer value. Post-releases are ordered by their
numerical component, immediately following the corresponding release,
and ahead of any subsequent release.
.. note::
The use of post-releases to publish maintenance releases containing
- actual bug fixes is strongly discouraged. In general, it is better
+ actual bug fixes is strongly discouraged. In general, it is better
to use a longer release number and increment the final component
for each maintenance release.
@@ -258,22 +273,22 @@
.. note::
Creating post-releases of pre-releases is strongly discouraged, as
- it makes the version identifier difficult to parse for human readers.
- In general, it is substantially clearer to simply create a new
- pre-release by incrementing the numeric component.
+ it makes the version identifier difficult to parse for human
+ readers. In general, it is substantially clearer to simply create
+ a new pre-release by incrementing the numeric component.
Developmental releases
----------------------
-Some projects make regular developmental releases, and system packagers
-(especially for Linux distributions) may wish to create early releases
-directly from source control which do not conflict with later project
-releases.
+Some projects make regular developmental releases, and system
+packagers (especially for Linux distributions) may wish to create
+early releases directly from source control which do not conflict with
+later project releases.
If used as part of a project's development cycle, these developmental
-releases are indicated by including a developmental release segment in the
-version identifier::
+releases are indicated by including a developmental release segment in
+the version identifier::
X.Y.devN # Developmental release
@@ -281,10 +296,11 @@
termed a "developmental release".
The developmental release segment consists of the string ``.dev``,
-followed by a non-negative integer value. Developmental releases are ordered
-by their numerical component, immediately before the corresponding release
-(and before any pre-releases with the same release segment), and following
-any previous release (including any post-releases).
+followed by a non-negative integer value. Developmental releases are
+ordered by their numerical component, immediately before the
+corresponding release (and before any pre-releases with the same
+release segment), and following any previous release (including any
+post-releases).
Developmental releases are also permitted for pre-releases and
post-releases::
@@ -297,24 +313,27 @@
.. note::
Creating developmental releases of pre-releases is strongly
- discouraged, as it makes the version identifier difficult to parse for
- human readers. In general, it is substantially clearer to simply create
- additional pre-releases by incrementing the numeric component.
+ discouraged, as it makes the version identifier difficult to parse
+ for human readers. In general, it is substantially clearer to
+ simply create additional pre-releases by incrementing the numeric
+ component.
- Developmental releases of post-releases are also strongly discouraged,
- but they may be appropriate for projects which use the post-release
- notation for full maintenance releases which may include code changes.
+ Developmental releases of post-releases are also strongly
+ discouraged, but they may be appropriate for projects which use the
+ post-release notation for full maintenance releases which may
+ include code changes.
Examples of compliant version schemes
-------------------------------------
The standard version scheme is designed to encompass a wide range of
-identification practices across public and private Python projects. In
-practice, a single project attempting to use the full flexibility offered
-by the scheme would create a situation where human users had difficulty
-figuring out the relative order of versions, even though the rules above
-ensure all compliant tools will order them consistently.
+identification practices across public and private Python projects.
+In practice, a single project attempting to use the full flexibility
+offered by the scheme would create a situation where human users had
+difficulty figuring out the relative order of versions, even though
+the rules above ensure all compliant tools will order them
+consistently.
The following examples illustrate a small selection of the different
approaches projects may choose to identify their releases, while still
@@ -350,8 +369,8 @@
1.1a1
...
-"major.minor" versioning with developmental releases, release candidates
-and post-releases for minor corrections::
+"major.minor" versioning with developmental releases, release
+candidates and post-releases for minor corrections::
0.9
1.0.dev1
@@ -375,9 +394,9 @@
automatically process distribution metadata, rather than developers
of Python distributions deciding on a versioning scheme.
-The release segment of version identifiers MUST be sorted in
-the same order as Python's tuple sorting when the release segment is
-parsed as follows::
+The release segment of version identifiers MUST be sorted in the same
+order as Python's tuple sorting when the release segment is parsed as
+follows::
tuple(map(int, release_segment.split(".")))
@@ -390,26 +409,28 @@
.devN, aN, bN, cN, rcN, <no suffix>, .postN
Note that `rc` will always sort after `c` (regardless of the numeric
-component) although they are semantically equivalent. Tools are free to
-reject this case as ambiguous and remain in compliance with the PEP.
+component) although they are semantically equivalent. Tools are free
+to reject this case as ambiguous and remain in compliance with the
+PEP.
Within an alpha (``1.0a1``), beta (``1.0b1``), or release candidate
-(``1.0c1``, ``1.0rc1``), the following suffixes are permitted and MUST be
-ordered as shown::
+(``1.0c1``, ``1.0rc1``), the following suffixes are permitted and MUST
+be ordered as shown::
.devN, <no suffix>, .postN
-Within a post-release (``1.0.post1``), the following suffixes are permitted
-and MUST be ordered as shown::
+Within a post-release (``1.0.post1``), the following suffixes are
+permitted and MUST be ordered as shown::
.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``).
+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 pre-release, post-release or development release segment with a
-shared prefix, ordering MUST be by the value of the numeric component.
+Within a pre-release, post-release or development release segment with
+a shared prefix, ordering MUST be by the value of the numeric
+component.
The following example covers many of the possible combinations::
@@ -433,67 +454,70 @@
Version ordering across different metadata versions
---------------------------------------------------
-Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not
-specify a standard version identification or ordering scheme. This PEP does
-not mandate any particular approach to handling such versions, but
-acknowledges that the de facto standard for ordering them is
-the scheme used by the ``pkg_resources`` component of ``setuptools``.
+Metadata v1.0 (PEP 241) and metadata v1.1 (PEP 314) do not specify a
+standard version identification or ordering scheme. This PEP does not
+mandate any particular approach to handling such versions, but
+acknowledges that the de facto standard for ordering them is the
+scheme used by the ``pkg_resources`` component of ``setuptools``.
-Software that automatically processes distribution metadata SHOULD attempt
-to normalize non-compliant version identifiers to the standard scheme, and
-ignore them if normalization fails. As any normalization scheme will be
-implementation specific, this means that projects using non-compliant
-version identifiers may not be handled consistently across different
-tools, even when correctly publishing the earlier metadata versions.
+Software that automatically processes distribution metadata SHOULD
+attempt to normalize non-compliant version identifiers to the standard
+scheme, and ignore them if normalization fails. As any normalization
+scheme will be implementation specific, this means that projects using
+non-compliant version identifiers may not be handled consistently
+across different tools, even when correctly publishing the earlier
+metadata versions.
-For distributions currently using non-compliant version identifiers, these
-filtering guidelines mean that it should be enough for the project to
-simply switch to the use of compliant version identifiers to ensure
-consistent handling by automated tools.
+For distributions currently using non-compliant version identifiers,
+these filtering guidelines mean that it should be enough for the
+project to simply switch to the use of compliant version identifiers
+to ensure consistent handling by automated tools.
-Distribution users may wish to explicitly remove non-compliant versions from
-any private package indexes they control.
+Distribution users may wish to explicitly remove non-compliant
+versions from any private package indexes they control.
-For metadata v1.2 (PEP 345), the version ordering described in this PEP
-SHOULD be used in preference to the one defined in PEP 386.
+For metadata v1.2 (PEP 345), the version ordering described in this
+PEP SHOULD be used in preference to the one defined in PEP 386.
Compatibility with other version schemes
----------------------------------------
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
-record the project specific version as an arbitrary label, while the
-translated public version is published in the version field.
+translation in order to comply with the public version scheme defined
+in this PEP. In such cases, the build 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.
-This allows automated distribution tools to provide consistently correct
-ordering of published releases, while still allowing developers to use
-the internal versioning scheme they prefer for their projects.
+This allows automated distribution tools to provide consistently
+correct ordering of published releases, while still allowing
+developers to use the internal versioning scheme they prefer for their
+projects.
Semantic versioning
~~~~~~~~~~~~~~~~~~~
-`Semantic versioning`_ is a popular version identification scheme that is
-more prescriptive than this PEP regarding the significance of different
-elements of a release number. Even if a project chooses not to abide by
-the details of semantic versioning, the scheme is worth understanding as
-it covers many of the issues that can arise when depending on other
-distributions, and when publishing a distribution that others rely on.
+`Semantic versioning`_ is a popular version identification scheme that
+is more prescriptive than this PEP regarding the significance of
+different elements of a release number. Even if a project chooses not
+to abide by the details of semantic versioning, the scheme is worth
+understanding as it covers many of the issues that can arise when
+depending on other distributions, and when publishing a distribution
+that others rely on.
The "Major.Minor.Patch" (described in this PEP as "major.minor.micro")
-aspects of semantic versioning (clauses 1-9 in the 2.0.0-rc-1 specification)
-are fully compatible with the version scheme defined in this PEP, and abiding
-by these aspects is encouraged.
+aspects of semantic versioning (clauses 1-9 in the 2.0.0-rc-1
+specification) are fully compatible with the version scheme defined in
+this PEP, and abiding by these aspects is encouraged.
Semantic versions containing a hyphen (pre-releases - clause 10) or a
-plus sign (builds - clause 11) are *not* compatible with this PEP
-and are not permitted in the public version field.
+plus sign (builds - clause 11) are *not* compatible with this PEP and
+are not permitted in the public version field.
-One possible mechanism to translate such semantic versioning based build
-labels to compatible public versions is to use the ``.devN`` suffix to
-specify the appropriate version order.
+One possible mechanism to translate such semantic versioning based
+build labels to compatible public versions is to use the ``.devN``
+suffix to specify the appropriate version order.
.. _Semantic versioning: http://semver.org/
@@ -501,40 +525,40 @@
DVCS based version labels
~~~~~~~~~~~~~~~~~~~~~~~~~
-Many build tools integrate with distributed version control systems like
-Git and Mercurial in order to add an identifying hash to the version
-identifier. As hashes cannot be ordered reliably such versions are not
-permitted in the public version field.
+Many build tools integrate with distributed version control systems
+like Git and Mercurial in order to add an identifying hash to the
+version identifier. As hashes cannot be ordered reliably such
+versions are not 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
-used to record the original DVCS based version label.
+As with semantic versioning, the public ``.devN`` suffix may be used
+to uniquely identify such releases for publication, while the build
+label is used to record the original DVCS based version label.
Date based versions
~~~~~~~~~~~~~~~~~~~
As with other incompatible version schemes, date based versions can be
-stored in the build 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.
+stored in the build 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.
This has the dual benefit of allowing subsequent migration to version
-numbering based on API compatibility, as well as triggering more appropriate
-version comparison semantics.
+numbering based on API compatibility, as well as triggering more
+appropriate version comparison semantics.
Version specifiers
==================
-A version specifier consists of a series of version clauses, separated by
-commas. For example::
+A version specifier consists of a series of version clauses, separated
+by commas. For example::
0.9, >= 1.0, != 1.3.4.*, < 2.0
-The comparison operator (or lack thereof) determines the kind of version
-clause:
+The comparison operator (or lack thereof) determines the kind of
+version clause:
* No operator: `Compatible release`_ clause
* ``==``: `Version matching`_ clause
@@ -542,32 +566,32 @@
* ``is``: `Build reference`_ clause
* ``<``, ``>``, ``<=``, ``>=``: `Ordered comparison`_ clause
-The comma (",") is equivalent to a logical **and** operator: a candidate
-version must match all given version clauses in order to match the
-specifier as a whole.
+The comma (",") is equivalent to a logical **and** operator: a
+candidate version must match all given version clauses in order to
+match the specifier as a whole.
Whitespace between a conditional operator and the following version
identifier is optional, as is the whitespace around the commas.
-When multiple candidate versions match a version specifier, the preferred
-version SHOULD be the latest version as determined by the consistent
-ordering defined by the standard `Version scheme`_. Whether or not
-pre-releases are considered as candidate versions SHOULD be handled as
-described in `Handling of pre-releases`_.
+When multiple candidate versions match a version specifier, the
+preferred version SHOULD be the latest version as determined by the
+consistent ordering defined by the standard `Version scheme`_.
+Whether or not pre-releases are considered as candidate versions
+SHOULD be handled as described in `Handling of pre-releases`_.
Compatible release
------------------
-A compatible release clause consists solely of a version identifier without
-any comparison operator. It matches any candidate version that is expected
-to be compatible with the specified version.
+A compatible release clause consists solely of a version identifier
+without any comparison operator. It matches any candidate version
+that is expected to be compatible with the specified version.
-The specified version identifier must be in the standard format described in
-`Version scheme`_.
+The specified version identifier must be in the standard format
+described in `Version scheme`_.
-For a given release identifier ``V.N``, the compatible release clause is
-approximately equivalent to the pair of comparison clauses::
+For a given release identifier ``V.N``, the compatible release clause
+is approximately equivalent to the pair of comparison clauses::
>= V.N, == V.*
@@ -580,8 +604,8 @@
>= 1.4.5, == 1.4.*
If a pre-release, post-release or developmental release is named in a
-compatible release clause as ``V.N.suffix``, then the suffix is ignored
-when determining the required prefix match::
+compatible release clause as ``V.N.suffix``, then the suffix is
+ignored when determining the required prefix match::
2.2.post3
>= 2.2.post3, == 2.*
@@ -589,9 +613,10 @@
1.4.5a4
>= 1.4.5a4, == 1.4.*
-The padding rules for release segment comparisons means that the assumed
-degree of forward compatibility in a compatible release clause can be
-controlled by appending additional zeroes to the version specifier::
+The padding rules for release segment comparisons means that the
+assumed degree of forward compatibility in a compatible release clause
+can be controlled by appending additional zeroes to the version
+specifier::
2.2.0
>= 2.2.0, == 2.2.*
@@ -603,24 +628,25 @@
Version matching
----------------
-A version matching clause includes the version matching operator ``==``
-and a version identifier.
+A version matching clause includes the version matching operator
+``==`` and a version identifier.
-The specified version identifier must be in the standard format described in
-`Version scheme`_, but a trailing ``.*`` is permitted as described below.
+The specified version identifier must be in the standard format
+described in `Version scheme`_, but a trailing ``.*`` is permitted as
+described below.
-By default, the version matching operator is based on a strict equality
-comparison: the specified version must be exactly the same as the requested
-version. The *only* substitution performed is the zero padding of the
-release segment to ensure the release segments are compared with the same
-length.
+By default, the version matching operator is based on a strict
+equality comparison: the specified version must be exactly the same as
+the requested version. The *only* substitution performed is the zero
+padding of the release segment to ensure the release segments are
+compared with the same length.
-Prefix matching may be requested instead of strict comparison, by appending
-a trailing ``.*`` to the version identifier in the version matching clause.
-This means that additional trailing segments will be ignored when
-determining whether or not a version identifier matches the clause. If the
-version includes only a release segment, than trailing components in the
-release segment are also ignored.
+Prefix matching may be requested instead of strict comparison, by
+appending a trailing ``.*`` to the version identifier in the version
+matching clause. This means that additional trailing segments will be
+ignored when determining whether or not a version identifier matches
+the clause. If the version includes only a release segment, than
+trailing components in the release segment are also ignored.
For example, given the version ``1.1.post1``, the following clauses would
match or not as shown:
@@ -633,23 +659,24 @@
The use of ``==`` when defining dependencies for published
distributions is strongly discouraged as it greatly complicates the
- deployment of security fixes. The strict version comparison operator
- is intended primarily for use when defining dependencies for repeatable
- *deployments of applications* while using a shared distribution index.
+ deployment of security fixes. The strict version comparison
+ operator is intended primarily for use when defining dependencies
+ for repeatable *deployments of applications* while using a shared
+ distribution index.
Version exclusion
-----------------
-A version exclusion clause includes the version matching operator ``!=``
-and a version identifier.
+A version exclusion clause includes the version matching operator
+``!=`` and a version identifier.
-The allowed version identifiers and comparison semantics are the same as
-those of the `Version matching`_ operator, except that the sense of any
-match is inverted.
+The allowed version identifiers and comparison semantics are the same
+as those of the `Version matching`_ operator, except that the sense of
+any match is inverted.
-For example, given the version ``1.1.post1``, the following clauses would
-match or not as shown:
+For example, given the version ``1.1.post1``, the following clauses
+would match or not as shown:
!= 1.1 # Not equal, so 1.1.post1 matches clause
!= 1.1.post1 # Equal, so 1.1.post1 does not match clause
@@ -663,51 +690,54 @@
a build reference.
A build reference is a direct URI reference supplied to satisfy a
-dependency. The exact kinds of URIs and targets supported will be determined
-by the specific installation tool used.
+dependency. The exact kinds of URIs and targets supported will be
+determined by the specific installation tool used.
Publication tools and public index servers SHOULD NOT permit build
references in dependency specifications.
-Installation tools SHOULD support the use of build references to identify
-dependencies.
+Installation tools SHOULD support the use of build references to
+identify dependencies.
Automated tools MAY support the use of build labels in build reference
-clauses. They can be clearly distinguished from URI references without
-ambiguity, as ``:`` and ``/`` are not permitted in build labels.
+clauses. They can be clearly distinguished from URI references
+without ambiguity, as ``:`` and ``/`` are not permitted in build
+labels.
Build label matching works solely on strict equality comparisons: the
-candidate build label must be exactly the same as the build label in the
-version clause.
+candidate build label must be exactly the same as the build label in
+the version clause.
Ordered comparison
------------------
-An ordered comparison clause includes a comparison operator and a version
-identifier, and will match any version where the comparison is correct
-based on the relative position of the candidate version and the specified
-version given the consistent ordering defined by the standard
-`Version scheme`_.
+An ordered comparison clause includes a comparison operator and a
+version identifier, and will match any version where the comparison is
+correct based on the relative position of the candidate version and
+the specified version given the consistent ordering defined by the
+standard `Version scheme`_.
-The supported ordered comparison operators are ``<``, ``>``, ``<=``, ``>=``.
+The supported ordered comparison operators are ``<``, ``>``, ``<=``,
+``>=``.
-As with version matching, the release segment is zero padded as necessary to
-ensure the release segments are compared with the same length.
+As with version matching, the release segment is zero padded as
+necessary to ensure the release segments are compared with the same
+length.
-To exclude pre-releases and post-releases correctly, the comparison clauses
-``< V`` and ``> V`` MUST be interpreted as also implying the version matching
-clause ``!= V.*``.
+To exclude pre-releases and post-releases correctly, the comparison
+clauses ``< V`` and ``> V`` MUST be interpreted as also implying the
+version matching clause ``!= V.*``.
Handling of pre-releases
------------------------
-Pre-releases of any kind, including developmental releases, are implicitly
-excluded from all version specifiers, *unless* a pre-release or developmental
-release is explicitly mentioned in one of the clauses. For example, these
-specifiers implicitly exclude all pre-releases and development
-releases of later versions::
+Pre-releases of any kind, including developmental releases, are
+implicitly excluded from all version specifiers, *unless* a
+pre-release or developmental release is explicitly mentioned in one of
+the clauses. For example, these specifiers implicitly exclude all
+pre-releases and development releases of later versions::
2.2
>= 1.0
@@ -721,47 +751,50 @@
>= 1.0, != 1.0b2
>= 1.0, < 2.0.dev123
-Dependency resolution tools SHOULD exclude pre-releases by default, but
-SHOULD also allow users to request the following alternative behaviours:
+Dependency resolution tools SHOULD exclude pre-releases by default,
+but SHOULD 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
+* retrieve and install available pre-releases for all version
+ specifiers
Dependency resolution tools MAY also allow the above behaviour to be
controlled on a per-distribution basis.
-Post-releases and purely numeric releases receive no special treatment -
-they are always included unless explicitly excluded.
+Post-releases and purely numeric releases receive no special treatment
+- they are always included unless explicitly excluded.
Examples
--------
-* ``3.1``: version 3.1 or later, but not
- version 4.0 or later. Excludes pre-releases and developmental releases.
-* ``3.1.2``: version 3.1.2 or later, but not
- version 3.2.0 or later. Excludes pre-releases and developmental releases.
-* ``3.1a1``: version 3.1a1 or later, but not
- version 4.0 or later. Allows pre-releases like 3.2a4 and developmental
- releases like 3.2.dev1.
-* ``== 3.1``: specifically version 3.1 (or 3.1.0), excludes all pre-releases,
- post releases, developmental releases and any 3.1.x maintenance releases.
-* ``== 3.1.*``: any version that starts with 3.1, excluding pre-releases and
- developmental releases. Equivalent to the ``3.1.0`` compatible release
- clause.
-* ``3.1.0, != 3.1.3``: version 3.1.0 or later, but not version 3.1.3 and
- not version 3.2.0 or later. Excludes pre-releases and developmental
- releases.
+* ``3.1``: version 3.1 or later, but not version 4.0 or
+ later. Excludes pre-releases and developmental releases.
+* ``3.1.2``: version 3.1.2 or later, but not version 3.2.0 or
+ later. Excludes pre-releases and developmental releases.
+* ``3.1a1``: version 3.1a1 or later, but not version 4.0 or
+ later. Allows pre-releases like 3.2a4 and developmental releases
+ like 3.2.dev1.
+* ``== 3.1``: specifically version 3.1 (or 3.1.0), excludes all
+ pre-releases, post releases, developmental releases and any 3.1.x
+ maintenance releases.
+* ``== 3.1.*``: any version that starts with 3.1, excluding
+ pre-releases and developmental releases. Equivalent to the ``3.1.0``
+ compatible release clause.
+* ``3.1.0, != 3.1.3``: version 3.1.0 or later, but not version 3.1.3
+ and not version 3.2.0 or later. Excludes pre-releases and
+ developmental releases.
Updating the versioning specification
=====================================
-The versioning specification may be updated with clarifications without
-requiring a new PEP or a change to the metadata version.
+The versioning specification may be updated with clarifications
+without requiring a new PEP or a change to the metadata version.
-Actually changing the version comparison semantics still requires a new
-versioning scheme and metadata version defined in new PEPs.
+Actually changing the version comparison semantics still requires a
+new versioning scheme and metadata version defined in new PEPs.
Open issues
@@ -769,7 +802,7 @@
* The new ``is`` operator seems like a reasonable way to cleanly allow
*deployments* to bring in non-published dependencies, while heavily
- discouraging the practice for published libraries. However, it's a
+ discouraging the practice for published libraries. However, it's a
first draft of the idea, so feedback is definitely welcome.
* Currently, the cleanest way to specify that a project runs on Python
@@ -777,13 +810,14 @@
Requires-Python: >= 2.6, < 4.0, != 3.0.*, != 3.1.*, != 3.2.*
- It would be better if there was a cleaner way to specify "this OR that" in
- a version specifier. Perhaps something like::
+ It would be better if there was a cleaner way to specify "this OR
+ that" in a version specifier. Perhaps something like::
Requires-Python: (2.6) or (3.3)
- This would be a respectable increase in the complexity of the parsing for
- version specifiers though, even if it was only allowed at the top level.
+ This would be a respectable increase in the complexity of the
+ parsing for version specifiers though, even if it was only allowed
+ at the top level.
Summary of differences from \PEP 386
@@ -791,15 +825,16 @@
* Moved the description of version specifiers into the versioning PEP
-* added the "build label" concept to better handle projects that wish to
- use a non-compliant versioning scheme internally, especially those based
- on DVCS hashes
+* added the "build 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
-* separated the two kinds of "version matching" clause (strict and prefix)
+* separated the two kinds of "version matching" clause (strict and
+ prefix)
* changed the top level sort position of the ``.devN`` suffix
@@ -822,108 +857,111 @@
-------------------
The new build 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
-as they are able to translate it to something the dependency analysis tools
-will understand.
+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 as they are able to translate it to something the
+dependency analysis tools will understand.
Changing the version scheme
---------------------------
The key change in the version scheme in this PEP relative to that in
-PEP 386 is to sort top level developmental releases like ``X.Y.devN`` ahead
-of alpha releases like ``X.Ya1``. This is a far more logical sort order, as
-projects already using both development releases and alphas/betas/release
-candidates do not want their developmental releases sorted in
-between their release candidates and their full releases. There is no
-rationale for using ``dev`` releases in that position rather than
-merely creating additional release candidates.
+PEP 386 is to sort top level developmental releases like ``X.Y.devN``
+ahead of alpha releases like ``X.Ya1``. This is a far more logical
+sort order, as projects already using both development releases and
+alphas/betas/release candidates do not want their developmental
+releases sorted in between their release candidates and their full
+releases. There is no rationale for using ``dev`` releases in that
+position rather than merely creating additional release candidates.
-The updated sort order also means the sorting of ``dev`` versions is now
-consistent between the metadata standard and the pre-existing behaviour
-of ``pkg_resources`` (and hence the behaviour of current installation
-tools).
+The updated sort order also means the sorting of ``dev`` versions is
+now consistent between the metadata standard and the pre-existing
+behaviour of ``pkg_resources`` (and hence the behaviour of current
+installation tools).
-Making this change should make it easier for affected existing projects to
-migrate to the latest version of the metadata standard.
+Making this change should make it easier for affected existing
+projects to migrate to the latest version of the metadata standard.
Another change to the version scheme is to allow single number
versions, similar to those used by non-Python projects like Mozilla
-Firefox, Google Chrome and the Fedora Linux distribution. This is actually
-expected to be more useful for version specifiers (allowing things like
-the simple ``Requires-Python: 3`` rather than the more convoluted
-``Requires-Python: >= 3.0, < 4``), but it is easier to allow it for both
-version specifiers and release numbers, rather than splitting the
-two definitions.
+Firefox, Google Chrome and the Fedora Linux distribution. This is
+actually expected to be more useful for version specifiers (allowing
+things like the simple ``Requires-Python: 3`` rather than the more
+convoluted ``Requires-Python: >= 3.0, < 4``), but it is easier to
+allow it for both version specifiers and release numbers, rather than
+splitting the two definitions.
-The exclusion of leading and trailing whitespace was made explicit after
-a couple of projects with version identifiers differing only in a
-trailing ``\n`` character were found on PyPI.
+The exclusion of leading and trailing whitespace was made explicit
+after a couple of projects with version identifiers differing only in
+a trailing ``\n`` character were found on PyPI.
-The exclusion of major release numbers that looks like dates was implied
-by the overall text of PEP 386, but not clear in the definition of the
-version scheme. This exclusion has been made clear in the definition of
-the release component.
+The exclusion of major release numbers that looks like dates was
+implied by the overall text of PEP 386, but not clear in the
+definition of the version scheme. This exclusion has been made clear
+in the definition of the release component.
-`Appendix A` shows detailed results of an analysis of PyPI distribution
-version information, as collected on 19th February, 2013. This analysis
-compares the behaviour of the explicitly ordered version schemes defined in
-this PEP and PEP 386 with the de facto standard defined by the behaviour
-of setuptools. These metrics are useful, as the intent of both PEPs is to
-follow existing setuptools behaviour as closely as is feasible, while
-still throwing exceptions for unorderable versions (rather than trying
-to guess an appropriate order as setuptools does).
+`Appendix A` shows detailed results of an analysis of PyPI
+distribution version information, as collected on 19th February, 2013.
+This analysis compares the behaviour of the explicitly ordered version
+schemes defined in this PEP and PEP 386 with the de facto standard
+defined by the behaviour of setuptools. These metrics are useful, as
+the intent of both PEPs is to follow existing setuptools behaviour as
+closely as is feasible, while still throwing exceptions for
+unorderable versions (rather than trying to guess an appropriate order
+as setuptools does).
-Overall, the percentage of compatible distributions improves from 97.7%
-with PEP 386 to 98.7% with this PEP. While the number of projects affected
-in practice was small, some of the affected projects are in widespread use
-(such as Pinax and selenium). The surprising ordering discrepancy also
-concerned developers and acted as an unnecessary barrier to adoption of
-the new metadata standard, even for projects that weren't directly affected.
+Overall, the percentage of compatible distributions improves from
+97.7% with PEP 386 to 98.7% with this PEP. While the number of
+projects affected in practice was small, some of the affected projects
+are in widespread use (such as Pinax and selenium). The surprising
+ordering discrepancy also concerned developers and acted as an
+unnecessary barrier to adoption of the new metadata standard, even for
+projects that weren't directly affected.
-The data also shows that the pre-release sorting discrepancies are seen
-only when analysing *all* versions from PyPI, rather than when analysing
-public versions. This is largely due to the fact that PyPI normally reports
-only the most recent version for each project (unless maintainers
-explicitly configure their project to display additional versions). However,
-installers that need to satisfy detailed version constraints often need
-to look at all available versions, as they may need to retrieve an older
-release.
+The data also shows that the pre-release sorting discrepancies are
+seen only when analysing *all* versions from PyPI, rather than when
+analysing public versions. This is largely due to the fact that PyPI
+normally reports only the most recent version for each project (unless
+maintainers explicitly configure their project to display additional
+versions). However, installers that need to satisfy detailed version
+constraints often need to look at all available versions, as they may
+need to retrieve an older release.
-Even this PEP doesn't completely eliminate the sorting differences relative
-to setuptools:
+Even this PEP doesn't completely eliminate the sorting differences
+relative to setuptools:
* Sorts differently (after translations): 38 / 28194 (0.13 %)
* Sorts differently (no translations): 2 / 28194 (0.01 %)
-The two remaining sort order discrepancies picked up by the analysis are due
-to a pair of projects which have PyPI releases ending with a carriage
-return, alongside releases with the same version number, only *without* the
-trailing carriage return.
+The two remaining sort order discrepancies picked up by the analysis
+are due to a pair of projects which have PyPI releases ending with a
+carriage return, alongside releases with the same version number, only
+*without* the trailing carriage return.
-The sorting discrepancies after translation relate mainly to differences
-in the handling of pre-releases where the standard mechanism is considered
-to be an improvement. For example, the existing pkg_resources scheme will
-sort "1.1beta1" *after* "1.1b2", whereas the suggested standard translation
-for "1.1beta1" is "1.1b1", which sorts *before* "1.1b2". Similarly, the
-pkg_resources scheme will sort "-dev-N" pre-releases differently from
-"devN" pre-releases when they occur within the same release, while the
-scheme in this PEP requires normalizing both representations to ".devN" and
-sorting them by the numeric component.
+The sorting discrepancies after translation relate mainly to
+differences in the handling of pre-releases where the standard
+mechanism is considered to be an improvement. For example, the
+existing pkg_resources scheme will sort "1.1beta1" *after* "1.1b2",
+whereas the suggested standard translation for "1.1beta1" is "1.1b1",
+which sorts *before* "1.1b2". Similarly, the pkg_resources scheme
+will sort "-dev-N" pre-releases differently from "devN" pre-releases
+when they occur within the same release, while the scheme in this PEP
+requires normalizing both representations to ".devN" and sorting them
+by the numeric component.
A more opinionated description of the versioning scheme
-------------------------------------------------------
-As in PEP 386, the primary focus is on codifying existing practices to make
-them more amenable to automation, rather than demanding that existing
-projects make non-trivial changes to their workflow. However, the
-standard scheme allows significantly more flexibility than is needed
-for the vast majority of simple Python packages (which often don't even
-need maintenance releases - many users are happy with needing to upgrade to a
-new feature release to get bug fixes).
+As in PEP 386, the primary focus is on codifying existing practices to
+make them more amenable to automation, rather than demanding that
+existing projects make non-trivial changes to their workflow.
+However, the standard scheme allows significantly more flexibility
+than is needed for the vast majority of simple Python packages (which
+often don't even need maintenance releases - many users are happy with
+needing to upgrade to a new feature release to get bug fixes).
For the benefit of novice developers, and for experienced developers
wishing to better understand the various use cases, the specification
@@ -931,55 +969,57 @@
version scheme, including examples of how each component may be used
in practice.
-The PEP also explicitly guides developers in the direction of
-semantic versioning (without requiring it), and discourages the use of
-several aspects of the full versioning scheme that have largely been
-included in order to cover esoteric corner cases in the practices of
-existing projects and in repackaging software for Linux distributions.
+The PEP also explicitly guides developers in the direction of semantic
+versioning (without requiring it), and discourages the use of several
+aspects of the full versioning scheme that have largely been included
+in order to cover esoteric corner cases in the practices of existing
+projects and in repackaging software for Linux distributions.
Describing version specifiers alongside the versioning scheme
-------------------------------------------------------------
-The main reason to even have a standardised version scheme in the first place
-is to make it easier to do reliable automated dependency analysis. It makes
-more sense to describe the primary use case for version identifiers alongside
-their definition.
+The main reason to even have a standardised version scheme in the
+first place is to make it easier to do reliable automated dependency
+analysis. It makes more sense to describe the primary use case for
+version identifiers alongside their definition.
Changing the interpretation of version specifiers
-------------------------------------------------
The previous interpretation of version specifiers made it very easy to
-accidentally download a pre-release version of a dependency. This in
+accidentally download a pre-release version of a dependency. This in
turn made it difficult for developers to publish pre-release versions
-of software to the Python Package Index, as even marking the package as
-hidden wasn't enough to keep automated tools from downloading it, and also
-made it harder for users to obtain the test release manually through the
-main PyPI web interface.
+of software to the Python Package Index, as even marking the package
+as hidden wasn't enough to keep automated tools from downloading it,
+and also made it harder for users to obtain the test release manually
+through the main PyPI web interface.
-The previous interpretation also excluded post-releases from some version
-specifiers for no adequately justified reason.
+The previous interpretation also excluded post-releases from some
+version specifiers for no adequately justified reason.
-The updated interpretation is intended to make it difficult to accidentally
-accept a pre-release version as satisfying a dependency, while allowing
-pre-release versions to be explicitly requested when needed.
+The updated interpretation is intended to make it difficult to
+accidentally accept a pre-release version as satisfying a dependency,
+while allowing pre-release versions to be explicitly requested when
+needed.
The "some forward compatibility assumed" default version constraint is
-taken directly from the Ruby community's "pessimistic version constraint"
-operator [2]_ to allow projects to take a cautious approach to forward
-compatibility promises, while still easily setting a minimum required
-version for their dependencies. It is made the default behaviour rather
-than needing a separate operator in order to explicitly discourage
-overspecification of dependencies by library developers. The explicit
-comparison operators remain available to cope with dependencies with
-unreliable or non-existent backwards compatibility policies, as well
-as for legitimate use cases related to deployment of integrated applications.
+taken directly from the Ruby community's "pessimistic version
+constraint" operator [2]_ to allow projects to take a cautious
+approach to forward compatibility promises, while still easily setting
+a minimum required version for their dependencies. It is made the
+default behaviour rather than needing a separate operator in order to
+explicitly discourage overspecification of dependencies by library
+developers. The explicit comparison operators remain available to cope
+with dependencies with unreliable or non-existent backwards
+compatibility policies, as well as for legitimate use cases related to
+deployment of integrated applications.
-The two kinds of version matching (strict and prefix based) were separated
-to make it possible to sensibly define the compatible release clauses and the
-desired pre-release handling semantics for ``<`` and ``>`` ordered
-comparison clauses.
+The two kinds of version matching (strict and prefix based) were
+separated to make it possible to sensibly define the compatible
+release clauses and the desired pre-release handling semantics for
+``<`` and ``>`` ordered comparison clauses.
References
@@ -988,18 +1028,18 @@
The initial attempt at a standardised version scheme, along with the
justifications for needing such a standard can be found in PEP 386.
-.. [1] Version compatibility analysis script:
- http://hg.python.org/peps/file/default/pep-0426/pepsort.py
+.. [1] Version compatibility analysis script
+ (http://hg.python.org/peps/file/default/pep-0426/pepsort.py)
.. [2] Pessimistic version constraint
- http://docs.rubygems.org/read/chapter/16
+ (http://docs.rubygems.org/read/chapter/16)
Appendix A
==========
-Metadata v2.0 guidelines versus setuptools (note that this analysis was
-run when this PEP was still embedded as part of PEP 426)::
+Metadata v2.0 guidelines versus setuptools (note that this analysis
+was run when this PEP was still embedded as part of PEP 426)::
$ ./pepsort.py
Comparing PEP 426 version sort to setuptools.
@@ -1070,6 +1110,7 @@
This document has been placed in the public domain.
+
..
Local Variables:
mode: indented-text
diff --git a/pep-0441.txt b/pep-0441.txt
--- a/pep-0441.txt
+++ b/pep-0441.txt
@@ -12,18 +12,18 @@
Improving Python ZIP Application Support
========================================
-Python has had the ability to execute directories or ZIP-format archives
-as scripts since version 2.6 [1]_. When invoked with a zip file or
-directory as its first argument the interpreter adds that directory
-to sys.path and executes the __main__ module. These archives provide a
-great way to publish software that needs to be distributed as a single
-file script but is complex enough to need to be written as a collection
-of modules.
+Python has had the ability to execute directories or ZIP-format
+archives as scripts since version 2.6 [1]_. When invoked with a zip
+file or directory as its first argument the interpreter adds that
+directory to sys.path and executes the __main__ module. These
+archives provide a great way to publish software that needs to be
+distributed as a single file script but is complex enough to need to
+be written as a collection of modules.
This feature is not as popular as it should be mainly because no one’s
heard of it as it wasn’t promoted as part of Python 2.6 [2]_, but also
-because Windows users don’t have a file extension (other than .py)
-to associate with the launcher.
+because Windows users don’t have a file extension (other than .py) to
+associate with the launcher.
This PEP proposes to fix these problems by re-publicising the feature,
defining the .pyz and .pyzw extensions as “Python ZIP Applications”
@@ -34,35 +34,37 @@
======================================
The Python 3.4 installer will associate .pyz and .pyzw “Python ZIP
-Applications” with the platform launcher so they can be executed. A
-.pyz archive is a console application and a .pyzw archive is a windowed
-application, indicating whether the console should appear when running
-the app.
+Applications” with the platform launcher so they can be executed. A
+.pyz archive is a console application and a .pyzw archive is a
+windowed application, indicating whether the console should appear
+when running the app.
Why not use .zip or .py? Users expect a .zip file would be opened with
-an archive tool, and users expect .py to contain text. Both would be
+an archive tool, and users expect .py to contain text. Both would be
confusing for this use case.
For UNIX users, .pyz applications should be prefixed with a #! line
-pointing to the correct Python interpreter and an optional explanation::
+pointing to the correct Python interpreter and an optional
+explanation::
#!/usr/bin/env python3
# This is a Python application stored in a ZIP archive, created with
# pyzaa.
(binary contents of archive)
-As background, ZIP archives are defined with a footer containing relative
-offsets from the end of the file. They remain valid when concatenated to
-the end of any other file. This feature is completely standard and is how
-self-extracting ZIP archives and the bdist_wininst installer format work.
+As background, ZIP archives are defined with a footer containing
+relative offsets from the end of the file. They remain valid when
+concatenated to the end of any other file. This feature is completely
+standard and is how self-extracting ZIP archives and the bdist_wininst
+installer format work.
Minimal Tooling: The pyzaa Module
=================================
This PEP also proposes including a simple application for working with
these archives: The Python Zip Application Archiver “pyzaa” (rhymes
-with “huzzah” or “pizza”). “pyzaa” can archive these files,
-compile bytecode, and can write the __main__ module if it is not present.
+with “huzzah” or “pizza”). “pyzaa” can archive these files, compile
+bytecode, and can write the __main__ module if it is not present.
Usage
-----
@@ -88,7 +90,7 @@
pyzaa pack will warn if the directory contains C extensions or if
it doesn’t contain __main__.py.
-``python -m pyzaa compile arcname.pyz[w]``
+``python -m pyzaa compile arcname.pyz[w]``::
The Python files in arcname.pyz[w] are compiled and appended to the
ZIP file.
@@ -97,6 +99,7 @@
archives.
FAQ
+---
Q. Are you sure a standard ZIP utility can handle #! at the beginning?
@@ -109,21 +112,31 @@
Q. How does this compete with existing sdist/bdist formats?
A. There is some overlap, but .pyz files are especially interesting
-as a way to distribute an installer. They may also prove useful as a
+as a way to distribute an installer. They may also prove useful as a
way to deliver applications when users shouldn’t be asked to perform
virtualenv + “pip install”.
References
==========
-.. [1] “Allow interpreter to execute a zip file”:
- http://bugs.python.org/issue1739468
+.. [1] “Allow interpreter to execute a zip file”
+ (http://bugs.python.org/issue1739468)
-.. [2] “Feature is not documented”:
- http://bugs.python.org/issue17359
+.. [2] “Feature is not documented”
+ (http://bugs.python.org/issue17359)
Copyright
=========
This document has been placed into the public domain.
+
+
+..
+ Local Variables:
+ mode: indented-text
+ indent-tabs-mode: nil
+ sentence-end-double-space: t
+ fill-column: 70
+ coding: utf-8
+ End:
--
Repository URL: http://hg.python.org/peps
More information about the Python-checkins
mailing list