Text of docs.python.org › id › 3 › library › typing.html as Styx crawled it on Nov 19, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

typing --- Support for type hints — Dokumentasi Python 3.15.2

Navigasi index modul | berikut | sebelum | Python » 3.15.2 documentation » The Python standard library » Alat Pengembangan » typing --- Support for type hints | Tema | typing --- Support for type hints ¶ Added in version 3.5. Source code: Lib/typing.py Catatan The Python runtime does not enforce function and variable type annotations. They can be used by third party tools such as type checkers , IDEs, linters, etc.

This module provides runtime support for type hints. Consider the function below: def surface_area_of_cube ( edge_length : float ) -> str : return f "The surface area of the cube is { 6 * edge_length ** 2 } ." The function surface_area_of_cube takes an argument expected to be an instance of float , as indicated by the type hint edge_length: float . The function is expected to return an instance of str , as indicated by the -> str hint.

While type hints can be simple classes like float or str , they can also be more complex. The typing module provides a vocabulary of more advanced type hints. New features are frequently added to the typing module. The typing_extensions package provides backports of these new features to older versions of Python. Lihat juga Typing cheat sheet A quick overview of type hints (hosted at the mypy docs) Type System Reference section of the mypy docs The Python typing system is standardised via PEPs, so this reference should broadly apply to most Python type checkers. (Some parts may still be specific to mypy.) Static Typing with Python Type-checker-agnostic documentation written by the community detailing type system features, useful typing related tools and typing best practices.

Specification for the Python Type System ¶ The canonical, up-to-date specification of the Python type system can be found at Specification for the Python type system . Type aliases ¶ A type alias is defined using the type statement, which creates an instance of TypeAliasType . In this example, Vector and list[float] will be treated equivalently by static type checkers: type Vector = list [ float ] def scale ( scalar : float , vector : Vector ) -> Vector : return [ scalar * num for num in vector ] # passes type checking; a list of floats qualifies as a Vector. new_vector = scale ( 2.0 , [ 1.0 , - 4.2 , 5.4 ]) Type aliases are useful for simplifying complex type signatures.

For example: from collections.abc import Sequence type ConnectionOptions = dict [ str , str ] type Address = tuple [ str , int ] type Server = tuple [ Address , ConnectionOptions ] def broadcast_message ( message : str , servers : Sequence [ Server ]) -> None : ... # The static type checker will treat the previous type signature as # being exactly equivalent to this one. def broadcast_message ( message : str , servers : Sequence [ tuple [ tuple [ str , int ], dict [ str , str ]]] ) -> None : ...

The type statement is new in Python 3.12. For backwards compatibility, type aliases can also be created through simple assignment: Vector = list [ float ] Or marked with TypeAlias to make it explicit that this is a type alias, not a normal variable assignment: from typing import TypeAlias Vector : TypeAlias = list [ float ] NewType ¶ Use the NewType helper to create distinct types: from typing import NewType UserId = NewType ( 'UserId' , int ) some_id = UserId ( 524313 ) The static type checker will treat the new type as if it were a subclass of the original type.

This is useful in helping catch logical errors: def get_user_name ( user_id : UserId ) -> str : ... # passes type checking user_a = get_user_name ( UserId ( 42351 )) # fails type checking; an int is not a UserId user_b = get_user_name ( - 1 ) 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 a UserId wherever an int might be expected, but will prevent you from accidentally creating a UserId in an invalid way: # 'output' is of type 'int', not 'UserId' output = UserId ( 23413 ) + UserId ( 54341 ) Note that these checks are enforced only by the static type checker.

At runtime, the statement Derived = NewType('Derived', Base) will make Derived a callable that immediately returns whatever parameter you pass it. That means the expression Derived(some_value) does not create a new class or introduce much overhead beyond that of a regular function call. More precisely, the expression some_value is Derived(some_value) is always true at runtime. It is invalid to create a subtype of Derived : from typing import NewType UserId = NewType ( 'UserId' , int ) # Fails at runtime and does not pass type checking class AdminUserId ( UserId ): pass However, it is possible to create a NewType based on a 'derived' NewType : from typing import NewType UserId = NewType ( 'UserId' , int ) ProUserId = NewType ( 'ProUserId' , UserId ) and typechecking for ProUserId will work as expected.

See PEP 484 for more details. Catatan Recall that the use of a type alias declares two types to be equivalent to one another. Doing type Alias = Original will make the static type checker treat 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 type checker treat Derived as a subclass of Original , which means a value of type Original cannot be used in places where a value of type Derived is expected.

This is useful when you want to prevent logic errors with minimal runtime cost. Added in version 3.5.2. Berubah pada versi 3.10: NewType is now a class rather than a function. As a result, there is some additional runtime cost when calling NewType over a regular function. Berubah pada versi 3.11: The performance of calling NewType has been restored to its level in Python 3.9. Annotating callable objects ¶ Functions -- or other callable objects -- can be annotated using collections.abc.Callable or deprecated typing.Callable .

Callable[[int], str] signifies a function that takes a single parameter of type int and returns a str . Sebagai contoh: from collections.abc import Callable , Awaitable def feeder ( get_next_item : Callable [[], str ]) -> None : ... # Body def async_query ( on_success : Callable [[ int ], None ], on_error : Callable [[ int , Exception ], None ]) -> None : ... # Body async def on_update ( value : str ) -> None : ... # Body callback : Callable [[ str ], Awaitable [ None ]] = on_update The subscription syntax must always be used with exactly two values: the argument list and the return type.

The argument list must be a list of types, a ParamSpec , Concatenate , or an ellipsis ( ... ). The return type must be a single type. If a literal ellipsis ... is given as the argument list, it indicates that a callable with any arbitrary parameter list would be acceptable: def concat ( x : str , y : str ) -> str : return x + y x : Callable [ ... , str ] x = str # OK x = concat # Also OK Callable cannot express complex signatures such as functions that take a variadic number of arguments, overloaded functions , or functions that have keyword-only parameters.

However, these signatures can be expressed by defining a Protocol class with a __call__() method: from collections.abc import Iterable from typing import Protocol class Combiner ( Protocol ): def __call__ ( self , * vals : bytes , maxlen : int | None = None ) -> list [ bytes ]: ... def batch_proc ( data : Iterable [ bytes ], cb_results : Combiner ) -> bytes : for item in data : ... def good_cb ( * vals : bytes , maxlen : int | None = None ) -> list [ bytes ]: ... def bad_cb ( * vals : bytes , maxitems : int | None ) -> list [ bytes ]: ... batch_proc ([], good_cb ) # OK batch_proc ([], bad_cb ) # Error!

Argument 2 has incompatible type because of # different name and kind in the callback Callables which take other callables as arguments may indicate that their parameter types are dependent on each other usi

The rest of this page is on the live site.