Repository navigation
PEP 694: Address PEP Delegate's feedback - #4794
Merged
Merged
Conversation
* Remove the "action" keys in request bodies, and substitute for explicit end-points. This feels much more REST-ish. This is for both the publishing and file upload sessions. * Add an `authentication` cross-reference anchor. * Add a Recommendations for Client Implementers section for how clients like twine, uv, and GitHub actions *might* utilize the PEP 694 API. * Update the Change Log accordingly.
…at session creation.
Documentation build overview
|
willingc
approved these changes
Jun 22, 2026
* Fixed: some discrepancies about when an open publishing session is reused or when a new session is created. * Added: some language about creating a new publishing session for a name-version pair even if such has already been published. However the new session disallows uploading a file that has already been published, since those are immutable. * Added some client recommendations about multiple sessions.
* The file's contents are always the authoritative source of truth * PyPI is actively moving toward extracting metadata from the file. Also, add a little clarifying text to the Security Implications section.
adocarmo748-max
approved these changes
Jul 6, 2026
ethanfurman
pushed a commit
to ethanfurman/peps
that referenced
this pull request
Oct 8, 2026
…on#4794) * Session actions now use dedicated endpoint links instead of an ``action`` key in request bodies. Publishing sessions add ``links.publish`` and ``links.extend``; file upload sessions add ``links.complete`` and ``links.extend``. The ``links.session`` and ``links.file-upload-session`` endpoints are now used only for ``GET`` (status) and ``DELETE`` (cancel) operations. * Add non-normative :ref:`Recommendations for Client Implementers <client-recommendations>` section with suggested UX patterns for tools like twine, uv, and GitHub Actions. * Add FAQ entries explaining why project name and version are required at session creation. * Add a :ref:`security-implications` section. * Specify that attempting to replace an in-progress file upload returns a ``409 Conflict``. * Specify that uploading a file matching one already published for an existing release returns a ``409 Conflict``, since published artifacts are immutable. * Clarify the wording of the **Multiple Sessions** client recommendation example. * Relax session access from the exact creating credentials to any principal authorized to upload to the project, evaluated contemporaneously on each request. Adds an **Authentication and Authorization** model, handles permission changes mid-session, supports rotating Trusted Publishing tokens and multiple publishers contributing to one session, and notes the related security implications. * Remove the optional ``metadata`` key from the file upload session creation request. The uploaded file is the authoritative source of metadata, which the index extracts from the file itself. * Define an explicit publishing-session state machine. Rename the session-level ``pending`` status to ``open``, add a transitional ``processing`` status for deferred (``202 Accepted``) publishing, and document the ``error`` status as a still-editable state that records a failed deferred publish (with the reason reported in ``notices``). Add a **Publishing Session States** section with state descriptions and a transition table, specify that a synchronous publish failure leaves the session editable rather than entering ``error``, and require the server to reject cancellation with a ``409 Conflict`` while a session is ``processing``. Key the **Multiple Session Creation Requests** rule off any non-terminal state rather than ``pending``. * Document the file upload session state machine with a **File Upload Session States** section and transition table. Specify that any completion failure -- synchronous or deferred -- moves the session to ``error``, that an ``error`` file cannot be repaired in place (the client cancels or deletes it and starts a new file upload session), and that the server **MUST** reject a ``DELETE`` with a ``409 Conflict`` while a session is ``processing``. * Add state transition diagrams to the **Publishing Session States** and **File Upload Session States** sections, alongside the existing transition tables. * Make the suggested ``twine`` and ``uv`` command-line interfaces consistent: group the staged-session operations under a ``session`` subcommand (``session publish``/``session cancel``/``session status``), give ``uv`` the same staged-session follow-ups and session-id output as ``twine``, and align the GitHub Action's ``stage`` input with the ``--stage`` flag.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
📚 Documentation preview 📚: https://pep-previews--4794.org.readthedocs.build/