sevaht_utility.hinting

Runtime inspection of type hints and unions.

Helpers for working with annotations at runtime: flattening unions (iterate_types()), checking a value against an expected runtime type (verify_type()), and extracting a callable’s argument types (get_callable_argument_hints()). These back the type-aware conversion in sevaht_utility.parsing.csv_load().

exception sevaht_utility.hinting.InvalidTypeError(value: object, *, expected_type: type[T] | UnionType)

Bases: TypeError

Raised when a value’s type does not match the expected type.

exception sevaht_utility.hinting.ParameterizedTypeNotSupportedError(expected_type: object)

Bases: TypeError

Raised when verify_type receives a parameterized generic.

sevaht_utility.hinting.iterate_types(*source_types: type | UnionType) → Iterator[type]

Yield the distinct member types of one or more (possibly union) types.

Unions are flattened recursively (both X | Y and typing.Union), and duplicates are skipped, preserving first-seen order.

Parameters:

*source_types – Types or unions to flatten.

Yields:

Each distinct constituent type, in order.

Example

>>> list(iterate_types(int | str))
[<class 'int'>, <class 'str'>]

sevaht_utility.hinting.verify_type(expected_type: type | UnionType, value: T) → T

Return value if it matches expected_type, else raise.

expected_type may be a single type or a union of types; value matches if it is an instance of any member (Any and object always match). Parameterized generics such as list[int] cannot be checked at runtime and are rejected.

Parameters:

• expected_type – The required type or union of types.

• value – The value to check.

Returns:

value unchanged, for convenient inline use.

Raises:

• InvalidTypeError – value matches no member of expected_type.

• ParameterizedTypeNotSupportedError – expected_type contains a parameterized generic.

sevaht_utility.hinting.get_callable_argument_hints(function: Callable[..., Any]) → dict[str, type]

Return a callable’s parameters mapped to their annotated types.

The return annotation is excluded, dataclass InitVar wrappers are unwrapped to their inner type, and unannotated parameters map to Any.

Parameters:

function – Any callable (function, dataclass type, etc.).

Returns:

A mapping of parameter name to its type.