Skip to content

Commit 9264235

Browse files
committed
more clarity
1 parent 77ae2d1 commit 9264235

File tree

1 file changed

+11
-5
lines changed

1 file changed

+11
-5
lines changed

docs/spec/typeddict.rst

Lines changed: 11 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -112,7 +112,8 @@ in the class definition:
112112
* ``closed``: a boolean literal (``True`` or ``False``) indicating whether
113113
the TypedDict is :term:`closed` (``True``) or :term:`open` (``False``).
114114
The latter is the default, except when inheriting from another TypedDict that
115-
is not open (see :ref:`typeddict-inheritance`).
115+
is not open (see :ref:`typeddict-inheritance`), or when the ``extra_items``
116+
argument is also used.
116117
As with ``total``, the value must be exactly ``True`` or ``False``. It is an error
117118
to use this argument together with ``extra_items=``.
118119
* ``extra_items``: indicates that the TypedDict has :term:`extra items`. The argument
@@ -492,7 +493,7 @@ Multiple inheritance does not allow conflicting types for the same item::
492493
Subtyping and assignability
493494
---------------------------
494495

495-
Because TypedDict types are :term:`structural` types, a TypedDict ``T1`` is assignable to another
496+
Because TypedDict types are :term:`structural` types, a TypedDict ``T1`` is :term:`assignable` to another
496497
TypedDict type ``T2`` if the two are structurally compatible, meaning that all operations that
497498
are allowed on ``T2`` are also allowed on ``T1``. For similar reasons, TypedDict types are
498499
generally not assignable to any specialization of ``dict`` or ``Mapping``, other than ``Mapping[str, object]``,
@@ -501,7 +502,10 @@ to these types.
501502

502503
The rest of this section discusses the :term:`subtyping <subtype>` rules for TypedDict in more detail.
503504
As with any type, the rules for :term:`assignability <assignable>` can be derived from the subtyping
504-
rules using the :term:`materialization <materialize>` procedure.
505+
rules using the :term:`materialization <materialize>` procedure. Generally, this means that where
506+
":term:`equivalent`" is mentioned below, the :term:`consistency <consistent>` relation can be used instead
507+
when implementing assignability, and where ":term:`subtyping <subtype>`" between elements of a
508+
TypedDict is mentioned, assignability can be used instead when implementing assignability between TypedDicts.
505509

506510
Subtyping between TypedDict types
507511
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -518,6 +522,8 @@ The conditions are as follows:
518522

519523
- It must also be required in ``B``.
520524
- If it is read-only in ``A``, the item type in ``B`` must be a subtype of the item type in ``A``.
525+
(For :term:`assignability <assignable>` between two TypedDicts, the first item must instead
526+
be assignable to the second.)
521527

522528
- If it is mutable in ``A``, it must also be mutable in ``B``, and the item type in ``B`` must be
523529
:term:`equivalent` to the item type in ``A``. (It follows that for assignability, the two item types
@@ -536,14 +542,14 @@ The conditions are as follows:
536542
- If it is mutable in ``A``:
537543

538544
- If ``B`` has an item with the same key, it must also be mutable, and its item type must be
539-
:term:`equivalent` to the item type in ``A``. (As before, it follows that for assignability, the two item types
540-
must be :term:`consistent`.)
545+
:term:`equivalent` to the item type in ``A``.
541546

542547
- Else:
543548

544549
- If ``B`` is closed, the check fails.
545550
- If ``B`` has extra items, the extra items type must not be read-only and must
546551
be :term:`equivalent` to the item type in ``A``.
552+
547553
- If ``A`` is closed, ``B`` must also be closed, and it must not contain any items that are not present in ``A``.
548554
- If ``A`` has read-only extra items, ``B`` must either be closed or also have extra items, and the extra items type in ``B``
549555
must be a subtype of the extra items type in ``A``. Additionally, for any items in ``B`` that are not present in ``A``,

0 commit comments

Comments
 (0)