PEP 835: Trim redundancy and tighten narrative

Author: till-varoquaux

peps/pep-0835.rst

@@ -30,37 +30,33 @@ Historically, Python has treated type metadata as an afterthought.
 ``Annotated[T, M]`` models metadata as a generic container, similar to how
 ``Union[X, Y]`` once modeled unions. But metadata is not a container; it is a
 modifier applied to a type.
-
-Just as :pep:`604` evolved unions from the ``Union`` container to the ``|``
-operator, the ``@`` syntax evolves metadata into a native language operator.
 Elevating metadata to first-class syntax recognizes that modern libraries
 increasingly use constraints on types (e.g., bounds, shapes, patterns).
 
-Previously, applying these constraints forced a frustrating compromise between
-type safety and readability. Before :pep:`593` (``Annotated``), frameworks like
-Pydantic and FastAPI embedded metadata directly into default values. This was
-concise but broke static analysis:
+Previously, applying these constraints forced a compromise between type safety
+and readability. Before :pep:`593` (``Annotated``), frameworks like Pydantic and
+FastAPI embedded metadata directly into default values. This was concise but
+broke static analysis:
 
 .. code-block::
    :class: bad
 
     class User(BaseModel):
-        id: int = Field(gt=0)
-        name: str = Field(min_length=3)
+        id: int = Field(gt=0, le=1000)
 
-Moving to ``Annotated`` fixed the typing semantics but introduced significant
-complexity. To hide the visual noise, libraries introduced alias types (e.g.,
-``PositiveInt``). However, the moment users step outside pre-packaged
+Moving to ``Annotated`` fixed the typing semantics but introduced deep nesting
+and syntactic overhead. To hide the complexity, libraries introduced alias types
+(e.g., ``PositiveInt``). However, the moment users step outside pre-packaged
 constraints, they are forced back into the complex syntax::
 
     from typing import Annotated
     from pydantic import BaseModel, Field, PositiveInt
 
     class User(BaseModel):
-        age: PositiveInt  # Concise but limited
+        age: PositiveInt  # Concise but limited alias
         id: Annotated[int, Field(gt=0, le=1000)]  # Verbose fallback
 
-The ``@`` shorthand resolves the ergonomic tradeoff, restoring the conciseness
+The ``@`` shorthand resolves this structural tradeoff, restoring the readability
 of early frameworks while preserving the strict semantics of ``Annotated``:
 
 .. code-block::
@@ -326,27 +322,15 @@ The metadata remains immediately accessible. This also resolves the pre-existing
 issue where ``"Foo" | int`` incorrectly produced ``ForwardRef('Foo | int')``
 under ``Format.FORWARDREF``.
 
-Importantly, because ``Format.TYPE`` can evaluate structurally when runtime
-dunder methods are missing (falling back to ``types.UnionType`` and
-``types.AnnotatedType`` for the ``|`` and ``@`` operators), it parses ``None
-@Metadata`` without requiring ``NoneType.__matmul__``.
-
-Parsing and Grammar
--------------------
-
-No changes to the Python grammar are required. Because ``@`` is already a valid
-operator, it is natively parsed as a binary operation. The shorthand is resolved
-during semantic analysis, entirely bypassing the need to patch grammar files or
-update the parser.
-
 Rationale
 =========
 
-Baking ``Annotated`` into native syntax removes ``typing`` import overhead,
+Integrating ``Annotated`` into native syntax removes ``typing`` import overhead,
 directly aiding runtime type introspection.
 
-Because ``@`` is already a valid expression operator, type checkers (Mypy,
-Pyright) require no parser changes, handling the syntax entirely during semantic
+Because ``@`` is already a valid expression operator, no changes to the Python
+grammar are required. Type checkers (Mypy, Pyright) and other static tools
+require no parser changes, handling the syntax entirely during semantic
 analysis. We have prototyped an automated conversion rule in Ruff, enabling
 automated codebase migrations, and CPython prototype testing confirms that
 libraries like ``typer`` and ``pydantic`` work natively out of the box.