Skip to content

PEP 821: Support for unpacking TypedDicts in Callable type hints #4764

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
Daraan wants to merge 2 commits into
base: main
Choose a base branch
from
Open

PEP 821: Support for unpacking TypedDicts in Callable type hints #4764

Daraan wants to merge 2 commits into from
+360 −0

Conversation

@Daraan
Copy link

@Daraan Daraan commented Dec 30, 2025 •
edited by hugovk
Loading

Basic requirements (all PEP Types)

  • Read and followed PEP 1 & PEP 12
  • File created from the latest PEP template
  • PEP has next available number, & set in filename (pep-NNNN.rst), PR title (PEP 123: <Title of PEP>) and PEP header
  • Title clearly, accurately and concisely describes the content in 79 characters or less
  • Core dev/PEP editor listed as Author or Sponsor, and formally confirmed their approval
  • Author, Status (Draft), Type and Created headers filled out correctly
  • PEP-Delegate, Topic, Requires and Replaces headers completed if appropriate
  • Required sections included
    • Abstract (first section)
    • Copyright (last section; exact wording from template required)
  • Code is well-formatted (PEP 7/PEP 8) and is in code blocks, with the right lexer names if non-Python
  • PEP builds with no warnings, pre-commit checks pass and content displays as intended in the rendered HTML
  • Authors/sponsor added to .github/CODEOWNERS for the PEP

Standards Track requirements

  • PEP topic discussed in a suitable venue with general agreement that a PEP is appropriate
  • Suggested sections included (unless not applicable)
    • Motivation
    • Rationale
    • Specification
    • Backwards Compatibility
    • Security Implications
    • How to Teach This
    • Reference Implementation
    • Rejected Ideas
    • Open Issues
  • Python-Version set to valid (pre-beta) future Python version, if relevant
  • Any project stated in the PEP as supporting/endorsing/benefiting from the PEP formally confirmed such
  • Right before or after initial merging, PEP discussion thread created and linked to in Discussions-To and Post-History

@ Editors and Team - There has been an initial discussion which went off track. I am inclined to open up a new one, or should the old one be continued?

📚 Documentation preview 📚: https://pep-previews--4764.org.readthedocs.build/

@Daraan Daraan requested a review from a team as a code owner December 30, 2025 17:14
@hugovk
Copy link
Member

hugovk commented Jan 5, 2026

Hello, PEPs need a sponsor before opening and assigning a PEP number. Please can you find a core dev sponsor via the discussion thread, and we can re-open then?

See https://peps.python.org/pep-0001/#submitting-a-pep

Thanks.

@hugovk hugovk closed this Jan 5, 2026
@JelleZijlstra
Copy link
Member

JelleZijlstra commented Jan 12, 2026

I can sponsor this PEP. I think PEP 821 is taken by now but @Daraan if you renumber it to the latest available number, we can merge it.

@JelleZijlstra JelleZijlstra reopened this Jan 12, 2026
@hugovk
Copy link
Member

hugovk commented Jan 12, 2026 •
edited
Loading

823 is next, please update the files to use this.

@hugovk hugovk changed the title PEP 821: Support for unpacking TypedDicts in Callable type hints PEP 823: Support for unpacking TypedDicts in Callable type hints Jan 12, 2026
@hugovk hugovk changed the title PEP 823: Support for unpacking TypedDicts in Callable type hints PEP 821: Support for unpacking TypedDicts in Callable type hints Jan 12, 2026
@hugovk
Copy link
Member

hugovk commented Jan 12, 2026

Actually, 821 isn't used, please keep it :)

hugovk
hugovk reviewed Jan 12, 2026
View reviewed changes
Copy link
Member

@hugovk hugovk left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Please also wrap to ~80 columns.

.github/CODEOWNERS
peps/pep-0815.rst @emmatyping
peps/pep-0816.rst @brettcannon
# ...
peps/pep-0821.rst @Daraan
Copy link
Member

@hugovk hugovk Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

CODEOWNERS can only list those with write permission, so put Jelle here:

Suggested change
peps/pep-0821.rst @Daraan
peps/pep-0821.rst @JelleZijlstra

peps/pep-0821.rst
Status: Draft
Type: Standards Track
Topic: Typing
Created: 30-Dec-2025
Copy link
Member

@hugovk hugovk Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Date of PEP number assingment:

Suggested change
Created: 30-Dec-2025
Created: 12-Jan-2026

peps/pep-0821.rst
Motivation
==========

The typing specification states:
Copy link
Member

@hugovk hugovk Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can link to the spec using intersphinx, something like:

Suggested change
The typing specification states:
The `typing specification <typing:callable>` states:

peps/pep-0821.rst
Comment on lines +34 to +35
— https://typing.python.org/en/latest/spec/callables.html#callable

Copy link
Member

@hugovk hugovk Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
— https://typing.python.org/en/latest/spec/callables.html#callable

peps/pep-0821.rst
— https://typing.python.org/en/latest/spec/callables.html#callable

This limitation makes it cumbersome to declare callables meant to be invoked
with keyword arguments. The existing solution is to define a Protocol::
Copy link
Member

@hugovk hugovk Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
with keyword arguments. The existing solution is to define a Protocol::
with keyword arguments. The existing solution is to define a ``Protocol``::

peps/pep-0821.rst
* ``extra_items`` from PEP 728 is respected: functions accepting additional
``**kwargs`` are valid if their annotation is compatible with the declared
type.
* If neither ``extra_items`` nor ``closed`` (PEP 728) is specified on the
Copy link
Member

@hugovk hugovk Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* If neither ``extra_items`` nor ``closed`` (PEP 728) is specified on the
* If neither ``extra_items`` nor ``closed`` (:pep:`728`) is specified on the

peps/pep-0821.rst
also accepted positionally); positional-only parameters for those keys are
rejected.

.. code-block:: python
Copy link
Member

@hugovk hugovk Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nit, you used :: elsewhere, which defaults to Python, so you could pick one and be consistent.

peps/pep-0821.rst
m2: IntKwPosCallable = mixed_poskw # Accepted
m3: IntKwPosCallable = mixed_posonly # Rejected
Inline TypedDicts (PEP 764):
Copy link
Member

@hugovk hugovk Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
Inline TypedDicts (PEP 764):
Inline ``TypedDicts`` (:pep:`764`):

peps/pep-0821.rst
========================

A prototype exists in mypy:
https://github.com/python/mypy/pull/16083
Copy link
Member

@hugovk hugovk Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
https://github.com/python/mypy/pull/16083
`python/mypy#16083 <https://github.com/python/mypy/pull/16083>`__.

peps/pep-0821.rst
Comment on lines +349 to +350
* :pep:`728` - ``extra_items`` in TypedDict
* :pep:`764` - Inline TypedDict
Copy link
Member

@hugovk hugovk Jan 12, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
* :pep:`728` - ``extra_items`` in TypedDict
* :pep:`764` - Inline TypedDict
* :pep:`728` - ``extra_items`` in ``TypedDict``
* :pep:`764` - Inline ``TypedDict``

@hugovk hugovk added the new-pep A new draft PEP submitted for initial review label Jan 12, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@hugovk hugovk hugovk left review comments

Assignees

No one assigned

Labels

new-pep A new draft PEP submitted for initial review

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@Daraan @hugovk @JelleZijlstra