Skip to content

Commit 6b10bd2

Browse files
woodruffwwoodruffw
committed
simple-repository-api: add PEP 792, clean up layout
1 parent 0edbfa0 commit 6b10bd2

File tree

4 files changed

+377
-175
lines changed

4 files changed

+377
-175
lines changed

‎source/specifications/file-yanking.rst

Lines changed: 92 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,92 @@
1+
.. _file-yanking:
2+
3+
============
4+
File Yanking
5+
============
6+
7+
.. note::
8+
9+
This specification was originally defined in
10+
:pep:`592`.
11+
12+
.. note::
13+
14+
:pep:`592` includes changes to the HTML and JSON index APIs.
15+
These changes are documented in the :ref:`simple-repository-api`
16+
under :ref:`HTML - Project Detail <simple-repository-html-project-detail>`
17+
and :ref:`JSON - Project Detail <simple-repository-json-project-detail>`.
18+
19+
Specification
20+
=============
21+
22+
Links in the simple repository **MAY** have a ``data-yanked`` attribute
23+
which may have no value, or may have an arbitrary string as a value. The
24+
presence of a ``data-yanked`` attribute **SHOULD** be interpreted as
25+
indicating that the file pointed to by this particular link has been
26+
"Yanked", and should not generally be selected by an installer, except
27+
under specific scenarios.
28+
29+
The value of the ``data-yanked`` attribute, if present, is an arbitrary
30+
string that represents the reason for why the file has been yanked. Tools
31+
that process the simple repository API **MAY** surface this string to
32+
end users.
33+
34+
The yanked attribute is not immutable once set, and may be rescinded in
35+
the future (and once rescinded, may be reset as well). Thus API users
36+
**MUST** be able to cope with a yanked file being "unyanked" (and even
37+
yanked again).
38+
39+
Installers
40+
----------
41+
42+
The desirable experience for users is that once a file is yanked, when
43+
a human being is currently trying to directly install a yanked file, that
44+
it fails as if that file had been deleted. However, when a human did that
45+
awhile ago, and now a computer is just continuing to mechanically follow
46+
the original order to install the now yanked file, then it acts as if it
47+
had not been yanked.
48+
49+
An installer **MUST** ignore yanked releases, if the selection constraints
50+
can be satisfied with a non-yanked version, and **MAY** refuse to use a
51+
yanked release even if it means that the request cannot be satisfied at all.
52+
An implementation **SHOULD** choose a policy that follows the spirit of the
53+
intention above, and that prevents "new" dependencies on yanked
54+
releases/files.
55+
56+
What this means is left up to the specific installer, to decide how to best
57+
fit into the overall usage of their installer. However, there are two
58+
suggested approaches to take:
59+
60+
1. Yanked files are always ignored, unless they are the only file that
61+
matches a version specifier that "pins" to an exact version using
62+
either ``==`` (without any modifiers that make it a range, such as
63+
``.*``) or ``===``. Matching this version specifier should otherwise
64+
be done as per :ref:`the version specifiers specification
65+
<version-specifiers>` for things like local versions, zero padding,
66+
etc.
67+
2. Yanked files are always ignored, unless they are the only file that
68+
matches what a lock file (such as ``Pipfile.lock`` or ``poetry.lock``)
69+
specifies to be installed. In this case, a yanked file **SHOULD** not
70+
be used when creating or updating a lock file from some input file or
71+
command.
72+
73+
Regardless of the specific strategy that an installer chooses for deciding
74+
when to install yanked files, an installer **SHOULD** emit a warning when
75+
it does decide to install a yanked file. That warning **MAY** utilize the
76+
value of the ``data-yanked`` attribute (if it has a value) to provide more
77+
specific feedback to the user about why that file had been yanked.
78+
79+
80+
Mirrors
81+
-------
82+
83+
Mirrors can generally treat yanked files one of two ways:
84+
85+
1. They may choose to omit them from their simple repository API completely,
86+
providing a view over the repository that shows only "active", unyanked
87+
files.
88+
2. They may choose to include yanked files, and additionally mirror the
89+
``data-yanked`` attribute as well.
90+
91+
Mirrors **MUST NOT** mirror a yanked file without also mirroring the
92+
``data-yanked`` attribute for it.

‎source/specifications/project-status-markers.rst

Lines changed: 89 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,89 @@
1+
.. _project-status-markers:
2+
3+
======================
4+
Project Status Markers
5+
======================
6+
7+
.. note::
8+
9+
This specification was originally defined in
10+
:pep:`792`.
11+
12+
.. note::
13+
14+
:pep:`792` includes changes to the HTML and JSON index APIs.
15+
These changes are documented in the :ref:`simple-repository-api`
16+
under :ref:`HTML - Project Detail <simple-repository-html-project-detail>`
17+
and :ref:`JSON - Project Detail <simple-repository-json-project-detail>`.
18+
19+
Specification
20+
=============
21+
22+
A project always has exactly one status. If no status is explicitly noted,
23+
then the project is considered to be in the ``active`` state.
24+
25+
Indices **MAY** implement any subset of the status markers specified,
26+
as applicable to their needs.
27+
28+
This standard does not prescribe *which* principals (i.e. project maintainers,
29+
index administrators, etc.) are allowed to set and unset which statuses.
30+
31+
``active``
32+
----------
33+
34+
Description: The project is active. This is the default status for a project.
35+
36+
Index semantics:
37+
38+
* The index hosting the project **MUST** allow uploads of new distributions to
39+
the project.
40+
* The index **MUST** offer existing distributions of the project for download.
41+
42+
Installer semantics: none.
43+
44+
``archived``
45+
------------
46+
47+
Description: The project does not expect to be updated in the future.
48+
49+
Index semantics:
50+
51+
* The index hosting the project **MUST NOT** allow uploads of new distributions to
52+
the project.
53+
* The index **MUST** offer existing distributions of the project for download.
54+
55+
Installer semantics:
56+
57+
* Installers **MAY** produce warnings about a project's archival.
58+
59+
``quarantined``
60+
---------------
61+
62+
Description: The project is considered generally unsafe for use, e.g. due to
63+
malware.
64+
65+
Index semantics:
66+
67+
* The index hosting the project **MUST NOT** allow uploads of new distributions to
68+
the project.
69+
* The index **MUST NOT** offer any distributions of the project for download.
70+
71+
Installer semantics:
72+
73+
* Installers **MAY** produce warnings about a project's quarantine, although
74+
doing so is effectively moot (as the index will not offer any distributions
75+
for installation).
76+
77+
``deprecated``
78+
--------------
79+
80+
Description: The project is considered obsolete, and may have been superseded
81+
by another project.
82+
83+
Index semantics:
84+
85+
* This status shares the same semantics as ``active``.
86+
87+
Installer semantics:
88+
89+
* Installers **MAY** produce warnings about a project's deprecation.

‎source/specifications/section-package-indices.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -7,4 +7,6 @@ Package Index Interfaces
77

88
pypirc
99
simple-repository-api
10+
file-yanking
1011
index-hosted-attestations
12+
project-status-markers

0 commit comments

Comments
 (0)