Typing

This module contains various useful typing definitions to simplify using some of the advanced typing features and avoid creating the same generic declarations from project to project.

It also fallbacks for the following common new typing features to avoid import errors on older versions of Python:

• Literal

• Protocol

• TypedDict

• TypeAlias

• ParamSpec

• ParamSpecArgs

• ParamSpecKwargs

• Concatenate

class aiuti.typing.ParamSpec(name, *, bound=None, covariant=False, contravariant=False, infer_variance=False, default=<sentinel>)

Parameter specification variable.

Usage:

P = ParamSpec('P')

Parameter specification variables exist primarily for the benefit of static type checkers. They are used to forward the parameter types of one callable to another callable, a pattern commonly found in higher order functions and decorators. They are only valid when used in Concatenate, or s the first argument to Callable. In Python 3.10 and higher, they are also supported in user-defined Generics at runtime. See class Generic for more information on generic types. An example for annotating a decorator:

T = TypeVar('T')
P = ParamSpec('P')

def add_logging(f: Callable[P, T]) -> Callable[P, T]:
    '''A type-safe decorator to add logging to a function.'''
    def inner(*args: P.args, **kwargs: P.kwargs) -> T:
        logging.info(f'{f.__name__} was called')
        return f(*args, **kwargs)
    return inner

@add_logging
def add_two(x: float, y: float) -> float:
    '''Add two numbers together.'''
    return x + y

Parameter specification variables defined with covariant=True or contravariant=True can be used to declare covariant or contravariant generic types. These keyword arguments are valid, but their actual semantics are yet to be decided. See PEP 612 for details.

Parameter specification variables can be introspected. e.g.:

P.__name__ == ‘T’ P.__bound__ == None P.__covariant__ == False P.__contravariant__ == False

Note that only parameter specification variables defined in global scope can be pickled.

append(object, /)

Append object to the end of the list.

clear()

Remove all items from list.

copy()

Return a shallow copy of the list.

count(value, /)

Return number of occurrences of value.

extend(iterable, /)

Extend list by appending elements from the iterable.

index(value, start=0, stop=9223372036854775807, /)

Return first index of value.

Raises ValueError if the value is not present.

insert(index, object, /)

Insert object before index.

pop(index=-1, /)

Remove and return item at index (default last).

Raises IndexError if list is empty or index is out of range.

remove(value, /)

Remove first occurrence of value.

Raises ValueError if the value is not present.

reverse()

Reverse IN PLACE.

sort(*, key=None, reverse=False)

Stable sort IN PLACE.

class aiuti.typing.ParamSpecArgs(origin)

The args for a ParamSpec object.

Given a ParamSpec object P, P.args is an instance of ParamSpecArgs.

ParamSpecArgs objects have a reference back to their ParamSpec:

P.args.__origin__ is P

This type is meant for runtime introspection and has no special meaning to static type checkers.

class aiuti.typing.ParamSpecKwargs(origin)

The kwargs for a ParamSpec object.

Given a ParamSpec object P, P.kwargs is an instance of ParamSpecKwargs.

ParamSpecKwargs objects have a reference back to their ParamSpec:

P.kwargs.__origin__ is P

This type is meant for runtime introspection and has no special meaning to static type checkers.

aiuti.typing.MaybeIter

Generic type for an object which may be a single value of a given type or an iterable of that type

alias of Union[T, Iterable[T]]

aiuti.typing.MaybeAwaitable

Generic type for an object which could be wrapped in an awaitable

alias of Union[T, Awaitable[T]]

aiuti.typing.Yields

Generic type for a Generator which only yields

This is different from Iterator[T] as it also declares that the object implements the rest Generator interface such as gen.close() and gen.throw().

alias of Generator[T, None, None]

aiuti.typing.AYields

Generic type for an AsyncGenerator which only yields

alias of AsyncGenerator[T, None]

aiuti.typing.T

Generic invariant type var

alias of TypeVar(‘T’)

aiuti.typing.T_co

Generic covariant type var

alias of TypeVar(‘T_co’, covariant=True)

aiuti.typing.T_contra

Generic contravariant type var

alias of TypeVar(‘T_contra’, contravariant=True)

aiuti.typing.KT

Generic invariant type var for keys

alias of TypeVar(‘KT’)

aiuti.typing.VT

Generic invariant type var for values

alias of TypeVar(‘VT’)

aiuti.typing.KT_co

Generic covariant type var for keys

alias of TypeVar(‘KT_co’, covariant=True)

aiuti.typing.VT_co

Generic covariant type var for values

alias of TypeVar(‘VT_co’, covariant=True)

aiuti.typing.F

Generic type var for a callable function

alias of TypeVar(‘F’, bound=Callable[[…], Any])