Module aws_lambda_powertools.shared.types
Expand source code
import sys
from typing import Any, Callable, Dict, List, TypeVar, Union
if sys.version_info >= (3, 8):
from typing import Literal, Protocol, TypedDict
else:
from typing_extensions import Literal, Protocol, TypedDict
if sys.version_info >= (3, 9):
from typing import Annotated
else:
from typing_extensions import Annotated
if sys.version_info >= (3, 11):
from typing import NotRequired
else:
from typing_extensions import NotRequired
# Even though `get_args` and `get_origin` were added in Python 3.8, they only handle Annotated correctly on 3.10.
# So for python < 3.10 we use the backport from typing_extensions.
if sys.version_info >= (3, 10):
from typing import TypeAlias, get_args, get_origin
else:
from typing_extensions import TypeAlias, get_args, get_origin
AnyCallableT = TypeVar("AnyCallableT", bound=Callable[..., Any]) # noqa: VNE001
# JSON primitives only, mypy doesn't support recursive tho
JSONType = Union[str, int, float, bool, None, Dict[str, Any], List[Any]]
__all__ = ["get_args", "get_origin", "Annotated", "Protocol", "TypedDict", "Literal", "NotRequired", "TypeAlias"]
Functions
-
A simple typed namespace. At runtime it is equivalent to a plain dict.
TypedDict creates a dictionary type such that a type checker will expect all instances to have a certain set of keys, where each key is associated with a value of a consistent type. This expectation is not checked at runtime.
Usage::
>>> class Point2D(TypedDict): ... x: int ... y: int ... label: str ... >>> a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK >>> b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check >>> Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') True
The type info can be accessed via the Point2D.annotations dict, and the Point2D.required_keys and Point2D.optional_keys frozensets. TypedDict supports an additional equivalent form::
Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str})
By default, all keys must be present in a TypedDict. It is possible to override this by specifying totality::
class Point2D(TypedDict, total=False): x: int y: int
This means that a Point2D TypedDict can have any of the keys omitted. A type checker is only expected to support a literal False or True as the value of the total argument. True is the default, and makes all items defined in the class body be required.
The Required and NotRequired special forms can also be used to mark individual keys as being required or not required::
class Point2D(TypedDict): x: int # the "x" key must always be present (Required is the default) y: NotRequired[int] # the "y" key can be omitted
See PEP 655 for more details on Required and NotRequired.
Expand source code
def TypedDict(typename, fields=None, /, *, total=True, **kwargs): """A simple typed namespace. At runtime it is equivalent to a plain dict. TypedDict creates a dictionary type such that a type checker will expect all instances to have a certain set of keys, where each key is associated with a value of a consistent type. This expectation is not checked at runtime. Usage:: >>> class Point2D(TypedDict): ... x: int ... y: int ... label: str ... >>> a: Point2D = {'x': 1, 'y': 2, 'label': 'good'} # OK >>> b: Point2D = {'z': 3, 'label': 'bad'} # Fails type check >>> Point2D(x=1, y=2, label='first') == dict(x=1, y=2, label='first') True The type info can be accessed via the Point2D.__annotations__ dict, and the Point2D.__required_keys__ and Point2D.__optional_keys__ frozensets. TypedDict supports an additional equivalent form:: Point2D = TypedDict('Point2D', {'x': int, 'y': int, 'label': str}) By default, all keys must be present in a TypedDict. It is possible to override this by specifying totality:: class Point2D(TypedDict, total=False): x: int y: int This means that a Point2D TypedDict can have any of the keys omitted. A type checker is only expected to support a literal False or True as the value of the total argument. True is the default, and makes all items defined in the class body be required. The Required and NotRequired special forms can also be used to mark individual keys as being required or not required:: class Point2D(TypedDict): x: int # the "x" key must always be present (Required is the default) y: NotRequired[int] # the "y" key can be omitted See PEP 655 for more details on Required and NotRequired. """ if fields is None: fields = kwargs elif kwargs: raise TypeError("TypedDict takes either a dict or keyword arguments," " but not both") if kwargs: warnings.warn( "The kwargs-based syntax for TypedDict definitions is deprecated " "in Python 3.11, will be removed in Python 3.13, and may not be " "understood by third-party type checkers.", DeprecationWarning, stacklevel=2, ) ns = {'__annotations__': dict(fields)} module = _caller() if module is not None: # Setting correct module is necessary to make typed dict classes pickleable. ns['__module__'] = module td = _TypedDictMeta(typename, (), ns, total=total) td.__orig_bases__ = (TypedDict,) return td
-
Get type arguments with all substitutions performed.
For unions, basic simplifications used by Union constructor are performed.
Examples::
>>> T = TypeVar('T') >>> assert get_args(Dict[str, int]) == (str, int) >>> assert get_args(int) == () >>> assert get_args(Union[int, Union[T, int], str][int]) == (int, str) >>> assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int]) >>> assert get_args(Callable[[], T][int]) == ([], int)
Expand source code
def get_args(tp): """Get type arguments with all substitutions performed. For unions, basic simplifications used by Union constructor are performed. Examples:: >>> T = TypeVar('T') >>> assert get_args(Dict[str, int]) == (str, int) >>> assert get_args(int) == () >>> assert get_args(Union[int, Union[T, int], str][int]) == (int, str) >>> assert get_args(Union[int, Tuple[T, int]][str]) == (int, Tuple[str, int]) >>> assert get_args(Callable[[], T][int]) == ([], int) """ if isinstance(tp, _AnnotatedAlias): return (tp.__origin__,) + tp.__metadata__ if isinstance(tp, (_GenericAlias, GenericAlias)): res = tp.__args__ if _should_unflatten_callable_args(tp, res): res = (list(res[:-1]), res[-1]) return res if isinstance(tp, types.UnionType): return tp.__args__ return ()
-
Get the unsubscripted version of a type.
This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar, Annotated, and others. Return None for unsupported types.
Examples::
>>> P = ParamSpec('P') >>> assert get_origin(Literal[42]) is Literal >>> assert get_origin(int) is None >>> assert get_origin(ClassVar[int]) is ClassVar >>> assert get_origin(Generic) is Generic >>> assert get_origin(Generic[T]) is Generic >>> assert get_origin(Union[T, int]) is Union >>> assert get_origin(List[Tuple[T, T]][int]) is list >>> assert get_origin(P.args) is P
Expand source code
def get_origin(tp): """Get the unsubscripted version of a type. This supports generic types, Callable, Tuple, Union, Literal, Final, ClassVar, Annotated, and others. Return None for unsupported types. Examples:: >>> P = ParamSpec('P') >>> assert get_origin(Literal[42]) is Literal >>> assert get_origin(int) is None >>> assert get_origin(ClassVar[int]) is ClassVar >>> assert get_origin(Generic) is Generic >>> assert get_origin(Generic[T]) is Generic >>> assert get_origin(Union[T, int]) is Union >>> assert get_origin(List[Tuple[T, T]][int]) is list >>> assert get_origin(P.args) is P """ if isinstance(tp, _AnnotatedAlias): return Annotated if isinstance(tp, (_BaseGenericAlias, GenericAlias, ParamSpecArgs, ParamSpecKwargs)): return tp.__origin__ if tp is Generic: return Generic if isinstance(tp, types.UnionType): return types.UnionType return None
Classes
-
Add context-specific metadata to a type.
Example: Annotated[int, runtime_check.Unsigned] indicates to the hypothetical runtime_check module that this type is an unsigned int. Every other consumer of this type can ignore this metadata and treat this type as int.
The first argument to Annotated must be a valid type.
Details:
- It's an error to call
Annotated
with less than two arguments. -
Access the metadata via the
__metadata__
attribute::assert Annotated[int, '$'].metadata == ('$',)
-
Nested Annotated types are flattened::
assert Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3]
-
Instantiating an annotated type is equivalent to instantiating the underlying type::
assert AnnotatedC, Ann1 == C(5)
-
Annotated can be used as a generic type alias::
type Optimized[T] = Annotated[T, runtime.Optimize()]
type checker will treat Optimized[int]
as equivalent to Annotated[int, runtime.Optimize()]
type OptimizedList[T] = Annotated[list[T], runtime.Optimize()]
type checker will treat OptimizedList[int]
as equivalent to Annotated[list[int], runtime.Optimize()]
-
Annotated cannot be used with an unpacked TypeVarTuple::
type Variadic[Ts] = Annotated[Ts, Ann1] # NOT valid
This would be equivalent to::
Annotated[T1, T2, T3, ..., Ann1]
where T1, T2 etc. are TypeVars, which would be invalid, because only one type should be passed to Annotated.
Expand source code
class Annotated: """Add context-specific metadata to a type. Example: Annotated[int, runtime_check.Unsigned] indicates to the hypothetical runtime_check module that this type is an unsigned int. Every other consumer of this type can ignore this metadata and treat this type as int. The first argument to Annotated must be a valid type. Details: - It's an error to call `Annotated` with less than two arguments. - Access the metadata via the ``__metadata__`` attribute:: assert Annotated[int, '$'].__metadata__ == ('$',) - Nested Annotated types are flattened:: assert Annotated[Annotated[T, Ann1, Ann2], Ann3] == Annotated[T, Ann1, Ann2, Ann3] - Instantiating an annotated type is equivalent to instantiating the underlying type:: assert Annotated[C, Ann1](5) == C(5) - Annotated can be used as a generic type alias:: type Optimized[T] = Annotated[T, runtime.Optimize()] # type checker will treat Optimized[int] # as equivalent to Annotated[int, runtime.Optimize()] type OptimizedList[T] = Annotated[list[T], runtime.Optimize()] # type checker will treat OptimizedList[int] # as equivalent to Annotated[list[int], runtime.Optimize()] - Annotated cannot be used with an unpacked TypeVarTuple:: type Variadic[*Ts] = Annotated[*Ts, Ann1] # NOT valid This would be equivalent to:: Annotated[T1, T2, T3, ..., Ann1] where T1, T2 etc. are TypeVars, which would be invalid, because only one type should be passed to Annotated. """ __slots__ = () def __new__(cls, *args, **kwargs): raise TypeError("Type Annotated cannot be instantiated.") def __class_getitem__(cls, params): if not isinstance(params, tuple): params = (params,) return cls._class_getitem_inner(cls, *params) @_tp_cache(typed=True) def _class_getitem_inner(cls, *params): if len(params) < 2: raise TypeError("Annotated[...] should be used " "with at least two arguments (a type and an " "annotation).") if _is_unpacked_typevartuple(params[0]): raise TypeError("Annotated[...] should not be used with an " "unpacked TypeVarTuple") msg = "Annotated[t, ...]: t must be a type." origin = _type_check(params[0], msg, allow_special_forms=True) metadata = tuple(params[1:]) return _AnnotatedAlias(origin, metadata) def __init_subclass__(cls, *args, **kwargs): raise TypeError( "Cannot subclass {}.Annotated".format(cls.__module__) )
- It's an error to call
-
Base class for protocol classes.
Protocol classes are defined as::
class Proto(Protocol): def meth(self) -> int: ...
Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing).
For example::
class C: def meth(self) -> int: return 0 def func(x: Proto) -> int: return x.meth() func(C()) # Passes static type check
See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as::
class GenProto[T](Protocol): def meth(self) -> T: ...
Expand source code
class Protocol(Generic, metaclass=_ProtocolMeta): """Base class for protocol classes. Protocol classes are defined as:: class Proto(Protocol): def meth(self) -> int: ... Such classes are primarily used with static type checkers that recognize structural subtyping (static duck-typing). For example:: class C: def meth(self) -> int: return 0 def func(x: Proto) -> int: return x.meth() func(C()) # Passes static type check See PEP 544 for details. Protocol classes decorated with @typing.runtime_checkable act as simple-minded runtime protocols that check only the presence of given attributes, ignoring their type signatures. Protocol classes can be generic, they are defined as:: class GenProto[T](Protocol): def meth(self) -> T: ... """ __slots__ = () _is_protocol = True _is_runtime_protocol = False def __init_subclass__(cls, *args, **kwargs): super().__init_subclass__(*args, **kwargs) # Determine if this is a protocol or a concrete subclass. if not cls.__dict__.get('_is_protocol', False): cls._is_protocol = any(b is Protocol for b in cls.__bases__) # Set (or override) the protocol subclass hook. if '__subclasshook__' not in cls.__dict__: cls.__subclasshook__ = _proto_hook # Prohibit instantiation for protocol classes if cls._is_protocol and cls.__init__ is Protocol.__init__: cls.__init__ = _no_init_or_replace_init
Ancestors
- typing.Generic
Subclasses
- NextMiddleware
- RedisClientProtocol
- importlib.metadata._meta.PackageMetadata
- importlib.metadata._meta.SimplePath
- importlib.resources.abc.Traversable
- redis.asyncio.client.AsyncPubsubWorkerExceptionHandler
- redis.asyncio.client.AsyncResponseCallbackProtocol
- redis.asyncio.client.PubsubWorkerExceptionHandler
- redis.asyncio.client.ResponseCallbackProtocol
- redis.asyncio.connection.AsyncConnectCallbackProtocol
- redis.asyncio.connection.ConnectCallbackProtocol
- redis.typing.ClusterCommandsProtocol
- redis.typing.CommandsProtocol
- typing.SupportsAbs
- typing.SupportsBytes
- typing.SupportsComplex
- typing.SupportsFloat
- typing.SupportsIndex
- typing.SupportsInt
- typing.SupportsRound
- typing._IdentityCallable