Operations on key specifications

Two type-level operations can be applied on key specifications:

• Removing keys from a key specification, using the - operator:

  assert_type(Literal['a', 'b'] - Literal['b'], Literal['a'])
  assert_type(Literal['a', 'b'] - Literal['c'], Literal['a', 'b'])
  
  class TD(TypedDict):
      a: str
      b: NotRequired[str]
  
  assert_type(KeyOf[TD] - Literal['b'], Literal['a'])
  

  A key specification that results in an empty set of keys is equivalent to Never:

  assert_type(Literal['a'] - Literal['a'], Never)
  

• Adding keys to a key specification, using the + operator:

  assert_type(Literal['a'] + Literal['b'], Literal['a', 'b'])
  

When applying such operations on bound KeyOf specifications, the evaluation of the type is deferred until it is parameterized:

def keys_minus_a[T: TypedDict](d: T) -> KeyOf[T] - Literal['a']:
    ...

class TD(TypedDict):
    a: str
    b: NotRequired[str]

d: TD = {'a': 'value'}

assert_type(keys_minus_a(d), Literal['b'])

Key specification views

A key specification view represents a single key in a key specification. It can appear only in a specific context: inline typed dictionaries with the comprehension syntax, described below.

Simple display syntax

This syntax follows the same semantics as the functional syntax (the keys are strings representing the field names, and values are valid annotation expressions), and allows defining typed dictionaries “statically”:

type Movie = <{'name': str, 'location': <{'city': str}>}>

Although it is not possible to specify class arguments such as total (the comprehension syntax aims to solve that), any type qualifier can be used for indiviual fields:

type Movie = <{'name': NotRequired[str], 'year': ReadOnly[int]}>

Comprehension syntax

The comprehension syntax allows creating typed dictionary types dynamically. It is inspired from the existing dictionary comprehension syntax, with some simplifications. The general syntax is as follows:

type ComprTD = <{K: _type_expr_ for K in _key_spec_}>

Conceptually, the comprehension syntax enables the possibility to express a new typed dictionary type by mapping each key from a key specification to a specific value type, while preserving (and potentially altering) the qualifiers of such key.

By iterating [1] over the key specification using the for clause, a key specification view is created (in the given example, K is a key specification view). It carries the following information about a key:

• The key name.
• The associated value type.
• The associated type qualifiers.

These three informations are mapped to the newly created typed dictionary type, possibly with some modifications:

• The key name cannot be changed (e.g. it isn’t possible to add a string suffix). In the general syntax example, K must be specified as is in the first expression on the left side of the colon.
• The associated value type can be changed. Any valid annotation expression can be used (e.g. int, Annotated[str, ...]). If the key specification iterated over is a KeyOf special form (and as such, brings a TypedDict class or a type variable T bound to TypedDict in scope), the original value type can be accessed using the ValueOf special form.

• The associated type qualifiers are carried over, and can be overridden for Required and NotRequired (ReadOnly is always carried over), by wrapping the associated value type inside the desired type qualifiers.

Here are some examples demonstrating these rules:

• Standalone type:

  Comprehension syntax	type Standalone = <{K: int for K in Literal['a', 'b']}>
  Class equivalent	class Standalone(TypedDict): a: int b: int

• Invalid modifications on keys:

  Comprehension syntax	type InvalidKeysAltering = <{K + '_suffix': int for K in Literal['a', 'b']}>
  Class equivalent	N/A
  Notes	Must raise a type checker error

• Changing the value type to str:

  Comprehension syntax	class TD(TypedDict): a: int type TDAsStr = <{K: str for K in KeyOf[TD]}>
  Class equivalent	class TDAsStr(TypedDict): a: str

• Changing the value type to str, making the key not required:

  Comprehension syntax	class TD(TypedDict): a: int type TDAsNotRequiredStr = <{K: NotRequired[str] for K in KeyOf[TD]}>
  Class equivalent	class TDAsNotRequiredStr(TypedDict): a: NotRequired[str]
  Notes	The NotRequired type qualifier overrides the original ones (in this case, we can assume Required is an implicit qualifier on a).

• Making all keys not required, keeping the value type:

  Comprehension syntax	class TD(TypedDict): a: int type TDAsNotRequired = <{K: NotRequired[ValueOf[TD, K]] for K in KeyOf[TD]}>
  Class equivalent	class TDAsNotRequired(TypedDict): a: NotRequired[int]
  Notes	The NotRequired type qualifier overrides the original ones (in this case, we can assume Required is an implicit qualifier on a).

• Making all keys read only, wrapping the value type inside list:

  Comprehension syntax	class TD(TypedDict): a: NotRequired[int] type TDAsReadOnlyList = <{K: ReadOnly[list[ValueOf[TD, K]]] for K in KeyOf[TD]}>
  Class equivalent	class TDAsReadOnlyList(TypedDict): a: ReadOnly[NotRequired[list[int]]]
  Notes	Notice that NotRequired is carried over, even if ValueOf[TD, K] is mapped in a “nested” way.

• Using a type alias to make every key not required:

  Comprehension syntax	type Partial[T: TypedDict] = <{K: NotRequired[ValueOf[TD, K]] for K in KeyOf[T]}>
  Class equivalent	Not expressible

• Using a type alias to select only certain keys:

  Comprehension syntax	type Omit[T: TypedDict, K: KeyOf[T]] = <{P: ValueOf[T, P] for P in KeyOf[T] - K}>
  Class equivalent	Not expressible

While similar to the existing dictionary comprehension syntax, this syntax is defined separately, and the following differences can be found:

• Only a single for clause can be used. It must iterate over a key specification, and the key specification view variable used for the iteration must be used as the key (the first expression on the left side of the colon).
• Unlike the dictionary comprehension syntax, it is not possible to use an if clause.