From a043d889459c6652a69ed43d161c6dd345312e03 Mon Sep 17 00:00:00 2001 From: Nick Coghlan Date: Sun, 14 Jul 2013 23:27:22 +1000 Subject: [PATCH] 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) --- pep-0426.txt | 424 +++++++++++++++--------------------- pep-0426/pymeta-schema.json | 111 +++++----- 2 files changed, 228 insertions(+), 307 deletions(-) diff --git a/pep-0426.txt b/pep-0426.txt index f790cd6fc..3241295d2 100644 --- a/pep-0426.txt +++ b/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 `__ description of the distribution metadata is `available -`__. +`__. 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 + `__ 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 --------------------------------------------- diff --git a/pep-0426/pymeta-schema.json b/pep-0426/pymeta-schema.json index 2b67dafa8..fd0d888fd 100644 --- a/pep-0426/pymeta-schema.json +++ b/pep-0426/pymeta-schema.json @@ -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" }