ubii.framework.util.typing module

Defines some special TypeVars and Type Aliases to be used throughout the codebase.

Also fixes the imports for some names that are not compatible with older python versions, namely runtime_checkable and Protocol, so the special import handling can be done in one place instead of every module that imports them.

Note

ubii.framework.util.typing.SimpleCoroutine

TypeAlias for a Coroutine that only cares about return Type

alias of Coroutine[Any, Any, T]

ubii.framework.util.typing.Decorator

A Callable that decorates other Callables

alias of Callable[[Callable], Callable]

ubii.framework.util.typing.ExcInfo

Types according to return of sys.exc_info()

alias of Tuple[Optional[Type[T_Exception]], Optional[T_Exception], Any]

class ubii.framework.util.typing.Descriptor(*args, **kwargs)

Bases: Protocol[T_co]

__get__(instance: Any | None = ..., owner: Type[Any] | None = ...) → T_co

Descriptors need to have this method. For more inforation see https://docs.python.org/3/howto/descriptor.html

class ubii.framework.util.typing.Documented(*args, **kwargs)

Bases: Protocol

__doc__

Documented objects need to have a __doc__ attribute

class ubii.framework.util.typing.Protocol

Bases: Generic

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(Protocol[T]):
    def meth(self) -> T:
        ...
ubii.framework.util.typing.runtime_checkable(cls)

Mark a protocol class as a runtime protocol.

Such protocol can be used with isinstance() and issubclass(). Raise TypeError if applied to a non-protocol class. This allows a simple-minded structural check very similar to one trick ponies in collections.abc such as Iterable. For example:

@runtime_checkable
class Closable(Protocol):
    def close(self): ...

assert isinstance(open('/some/file'), Closable)

Warning: this will check only the presence of the required methods, not their type signatures!

ubii.framework.util.typing.T

Simple TypeVar

alias of TypeVar(‘T’)

ubii.framework.util.typing.S

Simple TypeVar

alias of TypeVar(‘S’)

ubii.framework.util.typing.R

Simple TypeVar

alias of TypeVar(‘R’)

ubii.framework.util.typing.T_Exception

bound to Exception

alias of TypeVar(‘T_Exception’, bound=Exception)

ubii.framework.util.typing.T_EnumFlag

bound to enum.IntFlag

alias of TypeVar(‘T_EnumFlag’, bound=IntFlag)

ubii.framework.util.typing.T_co

covariant values

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

ubii.framework.util.typing.T_contra

contravariant values

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

ubii.framework.util.typing.AsyncSetter

alias of Callable[[T], Awaitable[None]]

ubii.framework.util.typing.AsyncGetter

alias of Callable[[], Awaitable[T]]

ubii.framework.util.typing.__all__ = ('SimpleCoroutine', 'Decorator', 'ExcInfo', 'Descriptor', 'Documented', 'Protocol', 'runtime_checkable', 'T', 'S', 'R', 'T_Exception', 'T_EnumFlag', 'T_co', 'T_contra', 'AsyncSetter', 'AsyncGetter')

names that should be imported from ubii.util.typing and not from other modules