PEP 835: Shorthand syntax for Annotated type metadata by till-varoquaux · Pull Request #4995 · python/peps

till-varoquaux · 2026-06-11T02:52:53Z

This PR introduces a draft PEP proposing a shorthand syntax for typing.Annotated using the @ operator (e.g., x: int @ "metadata" instead of typing.Annotated[int, "metadata"]).

This proposal aims to improve the developer ergonomics of metadata-heavy typing frameworks like Pydantic, FastAPI, and SQLModel, aligning Python's type annotations with the conciseness of JVM languages (Java, Kotlin).

Author: Till Varoquaux
Sponsor: Ivan Levkivskyi (@ilevkivskyi)
Discourse Thread: https://discuss.python.org/t/106888

All prototype implementations (CPython, Mypy, Pyright, Ruff) are complete and linked in the Reference Implementation section.

Basic requirements (all PEP Types)

Standards Track requirements

till-varoquaux · 2026-06-11T02:55:29Z

@ilevkivskyi The draft is up and ready for your official sponsorship sign-off whenever you have a moment!

read-the-docs-community · 2026-06-11T02:57:04Z

Documentation build overview

📚 pep-previews | 🛠️ Build #33105185 | 📁 Comparing c237409 against latest (0cc5e08)

🔍 Preview build

701 files changed · + 1 added · ± 700 modified

+ Added

pep-9999/index.html

± Modified

ilevkivskyi

The draft LG! But please take a look at comments by @JelleZijlstra

till-varoquaux · 2026-06-12T03:08:34Z

Thanks so much for the review and the help getting this staged, @JelleZijlstra and @ilevkivskyi !

Since my sponsor (@ilevkivskyi) has officially signed off on the draft, could one of the PEP editors go ahead and assign this an official PEP number?

Let me know if there is anything else needed from my end before we can get this merged and move the conversation over to Discourse.

hugovk · 2026-06-12T05:14:43Z

Since my sponsor (@ilevkivskyi) has officially signed off on the draft, could one of the PEP editors go ahead and assign this an official PEP number?

Please use 835.

hugovk · 2026-06-12T05:16:12Z

+Title: Shorthand syntax for Annotated type metadata (Draft Proposal)
+Author: Till Varoquaux <till.varoquaux@gmail.com>
+Sponsor: Ivan Levkivskyi <levkivskyi@gmail.com>
+Discussions-To: https://discuss.python.org/t/106888


Put this old one in the Post-History, the new one will go here.

hugovk · 2026-06-12T05:17:13Z

+Status: Draft
+Type: Standards Track
+Topic: Typing
+Created: 19-Apr-2026


This is the date the PEP number is assigned.

Suggested change

Created: 19-Apr-2026

Created: 12-Jun-2026

hugovk · 2026-06-12T05:20:48Z

+Topic: Typing
+Created: 19-Apr-2026
+Python-Version: 3.16
+Post-History: 19-Apr-2026


This should be the date of each Discuss topic, with links.

hugovk · 2026-06-12T05:23:10Z

@@ -0,0 +1,473 @@
+PEP: 9999


Suggested change

PEP: 9999

PEP: 835

I've also added the new PEP checklist to the PR description, please check off the relevant ones, and remember the CODEOWNERS file.

hugovk · 2026-06-12T15:30:00Z

@@ -0,0 +1,473 @@
+PEP: 9999
+Title: Shorthand syntax for Annotated type metadata (Draft Proposal)


Suggested change

Title: Shorthand syntax for Annotated type metadata (Draft Proposal)

Title: Shorthand syntax for Annotated type metadata

hugovk · 2026-06-12T15:35:30Z

+that was concise but problematic for type checkers and runtime defaults::
+
+    # The older, now discouraged pattern


If you like, you can add red or green sidebars to code blocks to indicate which are "bad"/"discouraged" or "good"/"preferred". See how PEP 8 does it.

For example:

Suggested change

that was concise but problematic for type checkers and runtime defaults::

# The older, now discouraged pattern

that was concise but problematic for type checkers and runtime defaults:

.. code-block::

:class: bad

# The older, now discouraged pattern

Not required, and will leave others for you if you like :)

hugovk · 2026-06-12T15:38:02Z

+
+Since its introduction in :pep:`593`, ``Annotated`` has become the standard
+mechanism for attaching context-specific metadata to types. It is widely
+embraced by libraries such as **Pydantic**, **FastAPI**, and **SQLModel**.


Not sure if we need bold for these in the abstract and here, at least not the second time.

Suggested change

embraced by libraries such as **Pydantic**, **FastAPI**, and **SQLModel**.

embraced by libraries such as Pydantic, FastAPI, and SQLModel.

hugovk · 2026-06-12T15:41:28Z

+the language.
+
+This syntax also draws inspiration from other languages with strong metadata
+ecosystems, notably Java. In Java (formalized in `JSR 308 <https://jcp.org/en/jsr/detail?id=308>`_)


Prefer anonymous links:

Suggested change

ecosystems, notably Java. In Java (formalized in `JSR 308 <https://jcp.org/en/jsr/detail?id=308>`_)

ecosystems, notably Java. In Java (formalized in `JSR 308 <https://jcp.org/en/jsr/detail?id=308>`__)

hugovk · 2026-06-12T15:42:36Z

+and other JVM languages, the ``@`` symbol is standard for type annotations::
+


Suggested change

and other JVM languages, the ``@`` symbol is standard for type annotations::

and other JVM languages, the ``@`` symbol is standard for type annotations:

.. code-block:: java

hugovk · 2026-06-12T15:43:26Z

+object as ``X @ Y``::
+


pycon for Python console

Suggested change

object as ``X @ Y``::

object as ``X @ Y``:

.. code-block:: pycon

hugovk · 2026-06-12T15:43:44Z

+The ``repr()`` of an ``AnnotatedType`` uses the shorthand syntax::
+


Suggested change

The ``repr()`` of an ``AnnotatedType`` uses the shorthand syntax::

The ``repr()`` of an ``AnnotatedType`` uses the shorthand syntax:

.. code-block:: pycon

hugovk · 2026-06-12T15:44:03Z

+origin::
+


Suggested change

origin::

origin:

.. code-block:: pycon

PEP 9999: Shorthand syntax for Annotated type metadata

8f047d4

till-varoquaux requested a review from a team as a code owner June 11, 2026 02:52

JelleZijlstra reviewed Jun 11, 2026

View reviewed changes

Comment thread peps/pep-9999.rst Outdated

Comment thread peps/pep-9999.rst Outdated

Comment thread peps/pep-9999.rst Outdated

Comment thread peps/pep-9999.rst Outdated

Comment thread peps/pep-9999.rst

Comment thread peps/pep-9999.rst Outdated

Comment thread peps/pep-9999.rst Outdated

ilevkivskyi approved these changes Jun 12, 2026

View reviewed changes

Address review feedback

c237409

till-varoquaux force-pushed the feature/at-type-annot branch from b646aa7 to c237409 Compare June 12, 2026 03:02

hugovk changed the title ~~PEP 9999: Shorthand syntax for Annotated type metadata~~ PEP 835: Shorthand syntax for Annotated type metadata Jun 12, 2026

hugovk reviewed Jun 12, 2026

View reviewed changes

brianschubert added the new-pep A new draft PEP submitted for initial review label Jun 12, 2026

		@@ -0,0 +1,473 @@
		PEP: 9999
		Title: Shorthand syntax for Annotated type metadata (Draft Proposal)

		that was concise but problematic for type checkers and runtime defaults::

		# The older, now discouraged pattern

	embraced by libraries such as Pydantic, FastAPI, and SQLModel.
	embraced by libraries such as Pydantic, FastAPI, and SQLModel.

	ecosystems, notably Java. In Java (formalized in `JSR 308 <https://jcp.org/en/jsr/detail?id=308>`_)
	ecosystems, notably Java. In Java (formalized in `JSR 308 <https://jcp.org/en/jsr/detail?id=308>`__)

		and other JVM languages, the ``@`` symbol is standard for type annotations::

		The ``repr()`` of an ``AnnotatedType`` uses the shorthand syntax::

Uh oh!

Conversation

till-varoquaux commented Jun 11, 2026 • edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Basic requirements (all PEP Types)

Standards Track requirements

Uh oh!

till-varoquaux commented Jun 11, 2026

Uh oh!

read-the-docs-community Bot commented Jun 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Documentation build overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ilevkivskyi left a comment

Choose a reason for hiding this comment

Uh oh!

till-varoquaux commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk commented Jun 12, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

hugovk Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

till-varoquaux commented Jun 11, 2026 •

edited by hugovk

Loading

read-the-docs-community Bot commented Jun 11, 2026 •

edited

Loading

till-varoquaux commented Jun 12, 2026 •

edited

Loading

hugovk Jun 12, 2026 •

edited

Loading