Note
This PEP wasaccepted on 2020-08-20.PyPImerged an implementationon 2020-01-28, marking this PEP as “Final”.
This PEP proposes adding a method for versioning the simple API sothat clients can determine which features of the simple API that aspecific repository supports.
When evolving the simple API, clients wish to be able to determinewhich features the repository supports. Currently there is nomechanism to do this, except by attempting to detect new featuresby looking at the data in the responses and see if it appears likea particular feature is in use.
This works reasonably well for a modern version of a client to determineif the repository supports all of the features it wants to implement,however it does not do anything to tell an older version the client thatthe repository supports features that it might not understand and toallow messaging to indicate that it might not be correctly understandingthe output of the repository.
An example of a scenario where this happened was the phasing in ofpython-requires metadata, while existing clients could still successfullyuse the repository, they were lacking the ability to understand this newpiece of data which would have informed their behavior to select a betterfile for end users.
This PEP proposes the inclusion of a meta tag on the responses of everysuccessful request to a simple API page, which contains a name attributeof “pypi:repository-version”, and a content that is aPEP 440 compatibleversion number, which is further constrained to ONLY be Major.Minor, andnone of the additional features supported byPEP 440.
This would end up looking like:
<metaname="pypi:repository-version"content="1.0">
When interpreting the repository version:
It is left up to the discretion of any future PEPs as to whatspecifically constitutes a backwards incompatible vs compatible changebeyond the broad suggestion that existing clients will be able to“meaningfully” continue to use the API, and can include adding,modifying, or removing existing features.
It is expectation of this PEP that the major version will never beincremented, and any future major API evolutions would utilize adifferent mechanism for API evolution. However the major versionis included to disambiguate with future versions (e.g. a hypotheticalsimple api v2 that lived at /v2/, but which would be confusing if therepository-version was set to a version >= 2).
This PEP sets the current API version to “1.0”, and expects thatfuture PEPs that further evolve the simple API will increment theminor version number.
Clients interacting with the simple APISHOULD introspect eachresponse for the repository version, and if that data does not existMUST assume that it is version 1.0.
When encountering a major version greater than expected, clientsMUST hard fail with an appropriate error message for the user.
When encountering a minor version greater than expected, clientsSHOULD warn users with an appropriate message.
ClientsMAY still continue to use feature detection in order todetermine what features a repository uses.
Instead of baking this information into the actual HTML, analternative would be to use a HTTP header. This idea wasconsidered and ultimately was rejected because it would makemirrors have to start modifying headers instead of being ableto operate as a “dumb” HTTP server of files.
Another traditional mechanism for versioning APIs is to bake itinto the URL, something like/1.0/simple/ or so. This workswell for major version changes where olders clients are notexpected to be capable of continuing to use it, but it is notwell suited to minor version bumps, particularly when the versionnumbers can be viewed as largely advisory for end users.
This document is placed in the public domain or under theCC0-1.0-Universal license, whichever is more permissive.
Source:https://github.com/python/peps/blob/main/peps/pep-0629.rst
Last modified:2025-02-01 08:55:40 GMT