bagof.core.magic

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

Safe version of tx.get_args that unwraps Annotated hints.

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

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'>

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.

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

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

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.

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_origin.

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

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

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

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

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'})

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'>

Drop the pending registrations (of registry, or of every registry) without applying them. Meant for test isolation.

Register value in registry under the object ref names, once that object has been imported - see find_name for how it is found.

This is the lazy counterpart of registry[key] = value: if the object can already be found, it is registered at once; otherwise the registration is kept pending, and resolve_pending (which get_from_registry calls before every lookup) moves it into the registry as soon as the object can be found. Nothing is ever imported or evaluated to find it.

Parameters:

Raises:

The object a dotted name refers to, if it is already imported. Never imports anything, and never evaluates the name.

1. Relative: the first part of the name is looked up in the globals of the context module (if it is imported), and the rest is walked as attributes. This follows the module's own runtime imports, such as import numpy as np for "np.ndarray".
2. Absolute: the longest dotted prefix of the name present in sys.modules is taken, and the rest is walked as attributes.

A module is always read through its __dict__, so a module-level __getattr__ (PEP 562) cannot import anything: a submodule that has not been imported yet is not found. Builtins are not looked up.

Returns:

Raises:

Whether the top-level package of name can be imported, without importing it.

Only the top-level name is looked up - finding a submodule's spec would import its parent package - so has_module("dask.array") tells whether dask is installed.

Whether obj is a ForwardRef (a lazy key).

The registrations still pending (in registry, or in any registry), oldest first, as (context_module, "dotted.name", value). Meant for debugging a key that never resolves.

Move the pending registrations that can now be resolved into their registry, oldest first. Returns at once when nothing is pending.

get_from_registry calls this before every lookup, so a caller only needs it before reading a registry directly. A resolved entry is not written over a key already present for its object - see the ordering note of defer.

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.

Pending lazy keys (see defer) whose target has been imported since are moved into their registry first, so every caller sees them.

Two keys at the same distance from hint are told apart by specificity (a subclass key beats its superclass), and then by registry order. Distances along an MRO are all different, so a true tie only happens between keys hint is a virtual subclass of (such as two unrelated ABCs it is registered with). A lazy key enters the registry when it resolves, so that is the position it ties at.

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

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