PEP 426: Further simplifications
- make expected filename pysdist.json and be clear this metadata is about the published source code, not any particular built or installed artifacts - defer any changes to handling of project obsolescence - add "all" and "alldev" as implied extras if not defined - drop "self", "runtime" and proposed changes to the extras notation
This commit is contained in:
Nick Coghlan
parent
918d676de1
commit
24cd02b34c
233
pep-0426.txt
233
pep-0426.txt
|
|
@ -25,13 +25,16 @@ This PEP describes a mechanism for publishing and exchanging metadata
|
|||
related to Python distributions. It includes specifics of the field names,
|
||||
and their semantics and usage.
|
||||
|
||||
This document specifies version 2.0 of the metadata format.
|
||||
This document specifies version 3.0 of the metadata format.
|
||||
|
||||
Version 1.0 is specified in PEP 241.
|
||||
Version 1.1 is specified in PEP 314.
|
||||
Version 1.2 is specified in PEP 345.
|
||||
|
||||
Version 2.0 of the metadata format migrates from directly defining a
|
||||
Version 2.0 is specified in earlier drafts of this PEP and was never formally
|
||||
approved for use.
|
||||
|
||||
Version 3.0 of the metadata format migrates from directly defining a
|
||||
custom key-value file format to instead defining a JSON-compatible in-memory
|
||||
representation that may be used to define metadata representation in other
|
||||
contexts (such as API and archive format definitions).
|
||||
|
|
@ -66,7 +69,7 @@ The time spent pursuing these changes provided additional perspective on which
|
|||
metadata format changes were genuinely desirable, and which could be omitted
|
||||
from the revised specification as merely being "change for change's sake".
|
||||
|
||||
It is allowed a number of features that aren't critical to the core activity
|
||||
It also allowed a number of features that aren't critical to the core activity
|
||||
of publishing and distributing software to be moved out to PEP 459, a separate
|
||||
proposal for a number of standard metadata extensions that provide additional
|
||||
optional information about a release.
|
||||
|
|
@ -350,7 +353,7 @@ judgment of reasonable metadata capacity requirements.
|
|||
Metadata files
|
||||
--------------
|
||||
|
||||
The information defined in this PEP is serialised to ``pydist.json``
|
||||
The information defined in this PEP is serialised to ``pysdist.json``
|
||||
files for some use cases. These are files containing UTF-8 encoded JSON
|
||||
metadata.
|
||||
|
||||
|
|
@ -361,25 +364,30 @@ of any changes.
|
|||
|
||||
There are expected to be three standard locations for these metadata files:
|
||||
|
||||
* as a ``{distribution}-{version}.dist-info/pydist.json`` file in an
|
||||
* as a ``{distribution}-{version}.dist-info/pysdist.json`` file in an
|
||||
``sdist`` source distribution archive
|
||||
* as a ``{distribution}-{version}.dist-info/pydist.json`` file in a ``wheel``
|
||||
* as a ``{distribution}-{version}.dist-info/pysdist.json`` file in a ``wheel``
|
||||
binary distribution archive
|
||||
* as a ``{distribution}-{version}.dist-info/pydist.json`` file in a local
|
||||
* as a ``{distribution}-{version}.dist-info/pysdist.json`` file in a local
|
||||
Python installation database
|
||||
|
||||
This file is expected to be identical in all three locations - it is
|
||||
generated when creating a source archive or binary archive from a source
|
||||
tree, and then preserved unchanged on installation, or when building a
|
||||
binary archive from a source archive.
|
||||
|
||||
.. note::
|
||||
|
||||
These locations are to be confirmed, since they depend on the definition
|
||||
of sdist 2.0 and the revised installation database standard. There will
|
||||
also be a wheel 1.1 format update after this PEP is approved that
|
||||
mandates provision of 2.0+ metadata.
|
||||
mandates provision of 3.0+ metadata.
|
||||
|
||||
Note that these metadata files MAY be processed even if the version of the
|
||||
containing location is too low to indicate that they are valid. Specifically,
|
||||
unversioned ``sdist`` archives, unversioned installation database directories
|
||||
and version 1.0 of the ``wheel`` specification may still provide ``pydist.json``
|
||||
files.
|
||||
and version 1.0 of the ``wheel`` specification may still provide
|
||||
``pysdist.json`` files.
|
||||
|
||||
.. note::
|
||||
|
||||
|
|
@ -390,14 +398,13 @@ files.
|
|||
|
||||
Other tools involved in Python distribution MAY also use this format.
|
||||
|
||||
As JSON files are generally awkward to edit by hand, it is RECOMMENDED
|
||||
that these metadata files be generated by build tools based on other
|
||||
Note that these metadata files are generated by build tools based on other
|
||||
input formats (such as ``setup.py`` and ``pyproject.toml``) rather than being
|
||||
used directly as a data input format. Generating the metadata as part of the
|
||||
publication process also helps to deal with version specific fields (including
|
||||
the source URL and the version field itself).
|
||||
|
||||
For backwards compatibility with older installation tools, metadata 2.0
|
||||
For backwards compatibility with older installation tools, metadata 3.0
|
||||
files MAY be distributed alongside legacy metadata.
|
||||
|
||||
Index servers MAY allow distributions to be uploaded and installation tools
|
||||
|
|
@ -426,8 +433,8 @@ with RFC 3986.
|
|||
The current version of the schema file covers the previous draft of the
|
||||
PEP, and has not yet been updated for the split into the essential
|
||||
dependency resolution metadata and multiple standard extensions, and nor
|
||||
has it been updated for the replacement of the various "semantic dependency"
|
||||
fields with particular conventional "extras" declarations.
|
||||
has it been updated for the various other differences between the 3.0
|
||||
draft and the earlier 2.0 drafts.
|
||||
|
||||
|
||||
Core metadata
|
||||
|
|
@ -450,7 +457,7 @@ installation to occur.
|
|||
Metadata version
|
||||
----------------
|
||||
|
||||
Version of the file format; ``"2.0"`` is the only legal value.
|
||||
Version of the file format; ``"3.0"`` is the only legal value.
|
||||
|
||||
Automated tools consuming metadata SHOULD warn if ``metadata_version`` is
|
||||
greater than the highest version they support, and MUST fail if
|
||||
|
|
@ -464,7 +471,7 @@ all of the needed fields.
|
|||
|
||||
Example::
|
||||
|
||||
"metadata_version": "2.0"
|
||||
"metadata_version": "3.0"
|
||||
|
||||
|
||||
Generator
|
||||
|
|
@ -720,6 +727,12 @@ These optional categories are known as
|
|||
standard categories, projects may also declare their own custom categories
|
||||
in the `Extras`_ field.
|
||||
|
||||
There are also two standard extra categories that imply dependencies on
|
||||
other extras:
|
||||
|
||||
* ``alldev``: implies the ``test``, ``build``, ``doc``, ``dev`` extras
|
||||
* ``all``: if not otherwise defined, implies all declared extras
|
||||
|
||||
Dependency management is heavily dependent on the version identification
|
||||
and specification scheme defined in PEP 440 and the dependency specification,
|
||||
extra, and environment marker schemes defined in PEP 508.
|
||||
|
|
@ -776,22 +789,19 @@ conditional dependencies in dependency fields. See
|
|||
The names of extras MUST abide by the same restrictions as those for
|
||||
distribution names.
|
||||
|
||||
The following extra names are available by default and SHOULD NOT be
|
||||
declared explicitly:
|
||||
The following extra names are available by default and MUST NOT be
|
||||
declared explicitly in this field:
|
||||
|
||||
* ``test``
|
||||
* ``all``
|
||||
* ``alldev``
|
||||
* ``build``
|
||||
* ``doc``
|
||||
* ``dev``
|
||||
|
||||
The following extra names are reserved, and MUST NOT be declared:
|
||||
|
||||
* ``self``
|
||||
* ``runtime``
|
||||
* ``doc``
|
||||
* ``test``
|
||||
|
||||
Example::
|
||||
|
||||
"extras": ["warmup"]
|
||||
"extras": ["warmup", "tea"]
|
||||
|
||||
|
||||
Dependencies
|
||||
|
|
@ -854,87 +864,14 @@ for example, if an extra itself only needs some of its dependencies in
|
|||
specific environments. It is only the combination of extras and environment
|
||||
markers that is required to be unique in a list of dependency specifiers.
|
||||
|
||||
Aside from the four standard extra categories, any extras referenced from a
|
||||
Aside from the six standard extra categories, any extras referenced from a
|
||||
dependency specifier MUST be named in the `Extras`_ field for this distribution.
|
||||
This helps avoid typographical errors and also makes it straightforward to
|
||||
identify the available extras without scanning the full set of dependencies.
|
||||
|
||||
|
||||
Provides
|
||||
--------
|
||||
|
||||
A list of strings naming additional dependency requirements that are
|
||||
satisfied by installing this distribution. These strings must be of the
|
||||
form ``Name`` or ``Name (Version)``, as for the ``requires`` field.
|
||||
|
||||
While dependencies are usually resolved based on distribution names and
|
||||
versions, a distribution may provide additional names explicitly in the
|
||||
``provides`` field.
|
||||
|
||||
For example, this may be used to indicate that multiple projects have
|
||||
been merged into and replaced by a single distribution or to indicate
|
||||
that this project is a substitute for another.
|
||||
|
||||
To avoid malicious hijacking of names, when interpreting metadata retrieved
|
||||
from a public index server, automated tools MUST NOT pay any attention to
|
||||
``"provides"`` entries that do not correspond to a published distribution.
|
||||
|
||||
However, to appropriately handle project forks and mergers, automated tools
|
||||
MUST accept ``"provides"`` entries that name other distributions when the
|
||||
entry is retrieved from a local installation database or when there is a
|
||||
corresponding ``"obsoleted_by"`` entry in the metadata for the named
|
||||
distribution.
|
||||
|
||||
A distribution may wish to depend on a "virtual" project name, which does
|
||||
not correspond to any separately distributed project: such a name
|
||||
might be used to indicate an abstract capability which could be supplied
|
||||
by one of multiple projects. For example, multiple projects might supply
|
||||
PostgreSQL bindings for use with SQL Alchemy: each project might declare
|
||||
that it provides ``sqlalchemy-postgresql-bindings``, allowing other
|
||||
projects to depend only on having at least one of them installed.
|
||||
|
||||
To handle this case in a way that doesn't allow for name hijacking, the
|
||||
authors of the distribution that first defines the virtual dependency should
|
||||
create a project on the public index server with the corresponding name, and
|
||||
depend on the specific distribution that should be used if no other provider
|
||||
is already installed. This also has the benefit of publishing the default
|
||||
provider in a way that automated tools will understand.
|
||||
|
||||
A version declaration may be supplied as part of an entry in the provides
|
||||
field and must follow the rules described in PEP 440. The distribution's
|
||||
version identifier will be implied if none is specified.
|
||||
|
||||
Example::
|
||||
|
||||
"provides": ["AnotherProject (3.4)", "virtual-package"]
|
||||
|
||||
|
||||
Obsoleted by
|
||||
------------
|
||||
|
||||
A string that indicates that this project is no longer being developed. The
|
||||
named project provides a substitute or replacement.
|
||||
|
||||
A version declaration may be supplied and must follow the rules described
|
||||
in PEP 440.
|
||||
|
||||
An inactive project may be explicitly indicated by setting this field to
|
||||
``None`` (which is serialised as ``null`` in JSON as usual).
|
||||
|
||||
Automated tools SHOULD report a warning when installing an obsolete project.
|
||||
|
||||
Possible uses for this field include handling project name changes and
|
||||
project mergers.
|
||||
|
||||
Note that without a corresponding ``provides``, there is no expectation
|
||||
that the replacement project will be a "drop-in" replacement for the
|
||||
obsolete project - at the very least, upgrading to the new distribution
|
||||
is likely to require changes to import statements.
|
||||
|
||||
Examples::
|
||||
|
||||
"name": "BadName",
|
||||
"obsoleted_by": "AcceptableName"
|
||||
To reuse an extra definition as part of another extra, project releases MAY
|
||||
declare dependencies on themselves. To avoid infinite recursion in these cases,
|
||||
automated tools MUST special case dependencies from a project back onto itself.
|
||||
|
||||
|
||||
Metadata Extensions
|
||||
|
|
@ -1060,26 +997,15 @@ relevant extra names inside square brackets after the distribution name when
|
|||
specifying the dependency. Multiple extras from a dependency can be requested
|
||||
by placing to
|
||||
|
||||
In addition to the required syntax defined in PEP 508, automated tools
|
||||
MAY offer the following additional enhancements to control precisely
|
||||
which dependencies are installed:
|
||||
If the standard ``all`` extra has no explicitly declared entries, then
|
||||
integration tools SHOULD implicitly define it as a dependency on all of the
|
||||
extras explicitly declared by the project.
|
||||
|
||||
* The special extra ``*`` to request that all optional dependencies be
|
||||
installed (unless excluded based on environment markers)
|
||||
If the standard ``alldev`` extra has no explicitly declared entries, then
|
||||
integration tools SHOULD implicitly define it as a dependency on the standard
|
||||
``test``, ``build``, ``doc``, and ``dev`` extras.
|
||||
|
||||
* The special extra ``-self`` to indicate that the project itself should not
|
||||
be installed, only its dependencies
|
||||
|
||||
* The special extra ``-runtime`` to indicate that the otherwise unconditional
|
||||
runtime dependencies should not be installed, only the dependencies for the
|
||||
requested extras
|
||||
|
||||
* Other extras may be explicitly excluded by prefixing their name with a ``-``
|
||||
character (this is useful in conjunction with ``*`` to exclude only
|
||||
particular extras that are definitely not wanted, while enabling all
|
||||
others)
|
||||
|
||||
The full set of dependency requirements is then based on the top level
|
||||
The full set of dependency requirements is then based on the uncondtional
|
||||
dependencies, along with those of any requested extras.
|
||||
|
||||
Dependency examples (showing just the ``requires`` subfield)::
|
||||
|
|
@ -1090,25 +1016,10 @@ Dependency examples (showing just the ``requires`` subfield)::
|
|||
"requires": ["ComfyChair[warmup]"]
|
||||
-> requires ``ComfyChair`` and ``SoftCushions``
|
||||
|
||||
"requires": ["ComfyChair[*]"]
|
||||
"requires": ["ComfyChair[all]"]
|
||||
-> requires ``ComfyChair`` and ``SoftCushions``, but will also
|
||||
pick up any new extras defined in later versions
|
||||
|
||||
Command line examples::
|
||||
|
||||
pip install ComfyChair
|
||||
-> installs ComfyChair with applicable runtime dependencies
|
||||
|
||||
pip install ComfyChair[-build,-dev,-doc,-test,*]
|
||||
-> as above, but also installs all non-standard extra dependencies
|
||||
|
||||
pip install ComfyChair[-self,-runtime,build,dev]
|
||||
-> installs just the build and development dependencies
|
||||
|
||||
pip install ComfyChair[-self,*]
|
||||
-> installs the full set of runtime and development dependencies, but
|
||||
avoids installing ComfyChair itself
|
||||
|
||||
|
||||
Updating the metadata specification
|
||||
===================================
|
||||
|
|
@ -1125,7 +1036,7 @@ Appendix A: Conversion notes for legacy metadata
|
|||
================================================
|
||||
|
||||
The reference implementations for converting from legacy metadata to
|
||||
metadata 2.0 are:
|
||||
metadata 3.0 are:
|
||||
|
||||
* the `wheel project <https://bitbucket.org/dholth/wheel/overview>`__, which
|
||||
adds the ``bdist_wheel`` command to ``setuptools``
|
||||
|
|
@ -1193,7 +1104,7 @@ format.
|
|||
Appendix C: Summary of differences from \PEP 345
|
||||
=================================================
|
||||
|
||||
* Metadata-Version is now 2.0, with semantics specified for handling
|
||||
* Metadata-Version is now 3.0, with semantics specified for handling
|
||||
version changes
|
||||
|
||||
* The increasingly complex ad hoc "Key: Value" format has been replaced by
|
||||
|
|
@ -1254,7 +1165,7 @@ provision of multiple versions of the metadata in parallel.
|
|||
|
||||
Existing tools won't abide by this guideline until they're updated to
|
||||
support the new metadata standard, so the new semantics will first take
|
||||
effect for a hypothetical 2.x -> 3.0 transition. For the 1.x -> 2.0
|
||||
effect for a hypothetical 2.x -> 3.0 transition. For the 1.x -> 3.0
|
||||
transition, we will use the approach where tools continue to produce the
|
||||
existing supplementary files (such as ``entry_points.txt``) in addition
|
||||
to any equivalents specified using the new features of the standard
|
||||
|
|
@ -1362,28 +1273,13 @@ packages.
|
|||
|
||||
The ability to declare an extension as required is included primarily to
|
||||
allow the definition of the metadata hooks extension to be deferred until
|
||||
some time after the initial adoption of the metadata 2.0 specification. If
|
||||
some time after the initial adoption of the metadata 3.0 specification. If
|
||||
a release needs a ``postinstall`` hook to run in order to complete
|
||||
the installation successfully, then earlier versions of tools should fall
|
||||
back to installing from source rather than installing from a wheel file and
|
||||
then failing to run the expected postinstall hook.
|
||||
|
||||
|
||||
Updated obsolescence mechanism
|
||||
------------------------------
|
||||
|
||||
The marker to indicate when a project is obsolete and should be replaced
|
||||
has been moved to the obsolete project (the new ``obsoleted_by`` field),
|
||||
replacing the previous marker on the replacement project (the removed
|
||||
``Obsoletes-Dist`` field).
|
||||
|
||||
This should allow distribution tools to more easily warn users of
|
||||
obsolete projects and their suggested replacements.
|
||||
|
||||
The ``Obsoletes-Dist`` header is removed rather than deprecated as it
|
||||
is not widely supported, and so removing it does not present any significant
|
||||
barrier to tools and projects adopting the new metadata format.
|
||||
|
||||
|
||||
Appendix D: Deferred features
|
||||
=============================
|
||||
|
|
@ -1393,10 +1289,10 @@ order to better prioritise our efforts in migrating to the new metadata
|
|||
standard. These all reflect information that may be nice to have in the
|
||||
new metadata, but which can be readily added through metadata extensions or
|
||||
in metadata 2.1 without breaking any use cases already supported by metadata
|
||||
2.0.
|
||||
3.0.
|
||||
|
||||
Once the ``pypi``, ``setuptools``, ``pip``, ``wheel`` and ``distlib``
|
||||
projects support creation and consumption of metadata 2.0, then we may
|
||||
projects support creation and consumption of metadata 3.0, then we may
|
||||
revisit the creation of metadata 2.1 with some or all of these additional
|
||||
features.
|
||||
|
||||
|
|
@ -1407,11 +1303,22 @@ Standard extensions
|
|||
Some of the information provided by the legacy metadata system has been
|
||||
moved out to standard extensions defined in PEP 459.
|
||||
|
||||
This allows publication of the dependency metadata in a more readily
|
||||
This allows publication of the core dependency metadata in a more readily
|
||||
consumable format to proceed even before the full details of those extensions
|
||||
have been resolved.
|
||||
|
||||
|
||||
Improved handling of project obsolescence, renames and mergers
|
||||
--------------------------------------------------------------
|
||||
|
||||
Earlier drafts of this PEP included new ``Provides`` and ``Obsoleted-By``
|
||||
fields for more robust automated notifications and tracking of project
|
||||
obsolescence, renames and mergers.
|
||||
|
||||
This isn't an essential feature of a dependency management system, and has
|
||||
been deferred indefinitely as a possible future metadata extension.
|
||||
|
||||
|
||||
MIME type registration
|
||||
----------------------
|
||||
|
||||
|
|
@ -1537,10 +1444,6 @@ database driver" metadata extension where a project depends on SQL Alchemy,
|
|||
and then declares in the extension which database drivers are checked for
|
||||
compatibility by the upstream project.
|
||||
|
||||
We're also getting better support for "virtual provides" in this version of
|
||||
the metadata standard, so this may end up being an installer and index
|
||||
server problem to better track and publish those.
|
||||
|
||||
|
||||
Compatible release comparisons in environment markers
|
||||
-----------------------------------------------------
|
||||
|
|
@ -1571,7 +1474,7 @@ the idea won't be reconsidered until metadata 2.1 at the earliest).
|
|||
References
|
||||
==========
|
||||
|
||||
This document specifies version 2.0 of the metadata format.
|
||||
This document specifies version 3.0 of the metadata format.
|
||||
Version 1.0 is specified in PEP 241.
|
||||
Version 1.1 is specified in PEP 314.
|
||||
Version 1.2 is specified in PEP 345.
|
||||
|
|
|
|||
Loading…
Reference in New Issue