stouputils.typing.runtime module#

is_generic_instance( obj: Any, type_hint: type[T], ) → TypeIs[T][source]#

is_generic_instance( obj: Any, type_hint: UnionType, ) → TypeIs[Any]

is_generic_instance( obj: Any, type_hint: T, ) → TypeIs[T]

is_generic_instance( obj: Any, type_hint: Any, ) → TypeIs[Any]

Runtime equivalent of isinstance() for generic type hints. is_generic_instance(my_dict, dict[str, int]) checks that my_dict is a dictionary with string keys and integer values.

### Note: this function is not a perfect replacement for static type checking, and may not cover all edge cases or complex type hints.

Parameters:

obj – The object to check.
type_hint – The type hint to check against.

Returns:

True if obj matches type_hint, False otherwise.

>>> is_generic_instance(5, int)
True
>>> is_generic_instance("hello", str)
True
>>> is_generic_instance([1, 2, 3], list)
True
>>> is_generic_instance([1, 2, 3], list[int])
True
>>> is_generic_instance([1, 2, 3], list[str])
False
>>> is_generic_instance({"a": 1}, dict[str, int])
True
>>> is_generic_instance({"a": 1}, dict[str, int] | Mapping)
True
>>> is_generic_instance({"a": 1}, dict[str, int] | Mapping | JsonDict)
True
>>> is_generic_instance({"a": 1}, (dict[str, int], Mapping, JsonDict))
True
>>> is_generic_instance([1, 2, 3], dict[str, int])
False
>>> is_generic_instance({"a": 1}, "dict[str, int] | Mapping | JsonDict")
True

matches_generic_alias( obj: Any, type_hint: GenericAlias, ) → bool[source]#

The part of is_generic_instance() that handles a parameterized type such as list[int].

The origin type is always checked. Its parameters are checked only for a one-parameter container, against every item, and for a mapping, against every key and value. Any other parameterized type is matched on its origin alone.

>>> matches_generic_alias({"a": 1}, dict[str, int]), matches_generic_alias([1, "x"], list[int])
(True, False)
>>> matches_generic_alias((1, "x"), tuple[int, str])
True

is_sequence(obj: Iterable[T]) → TypeIs[Sequence[T]][source]#

is_sequence( obj: Any, ) → TypeIs[Sequence[Any]]

Return True if obj supports O(1) __len__ and __getitem__.

Such objects are used as-is without copying their contents into a list. Plain iterators (iter(), generators, …) return False.

>>> is_sequence(range(int(1e15)))
True
>>> is_sequence([1, 2, 3])
True
>>> is_sequence(iter(range(10)))
False
>>> is_sequence((x for x in range(10)))
False

convert_to_serializable(obj: Any) → Any[source]#

Recursively convert objects to JSON-serializable forms.

Objects with a to_dict() or asdict() method are converted to their dictionary representation. Dictionaries and lists are recursively processed.

Can also be used to convert nested structures containing custom objects, such as defaultdict, dataclasses, or other user-defined types.

Parameters:: obj – The object to convert
Returns:: The JSON-serializable version of the object

>>> from typing import defaultdict
>>> my_dict = defaultdict(lambda: defaultdict(int))
>>> my_dict['a']['b'] += 6
>>> my_dict['c']['d'] = 4
>>> my_dict['a']
defaultdict(<class 'int'>, {'b': 6})
>>> my_dict['c']
defaultdict(<class 'int'>, {'d': 4})
>>> convert_to_serializable(my_dict)
{'a': {'b': 6}, 'c': {'d': 4}}

>>> from dataclasses import dataclass
>>> @dataclass
... class Point:
...     x: int
...     y: int
...     some_list: list[int]
>>> convert_to_serializable(Point(3, 4, [1, 2, 3]))
{'x': 3, 'y': 4, 'some_list': [1, 2, 3]}