PEP 764: Inlined typed dictionaries

peps/conf.py

@@ -70,6 +70,7 @@
     "typing": ("https://typing.readthedocs.io/en/latest/", None),
     "trio": ("https://trio.readthedocs.io/en/latest/", None),
     "devguide": ("https://devguide.python.org/", None),
+    "mypy": ("https://mypy.readthedocs.io/en/latest/", None),
     "py3.11": ("https://docs.python.org/3.11/", None),
     "py3.12": ("https://docs.python.org/3.12/", None),
     "py3.13": ("https://docs.python.org/3.13/", None),

peps/pep-9995.rst

@@ -0,0 +1,218 @@
+PEP: 9995
+Title: Inlined typed dictionaries
+Author: Victorien Plot <[email protected]>
+Discussions-To:
+Status: Draft
+Type: Standards Track
+Topic: Typing
+Created: 23-Oct-2024
+Post-History:
+Python-Version: 3.14
+Resolution:
+
+.. highlight:: python
+
+
+Abstract
+========
+
+:pep:`589` defines a `class-based <https://typing.readthedocs.io/en/latest/spec/typeddict.html#class-based-syntax>`_ and a
+:ref:`functional syntax <typing:typeddict-functional-syntax>` to create typed
+dictionaries. In both scenarios, it requires defining a class or assigning to
+a value. In some situations, this can add unnecessary boilerplate, especially
+if the typed dictionary is only used once.
+
+This PEP proposes the addition of a new inlined syntax, by subscripting the
+:class:`~typing.TypedDict` type::
+
+    from typing import TypedDict
+
+    def get_movie() -> TypedDict[{'name': str, 'year': int}]:
+        return {
+            'name': 'Blade Runner',
+            'year': 1982,
+        }
+
+Motivation
+==========
+
+Python dictionaries are an essential data structure of the language. Many
+times, it is used to return or accept structured data in functions. However,
+it can get tedious to define :class:`~typing.TypedDict` classes:
+
+* A typed dictionary requires a name, which might not be relevant.
+* Nested dictionaries requires more than one class definition.
+
+Taking a simple function returning some nested structured data as an example::
+
+    from typing import TypedDict
+
+    class ProductionCompany(TypedDict):
+        name: str
+        location: str
+
+    class Movie(TypedDict):
+        name: str
+        year: int
+        production: ProductionCompany
+
+
+    def get_movie() -> Movie:
+        return {
+            'name': 'Blade Runner',
+            'year': 1982,
+            'production': {
+                'name': 'Warner Bros.',
+                'location': 'California',
+            }
+        }
+
+
+Rationale
+=========
+
+The new inlined syntax can be used to resolve these problems::
+
+    def get_movie() -> TypedDict[{'name': str, year: int, 'production': {'name': str, 'location': str}}]:
+        ...
+
+It is recommended to *only* make use of inlined typed dictionaries when the
+structured data isn't too large, as this can quickly get hard to read.
+
+While less useful (as the functional or even the class-based syntax can be
+used), inlined typed dictionaries can be defined as a type alias::
+
+    type InlinedDict = TypedDict[{'name': str}]
+
+Specification
+=============
+
+The :class:`~typing.TypedDict` class is made subscriptable, and accepts a
+single type argument which must be a :class:`dict`, following the same
+semantics as the :ref:`functional syntax <typing:typeddict-functional-syntax>`
+(the dictionary keys are strings representing the field names, and values are
+valid :ref:`annotation expressions <typing:annotation-expression>`).
+
+Inlined typed dictionaries can be referred as being *anonymous*, meaning they
+don't have a name. For this reason, their :attr:`~type.__name__` attribute
+will be set to an empty string.
+
+It is not possible to specify any class arguments such as ``total``.
+
+Runtime behavior
+----------------
+
+Although :class:`~typing.TypedDict` is commonly referred as a class, it is
+implemented as a function at runtime. To be made subscriptable, it will be
+changed to be a class.
+
+Creating an inlined typed dictionary results in a new class, so both syntaxes
+return the same type::
+
+    from typing import TypedDict
+
+    T1 = TypedDict('T1', {'a': int})
+    T2 = TypedDict[{'a': int}]
+
+
+Backwards Compatibility
+=======================
+
+Apart from the :class:`~typing.TypedDict` internal implementation change, this
+PEP does not bring any backwards incompatible changes.
+
+
+Security Implications
+=====================
+
+There are no known security consequences arising from this PEP.
+
+
+How to Teach This
+=================
+
+The new inlined syntax will be documented both in the :mod:`typing` module
+documentation and the :ref:`typing specification <typing:typed-dictionaries>`.
+
+As mentioned in the `Rationale`_, it should be mentioned that inlined typed
+dictionaries should be used for small structured data to not hurt readability.
+
+
+Reference Implementation
+========================
+
+Mypy supports a similar syntax as an :option:`experimental feature <mypy:mypy.--enable-incomplete-feature>`::
+
+    def test_values() -> {"int": int, "str": str}:
+        return {"int": 42, "str": "test"}
+
+Pyright has added support in version `1.1.297`_ (using :class:`dict`), but was later
+removed in version `1.1.366`_.
+
+.. _1.1.297: https://github.com/microsoft/pyright/releases/tag/1.1.297
+.. _1.1.366: https://github.com/microsoft/pyright/releases/tag/1.1.366
+
+Runtime implementation
+----------------------
+
+A draft implementation is available `here <https://github.com/Viicos/cpython/commit/49e5a83f>`_.
+
+
+Rejected Ideas
+==============
+
+Using the functional syntax in annotations
+------------------------------------------
+
+The alternative functional syntax could be used as an annotation directly::
+
+    def get_movie() -> TypedDict('Movie', {'title': str}): ...
+
+However, call expressions are currently unsupported in such a context for
+various reasons (expensive to process, evaluating them is not standardized).
+
+This would also require a name which is sometimes not relevant.
+
+Using ``dict`` with a single type argument
+------------------------------------------
+
+We could reuse :class:`dict` with a single type argument to express the same
+concept::
+
+    def get_movie() -> dict[{'title': str}]: ...
+
+While this would avoid having to import :class:`~typing.TypedDict` from
+:mod:`typing`, this solution has several downsides:
+
+* For type checkers, :class:`dict` is a regular class with two type variables.
+  Allowing :class:`dict` to be parametrized with a single type argument would
+  require special casing from type checkers, as there is no way to express
+  parametrization overloads. On ther other hand, :class:`~typing.TypedDict` is
+  already a :term:`special form <typing:special form>`.
+
+* If fufure work extends what inlined typed dictionaries can do, we don't have
+  to worry about impact of sharing the symbol with :class:`dict`.
+
+
+Open Issues
+===========
+
+Subclassing an inlined typed dictionary
+---------------------------------------
+
+Should we allow the following?::
+
+    from typing import TypedDict
+
+    InlinedTD = TypedDict[{'a': int}]
+
+
+    class SubTD(InlinedTD):
+        pass
+
+
+Copyright
+=========
+
+This document is placed in the public domain or under the
+CC0-1.0-Universal license, whichever is more permissive.