Type Fu 4.7.0
Malena Bower
The function moon_weight takes an argument expected to be an instance of float,as indicated by the type hint earth_weight: float. The function is expected toreturn an instance of str, as indicated by the -> str hint.
You may still perform all int operations on a variable of type UserId,but the result will always be of type int. This lets you pass in aUserId wherever an int might be expected, but will prevent you fromaccidentally creating a UserId in an invalid way:
Note that these checks are enforced only by the static type checker. At runtime,the statement Derived = NewType('Derived', Base) will make Derived acallable that immediately returns whatever parameter you pass it. That meansthe expression Derived(some_value) does not create a new class or introducemuch overhead beyond that of a regular function call.
Recall that the use of a type alias declares two types to be equivalent toone another. Doing type Alias = Original will make the static type checkertreat Alias as being exactly equivalent to Original in all cases.This is useful when you want to simplify complex type signatures.
In contrast, NewType declares one type to be a subtype of another.Doing Derived = NewType('Derived', Original) will make the static typechecker treat Derived as a subclass of Original, which means avalue of type Original cannot be used in places where a value of typeDerived is expected. This is useful when you want to prevent logicerrors with minimal runtime cost.
The subscription syntax must always be used with exactly two values: theargument list and the return type. The argument list must be a list of types,a ParamSpec, Concatenate, or an ellipsis. The return type mustbe a single type.
Callable cannot express complex signatures such as functions that take avariadic number of arguments, overloaded functions, orfunctions that have keyword-only parameters. However, these signatures can beexpressed by defining a Protocol class with a__call__() method:
Callables which take other callables as arguments may indicate that theirparameter types are dependent on each other using ParamSpec.Additionally, if that callable adds or removes arguments from othercallables, the Concatenate operator may be used. Theytake the form Callable[ParamSpecVariable, ReturnType] andCallable[Concatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable], ReturnType]respectively.
Since type information about objects kept in containers cannot be staticallyinferred in a generic way, many container classes in the standard library supportsubscription to denote the expected types of container elements.
list only accepts one type argument, so a type checker would emit anerror on the y assignment above. Similarly,Mapping only accepts two type arguments: the firstindicates the type of the keys, and the second indicates the type of thevalues.
To denote a tuple which could be of any length, and in which all elements areof the same type T, use tuple[T, ...]. To denote an empty tuple, usetuple[()]. Using plain tuple as an annotation is equivalent to usingtuple[Any, ...]:
Changed in version 3.12: Syntactic support for generics and type aliases is new in version 3.12.Previously, generic classes had to explicitly inherit from Genericor contain a type variable in one of their bases.
Another difference between TypeVar and ParamSpec is that ageneric with only one parameter specification variable will acceptparameter lists in the forms X[[Type1, Type2, ...]] and alsoX[Type1, Type2, ...] for aesthetic reasons. Internally, the latter is convertedto the former, so the following are equivalent:
A user-defined generic class can have ABCs as base classes without a metaclassconflict. Generic metaclasses are not supported. The outcome of parameterizinggenerics is cached, and most types in the typing module are hashable andcomparable for equality.
Notice that no type checking is performed when assigning a value of typeAny to a more precise type. For example, the static type checker didnot report an error when assigning a to s even though s wasdeclared to be of type str and receives an int value atruntime!
That means when the type of a value is object, a type checker willreject almost all operations on it, and assigning it to a variable (or usingit as a return value) of a more specialized type is a type error. For example:
Initially PEP 484 defined the Python static type system as usingnominal subtyping. This means that a class A is allowed wherea class B is expected if and only if A is a subclass of B.
This requirement previously also applied to abstract base classes, such asIterable. The problem with this approach is that a class hadto be explicitly marked to support them, which is unpythonic and unlikewhat one would normally do in idiomatic dynamically typed Python code.For example, this conforms to PEP 484:
PEP 544 allows to solve this problem by allowing users to writethe above code without explicit base classes in the class definition,allowing Bucket to be implicitly considered a subtype of both Sizedand Iterable[int] by static type checkers. This is known asstructural subtyping (or static duck-typing):
Any stringliteral is compatible with LiteralString, as is anotherLiteralString. However, an object typed as just str is not.A string created by composing LiteralString-typed objectsis also acceptable as a LiteralString.
LiteralString is useful for sensitive APIs where arbitrary user-generatedstrings could generate problems. For example, the two cases abovethat generate type checker errors could be vulnerable to an SQLinjection attack.
In general, if something returns self, as in the above examples, youshould use Self as the return annotation. If Foo.return_self wasannotated as returning "Foo", then the type checker would infer theobject returned from SubclassOfFoo.return_self as being of type Foorather than SubclassOfFoo.
TypeAlias is particularly useful on older Python versions for annotatingaliases that make use of forward references, as it can be hard for typecheckers to distinguish these from normal variable assignments:
Deprecated since version 3.12: TypeAlias is deprecated in favor of the type statement,which creates instances of TypeAliasTypeand which natively supports forward references.Note that while TypeAlias and TypeAliasType servesimilar purposes and have similar names, they are distinct and thelatter is not the type of the former.Removal of TypeAlias is not currently planned, but usersare encouraged to migrate to type statements.
Note that this is not the same concept as an optional argument,which is one that has a default. An optional argument with adefault does not require the Optional qualifier on its typeannotation just because it is optional. For example:
Concatenate can be used in conjunction with Callable andParamSpec to annotate a higher-order callable which adds, removes,or transforms parameters of anothercallable. Usage is in the formConcatenate[Arg1Type, Arg2Type, ..., ParamSpecVariable]. Concatenateis currently only valid when used as the first argument to a Callable.The last parameter to Concatenate must be a ParamSpec orellipsis (...).
Literal[...] cannot be subclassed. At runtime, an arbitrary valueis allowed as type argument to Literal[...], but type checkers mayimpose restrictions. See PEP 586 for more details about literal types.
Changed in version 3.9.1: Literal now de-duplicates parameters. Equality comparisons ofLiteral objects are no longer order dependent. Literal objectswill now raise a TypeError exception during equality comparisonsif one of their parameters are not hashable.
As introduced in PEP 526, a variable annotation wrapped in ClassVarindicates that a given attribute is intended to be used as a class variableand should not be set on instances of that class. Usage:
ClassVar is not a class itself, and should notbe used with isinstance() or issubclass().ClassVar does not change Python runtime behavior, butit can be used by third-party type checkers. For example, a type checkermight flag the following code as an error:
Add metadata x to a given type T by using the annotationAnnotated[T, x]. Metadata added using Annotated can be used bystatic analysis tools or at runtime. At runtime, the metadata is storedin a __metadata__ attribute.
Using Annotated[T, x] as an annotation still allows for statictypechecking of T, as type checkers will simply ignore the metadata x.In this way, Annotated differs from the@no_type_check decorator, which can also be used foradding annotations outside the scope of the typing system, butcompletely disables typechecking for a function or class.
The responsibility of how to interpret the metadatalies with the tool or library encountering anAnnotated annotation. A tool or library encountering an Annotated typecan scan through the metadata elements to determine if they are of interest(e.g., using isinstance()).
These objects can be created through special syntax(type parameter lists and the type statement).For compatibility with Python 3.11 and earlier, they can also be createdwithout the dedicated syntax, as documented below.
Type variables exist primarily for the benefit of static typecheckers. They serve as the parameters for generic types as wellas for generic function and type alias definitions.See Generic for moreinformation on generic types. Generic functions work as follows:
The variance of type variables is inferred by type checkers when they are createdthrough the type parameter syntax or wheninfer_variance=True is passed.Manually created type variables may be explicitly marked covariant or contravariant by passingcovariant=True or contravariant=True.By default, manually created type variables are invariant.See PEP 484 and PEP 695 for more details.
Bound type variables and constrained type variables have differentsemantics in several important ways. Using a bound type variable meansthat the TypeVar will be solved using the most specific type possible:
7fc3f7cf58