dev4py.utils.types

 1"""
 2The `types` module provides a set commonly used types useful for static type checking
 3"""
 4# Copyright 2022 the original author or authors (i.e.: St4rG00se for Dev4py).
 5#
 6# Licensed under the Apache License, Version 2.0 (the "License");
 7# you may not use this file except in compliance with the License.
 8# You may obtain a copy of the License at
 9#
10#      https://www.apache.org/licenses/LICENSE-2.0
11#
12# Unless required by applicable law or agreed to in writing, software
13# distributed under the License is distributed on an "AS IS" BASIS,
14# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15# See the License for the specific language governing permissions and
16# limitations under the License.
17
18from typing import TypeVar, TypeAlias, Callable, Union, Awaitable, ParamSpec, TypeVarTuple
19
20IN = TypeVar('IN')  # pragma: no mutate
21K = TypeVar('K')  # pragma: no mutate
22N = TypeVar('N')  # pragma: no mutate
23OUT = TypeVar('OUT')  # pragma: no mutate
24R = TypeVar('R')  # pragma: no mutate
25T = TypeVar('T')  # pragma: no mutate
26U = TypeVar('U')  # pragma: no mutate
27V = TypeVar('V')  # pragma: no mutate
28
29INs = TypeVarTuple('INs')  # pragma: no mutate
30Ks = TypeVarTuple('Ks')  # pragma: no mutate
31Ns = TypeVarTuple('Ns')  # pragma: no mutate
32OUTs = TypeVarTuple('OUTs')  # pragma: no mutate
33Rs = TypeVarTuple('Rs')  # pragma: no mutate
34Ts = TypeVarTuple('Ts')  # pragma: no mutate
35Us = TypeVarTuple('Us')  # pragma: no mutate
36Vs = TypeVarTuple('Vs')  # pragma: no mutate
37
38
39P = ParamSpec('P')  # pragma: no mutate
40# Fix Pycharm false positive warning
41P: ParamSpec = P  # pragma: no mutate
42
43# See: https://peps.python.org/pep-0484/#type-aliases
44#   Examples:
45#     -> Function[int, bool] is equivalent to Callable[[int], bool]
46#     -> Predicate[str] is equivalent to Callable[[str], bool]
47#     -> Supplier[str] is equivalent to Callable[[], str]
48# Note (on march 2022): Use mypy for typing validation (By default pycharm is not compliant)
49Function: TypeAlias = Callable[[T], R]
50"""Function[T, R]: A function that accepts one T type argument and produces a R type result"""
51Function.__doc__ = \
52    "Function[T, R]: A function that accepts one T type argument and produces a R type result"  # pragma: no mutate
53
54Predicate: TypeAlias = Callable[[T], bool]
55"""Predicate[T]: A predicate (boolean-valued function) of one T type argument"""
56Predicate.__doc__ = "Predicate[T]: A predicate (boolean-valued function) of one T type argument"  # pragma: no mutate
57
58Consumer: TypeAlias = Callable[[T], None]
59"""Consumer[T]: An operation that accepts a single T type argument and returns no result"""
60Consumer.__doc__ = \
61    "Consumer[T]: An operation that accepts a single T type argument and returns no result"  # pragma: no mutate
62
63Supplier: TypeAlias = Callable[[], R]
64"""Supplier[R]: A supplier of results of R type"""
65Supplier.__doc__ = "Supplier[R]: A supplier of results of R type"  # pragma: no mutate
66
67Runnable: TypeAlias = Callable[[], None]
68"""A function that accepts no T type argument and returns no result"""
69Runnable.__doc__ = "A function that accepts no T type argument and returns no result"  # pragma: no mutate
70
71BiFunction: TypeAlias = Callable[[T, U], R]
72"""Function[T, U, R]: A function that accepts two arguments and produces a R type result"""
73BiFunction.__doc__ = \
74    "Function[T, U, R]: A function that accepts two arguments and produces a R type result"  # pragma: no mutate
75
76SyncOrAsync: TypeAlias = Union[Awaitable[T], T]
77"""SyncOrAsync[T]: is used to specify that a value can be sync or async"""
78SyncOrAsync.__doc__ = \
79    "SyncOrAsync[T]: is used to specify that a value can be sync or async"  # pragma: no mutate
80
81BiConsumer: TypeAlias = Callable[[T, U], None]
82"""BiConsumer[T, U]: An operation that accepts two arguments and produces no result"""  # pragma: no mutate
83Consumer.__doc__ = \
84    "BiConsumer[T, U]: An operation that accepts two arguments and produces no result"  # pragma: no mutate