Assorted PEP 426 updates
* Merge conditional and unconditional deps * Don't trust public index server "Provides" metadata * Rename pymeta to pydist (schema file name change postponed for better diff) * Bring schema file up to date (I think - could use an audit)
This commit is contained in:
Nick Coghlan
parent
df6c195b0c
commit
a043d88945
424
pep-0426.txt
424
pep-0426.txt
|
|
@ -13,7 +13,7 @@ Content-Type: text/x-rst
|
|||
Requires: 440
|
||||
Created: 30 Aug 2012
|
||||
Post-History: 14 Nov 2012, 5 Feb 2013, 7 Feb 2013, 9 Feb 2013,
|
||||
27 May 2013, 20 Jun 2013, 23 Jun 2013
|
||||
27 May 2013, 20 Jun 2013, 23 Jun 2013, 14 Jul 2013
|
||||
Replaces: 345
|
||||
|
||||
|
||||
|
|
@ -63,13 +63,15 @@ identification scheme.
|
|||
* this PEP, covering the core metadata format
|
||||
* PEP 440, covering the versioning identification and selection scheme
|
||||
* a new PEP to define v2.0 of the sdist format
|
||||
* an updated wheel PEP (v1.1) to add pymeta.json
|
||||
* an updated installation database PEP both for pymeta.json and to add
|
||||
a linking scheme to better support runtime selection of dependencies
|
||||
* an updated wheel PEP (v1.1) to add pydist.json (and possibly convert
|
||||
the wheel metadata file from Key:Value to JSON)
|
||||
* an updated installation database PEP both for pydist.json (and possibly convert
|
||||
the wheel metadata file from Key:Value to JSON)
|
||||
* an alternative to *.pth files that avoids system global side effects
|
||||
and better supports runtime selection of dependencies
|
||||
* a new static config PEP to standardise metadata generation and
|
||||
creation of sdists
|
||||
* PEP 439, covering a bootstrapping mechanism for ``pip``
|
||||
* a distutils upgrade PEP, adding metadata v2.0 and wheel support.
|
||||
* a PEP to cover bundling ``pip`` with the CPython installers
|
||||
|
||||
It's going to take a while to work through all of these and make them
|
||||
a reality. The main change from our last attempt at this is that we're
|
||||
|
|
@ -361,7 +363,7 @@ judgment of reasonable metadata capacity requirements.
|
|||
Metadata files
|
||||
--------------
|
||||
|
||||
The information defined in this PEP is serialised to ``pymeta.json``
|
||||
The information defined in this PEP is serialised to ``pydist.json``
|
||||
files for some use cases. These are files containing UTF-8 encoded JSON
|
||||
metadata.
|
||||
|
||||
|
|
@ -370,11 +372,11 @@ described in this PEP.
|
|||
|
||||
There are three standard locations for these metadata files:
|
||||
|
||||
* as a ``{distribution}-{version}.dist-info/pymeta.json`` file in an
|
||||
* as a ``{distribution}-{version}.dist-info/pydist.json`` file in an
|
||||
``sdist`` source distribution archive
|
||||
* as a ``{distribution}-{version}.dist-info/pymeta.json`` file in a ``wheel``
|
||||
* as a ``{distribution}-{version}.dist-info/pydist.json`` file in a ``wheel``
|
||||
binary distribution archive
|
||||
* as a ``{distribution}-{version}.dist-info/pymeta.json`` file in a local
|
||||
* as a ``{distribution}-{version}.dist-info/pydist.json`` file in a local
|
||||
Python installation database
|
||||
|
||||
.. note::
|
||||
|
|
@ -422,21 +424,16 @@ fields:
|
|||
* ``source_url``
|
||||
* ``extras``
|
||||
* ``meta_requires``
|
||||
* ``meta_may_require``
|
||||
* ``run_requires``
|
||||
* ``run_may_require``
|
||||
* ``test_requires``
|
||||
* ``test_may_require``
|
||||
* ``build_requires``
|
||||
* ``build_may_require``
|
||||
* ``dev_requires``
|
||||
* ``dev_may_require``
|
||||
* ``provides``
|
||||
* ``obsoleted_by``
|
||||
* ``supports_environments``
|
||||
|
||||
When serialised to a file, the name used for this metadata set SHOULD
|
||||
be ``pymeta-dependencies.json``.
|
||||
be ``pydist-dependencies.json``.
|
||||
|
||||
|
||||
Included documents
|
||||
|
|
@ -457,7 +454,7 @@ Metadata validation
|
|||
|
||||
A `jsonschema <https://pypi.python.org/pypi/jsonschema>`__ description of
|
||||
the distribution metadata is `available
|
||||
<http://hg.python.org/peps/file/default/pep-0426/pymeta-schema.json>`__.
|
||||
<http://hg.python.org/peps/file/default/pep-0426/pydist-schema.json>`__.
|
||||
|
||||
This schema does NOT currently handle validation of some of the more complex
|
||||
string fields (instead treating them as opaque strings).
|
||||
|
|
@ -924,6 +921,10 @@ Distributions may declare five differents kinds of dependency:
|
|||
working on this distribution (but do not fit into one of the other
|
||||
dependency categories).
|
||||
|
||||
Within each of these categories, distributions may also declare "Extras".
|
||||
Extras are dependencies that may be needed for some optional functionality,
|
||||
or which are otherwise complementary to the distribution.
|
||||
|
||||
Dependency management is heavily dependent on the version identification
|
||||
and specification scheme defined in PEP 440.
|
||||
|
||||
|
|
@ -932,15 +933,58 @@ a distribution does not provide them, by assuming that a missing field
|
|||
indicates "Not applicable for this distribution".
|
||||
|
||||
|
||||
Dependency specifications
|
||||
-------------------------
|
||||
Dependency specifiers
|
||||
---------------------
|
||||
|
||||
Individual dependencies are typically defined as strings containing a
|
||||
distribution name (as found in the ``name`` field). The dependency name
|
||||
While many dependencies will be needed to use a distribution at all, others
|
||||
are needed only on particular platforms or only when particular optional
|
||||
features of the distribution are needed. To handle this, dependency
|
||||
specifiers are mappings with the following subfields:
|
||||
|
||||
* ``requires``: a list of `requirement specifiers
|
||||
<Requirement specifiers>`__ needed to satisfy the dependency
|
||||
* ``extra``: the name of a set of optional dependencies that are requested
|
||||
and installed together. See `Extras (optional dependencies)`_ for details.
|
||||
* ``environment``: an environment marker defining the environment that
|
||||
needs these dependencies. See `Environment markers`_ for details.
|
||||
|
||||
``requires`` is the only required subfield. When it is the only subfield, the
|
||||
dependencies are said to be *unconditional*. If ``extra`` or ``environment``
|
||||
is specified, then the dependencies are *conditional*.
|
||||
|
||||
All three fields may be supplied, indicating that the dependencies are
|
||||
needed only when the named extra is requested in a particular environment.
|
||||
|
||||
Automated tools MUST combine related dependency specifiers (those with
|
||||
common values for ``extra`` and ``environment``) into a single specifier
|
||||
listing multiple requirements when serialising metadata or
|
||||
passing it to an install hook.
|
||||
|
||||
Despite this required normalisation, the same extra name or environment
|
||||
marker MAY appear in multiple conditional dependencies. This may happen,
|
||||
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.
|
||||
|
||||
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.
|
||||
|
||||
|
||||
Requirement specifiers
|
||||
----------------------
|
||||
|
||||
Individual requirements are defined as strings containing a distribution
|
||||
name (as found in the ``name`` field). The distribution name
|
||||
may be followed by an extras specifier (enclosed in square
|
||||
brackets) and by a version specifier or direct reference (within
|
||||
parentheses).
|
||||
|
||||
Whitespace is permitted between the distribution name and an opening
|
||||
square bracket or parenthesis. Whitespace is also permitted between a
|
||||
closing square bracket and an opening parenthesis.
|
||||
|
||||
See `Extras (optional dependencies)`_ for details on extras and PEP 440
|
||||
for details on version specifiers and direct references.
|
||||
|
||||
|
|
@ -949,7 +993,7 @@ Package Index`_; while these names are often the same as the module names
|
|||
as accessed with ``import x``, this is not always the case (especially
|
||||
for distributions that provide multiple top level modules or packages).
|
||||
|
||||
Example dependency specifications::
|
||||
Example requirement specifiers::
|
||||
|
||||
"Flask"
|
||||
"Django"
|
||||
|
|
@ -959,36 +1003,6 @@ Example dependency specifications::
|
|||
"ComfyChair[warmup] (> 0.1)"
|
||||
|
||||
|
||||
Conditional dependencies
|
||||
------------------------
|
||||
|
||||
While many dependencies will be needed to use a distribution at all, others
|
||||
are needed only on particular platforms or only when particular optional
|
||||
features of the distribution are needed. To enable this, dependency fields
|
||||
are marked as either unconditional (indicated by ``requires`` in the field
|
||||
name) or conditional (indicated by ``may_require``) in the field name.
|
||||
|
||||
Unconditional dependency fields are lists of dependency specifications, with
|
||||
each entry indicated a required dependency.
|
||||
|
||||
Conditional dependencies are lists of mappings with the following fields:
|
||||
|
||||
* ``dependencies``: a list of relevant dependency specifications
|
||||
* ``extra``: the name of a set of optional dependencies that are requested
|
||||
and installed together. See `Extras (optional dependencies)`_ for details.
|
||||
* ``environment``: an environment marker defining the environment that
|
||||
needs these dependencies. See `Environment markers`_ for details.
|
||||
|
||||
The ``dependencies`` field is required, as is at least one of ``extra`` and
|
||||
``environment``. All three fields may be supplied, indicating that the
|
||||
dependency is needed only when that particular set of additional
|
||||
dependencies is requested in a particular environment.
|
||||
|
||||
Note that the same extras and environment markers MAY appear in multiple
|
||||
conditional dependencies. This may happen, for example, if an extra itself
|
||||
only needs some of its dependencies in specific environments.
|
||||
|
||||
|
||||
Mapping dependencies to development and distribution activities
|
||||
---------------------------------------------------------------
|
||||
|
||||
|
|
@ -999,44 +1013,33 @@ should be installed for the specified activities:
|
|||
* Implied runtime dependencies:
|
||||
|
||||
* ``meta_requires``
|
||||
* ``meta_may_require``
|
||||
* ``run_requires``
|
||||
* ``run_may_require``
|
||||
|
||||
* Implied build dependencies:
|
||||
|
||||
* ``build_requires``
|
||||
* ``build_may_require``
|
||||
* If running the distribution's test suite as part of the build process,
|
||||
request the ``:meta:``, ``:run:`` and ``:test:`` extras to also
|
||||
install:
|
||||
|
||||
* ``meta_requires``
|
||||
* ``meta_may_require``
|
||||
* ``run_requires``
|
||||
* ``run_may_require``
|
||||
* ``test_requires``
|
||||
* ``test_may_require``
|
||||
|
||||
* Implied development and publication dependencies:
|
||||
|
||||
* ``meta_requires``
|
||||
* ``meta_may_require``
|
||||
* ``run_requires``
|
||||
* ``run_may_require``
|
||||
* ``build_requires``
|
||||
* ``build_may_require``
|
||||
* ``test_requires``
|
||||
* ``test_may_require``
|
||||
* ``dev_requires``
|
||||
* ``dev_may_require``
|
||||
|
||||
The notation described in `Extras (optional dependencies)`_ SHOULD be used
|
||||
to determine exactly what gets installed for various operations.
|
||||
|
||||
Installation tools SHOULD report an error if dependencies cannot be found,
|
||||
MUST at least emit a warning, and MAY allow the user to force the
|
||||
installation to proceed regardless.
|
||||
Installation tools SHOULD report an error if dependencies cannot be
|
||||
satisfied, MUST at least emit a warning, and MAY allow the user to force
|
||||
the installation to proceed regardless.
|
||||
|
||||
See Appendix B for an overview of mapping these dependencies to an RPM
|
||||
spec file.
|
||||
|
|
@ -1046,8 +1049,8 @@ Extras
|
|||
------
|
||||
|
||||
A list of optional sets of dependencies that may be used to define
|
||||
conditional dependencies in ``"may_distribute"``, ``"run_may_require"`` and
|
||||
similar fields. See `Extras (optional dependencies)`_ for details.
|
||||
conditional dependencies in dependency fields. See
|
||||
`Extras (optional dependencies)`_ for details.
|
||||
|
||||
The names of extras MUST abide by the same restrictions as those for
|
||||
distribution names.
|
||||
|
|
@ -1080,39 +1083,13 @@ archives SHOULD define appropriate constraints in their
|
|||
|
||||
Example::
|
||||
|
||||
"meta_requires": ["ComfyUpholstery (== 1.0a2)",
|
||||
"ComfySeatCushion (== 1.0a2)"]
|
||||
|
||||
|
||||
Meta may require
|
||||
----------------
|
||||
|
||||
An abbreviation of "metadistribution may require". This is a list of
|
||||
subdistributions that can easily be installed and used together by
|
||||
depending on this metadistribution, but are not required in all
|
||||
circumstances.
|
||||
|
||||
Any extras referenced from this field MUST be named in the `Extras`_ field.
|
||||
|
||||
In this field, automated tools:
|
||||
|
||||
* MUST allow strict version matching
|
||||
* MUST NOT allow more permissive version specifiers.
|
||||
* MAY allow direct references
|
||||
|
||||
Public index servers SHOULD NOT allow the use of direct references in
|
||||
uploaded distributions. Direct references are intended primarily as a
|
||||
tool for software integrators rather than publishers.
|
||||
|
||||
Distributions that rely on direct references to platform specific binary
|
||||
archives SHOULD defined appropriate constraints in their
|
||||
``supports_environments`` field.
|
||||
|
||||
Example::
|
||||
|
||||
"meta_may_require": [
|
||||
"meta_requires":
|
||||
{
|
||||
"dependencies": ["CupOfTeaAtEleven (== 1.0a2)"],
|
||||
"requires": ["ComfyUpholstery (== 1.0a2)",
|
||||
"ComfySeatCushion (== 1.0a2)"]
|
||||
},
|
||||
{
|
||||
"requires": ["CupOfTeaAtEleven (== 1.0a2)"],
|
||||
"environment": "'linux' in sys.platform"
|
||||
}
|
||||
]
|
||||
|
|
@ -1129,31 +1106,16 @@ in ``meta_requires`` instead.
|
|||
|
||||
Example::
|
||||
|
||||
"run_requires": ["SciPy", "PasteDeploy", "zope.interface (>3.5.0)"]
|
||||
|
||||
|
||||
Run may require
|
||||
---------------
|
||||
|
||||
A list of other distributions that may be needed to actually run this
|
||||
distribution, based on the extras requested and the target deployment
|
||||
environment.
|
||||
|
||||
Any extras referenced from this field MUST be named in the `Extras`_ field.
|
||||
|
||||
Automated tools MUST NOT allow strict version matching clauses or direct
|
||||
references in this field - if permitted at all, such clauses should appear
|
||||
in ``meta_may_require`` instead.
|
||||
|
||||
Example::
|
||||
|
||||
"run_may_require": [
|
||||
"run_requires":
|
||||
{
|
||||
"dependencies": ["pywin32 (>1.0)"],
|
||||
"requires": ["SciPy", "PasteDeploy", "zope.interface (>3.5.0)"]
|
||||
},
|
||||
{
|
||||
"requires": ["pywin32 (>1.0)"],
|
||||
"environment": "sys.platform == 'win32'"
|
||||
},
|
||||
{
|
||||
"dependencies": ["SoftCushions"],
|
||||
"requires": ["SoftCushions"],
|
||||
"extra": "warmup"
|
||||
}
|
||||
]
|
||||
|
|
@ -1173,32 +1135,16 @@ direct references in this field.
|
|||
|
||||
Example::
|
||||
|
||||
"test_requires": ["unittest2"]
|
||||
|
||||
|
||||
Test may require
|
||||
----------------
|
||||
|
||||
A list of other distributions that may be needed in order to run the
|
||||
automated tests for this distribution.
|
||||
|
||||
Any extras referenced from this field MUST be named in the `Extras`_ field.
|
||||
|
||||
Automated tools MAY disallow strict version matching clauses and direct
|
||||
references in this field and SHOULD at least emit a warning for such clauses.
|
||||
|
||||
Public index servers SHOULD NOT allow strict version matching clauses or
|
||||
direct references in this field.
|
||||
|
||||
Example::
|
||||
|
||||
"test_may_require": [
|
||||
"test_requires":
|
||||
{
|
||||
"dependencies": ["pywin32 (>1.0)"],
|
||||
"requires": ["unittest2"]
|
||||
},
|
||||
{
|
||||
"requires": ["pywin32 (>1.0)"],
|
||||
"environment": "sys.platform == 'win32'"
|
||||
},
|
||||
{
|
||||
"dependencies": ["CompressPadding"],
|
||||
"requires": ["CompressPadding"],
|
||||
"extra": "warmup"
|
||||
}
|
||||
]
|
||||
|
|
@ -1221,39 +1167,16 @@ direct references in this field.
|
|||
|
||||
Example::
|
||||
|
||||
"build_requires": ["setuptools (>= 0.7)"]
|
||||
|
||||
|
||||
Build may require
|
||||
-----------------
|
||||
|
||||
A list of other distributions that may be needed when this distribution
|
||||
is built (creating a binary archive from an sdist, source archive or
|
||||
VCS checkout), based on the features requested and the build environment.
|
||||
|
||||
Note that while these are build dependencies for the distribution being
|
||||
built, the installation is a *deployment* scenario for the dependencies.
|
||||
|
||||
Any extras referenced from this field MUST be named in the `Extras`_ field.
|
||||
|
||||
Automated tools MAY assume that all extras are implicitly requested when
|
||||
installing build dependencies.
|
||||
|
||||
Automated tools MAY disallow strict version matching clauses and direct
|
||||
references in this field and SHOULD at least emit a warning for such clauses.
|
||||
|
||||
Public index servers SHOULD NOT allow strict version matching clauses or
|
||||
direct references in this field.
|
||||
|
||||
Example::
|
||||
|
||||
"build_may_require": [
|
||||
"build_requires":
|
||||
{
|
||||
"dependencies": ["pywin32 (>1.0)"],
|
||||
"requires": ["setuptools (>= 0.7)"]
|
||||
},
|
||||
{
|
||||
"requires": ["pywin32 (>1.0)"],
|
||||
"environment": "sys.platform == 'win32'"
|
||||
},
|
||||
{
|
||||
"dependencies": ["cython"],
|
||||
"requires": ["cython"],
|
||||
"extra": "c-accelerators"
|
||||
}
|
||||
]
|
||||
|
|
@ -1280,35 +1203,12 @@ direct references in this field.
|
|||
|
||||
Example::
|
||||
|
||||
"dev_requires": ["hgtools", "sphinx (>= 1.0)"]
|
||||
|
||||
|
||||
Dev may require
|
||||
---------------
|
||||
|
||||
A list of other distributions that may be needed during development of
|
||||
this distribution, based on the features requested and the build environment.
|
||||
|
||||
This should only be needed if the project's own utility scripts have
|
||||
platform specific dependencies that aren't already defined as deployment
|
||||
or build dependencies.
|
||||
|
||||
Any extras referenced from this field MUST be named in the `Extras`_ field.
|
||||
|
||||
Automated tools MAY assume that all extras are implicitly requested when
|
||||
installing development dependencies.
|
||||
|
||||
Automated tools MAY disallow strict version matching clauses and direct
|
||||
references in this field and SHOULD at least emit a warning for such clauses.
|
||||
|
||||
Public index servers SHOULD NOT allow strict version matching clauses or
|
||||
direct references in this field.
|
||||
|
||||
Example::
|
||||
|
||||
"dev_may_require": [
|
||||
"dev_requires":
|
||||
{
|
||||
"dependencies": ["pywin32 (>1.0)"],
|
||||
"requires": ["hgtools", "sphinx (>= 1.0)"]
|
||||
},
|
||||
{
|
||||
"requires": ["pywin32 (>1.0)"],
|
||||
"environment": "sys.platform == 'win32'"
|
||||
}
|
||||
]
|
||||
|
|
@ -1334,11 +1234,8 @@ project is able to include a ``"provides": ["distribute"]`` entry to
|
|||
satisfy any projects that require the now obsolete distribution's name.
|
||||
|
||||
To avoid malicious hijacking of names, when interpreting metadata retrieved
|
||||
from a public index server, automated tools MUST prefer the distribution
|
||||
named in a version specifier over other distributions using that
|
||||
distribution's name in a ``"provides"`` entry. Index servers MAY drop such
|
||||
entries from the metadata they republish, but SHOULD NOT refuse to publish
|
||||
such distributions.
|
||||
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
|
||||
|
|
@ -1346,7 +1243,7 @@ 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 also provide a "virtual" project name, which does
|
||||
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
|
||||
|
|
@ -1354,13 +1251,20 @@ 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.
|
||||
|
||||
A version declaration may be supplied and must follow the rules described
|
||||
in PEP 440. The distribution's version identifier will be implied
|
||||
if none is specified.
|
||||
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"]
|
||||
"provides": ["AnotherProject (3.4)", "virtual-package"]
|
||||
|
||||
|
||||
Obsoleted by
|
||||
|
|
@ -1596,15 +1500,15 @@ Example of a distribution with optional dependencies::
|
|||
|
||||
"name": "ComfyChair",
|
||||
"extras": ["warmup", "c-accelerators"]
|
||||
"run_may_require": [
|
||||
"run_requires": [
|
||||
{
|
||||
"dependencies": ["SoftCushions"],
|
||||
"requires": ["SoftCushions"],
|
||||
"extra": "warmup"
|
||||
}
|
||||
]
|
||||
"build_may_require": [
|
||||
"build_requires": [
|
||||
{
|
||||
"dependencies": ["cython"],
|
||||
"requires": ["cython"],
|
||||
"extra": "c-accelerators"
|
||||
}
|
||||
]
|
||||
|
|
@ -1617,18 +1521,20 @@ Extra specifications MUST allow the following additional syntax:
|
|||
|
||||
* Multiple extras can be requested by separating them with a comma within
|
||||
the brackets.
|
||||
|
||||
* The following special extras request processing of the corresponding
|
||||
lists of dependencies:
|
||||
|
||||
* ``:meta:``: ``meta_requires`` and ``meta_may_require``
|
||||
* ``:run:``: ``run_requires`` and ``run_may_require``
|
||||
* ``:test:``: ``test_requires`` and ``test_may_require``
|
||||
* ``:build:``: ``build_requires`` and ``build_may_require``
|
||||
* ``:dev:``: ``dev_requires`` and ``dev_may_require``
|
||||
* ``:meta:``: ``meta_requires``
|
||||
* ``:run:``: ``run_requires``
|
||||
* ``:test:``: ``test_requires``
|
||||
* ``:build:``: ``build_requires``
|
||||
* ``:dev:``: ``dev_requires``
|
||||
* ``:*:``: process *all* dependency lists
|
||||
|
||||
* The ``*`` character as an extra is a wild card that enables all of the
|
||||
entries defined in the distribution's ``extras`` field.
|
||||
|
||||
* 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
|
||||
|
|
@ -1646,14 +1552,14 @@ allow extras to be requested explicitly.
|
|||
The full set of dependency requirements is then based on the top level
|
||||
dependencies, along with those of any requested extras.
|
||||
|
||||
Dependency examples::
|
||||
Dependency examples (showing just the ``requires`` subfield)::
|
||||
|
||||
"run_requires": ["ComfyChair[warmup]"]
|
||||
-> requires ``ComfyChair`` and ``SoftCushions`` at run time
|
||||
"requires": ["ComfyChair[warmup]"]
|
||||
-> requires ``ComfyChair`` and ``SoftCushions``
|
||||
|
||||
"run_requires": ["ComfyChair[*]"]
|
||||
-> requires ``ComfyChair`` and ``SoftCushions`` at run time, but
|
||||
will also pick up any new extras defined in later versions
|
||||
"requires": ["ComfyChair[*]"]
|
||||
-> requires ``ComfyChair`` and ``SoftCushions``, but will also
|
||||
pick up any new extras defined in later versions
|
||||
|
||||
Command line examples::
|
||||
|
||||
|
|
@ -1670,7 +1576,8 @@ Command line examples::
|
|||
-> as above, but also installs dependencies needed to run the tests
|
||||
|
||||
pip install ComfyChair[-,:*:,*]
|
||||
-> installs the full set of development dependencies
|
||||
-> installs the full set of development dependencies, but avoids
|
||||
installing ComfyChair itself
|
||||
|
||||
|
||||
Environment markers
|
||||
|
|
@ -1693,15 +1600,15 @@ And here's an example of some conditional metadata for a distribution that
|
|||
requires PyWin32 both at runtime and buildtime when using Windows::
|
||||
|
||||
"name": "ComfyChair",
|
||||
"run_may_require": [
|
||||
"run_requires": [
|
||||
{
|
||||
"dependencies": ["pywin32 (>1.0)"],
|
||||
"requires": ["pywin32 (>1.0)"],
|
||||
"environment": "sys.platform == 'win32'"
|
||||
}
|
||||
]
|
||||
"build_may_require": [
|
||||
"build_requires": [
|
||||
{
|
||||
"dependencies": ["pywin32 (>1.0)"],
|
||||
"requires": ["pywin32 (>1.0)"],
|
||||
"environment": "sys.platform == 'win32'"
|
||||
}
|
||||
]
|
||||
|
|
@ -1767,9 +1674,9 @@ Updating the metadata specification
|
|||
The metadata specification may be updated with clarifications without
|
||||
requiring a new PEP or a change to the metadata version.
|
||||
|
||||
Adding new features (other than through the extension mechanism), or
|
||||
changing the meaning of existing fields, requires a new metadata version
|
||||
defined in a new PEP.
|
||||
Changing the meaning of existing fields or adding new features (other than
|
||||
through the extension mechanism) requires a new metadata version defined in
|
||||
a new PEP.
|
||||
|
||||
|
||||
Appendix A: Conversion notes for legacy metadata
|
||||
|
|
@ -1801,28 +1708,21 @@ developers to upgrade to newer build systems.
|
|||
Appendix B: Mapping dependency declarations to an RPM SPEC file
|
||||
===============================================================
|
||||
|
||||
|
||||
As an example of mapping this PEP to Linux distro packages, assume an
|
||||
example project without any extras defined is split into 2 RPMs
|
||||
in a SPEC file: ``example`` and ``example-devel``.
|
||||
|
||||
The ``meta_requires``, ``run_requires`` and applicable
|
||||
``meta_may_require`` ``run_may_require`` dependencies would be mapped
|
||||
The ``meta_requires`` and ``run_requires`` dependencies would be mapped
|
||||
to the Requires dependencies for the "example" RPM (a mapping from
|
||||
environment markers relevant to Linux 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.
|
||||
The ``build_requires`` dependencies would be mapped to the BuildRequires
|
||||
dependencies for the "example" RPM.
|
||||
|
||||
All defined dependencies relevant to Linux, including those in
|
||||
``dev_requires``, ``test_requires``, ``dev_may_require``, and
|
||||
``test_may_require`` would become Requires dependencies for the
|
||||
"example-devel" RPM.
|
||||
|
||||
If the project did define any extras, those would likely be mapped to
|
||||
additional virtual RPMs with appropriate BuildRequires and Requires
|
||||
entries based on the details of the dependency specifications.
|
||||
``dev_requires`` and ``test_requires`` would become Requires dependencies
|
||||
for the "example-devel" RPM.
|
||||
|
||||
A documentation toolchain dependency like Sphinx would either go in
|
||||
``build_requires`` (for example, if man pages were included in the
|
||||
|
|
@ -1831,6 +1731,20 @@ documentation is published solely through ReadTheDocs or the
|
|||
project website). This would be enough to allow an automated converter
|
||||
to map it to an appropriate dependency in the spec file.
|
||||
|
||||
If the project did define any extras, those could be mapped to additional
|
||||
virtual RPMs with appropriate BuildRequires and Requires entries based on
|
||||
the details of the dependency specifications. Alternatively, they could
|
||||
be mapped to other system package manager features (such as package lists
|
||||
in ``yum``).
|
||||
|
||||
Other system package managers may have other options for dealing with
|
||||
extras (Debian packagers, for example, would have the option to map them
|
||||
to "Recommended" or "Suggested" package entries).
|
||||
|
||||
The metadata extension format should also allow distribution specific hints
|
||||
to be included in the upstream project metadata without needing to manually
|
||||
duplicate any of the upstream metadata in a distribution specific format.
|
||||
|
||||
|
||||
Appendix C: Summary of differences from \PEP 345
|
||||
=================================================
|
||||
|
|
@ -1986,7 +1900,7 @@ Support for optional dependencies for distributions
|
|||
---------------------------------------------------
|
||||
|
||||
The new extras system allows distributions to declare optional
|
||||
behaviour, and to use the ``*may_require`` fields to indicate when
|
||||
behaviour, and to use the dependency fields to indicate when
|
||||
particular dependencies are needed only to support that behaviour. It is
|
||||
derived from the equivalent system that is already in widespread use as
|
||||
part of ``setuptools`` and allows that aspect of the legacy ``setuptools``
|
||||
|
|
@ -2011,6 +1925,10 @@ to allow a distribution to depend on tools which *do* know how to handle
|
|||
the chosen extension, and the new extras mechanism, allowing support for
|
||||
particular extensions to be provided as optional features.
|
||||
|
||||
Possible future uses for extensions include declaration of plugins for
|
||||
other distributions, hints for automatic conversion to Linux system
|
||||
packages, and inclusion of CVE references to mark security releases.
|
||||
|
||||
|
||||
Support for install hooks
|
||||
---------------------------
|
||||
|
|
@ -2189,10 +2107,9 @@ MIME type registration
|
|||
At some point after acceptance of the PEP, I will likely submit the
|
||||
following MIME type registration requests to IANA:
|
||||
|
||||
* Full metadata: ``application/vnd.python.pymeta+json``
|
||||
* Abbreviated metadata: ``application/vnd.python.pymeta-short+json``
|
||||
* Full metadata: ``application/vnd.python.pydist+json``
|
||||
* Essential dependency resolution metadata:
|
||||
``application/vnd.python.pymeta-dependencies+json``
|
||||
``application/vnd.python.pydist-dependencies+json``
|
||||
|
||||
It's even possible we may be able to just register the ``vnd.python``
|
||||
namespace under the banner of the PSF rather than having to register
|
||||
|
|
@ -2365,6 +2282,15 @@ introducing too much additional complexity for too small a gain in
|
|||
expressiveness.
|
||||
|
||||
|
||||
Separate lists for conditional and unconditional dependencies
|
||||
-------------------------------------------------------------
|
||||
|
||||
Earlier versions of this PEP used separate lists for conditional and
|
||||
unconditional dependencies. This turned out to be annoying to handle in
|
||||
automated tools and removing it also made the PEP and metadata schema
|
||||
substantially shorter, suggesting it was actually harder to explain as well.
|
||||
|
||||
|
||||
Disallowing underscores in distribution names
|
||||
---------------------------------------------
|
||||
|
||||
|
|
|
|||
|
|
@ -17,7 +17,7 @@
|
|||
"name": {
|
||||
"description": "The name of the distribution.",
|
||||
"type": "string",
|
||||
"pattern": "^[0-9A-Za-z]([0-9A-Za-z_.-]*[0-9A-Za-z])?$"
|
||||
"$ref": "#/definitions/valid_name"
|
||||
},
|
||||
"version": {
|
||||
"description": "The distribution's public version identifier",
|
||||
|
|
@ -103,65 +103,43 @@
|
|||
"$ref": "#/definitions/extra_name"
|
||||
}
|
||||
},
|
||||
"distributes": {
|
||||
"meta_requires": {
|
||||
"description": "A list of subdistributions made available through this metadistribution.",
|
||||
"type": "array",
|
||||
"$ref": "#/definitions/dependencies"
|
||||
},
|
||||
"may_distribute": {
|
||||
"description": "A list of subdistributions that may be made available through this metadistribution, based on the extras requested and the target deployment environment.",
|
||||
"$ref": "#/definitions/conditional_dependencies"
|
||||
},
|
||||
"run_requires": {
|
||||
"description": "A list of other distributions needed when to run this distribution.",
|
||||
"description": "A list of other distributions needed to run this distribution.",
|
||||
"type": "array",
|
||||
"$ref": "#/definitions/dependencies"
|
||||
},
|
||||
"run_may_require": {
|
||||
"description": "A list of other distributions that may be needed when this distribution is deployed, based on the extras requested and the target deployment environment.",
|
||||
"$ref": "#/definitions/conditional_dependencies"
|
||||
},
|
||||
"test_requires": {
|
||||
"description": "A list of other distributions needed when this distribution is tested.",
|
||||
"type": "array",
|
||||
"$ref": "#/definitions/dependencies"
|
||||
},
|
||||
"test_may_require": {
|
||||
"description": "A list of other distributions that may be needed when this distribution is tested, based on the extras requested and the target deployment environment.",
|
||||
"type": "array",
|
||||
"$ref": "#/definitions/conditional_dependencies"
|
||||
},
|
||||
"build_requires": {
|
||||
"description": "A list of other distributions needed when this distribution is built.",
|
||||
"type": "array",
|
||||
"$ref": "#/definitions/dependencies"
|
||||
},
|
||||
"build_may_require": {
|
||||
"description": "A list of other distributions that may be needed when this distribution is built, based on the extras requested and the target deployment environment.",
|
||||
"type": "array",
|
||||
"$ref": "#/definitions/conditional_dependencies"
|
||||
},
|
||||
"dev_requires": {
|
||||
"description": "A list of other distributions needed when this distribution is developed.",
|
||||
"type": "array",
|
||||
"$ref": "#/definitions/dependencies"
|
||||
},
|
||||
"dev_may_require": {
|
||||
"description": "A list of other distributions that may be needed when this distribution is developed, based on the extras requested and the target deployment environment.",
|
||||
"type": "array",
|
||||
"$ref": "#/definitions/conditional_dependencies"
|
||||
},
|
||||
"provides": {
|
||||
"description": "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.",
|
||||
"description": "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)",
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string"
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/provides_declaration"
|
||||
}
|
||||
},
|
||||
"obsoleted_by": {
|
||||
"description": "A string that indicates that this project is no longer being developed. The named project provides a substitute or replacement.",
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/version_specifier"
|
||||
"$ref": "#/definitions/requirement"
|
||||
},
|
||||
"supports_environments": {
|
||||
"description": "A list of strings specifying the environments that the distribution explicitly supports.",
|
||||
|
|
@ -171,9 +149,19 @@
|
|||
"$ref": "#/definitions/environment_marker"
|
||||
}
|
||||
},
|
||||
"metabuild_hooks": {
|
||||
"description": "The metabuild_hooks field is used to define various operations that may be invoked on a distribution in a platform independent manner.",
|
||||
"type": "object"
|
||||
"install_hooks": {
|
||||
"description": "The install_hooks field is used to define various operations that may be invoked on a distribution in a platform independent manner.",
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"postinstall": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/entry_point"
|
||||
},
|
||||
"preuninstall": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/entry_point"
|
||||
}
|
||||
}
|
||||
},
|
||||
"extensions": {
|
||||
"description": "Extensions to the metadata may be present in a mapping under the 'extensions' key.",
|
||||
|
|
@ -181,7 +169,7 @@
|
|||
}
|
||||
},
|
||||
|
||||
"required": ["metadata_version", "name", "version"],
|
||||
"required": ["metadata_version", "name", "version", "summary"],
|
||||
"additionalProperties": false,
|
||||
|
||||
"definitions": {
|
||||
|
|
@ -205,43 +193,50 @@
|
|||
"additionalProperties": false
|
||||
},
|
||||
"dependencies": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/version_specifier"
|
||||
}
|
||||
},
|
||||
"conditional_dependencies": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"extra": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/extra_name"
|
||||
},
|
||||
"environment": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/environment_marker"
|
||||
},
|
||||
"dependencies": {
|
||||
"type": "array",
|
||||
"$ref": "#/definitions/dependencies"
|
||||
}
|
||||
},
|
||||
"required": ["dependencies"],
|
||||
"additionalProperties": false
|
||||
"$ref": "#/definitions/dependency"
|
||||
}
|
||||
},
|
||||
"version_specifier": {
|
||||
"dependency": {
|
||||
"type": "object",
|
||||
"properties": {
|
||||
"extra": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/valid_name"
|
||||
},
|
||||
"environment": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/environment_marker"
|
||||
},
|
||||
"requires": {
|
||||
"type": "array",
|
||||
"items": {
|
||||
"type": "string",
|
||||
"$ref": "#/definitions/requirement"
|
||||
}
|
||||
}
|
||||
},
|
||||
"required": ["requires"],
|
||||
"additionalProperties": false
|
||||
},
|
||||
"valid_name": {
|
||||
"type": "string",
|
||||
"pattern": "^[0-9A-Za-z]([0-9A-Za-z_.-]*[0-9A-Za-z])?$"
|
||||
},
|
||||
"requirement": {
|
||||
"type": "string"
|
||||
},
|
||||
"extra_name": {
|
||||
"provides_declaration": {
|
||||
"type": "string"
|
||||
},
|
||||
"environment_marker": {
|
||||
"type": "string"
|
||||
},
|
||||
"entry_point": {
|
||||
"type": "string"
|
||||
},
|
||||
"document_name": {
|
||||
"type": "string"
|
||||
}
|
||||
|
|
|
|||
Loading…
Reference in New Issue