gh-116127: PEP-705: Add `ReadOnly` support for `TypedDict` (#116350)

Co-authored-by: Jelle Zijlstra <jelle.zijlstra@gmail.com>

2 files changed, 43 insertions, 0 deletions

diff --git a/Doc/library/typing.rst b/Doc/library/typing.rst
index da70757..3db5f06 100644
--- a/Doc/library/typing.rst
+++ b/Doc/library/typing.rst
@@ -1274,6 +1274,26 @@ These can be used as types in annotations. They all support subscription using
 
    .. versionadded:: 3.11
 
+.. data:: ReadOnly
+
+   A special typing construct to mark an item of a :class:`TypedDict` as read-only.
+
+   For example::
+
+      class Movie(TypedDict):
+         title: ReadOnly[str]
+         year: int
+
+      def mutate_movie(m: Movie) -> None:
+         m["year"] = 1992  # allowed
+         m["title"] = "The Matrix"  # typechecker error
+
+   There is no runtime checking for this property.
+
+   See :class:`TypedDict` and :pep:`705` for more details.
+
+   .. versionadded:: 3.13
+
 .. data:: Annotated
 
    Special typing form to add context-specific metadata to an annotation.
@@ -2454,6 +2474,22 @@ types.
          ``__required_keys__`` and ``__optional_keys__`` rely on may not work
          properly, and the values of the attributes may be incorrect.
 
+   Support for :data:`ReadOnly` is reflected in the following attributes::
+
+   .. attribute:: __readonly_keys__
+
+      A :class:`frozenset` containing the names of all read-only keys. Keys
+      are read-only if they carry the :data:`ReadOnly` qualifier.
+
+      .. versionadded:: 3.13
+
+   .. attribute:: __mutable_keys__
+
+      A :class:`frozenset` containing the names of all mutable keys. Keys
+      are mutable if they do not carry the :data:`ReadOnly` qualifier.
+
+      .. versionadded:: 3.13
+
    See :pep:`589` for more examples and detailed rules of using ``TypedDict``.
 
    .. versionadded:: 3.8
@@ -2468,6 +2504,9 @@ types.
    .. versionchanged:: 3.13
       Removed support for the keyword-argument method of creating ``TypedDict``\ s.
 
+   .. versionchanged:: 3.13
+      Support for the :data:`ReadOnly` qualifier was added.
+
    .. deprecated-removed:: 3.13 3.15
       When using the functional syntax to create a TypedDict class, failing to
       pass a value to the 'fields' parameter (``TD = TypedDict("TD")``) is
diff --git a/Doc/whatsnew/3.13.rst b/Doc/whatsnew/3.13.rst
index 5193990..d78f219 100644
--- a/Doc/whatsnew/3.13.rst
+++ b/Doc/whatsnew/3.13.rst
@@ -602,6 +602,10 @@ typing
   check whether a class is a :class:`typing.Protocol`. (Contributed by Jelle Zijlstra in
   :gh:`104873`.)
 
+* Add :data:`typing.ReadOnly`, a special typing construct to mark
+  an item of a :class:`typing.TypedDict` as read-only for type checkers.
+  See :pep:`705` for more details.
+
 unicodedata
 -----------