Carl feedback

JelleZijlstra · JelleZijlstra · commit 77ae2d19d9ac · 2025-08-19T14:53:05.000-07:00
diff --git a/docs/spec/concepts.rst b/docs/spec/concepts.rst
@@ -69,7 +69,7 @@ attributes and/or methods.
 
 If an object ``v`` is a member of the set of objects denoted by a fully static
 type ``T``, we can say that ``v`` is a "member of" the type ``T``, or ``v``
-"inhabits" ``T``.
+":term:`inhabits <inhabit>`" ``T``.
 
 Gradual types
 ~~~~~~~~~~~~~
@@ -298,9 +298,9 @@ visualize this analogy in the following table:
    * - ``B`` is :term:`equivalent` to ``A``
      - ``B`` is :term:`consistent` with ``A``
 
-We can also define an **equivalence** relation on gradual types: the gradual 
-types ``A`` and ``B`` are equivalent (that is, the same gradual type, not 
-merely consistent with one another) if and only if all materializations of 
+We can also define an **equivalence** relation on gradual types: the gradual
+types ``A`` and ``B`` are equivalent (that is, the same gradual type, not
+merely consistent with one another) if and only if all materializations of
 ``A`` are also materializations of ``B``, and all materializations of ``B``
 are also materializations of ``A``.
 
diff --git a/docs/spec/glossary.rst b/docs/spec/glossary.rst
@@ -61,8 +61,8 @@ This section defines a few terms that may be used elsewhere in the specification
 
    extra items
       A :ref:`TypedDict <typeddict>` type with extra items may contain arbitrary
-      additional :term:`items <item>` beyond those specified in the TypedDict definition, but those
-      items must be of the type specified by that definition.
+      additional key-value pairs beyond those specified in the TypedDict definition, but those
+      values must be of the type specified by the ``extra_items=`` argument to the definition.
       A TypedDict with extra items can be created using the ``extra_items=``
       argument to :py:func:`typing.TypedDict`. Extra items may or may not be
       :term:`read-only`. Compare :term:`closed` and :term:`open`.
@@ -94,6 +94,11 @@ This section defines a few terms that may be used elsewhere in the specification
       They can be :term:`materialized <materialize>` to a more static, or fully static,
       type. See :ref:`type-system-concepts`.
 
+   inhabit
+      A value is said to inhabit a type if it is a member of the set of values
+      represented by that type. For example, the value ``42`` inhabits the type
+      ``int``, and the value ``"hello"`` inhabits the type ``str``.
+
    inline
       Inline type annotations are annotations that are included in the
       runtime code using :pep:`526` and
diff --git a/docs/spec/typeddict.rst b/docs/spec/typeddict.rst
@@ -10,7 +10,7 @@ and ``NotRequired`` in :pep:`655`, use with ``Unpack`` in :pep:`692`,
 
 A TypedDict type represents ``dict`` objects that contain only keys of
 type ``str``. There are restrictions on which string keys are valid, and
-which values can be associated with each key. Values that are members of a
+which values can be associated with each key. Values that :term:`inhabit` a
 TypedDict type must be instances of ``dict`` itself, not a subclass.
 
 TypedDict types can define any number of :term:`items <item>`, which are string
@@ -371,10 +371,12 @@ Example::
    class X(TypedDict):
        x: str
        y: ReadOnly[int]
+       z: int
 
    class Y(X):
        x: int  # Type check error: cannot overwrite TypedDict field "x"
        y: bool  # OK: bool is assignable to int, and a mutable item can override a read-only one
+       z: bool  # Type check error: key is mutable, so subclass type must be consistent with superclass
 
 Openness
 ^^^^^^^^
