bagof.core.magic

Get a valid concrete type from a type hint.

• If the hint is annotated, the Annotated wrapper is removed.
• If the hint has an origin, it is used.
• If the hint is a TypeVar:
  • its default value is used, if it has one; otherwise
  • the first of its constraints is used, if it has any; otherwise
  • its bound is used, if it has one; otherwise
  • the fallback type is used, if it is provided; otherwise
  • a TypeError is raised.
• If the (resolved) hint is a concrete, non-abstract type, it is returned as is; otherwise
• The fallback type is used, if it is provided; otherwise
• A TypeError is raised.

>>> get_concrete_type(List[int])
<class 'list'>
>>> get_concrete_type(TypeVar("T", int, str))
<class 'int'>

Get a default value from a type hint.

• If the hint is a Literal, the first value in the literal is returned (None, if None is one of the literal's values).
• If the hint is a Union that contains NoneType, None is returned.
• Otherwise, if the hint is a Union, we recurse through its sub-hints and return the first default found.
• If no default value can be found, a TypeError is raised. A factory should then be used.

Get the best matching value from a registry whose keys are types or type hints.

The best match is the registry key that is the narrowest superclass (or superhint) of hint, following its MRO; exact matches are always preferred. If hint is Annotated and no match is found for it directly, the search is retried against its unwrapped hint.

Exact matches are by hint equality, so List[int] and list[int] are different keys, but Union[int, str] and Union[str, int] are the same one.

>>> registry = {int: "number", object: "any"}
>>> get_from_registry(bool, registry)
'number'
>>> get_from_registry(str, registry)
'any'

Return true if an object is a type or is TypedDict.

Return true if an object is a TypedDict or a subclass of it.

The required keys of a TypedDict.

Reads __required_keys__ where the class has it -- the only source that accounts for Required / NotRequired (in either nesting with Annotated) and for inheriting from bases declared with a different total=.

Falls back to __total__ where it does not: typing.TypedDict gained __required_keys__ only in Python 3.9, and before that a key's requiredness came from the class's total= alone -- per-key Required/NotRequired did not exist.

>>> class Movie(TypedDict):
...     title: str
...     year: NotRequired[int]
>>> typeddict_required_keys(Movie)
frozenset({'title'})

Safe subclass (does not fail if arguments are not types).

>>> safe_issubclass(bool, int)
True
>>> safe_issubclass(bool, (str, int))  # a tuple, like `issubclass`
True
>>> safe_issubclass(int, "not a type")  # no error
False

Safe isinstance (does not fail if second argument is not a type).

>>> safe_isinstance(1, int)
True
>>> safe_isinstance(1, (str, int))  # a tuple, like `isinstance`
True
>>> safe_isinstance(1, "not a type")  # no error
False

Like isinstance, but the second argument can be a type hint.

• If hint is type or Type[...], checks that obj is a type and that it is valid subclass of the hint argument.
• If hint is a Literal, checks that obj is one of its values. The value must match in type as well: True is not a valid Literal[1], even though True == 1.
• If hint is a Union, checks obj against each of its members.
• Otherwise, returns issubhint(type(obj), hint).

>>> ishintstance(1, int)
True
>>> ishintstance(1, Literal[1, 2])
True
>>> ishintstance(bool, Type[int])
True

Check that a hint is a sub-hint for another hint.

A hint is a valid subhint if all values that are valid for the hint are also valid for the superhint.

Arguments are compared covariantly, so List[bool] is a subhint of List[int]. A hint with no arguments is not a subhint of one that has them - a bare list may hold anything, so it cannot stand in for a List[int].

>>> from typing import List, Union
>>> issubhint(bool, int)
True
>>> issubhint(Union[int, str], Union[int, str, bytes])
True
>>> issubhint(List[bool], List[int])
True
>>> issubhint(list, List[int])  # a bare list may hold anything
False
>>> issubhint(int, str)
False

Unwrap a type hint from its origin, if it is in the unwrap list.

If TypeVar is one of the origins to unwrap, it will be unwrapped to its default, its (union of) constraints, or its bound - in that order.

>>> from typing import Annotated
>>> unwrap(Annotated[int, "meta"])
<class 'int'>
>>> unwrap(Annotated[Annotated[str, 1], 2])
<class 'str'>
>>> unwrap(int)  # unchanged
<class 'int'>

Safe version of tx.get_origin.

Can also unwrap some hints (e.g. Annotated) if asked.

Safe version of tx.get_origin that unwraps Annotated hints.

Returns the input type, instead of None, if the input is not a generic type.

Safe version of tx.get_args.

Returns an empty tuple if the input is not a generic type. Can also unwrap some hints (e.g. Annotated) if asked.

Safe version of tx.get_args that unwraps Annotated hints.

Returns an empty tuple if the input is not a generic type.

Map a value to a form that compares equal across NaNs.

Since float("nan") != float("nan"), comparing values that may contain NaN with == is unsafe. Apply this function to both operands before comparing them: real NaN values are all mapped to one sentinel (so that two NaNs compare equal), while every other value is returned unchanged.

>>> nan = float("nan")
>>> nan == nan
False
>>> eq_safenan(nan) == eq_safenan(nan)
True

Check that an object is subscriptable (i.e. can be used with []).

True if the object is a type and has __class_getitem__, or if it is an instance and has __getitem__. Otherwise, returns False.

Convert a type to a (subscriptable) type hint.

• If the input is a type, and it does not have __class_getitem__, we try to find its corresponding type hint. For example, in python 3.8, type2hint(list) returns typing.List.
• Otherwise, the value is returned as is.

>>> type2hint(frozenset)
typing.FrozenSet
>>> type2hint(3)  # not a type, so unchanged
3