Python Enhancement Proposals

Python »
PEP Index »
PEP 503

PEP 503 – Simple Repository API

Author:: Donald Stufft <donald at stufft.io>
BDFL-Delegate:: Donald Stufft <donald at stufft.io>
Discussions-To:

Table of Contents

Important

This PEP is a historical document. The up-to-date, canonical spec,Simple repository API, is maintained on thePyPA specs page.

See thePyPA specification update process for how to propose changes.

Abstract

There are many implementations of a Python package repository and many toolsthat consume them. Of these, the canonical implementation that defines whatthe “simple” repository API looks like is the implementation that powersPyPI. This document will specify that API, documenting what the correctbehavior for any implementation of the simple repository API.

Specification

A repository that implements the simple API is defined by its base URL, this isthe 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 ishttps://pypi.org/simple/.

Note

All subsequent URLs in this document will be relative to this baseURL (so given PyPI’s URL, a URL of/foo/ would behttps://pypi.org/simple/foo/.

Within a repository, the root URL (/ for this PEP which represents the baseURL)MUST be a valid HTML5 page with a single anchor element per project inthe repository. The text of the anchor tagMUST be the name ofthe project and the href attributeMUST link to the URL for that particularproject. 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 withina 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 witha valid HTML5 page with a single anchor element per file for the project. Thehref attributeMUST be a URL that links to the location of the file fordownload, and the text of the anchor tagMUST match the final pathcomponent (the filename) of the URL. The URLSHOULD include a hash in theform of a URL fragment with the following syntax:#<hashname>=<hashvalue>,where<hashname> is the lowercase name of the hash function (such assha256) 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 pageMUST end with a/ and therepositorySHOULD redirect the URLs without a/ to add a/ to theend.
URLs may be either absolute or relative as long as they point to the correctlocation.
There are no constraints on where the files must be hosted relative to therepository.
There may be any other HTML elements on the API pages as long as the requiredanchor elements exist.
RepositoriesMAY redirect unnormalized URLs to the canonical normalizedURL (e.g./Foobar/ may redirect to/foobar/), however clientsMUST NOT rely on this redirection andMUST request the normalizedURL.
RepositoriesSHOULD choose a hash function from one of the onesguaranteed to be available via thehashlib module in the Python standardlibrary (currentlymd5,sha1,sha224,sha256,sha384,sha512). The current recommendation is to usesha256.
If there is a GPG signature for a particular distribution file itMUSTlive 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 anassociated signature, the signature would be located at/packages/HolyGrail-1.0.tar.gz.asc.
A repositoryMAY include adata-gpg-sig attribute on a file link witha value of eithertrue orfalse to indicate whether or not there is aGPG signature. Repositories that do thisSHOULD include it on every link.
A repositoryMAY include adata-requires-python attribute on a filelink. This exposes theRequires-Python metadata field, specified inPEP 345,for the corresponding release. Where this is present, installer toolsSHOULD ignore the download when installing to a Python version thatdoesn’t satisfy the requirement. For example:
```
<ahref="..."data-requires-python="&gt;=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 perPEP 426the only valid characters in a name are the ASCII alphabet, ASCII numbers,.,-, and_. The name should be lowercased with all runs of thecharacters.,-, or_ replaced with a single- character. Thiscan be implemented in Python with there module:

importredefnormalize(name):returnre.sub(r"[-_.]+","-",name).lower()

Changes

The optionaldata-requires-python attribute was added in July 2016.

Copyright

This document has been placed in the public domain.

Source:https://github.com/python/peps/blob/main/peps/pep-0503.rst