Class-based Syntax

A TypedDict type can be defined using the class definition syntax withtyping.TypedDict as the sole base class:

fromtypingimportTypedDictclassMovie(TypedDict):name:stryear:int

Movie is a TypedDict type with two items:'name' (with typestr) and'year' (with typeint).

A type checker should validate that the body of a class-basedTypedDict definition conforms to the following rules:

• The class body should only contain lines with item definitions of theformkey:value_type, optionally preceded by a docstring. Thesyntax for item definitions is identical to attribute annotations,but there must be no initializer, and the key name actually refersto the string value of the key instead of an attribute name.
• Type comments cannot be used with the class-based syntax, forconsistency with the class-basedNamedTuple syntax. (Note thatit would not be sufficient to support type comments for backwardscompatibility with Python 2.7, since the class definition may have atotal keyword argument, as discussed below, and this isn’t validsyntax in Python 2.7.) Instead, this PEP provides an alternative,assignment-based syntax for backwards compatibility, discussed inAlternative Syntax.
• String literal forward references are valid in the value types.
• Methods are not allowed, since the runtime type of a TypedDictobject will always be justdict (it is never a subclass ofdict).
• Specifying a metaclass is not allowed.

An empty TypedDict can be created by only includingpass in thebody (if there is a docstring,pass can be omitted):

classEmptyDict(TypedDict):pass

Using TypedDict Types

Here is an example of how the typeMovie can be used:

movie:Movie={'name':'Blade Runner','year':1982}

An explicitMovie type annotation is generally needed, asotherwise an ordinary dictionary type could be assumed by a typechecker, for backwards compatibility. When a type checker can inferthat a constructed dictionary object should be a TypedDict, anexplicit annotation can be omitted. A typical example is a dictionaryobject as a function argument. In this example, a type checker isexpected to infer that the dictionary argument should be understood asa TypedDict:

defrecord_movie(movie:Movie)->None:...record_movie({'name':'Blade Runner','year':1982})

Another example where a type checker should treat a dictionary displayas a TypedDict is in an assignment to a variable with a previouslydeclared TypedDict type:

movie:Movie...movie={'name':'Blade Runner','year':1982}

Operations onmovie can be checked by a static type checker:

movie['director']='Ridley Scott'# Error: invalid key 'director'movie['year']='1982'# Error: invalid value type ("int" expected)

The code below should be rejected, since'title' is not a validkey, and the'name' key is missing:

movie2:Movie={'title':'Blade Runner','year':1982}

The created TypedDict type object is not a real class object. Hereare the only uses of the type a type checker is expected to allow:

• It can be used in type annotations and in any context where anarbitrary type hint is valid, such as in type aliases and as thetarget type of a cast.
• It can be used as a callable object with keyword argumentscorresponding to the TypedDict items. Non-keyword arguments are notallowed. Example:

  m=Movie(name='Blade Runner',year=1982)

  When called, the TypedDict type object returns an ordinarydictionary object at runtime:

  print(type(m))# <class 'dict'>

• It can be used as a base class, but only when defining a derivedTypedDict. This is discussed in more detail below.

In particular, TypedDict type objects cannot be used inisinstance() tests such asisinstance(d,Movie). The reason isthat there is no existing support for checking types of dictionaryitem values, sinceisinstance() does not work with manyPEP 484types, including common ones likeList[str]. This would be neededfor cases like this:

classStrings(TypedDict):items:List[str]print(isinstance({'items':[1]},Strings))# Should be Falseprint(isinstance({'items':['x']},Strings))# Should be True

The above use case is not supported. This is consistent with howisinstance() is not supported forList[str].

Inheritance

It is possible for a TypedDict type to inherit from one or moreTypedDict types using the class-based syntax. In this case theTypedDict base class should not be included. Example:

classBookBasedMovie(Movie):based_on:str

NowBookBasedMovie has keysname,year, andbased_on.It is equivalent to this definition, since TypedDict types usestructural compatibility:

classBookBasedMovie(TypedDict):name:stryear:intbased_on:str

Here is an example of multiple inheritance:

classX(TypedDict):x:intclassY(TypedDict):y:strclassXYZ(X,Y):z:bool

The TypedDictXYZ has three items:x (typeint),y(typestr), andz (typebool).

A TypedDict cannot inherit from both a TypedDict type and anon-TypedDict base class.

Additional notes on TypedDict class inheritance:

• Changing a field type of a parent TypedDict class in a subclass is not allowed.Example:

  classX(TypedDict):x:strclassY(X):x:int# Type check error: cannot overwrite TypedDict field "x"

  In the example outlined above TypedDict class annotations returnstypestr for keyx:

  print(Y.__annotations__)# {'x': <class 'str'>}

• Multiple inheritance does not allow conflict types for the same name field:

  classX(TypedDict):x:intclassY(TypedDict):x:strclassXYZ(X,Y):# Type check error: cannot overwrite TypedDict field "x" while mergingxyz:bool

Totality

By default, all keys must be present in a TypedDict. It is possibleto override this by specifyingtotality. Here is how to do thisusing the class-based syntax:

classMovie(TypedDict,total=False):name:stryear:int

This means that aMovie TypedDict can have any of the keys omitted. Thusthese are valid:

m:Movie={}m2:Movie={'year':2015}

A type checker is only expected to support a literalFalse orTrue as the value of thetotal argument.True is thedefault, and makes all items defined in the class body be required.

The totality flag only applies to items defined in the body of theTypedDict definition. Inherited items won’t be affected, and insteaduse totality of the TypedDict type where they were defined. This makesit possible to have a combination of required and non-required keys ina single TypedDict type.

Alternative Syntax

This PEP also proposes an alternative syntax that can be backported toolder Python versions such as 3.5 and 2.7 that don’t support thevariable definition syntax introduced inPEP 526. Itresembles the traditional syntax for defining named tuples:

Movie=TypedDict('Movie',{'name':str,'year':int})

It is also possible to specify totality using the alternative syntax:

Movie=TypedDict('Movie',{'name':str,'year':int},total=False)

The semantics are equivalent to the class-based syntax. This syntaxdoesn’t support inheritance, however, and there is no way tohave both required and non-required fields in a single type. Themotivation for this is keeping the backwards compatible syntax assimple as possible while covering the most common use cases.

A type checker is only expected to accept a dictionary display expressionas the second argument toTypedDict. In particular, a variable thatrefers to a dictionary object does not need to be supported, to simplifyimplementation.

Type Consistency

Informally speaking,type consistency is a generalization of theis-subtype-of relation to support theAny type. It is definedmore formally inPEP 483. This section introduces thenew, non-trivial rules needed to support type consistency forTypedDict types.

First, any TypedDict type is consistent withMapping[str,object].Second, a TypedDict typeA is consistent with TypedDictB ifA is structurally compatible withB. This is true if and onlyif both of these conditions are satisfied:

• For each key inB,A has the corresponding key and thecorresponding value type inA is consistent with the value typeinB. For each key inB, the value type inB is alsoconsistent with the corresponding value type inA.
• For each required key inB, the corresponding key is requiredinA. For each non-required key inB, the corresponding keyis not required inA.

Discussion:

• Value types behave invariantly, since TypedDict objects are mutable.This is similar to mutable container types such asList andDict. Example where this is relevant:

  classA(TypedDict):x:Optional[int]classB(TypedDict):x:intdeff(a:A)->None:a['x']=Noneb:B={'x':0}f(b)# Type check error: 'B' not compatible with 'A'b['x']+1# Runtime error: None + 1

• A TypedDict type with a required key is not consistent with aTypedDict type where the same key is a non-required key, since thelatter allows keys to be deleted. Example where this is relevant:

  classA(TypedDict,total=False):x:intclassB(TypedDict):x:intdeff(a:A)->None:dela['x']b:B={'x':0}f(b)# Type check error: 'B' not compatible with 'A'b['x']+1# Runtime KeyError: 'x'

• A TypedDict typeA with no key'x' is not consistent with aTypedDict type with a non-required key'x', since at runtimethe key'x' could be present and have an incompatible type(which may not be visible throughA due to structural subtyping).Example:

  classA(TypedDict,total=False):x:inty:intclassB(TypedDict,total=False):x:intclassC(TypedDict,total=False):x:inty:strdeff(a:A)->None:a['y']=1defg(b:B)->None:f(b)# Type check error: 'B' incompatible with 'A'c:C={'x':0,'y':'foo'}g(c)c['y']+'bar'# Runtime error: int + str

• A TypedDict isn’t consistent with anyDict[...] type, sincedictionary types allow destructive operations, includingclear(). They also allow arbitrary keys to be set, whichwould compromise type safety. Example:

  classA(TypedDict):x:intclassB(A):y:strdeff(d:Dict[str,int])->None:d['y']=0defg(a:A)->None:f(a)# Type check error: 'A' incompatible with Dict[str, int]b:B={'x':0,'y':'foo'}g(b)b['y']+'bar'# Runtime error: int + str

• A TypedDict with allint values is not consistent withMapping[str,int], since there may be additional non-intvalues not visible through the type, due to structural subtyping.These can be accessed using thevalues() anditems()methods inMapping, for example. Example:

  classA(TypedDict):x:intclassB(TypedDict):x:inty:strdefsum_values(m:Mapping[str,int])->int:n=0forvinm.values():n+=v# Runtime errorreturnndeff(a:A)->None:sum_values(a)# Error: 'A' incompatible with Mapping[str, int]b:B={'x':0,'y':'foo'}f(b)

Supported and Unsupported Operations

Type checkers should support restricted forms of mostdictoperations on TypedDict objects. The guiding principle is thatoperations not involvingAny types should be rejected by typecheckers if they may violate runtime type safety. Here are some ofthe most important type safety violations to prevent:

1. A required key is missing.
2. A value has an invalid type.
3. A key that is not defined in the TypedDict type is added.

A key that is not a literal should generally be rejected, since itsvalue is unknown during type checking, and thus can cause some of theabove violations. (Use of Final Values and Literal Typesgeneralizes this to cover final names and literal types.)

The use of a key that is not known to exist should be reported as anerror, even if this wouldn’t necessarily generate a runtime typeerror. These are often mistakes, and these may insert values with aninvalid type if structural subtyping hides the types of certain items.For example,d['x']=1 should generate a type check error if'x' is not a valid key ford (which is assumed to be aTypedDict type).

Extra keys included in TypedDict object construction should also becaught. In this example, thedirector key is not defined inMovie and is expected to generate an error from a type checker:

m:Movie=dict(name='Alien',year=1979,director='Ridley Scott')# error: Unexpected key 'director'

Type checkers should reject the following operations on TypedDictobjects as unsafe, even though they are valid for normal dictionaries:

• Operations with arbitrarystr keys (instead of string literalsor other expressions with known string values) should generally berejected. This involves both destructive operations such as settingan item and read-only operations such as subscription expressions.As an exception to the above rule,d.get(e) andeindshould be allowed for TypedDict objects, for an arbitrary expressione with typestr. The motivation is that these are safe andcan be useful for introspecting TypedDict objects. The static typeofd.get(e) should beobject if the string value ofecannot be determined statically.
• clear() is not safe since it could remove required keys, some ofwhich may not be directly visible because of structuralsubtyping.popitem() is similarly unsafe, even if all knownkeys are not required (total=False).
• delobj['key'] should be rejected unless'key' is anon-required key.

Type checkers may allow reading an item usingd['x'] even ifthe key'x' is not required, instead of requiring the use ofd.get('x') or an explicit'x'ind check. The rationale isthat tracking the existence of keys is difficult to implement in fullgenerality, and that disallowing this could require many changes toexisting code.

The exact type checking rules are up to each type checker to decide.In some cases potentially unsafe operations may be accepted if thealternative is to generate false positive errors for idiomatic code.

Use of Final Values and Literal Types

Type checkers should allow final names (PEP 591) withstring values to be used instead of string literals in operations onTypedDict objects. For example, this is valid:

YEAR:Final='year'm:Movie={'name':'Alien','year':1979}years_since_epoch=m[YEAR]-1970

Similarly, an expression with a suitable literal type(PEP 586) can be used instead of a literal value:

defget_value(movie:Movie,key:Literal['year','name'])->Union[int,str]:returnmovie[key]

Type checkers are only expected to support actual string literals, notfinal names or literal types, for specifying keys in a TypedDict typedefinition. Also, only a boolean literal can be used to specifytotality in a TypedDict definition. The motivation for this is tomake type declarations self-contained, and to simplify theimplementation of type checkers.