Glossary¶

This section defines a few terms that may be used elsewhere in the specification.

annotation expression¶

An expression that is valid to use within an annotation. This is usually atype expression, sometimes with additionaltype qualifiers.See“Type and annotation expression” for details.

assignable¶

If a typeB is “assignable to” a typeA, a type checker shouldnot error on the assignmentx:A=b, whereb is some expressionwhose type isB. Similarly for function calls and returns:f(b)wheredeff(x:A):... andreturnb insidedeff(...)->A:... are both valid (not type errors) if and only ifB is assignabletoA. In this caseA is “assignable from”B. Forfullystatic types, “assignable to” is equivalent to“subtype of” and “assignable from” is equivalent to“supertype of”. Forgradual types, a typeB is assignable to a typeA if there exist fully staticmaterializationsA' andB' ofA andB, respectively, such thatB' is a subtype ofA'. SeeType system concepts.

closed¶

ATypedDict type is closed if it may not contain anyadditionalitems beyond those specified in the TypedDict definition.A closed TypedDict can be created using theclosed=True argument totyping.TypedDict(), or equivalently by settingextra_items=Never.Compareextra items andopen.

consistent¶

Twofully static types are “consistent with”each other if they areequivalent. Two gradual types are“consistent with” each other if they couldmaterialize to thesame type. SeeType system concepts. If two types are consistent,they are bothassignable to and from each other.

consistent subtype¶

“Consistent subtype” is synonymous with “assignable to” (and“consistent supertype” is synonymous with “assignable from”). SeeType system concepts.

distribution¶

The packaged file which is used to publish and distributea release. (PEP 426)

equivalent¶

Twofully static typesA andB areequivalent ifA is asubtype ofB andB is asubtype ofA. This implies thatA andB represent thesame set of possible runtime objects. Two gradual typesA andBare equivalent if allmaterializations ofA arealso materializations ofB, and all materializations ofB arealso materializations ofA.

extra items¶

ATypedDict type with extra items may contain arbitraryadditional key-value pairs beyond those specified in the TypedDict definition, but thosevalues must be of the type specified by theextra_items= argument to the definition.A TypedDict with extra items can be created using theextra_items=argument totyping.TypedDict(). Extra items may or may not beread-only. Compareclosed andopen.

fully static type¶

A type is “fully static” if it does not contain anygradual form.A fully static type represents a set of possible runtime values. Fullystatic types participate in thesubtype relation. SeeType system concepts.

gradual form¶

A gradual form is an element of atype expression which makes the type it ispart of not afully static type, but rather a representation of aset of possible static types. SeeType system concepts. Theprimary gradual form isAny. The ellipsis (...) is a gradualform in some, but not all, contexts. It is a gradual form when used in aCallable type, and when used intuple[Any,...] (but not inothertuple types).

gradual type¶

All types in the Python type system are “gradual”. A gradual type may beafully static type, or it may beAny, or a type thatcontainsAny or anothergradual form. A gradual type does notnecessarily represent a single set of possible runtime values; instead itcan represent a set of possible static types (a set of possible sets ofpossible runtime values). Gradual types which are not fully static do notparticipate in thesubtype relation, but they do participate inconsistency andassignability.They can bematerialized to a more static, or fully static,type. SeeType system concepts.

inhabit¶

A value is said to inhabit a type if it is a member of the set of valuesrepresented by that type. For example, the value42 inhabits the typeint, and the value"hello" inhabits the typestr.

inline¶

Inline type annotations are annotations that are included in theruntime code usingPEP 526 andPEP 3107 syntax (the filename ends in.py).

item¶

In the context of aTypedDict, an item consists of a name(the dictionary key) and a type (representing the type that values corresponding to the key must have).Items may berequired ornon-required, and may beread-only or writable.

materialize¶

Agradual type can be materialized to a more static type(possibly afully static type) by replacingAny with anyother type, or by replacing the… in aCallable type with alist of types, or by replacingtuple[Any,...] with a specific-lengthtuple type. This materialization relation is key to definingassignability for gradual types. SeeType system concepts.

module¶

A file containing Python runtime code or stubbed type information.

narrow¶

Afully static typeB is narrower than a fully static typeA ifB is asubtype ofA andB is notequivalent toA. This means thatB represents a propersubset of the possible objects represented byA. “Type narrowing” iswhen a type checker infers that a name or expression must have a narrowertype at some locations in control flow, due to an assignment or a runtimecheck of its value.

nominal¶

A nominal type (e.g. a class name) represents the set of values whose__class__ is that type, or any of its subclasses, transitively. Incontrast, seestructural types.

non-required¶

If anitem in aTypedDict is non-required, it may ormay not be present on an object of that TypedDict type, but if it is presentit must be of the type specified by the TypedDict definition.Items can be marked as non-required using thetyping.NotRequired qualifieror thetotal=False argument totyping.TypedDict(). Comparerequired.

open¶

ATypedDict type is open if it may contain arbitraryadditionalitems beyond those specified in the TypedDict definition.This is the default behavior for TypedDicts that do not use theclosed=Trueorextra_items= arguments totyping.TypedDict().Open TypedDicts behave similarly to TypedDicts withextra items of typeReadOnly[object], but differ in some behaviors; see the TypedDict specificationchapter for details.Compareextra items andclosed.

package¶

A directory or directories that namespace Python modules.(Note the distinction between packages anddistributions.While most distributions are named after the one package they install, somedistributions install multiple packages.)

read-only¶

A read-onlyitem in aTypedDict may not be modified.Attempts to delete or assign to that itemshould be reported as type errors by a type checker. Read-only items are createdusing thetyping.ReadOnly qualifier.

required¶

If anitem in aTypedDict is required, it must be presentin any object of that TypedDict type. Items arerequired by default, but items can also be explicitly marked as required usingthetyping.Required qualifier. Comparenon-required.

special form¶

A special form is an object that has a special meaning within the type system,comparable to a keyword in the language grammar. Examples includeAny,Generic,Literal, andTypedDict. Special forms can often but not always be usedwithintype expressions. Special forms can usuallybe imported from thetyping module or equivalently fromtyping_extensions,but some special forms are placed in other modules.

structural¶

A structural type (see e.g.Protocols,Typed dictionaries) defines aset of values not by their__class__, but by their properties (e.g.attributes, methods, dictionary key/value types).Callable typesare also structural; a callable type is a subtype of another callabletype based on their signatures, not a subclass relationship. In contrast,seenominal types.

stub¶

A file containing only type information, empty of runtime code(the filename ends in.pyi). SeeStub files.

subtype¶

Afully static typeB is a subtype of a fully static typeA if and only if the set of possible runtime values represented byB is a subset of the set of possible runtime values represented byA. Fornominal types (classes), subtyping is defined byinheritance. Forstructural types, subtyping is defined by ashared set of attributes/methods or keys. Subtype is the inverse ofsupertype. A type that is not fully static is not a subtype orsupertype of any other type, but viamaterialization can beassignable to another type. SeeType system concepts.

supertype¶

Afully static typeA is a supertype of a fully static typeB if and only if the set of possible runtime values represented byA is a superset of the set of possible runtime values represented byB. Supertype is the inverse ofsubtype. SeeType system concepts.

type expression¶

An expression that represents a type. The type system requires the use of typeexpressions withinannotation expression and also in several other contexts.See“Type and annotation expression” for details.

type qualifier¶

A type qualifier is aspecial form that qualifies atype expression toform anannotation expression. For example, the type qualifierFinalcan be used around a type to indicate that the annotated value may not be overridden or modified.This term is also used for other special forms that modify a type, but using a differentsyntactic context, such as the@final decorator.

wide¶

Afully static typeA is wider than a fully static typeBif and only ifB is asubtype ofA andB is notequivalent toA. This means thatA represents a propersuperset of the possible values represented byB. See also“narrow”.