Repository navigation
Expand file tree
/
Copy pathpep-0503.rst
More file actions
134 lines (101 loc) · 5.24 KB
/
Copy pathpep-0503.rst
File metadata and controls
134 lines (101 loc) · 5.24 KB
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
PEP: 503
Title: Simple Repository API
Author: Donald Stufft <donald@stufft.io>
BDFL-Delegate: Donald Stufft <donald@stufft.io>
Discussions-To: distutils-sig@python.org
Status: Final
Type: Standards Track
Topic: Packaging
Created: 04-Sep-2015
Post-History: 04-Sep-2015
Resolution: https://mail.python.org/pipermail/distutils-sig/2015-September/026899.html
.. canonical-pypa-spec:: :ref:`packaging:simple-repository-api`
Abstract
========
There are many implementations of a Python package repository and many tools
that consume them. Of these, the canonical implementation that defines what
the "simple" repository API looks like is the implementation that powers
PyPI. This document will specify that API, documenting what the correct
behavior for any implementation of the simple repository API.
Specification
=============
A repository that implements the simple API is defined by its base URL, this is
the top level URL that all additional URLs are below. The API is named the
"simple" repository due to the fact that PyPI's base URL is
``https://pypi.org/simple/``.
.. note:: All subsequent URLs in this document will be relative to this base
URL (so given PyPI's URL, a URL of ``/foo/`` would be
``https://pypi.org/simple/foo/``.
Within a repository, the root URL (``/`` for this PEP which represents the base
URL) **MUST** be a valid HTML5 page with a single anchor element per project in
the repository. The text of the anchor tag **MUST** be the name of
the project and the href attribute **MUST** link to the URL for that particular
project. As an example::
<!DOCTYPE html>
<html>
<body>
<a href="/frob/">frob</a>
<a href="/spamspamspam/">spamspamspam</a>
</body>
</html>
Below the root URL is another URL for each individual project contained within
a repository. The format of this URL is ``/<project>/`` where the ``<project>``
is replaced by the normalized name for that project, so a project named
"HolyGrail" would have a URL like ``/holygrail/``. This URL must respond with
a valid HTML5 page with a single anchor element per file for the project. The
href attribute **MUST** be a URL that links to the location of the file for
download, and the text of the anchor tag **MUST** match the final path
component (the filename) of the URL. The URL **SHOULD** include a hash in the
form of a URL fragment with the following syntax: ``#<hashname>=<hashvalue>``,
where ``<hashname>`` is the lowercase name of the hash function (such as
``sha256``) and ``<hashvalue>`` is the hex encoded digest.
In addition to the above, the following constraints are placed on the API:
* All URLs which respond with an HTML5 page **MUST** end with a ``/`` and the
repository **SHOULD** redirect the URLs without a ``/`` to add a ``/`` to the
end.
* URLs may be either absolute or relative as long as they point to the correct
location.
* There are no constraints on where the files must be hosted relative to the
repository.
* There may be any other HTML elements on the API pages as long as the required
anchor elements exist.
* Repositories **MAY** redirect unnormalized URLs to the canonical normalized
URL (e.g. ``/Foobar/`` may redirect to ``/foobar/``), however clients
**MUST NOT** rely on this redirection and **MUST** request the normalized
URL.
* Repositories **SHOULD** choose a hash function from one of the ones
guaranteed to be available via the ``hashlib`` module in the Python standard
library (currently ``md5``, ``sha1``, ``sha224``, ``sha256``, ``sha384``,
``sha512``). The current recommendation is to use ``sha256``.
* If there is a GPG signature for a particular distribution file it **MUST**
live alongside that file with the same name with a ``.asc`` appended to it.
So if the file ``/packages/HolyGrail-1.0.tar.gz`` existed and had an
associated signature, the signature would be located at
``/packages/HolyGrail-1.0.tar.gz.asc``.
* A repository **MAY** include a ``data-gpg-sig`` attribute on a file link with
a value of either ``true`` or ``false`` to indicate whether or not there is a
GPG signature. Repositories that do this **SHOULD** include it on every link.
* A repository **MAY** include a ``data-requires-python`` attribute on a file
link. This exposes the *Requires-Python* metadata field, specified in :pep:`345`,
for the corresponding release. Where this is present, installer tools
**SHOULD** ignore the download when installing to a Python version that
doesn't satisfy the requirement. For example::
<a href="..." data-requires-python=">=3">...</a>
In the attribute value, < and > have to be HTML encoded as ``<`` and
``>``, respectively.
Normalized Names
----------------
This PEP references the concept of a "normalized" project name. As per :pep:`426`
the only valid characters in a name are the ASCII alphabet, ASCII numbers,
``.``, ``-``, and ``_``. The name should be lowercased with all runs of the
characters ``.``, ``-``, or ``_`` replaced with a single ``-`` character. This
can be implemented in Python with the ``re`` module::
import re
def normalize(name):
return re.sub(r"[-_.]+", "-", name).lower()
Changes
-------
* The optional ``data-requires-python`` attribute was added in July 2016.
Copyright
=========
This document has been placed in the public domain.