From 241ab14717f56aa9741c30b7123a39f21952f671 Mon Sep 17 00:00:00 2001 From: Wouter Koorn <54982288+Wouterkoorn@users.noreply.github.com> Date: Mon, 27 Jun 2022 11:15:06 +0200 Subject: [PATCH 1/2] Grammer fixes and TODO's --- pep-0691.rst | 20 +++++++++++--------- 1 file changed, 11 insertions(+), 9 deletions(-) diff --git a/pep-0691.rst b/pep-0691.rst index a962c4007c9..c5710040587 100644 --- a/pep-0691.rst +++ b/pep-0691.rst @@ -51,7 +51,7 @@ did not propose any large changes to the API. In the intervening years, we've regularly talked about an "API V2" that would re-envision the entire API of PyPI. However, due to limited time constraints, -that effort has not gained much, if, any traction beyond people thinking that +that effort has not gained much, if any, traction beyond people thinking that it would be nice to do. This PEP attempts to take a different route. It doesn't fundamentally change @@ -99,7 +99,7 @@ Goals Specification ============= -To enable parsing responses with only the standard library, this PEP specifies that +To enable response parsing with only the standard library, this PEP specifies that all responses (besides the files themselves, and the HTML responses from :pep:`503`) should be serialized using `JSON `_. @@ -122,7 +122,7 @@ Similar to :pep:`629`, the major version number **MUST** be incremented if any changes to the new format would result in no longer being able to expect existing clients to meaningfully understand the format. -Likewise, incrementing the minor version **MUST** be incremented if features are +Likewise, the minor version **MUST** be incremented if features are added or removed from the format, but existing clients would be expected to continue to meaningfully understand the format. @@ -172,7 +172,7 @@ PEP: * All JSON responses will have a ``meta.api-version`` key, which will be a string that contains the :pep:`629` ``Major.Minor`` version number, with the same fail/warn - semantics as in :pep:`629`. + semantics as defined in :pep:`629`. * All requirements of :pep:`503` that are not HTML specific still apply. @@ -180,6 +180,7 @@ PEP: Project List ~~~~~~~~~~~~ +TODO: mention `metadata` key. The root URL ``/`` for this PEP (which represents the base URL) will be a JSON encoded dictionary which has a single key, ``projects``, which is an array where each entry is a dictionary with a single key, ``name``, which represents string of the project @@ -225,7 +226,7 @@ have a URL like ``/silly-walk/``. This URL must respond with a JSON encoded dictionary that has three keys: -- ``name``: The normalized name of the project. +- ``name``: The normalized name of the project. TODO: un-normalized isntead of normalized - ``files``: A list of dictionaries, each one representing an individual file. - ``meta``: The general response metadata as `described earlier `__. @@ -355,8 +356,8 @@ Version + Format Selection -------------------------- Now that there is multiple possible serializations, we need a mechanism to allow -clients to indicate what serialization formats that they're able to understand. In -addition, it would be a benefit if any possible new major version to the API can +clients to indicate what serialization formats they're able to understand. In +addition, it would be beneficial if any possible new major version to the API can be added without disrupting existing clients expecting the previous API version. To enable this, this PEP standardizes on the use of HTTP's @@ -512,7 +513,8 @@ Servers that implement the Simple API may choose to support an URL parameter nam ``format`` to allow the clients to request a specific version of the URL. The value of the ``format`` parameter should be **one** of the valid content types. -Passing multiple content types, wild cards, quality values, etc is **not** supported. +Passing multiple content types, wild cards, quality values, etc... is **not** +supported. Supporting this parameter is optional, and clients **SHOULD NOT** rely on it for interacting with the API. This negotiation mechanism is intended to allow for easier @@ -587,7 +589,7 @@ modified to include the API version and serialization format using something lik ``simple/PROJECT/vnd.pypi.simple.v1.json``. In this case, since ``text/html`` is an alias to ``application/vnd.pypi.simple.v1+html`` -when interacting through TUF, likely it will make the most sense to normalize to the +when interacting through TUF, it likely will make the most sense to normalize to the more explicit name. Likewise the ``latest`` metaversion should not be included in the targets, only From 867f19d2f0abff3746a0aa0b19e86d01a45ff77e Mon Sep 17 00:00:00 2001 From: Wouter Koorn <54982288+Wouterkoorn@users.noreply.github.com> Date: Mon, 27 Jun 2022 15:50:53 +0200 Subject: [PATCH 2/2] Added missing meta key to Project List description --- pep-0691.rst | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/pep-0691.rst b/pep-0691.rst index c5710040587..377381a162d 100644 --- a/pep-0691.rst +++ b/pep-0691.rst @@ -180,11 +180,12 @@ PEP: Project List ~~~~~~~~~~~~ -TODO: mention `metadata` key. The root URL ``/`` for this PEP (which represents the base URL) will be a JSON encoded -dictionary which has a single key, ``projects``, which is an array where each entry -is a dictionary with a single key, ``name``, which represents string of the project -name. As an example: +dictionary which has a two keys: +- ``projects``: An array where each entry is a dictionary with a single key, ``name``, which represents string of the project name. +- ``meta``: The general response metadata as `described earlier `__. + +As an example: .. code-block:: json @@ -226,7 +227,7 @@ have a URL like ``/silly-walk/``. This URL must respond with a JSON encoded dictionary that has three keys: -- ``name``: The normalized name of the project. TODO: un-normalized isntead of normalized +- ``name``: The normalized name of the project. - ``files``: A list of dictionaries, each one representing an individual file. - ``meta``: The general response metadata as `described earlier `__.