diff --git a/peps/pep-0792.rst b/peps/pep-0792.rst index 04f7b737254..dcb984689d8 100644 --- a/peps/pep-0792.rst +++ b/peps/pep-0792.rst @@ -108,7 +108,7 @@ A project always has exactly one status. If no status is explicitly noted, then the project is considered to be in the ``active`` state. Indices **MAY** implement any subset of the status markers specified in this -PEP, as applicable. +PEP, as applicable to their needs. This PEP does not prescribe *which* principals (i.e. project maintainers, index administrators, etc.) are allowed to set and unset which statuses. @@ -189,10 +189,14 @@ HTML index The following changes are made to the :ref:`simple repository API `: -* The per-project index **SHALL** define the ``pypi:repository-version`` as ``1.4``. +* The per-project index **MUST** define the ``pypi:repository-version`` as ``1.4``. * The per-project index **SHOULD** add an appropriate ``pypi:project-status`` meta tag, with a ``content`` of the project's status marker. The index **MAY** choose to omit the ``pypi:project-status`` meta tag if the project is marked as ``active``. +* The per-project index **MAY** include a ``pypi:project-status-reason`` meta tag, + with a ``content`` of free-form text contextualizing the project's status. + The index **MAY** choose to omit the ``pypi:project-status-reason`` meta tag + if the project is marked as ``active`` or if no reason is provided. For example, the following would be a valid HTML index response for ``sampleproject`` after is has been marked as ``quarantined``: @@ -205,6 +209,7 @@ For example, the following would be a valid HTML index response for + Links for sampleproject @@ -221,10 +226,14 @@ JSON index The following changes are made to the :ref:`JSON simple index `: -* The per-project index **SHALL** define the ``meta.api-version`` as ``1.4``. -* The per-project index **SHOULD** include a ``project-status`` key in the JSON response, +* The per-project index **MUST** define the ``meta.api-version`` as ``1.4``. +* The per-project index **SHOULD** include a ``project-status.state`` key in the JSON response, with a value of the project's status marker. The index **MAY** choose to omit - the ``project-status`` key if the project is marked as ``active``. + the ``project-status.state`` key if the project is marked as ``active``. +* The per-project index **MAY** include a ``project-status.reason`` key in the JSON response, + with a value of free-form text contextualizing the project's status. + The index **MAY** choose to omit the ``project-status.reason`` key + if the project is marked as ``active`` or if no reason is provided. For example, the following would be a valid JSON index response for ``sampleproject`` after is has been marked as ``quarantined``: @@ -236,7 +245,10 @@ For example, the following would be a valid JSON index response for "meta": { "api-version": "1.4" }, - "project-status": "quarantined", + "project-status": { + "status": "quarantined", + "reason": "the project is haunted" + }, "alternate-locations": [], "files": [], "name": "sampleproject",