Skip to content

Commit 159835b

Browse files
woodruffwwoodruffw
authored
Merge branch 'main' into ww/set-is-collection
2 parents e72d295 + ce55f8f commit 159835b

6 files changed

+396
-188
lines changed

‎source/conf.py

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -132,27 +132,31 @@
132132
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-the-linkcheck-builder
133133

134134
linkcheck_ignore = [
135-
"http://localhost:\\d+",
136-
"https://packaging.python.org/en/latest/specifications/schemas/.*",
137-
"https://test.pypi.org/project/example-package-YOUR-USERNAME-HERE",
138-
"https://pypi.org/manage/*",
139-
"https://test.pypi.org/manage/*",
135+
r"http://localhost:\d+",
136+
r"https://packaging\.python\.org/en/latest/specifications/schemas/.*",
137+
r"https://test\.pypi\.org/project/example-package-YOUR-USERNAME-HERE",
138+
r"https://pypi\.org/manage/.*",
139+
r"https://test\.pypi\.org/manage/.*",
140140
# Temporarily ignored. Ref:
141141
# https://github.com/pypa/packaging.python.org/pull/1308#issuecomment-1775347690
142-
"https://www.breezy-vcs.org/*",
142+
r"https://www\.breezy-vcs\.org/.*",
143143
# Ignore while StackOverflow is blocking GitHub CI. Ref:
144144
# https://github.com/pypa/packaging.python.org/pull/1474
145-
"https://stackoverflow.com/*",
146-
"https://pyscaffold.org/*",
147-
"https://anaconda.org",
148-
"https://www.cisa.gov/sbom",
149-
"https://developers.redhat.com/products/softwarecollections/overview",
145+
r"https://stackoverflow\.com/.*",
146+
r"https://pyscaffold\.org/.*",
147+
r"https://anaconda\.org",
148+
r"https://www\.cisa\.gov/sbom",
149+
r"https://developers\.redhat\.com/products/softwarecollections/overview",
150+
r"https://math-atlas\.sourceforge\.net/?",
151+
r"https://click\.palletsprojects\.com/.*",
152+
r"https://typer\.tiangolo\.com/.*",
150153
]
151154
linkcheck_retries = 5
152155
# Ignore anchors for common targets when we know they likely won't be found
153156
linkcheck_anchors_ignore_for_url = [
154157
# GitHub synthesises anchors in JavaScript, so Sphinx can't find them in the HTML
155158
r"https://github\.com/",
159+
r"https://docs\.github\.com/",
156160
# While PyPI has its botscraping defenses active, Sphinx can't resolve the anchors
157161
# https://github.com/pypa/packaging.python.org/issues/1744
158162
r"https://pypi\.org/",

‎source/guides/publishing-package-distribution-releases-using-github-actions-ci-cd-workflows.rst

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -75,7 +75,7 @@ Let's begin! 🚀
7575

7676
.. attention::
7777

78-
For security reasons, you must require `manual approval <https://docs.github.com/en/actions/deployment/targeting-different-environments/using-environments-for-deployment#deployment-protection-rules>`_
78+
For security reasons, you must require `manual approval <https://docs.github.com/en/actions/how-tos/managing-workflow-runs-and-deployments/managing-deployments/managing-environments-for-deployment#creating-an-environment>`_
7979
on each run for the ``pypi`` environment.
8080

8181

‎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)