Run-time type checker for Python
Project description
This library provides run-time type checking for functions defined with argument type annotations.
The typing module introduced in Python 3.5 (and available on PyPI for older versions of Python 3) is supported. See below for details.
There are three principal ways to use type checking, each with its pros and cons:
calling check_argument_types() from within the function body:
debugger friendly (except when running with the pydev debugger with the C extension installed)
cannot check the type of the return value
does not work reliably with dynamically defined type hints (e.g. in nested functions)
decorating the function with @typechecked:
100% reliable at finding the function object to be checked (does not need to check the garbage collector)
can check the type of the return value
adds an extra frame to the call stack for every call to a decorated function
using with TypeChecker('packagename')::
emits warnings instead of raising TypeError
eliminates boilerplate
multiple TypeCheckers can be stacked/nested
noninvasive (only records type violations; does not raise exceptions)
does not work reliably with dynamically defined type hints (e.g. in nested functions)
may cause problems with badly behaving debuggers or profilers
If a function is called with incompatible argument types or a @typechecked decorated function returns a value incompatible with the declared type, a descriptive TypeError exception is raised.
Type checks can be fairly expensive so it is recommended to run Python in “optimized” mode (python -O or setting the PYTHONOPTIMIZE environment variable) when running code containing type checks in production. The optimized mode will disable the type checks, by virtue of removing all assert statements and setting the __debug__ constant to False.
Using check_argument_types():
from typeguard import check_argument_types
def some_function(a: int, b: float, c: str, *args: str):
assert check_argument_types()
...
Using @typechecked:
from typeguard import typechecked
@typechecked
def some_function(a: int, b: float, c: str, *args: str) -> bool:
...
To enable type checks even in optimized mode:
@typechecked(always=True)
def foo(a: str, b: int, c: Union[str, int]) -> bool:
...
Using TypeChecker:
from warnings import filterwarnings
from typeguard import TypeChecker, TypeWarning
# Display all TypeWarnings, not just the first one
filterwarnings('always', category=TypeWarning)
# Run your entire application inside this context block
with TypeChecker(['mypackage', 'otherpackage']):
mypackage.run_app()
# Alternatively, manually start (and stop) the checker:
checker = TypeChecker('mypackage')
checker.start()
mypackage.start_app()
To directly check a value against the specified type:
from typeguard import check_type
check_type('variablename', [1234], List[int])
The following types from the typing package have specialized support:
Type |
Notes |
---|---|
Callable |
Argument count is checked but types are not (yet) |
Dict |
Keys and values are typechecked |
List |
Contents are typechecked |
NamedTuple |
Field values are typechecked |
Set |
Contents are typechecked |
Tuple |
Contents are typechecked |
Type |
|
TypeVar |
Constraints, bound types and co/contravariance are supported but custom generic types are not (due to type erasure) |
Union |
Project links
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for typeguard-2.2.2-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 13ecd6ca9cd4a8b7965138c5782e3ab3711096f573c91b3ce120ac4764a6a233 |
|
MD5 | 1d53596c73d612ed88501774f62ddf76 |
|
BLAKE2b-256 | de608b67e520d3d45bb385322cd0603ad055cebcd4006dc46a74d4f32a3792a9 |