import sys
from collections import Counter, deque
from collections.abc import Mapping as AbcMapping
from collections.abc import MutableMapping as AbcMutableMapping
from collections.abc import MutableSequence as AbcMutableSequence
from collections.abc import MutableSet as AbcMutableSet
from collections.abc import Sequence as AbcSequence
from collections.abc import Set as AbcSet
from dataclasses import MISSING, Field, is_dataclass
from dataclasses import fields as dataclass_fields
from functools import partial
from inspect import signature as _signature
from types import GenericAlias
from typing import (
Annotated,
Any,
Deque,
Dict,
Final,
FrozenSet,
Generic,
List,
Literal,
NewType,
Optional,
Protocol,
Tuple,
Union,
_AnnotatedAlias,
_GenericAlias,
_SpecialGenericAlias,
get_args,
get_origin,
get_type_hints,
)
from typing import Counter as TypingCounter
from typing import Mapping as TypingMapping
from typing import MutableMapping as TypingMutableMapping
from typing import MutableSequence as TypingMutableSequence
from typing import MutableSet as TypingMutableSet
from typing import Sequence as TypingSequence
from typing import Set as TypingSet
from attrs import NOTHING, Attribute, Factory, NothingType, resolve_types
from attrs import fields as attrs_fields
from attrs import fields_dict as attrs_fields_dict
__all__ = [
"ANIES",
"ExceptionGroup",
"ExtensionsTypedDict",
"TypeAlias",
"adapted_fields",
"fields_dict",
"has",
"is_typeddict",
]
try:
from typing_extensions import TypedDict as ExtensionsTypedDict
except ImportError: # pragma: no cover
ExtensionsTypedDict = None
if sys.version_info >= (3, 11):
from builtins import ExceptionGroup
else:
from exceptiongroup import ExceptionGroup
try:
from typing_extensions import is_typeddict as _is_typeddict
except ImportError: # pragma: no cover
assert sys.version_info >= (3, 10)
from typing import is_typeddict as _is_typeddict
try:
from typing_extensions import TypeAlias
except ImportError: # pragma: no cover
assert sys.version_info >= (3, 11)
from typing import TypeAlias
LITERALS = {Literal}
try:
from typing_extensions import Literal as teLiteral
LITERALS.add(teLiteral)
except ImportError: # pragma: no cover
pass
# On some Python versions, `typing_extensions.Any` is different than
# `typing.Any`.
try:
from typing_extensions import Any as teAny
ANIES = frozenset([Any, teAny])
except ImportError: # pragma: no cover
ANIES = frozenset([Any])
NoneType = type(None)
def is_optional(typ: Any) -> bool:
return is_union_type(typ) and NoneType in typ.__args__ and len(typ.__args__) == 2
def is_typeddict(cls: Any):
"""Thin wrapper around typing(_extensions).is_typeddict"""
return _is_typeddict(getattr(cls, "__origin__", cls))
def has(cls):
return hasattr(cls, "__attrs_attrs__") or hasattr(cls, "__dataclass_fields__")
def has_with_generic(cls):
"""Test whether the class if a normal or generic attrs or dataclass."""
return has(cls) or has(get_origin(cls))
def fields(type):
try:
return type.__attrs_attrs__
except AttributeError:
return dataclass_fields(type)
def fields_dict(type) -> dict[str, Union[Attribute, Field]]:
"""Return the fields_dict for attrs and dataclasses."""
if is_dataclass(type):
return {f.name: f for f in dataclass_fields(type)}
return attrs_fields_dict(type)
def adapted_fields(cl: type) -> list[Attribute]:
"""Return the attrs format of `fields()` for attrs and dataclasses.
Resolves `attrs` stringified annotations, if present.
"""
if is_dataclass(cl):
attrs = dataclass_fields(cl)
if any(isinstance(a.type, str) for a in attrs):
# Do this conditionally in case `get_type_hints` fails, so
# users can resolve on their own first.
type_hints = get_type_hints(cl)
else:
type_hints = {}
return [
Attribute(
attr.name,
(
attr.default
if attr.default is not MISSING
else (
Factory(attr.default_factory)
if attr.default_factory is not MISSING
else NOTHING
)
),
None,
True,
None,
True,
attr.init,
True,
type=type_hints.get(attr.name, attr.type),
alias=attr.name,
kw_only=getattr(attr, "kw_only", False),
)
for attr in attrs
]
attribs = attrs_fields(cl)
if any(isinstance(a.type, str) for a in attribs):
# PEP 563 annotations - need to be resolved.
resolve_types(cl)
attribs = attrs_fields(cl)
return attribs
def is_subclass(obj: type, bases) -> bool:
"""A safe version of issubclass (won't raise)."""
try:
return issubclass(obj, bases)
except TypeError:
return False
def is_hetero_tuple(type: Any) -> bool:
origin = getattr(type, "__origin__", None)
return origin is tuple and ... not in type.__args__
def is_protocol(type: Any) -> bool:
return is_subclass(type, Protocol) and getattr(type, "_is_protocol", False)
def is_bare_final(type) -> bool:
return type is Final
def get_final_base(type) -> Optional[type]:
"""Return the base of the Final annotation, if it is Final."""
if type is Final:
return Any
if type.__class__ is _GenericAlias and type.__origin__ is Final:
return type.__args__[0]
return None
OriginAbstractSet = AbcSet
OriginMutableSet = AbcMutableSet
signature = partial(_signature, eval_str=True)
try:
# Not present on 3.9.0, so we try carefully.
from typing import _LiteralGenericAlias
def is_literal(type: Any) -> bool:
"""Is this a literal?"""
return type in LITERALS or (
isinstance(
type, (_GenericAlias, _LiteralGenericAlias, _SpecialGenericAlias)
)
and type.__origin__ in LITERALS
)
except ImportError: # pragma: no cover
def is_literal(_) -> bool:
return False
Set = AbcSet
MutableSet = AbcMutableSet
Sequence = AbcSequence
MutableSequence = AbcMutableSequence
MutableMapping = AbcMutableMapping
Mapping = AbcMapping
FrozenSetSubscriptable = frozenset
TupleSubscriptable = tuple
def is_annotated(type) -> bool:
return getattr(type, "__class__", None) is _AnnotatedAlias
def is_tuple(type):
return (
type in (Tuple, tuple)
or (type.__class__ is _GenericAlias and is_subclass(type.__origin__, Tuple))
or (getattr(type, "__origin__", None) is tuple)
)
if sys.version_info >= (3, 14):
def is_union_type(obj):
from types import UnionType # noqa: PLC0415
return obj is Union or isinstance(obj, UnionType)
def get_newtype_base(typ: Any) -> Optional[type]:
if typ is NewType or isinstance(typ, NewType):
return typ.__supertype__
return None
from typing import NotRequired, Required
else:
from typing import _UnionGenericAlias
def is_union_type(obj):
from types import UnionType # noqa: PLC0415
return (
obj is Union
or (isinstance(obj, _UnionGenericAlias) and obj.__origin__ is Union)
or isinstance(obj, UnionType)
)
def get_newtype_base(typ: Any) -> Optional[type]:
if typ is NewType or isinstance(typ, NewType):
return typ.__supertype__
return None
if sys.version_info >= (3, 11):
from typing import NotRequired, Required
else:
from typing_extensions import NotRequired, Required
def get_notrequired_base(type) -> Union[Any, NothingType]:
if is_annotated(type):
# Handle `Annotated[NotRequired[int]]`
type = get_args(type)[0]
if get_origin(type) in (NotRequired, Required):
return get_args(type)[0]
return NOTHING
[docs]
def is_mutable_sequence(type: Any) -> bool:
"""A predicate function for mutable sequences.
Matches lists, mutable sequences, and deques.
"""
origin = getattr(type, "__origin__", None)
return (
type in (List, list, TypingMutableSequence, AbcMutableSequence, deque, Deque)
or (
type.__class__ is _GenericAlias
and (
((origin is not tuple) and is_subclass(origin, TypingMutableSequence))
or (origin is tuple and type.__args__[1] is ...)
)
)
or (origin in (list, deque, AbcMutableSequence))
)
[docs]
def is_sequence(type: Any) -> bool:
"""A predicate function for sequences.
Matches lists, sequences, mutable sequences, deques and homogenous
tuples.
"""
origin = getattr(type, "__origin__", None)
return is_mutable_sequence(type) or (
type in (TypingSequence, tuple, Tuple)
or (
type.__class__ is _GenericAlias
and (
((origin is not tuple) and is_subclass(origin, TypingSequence))
or (origin is tuple and type.__args__[1] is ...)
)
)
or (origin is AbcSequence)
or (origin is tuple and type.__args__[1] is ...)
)
def is_deque(type):
return (
type in (deque, Deque)
or (type.__class__ is _GenericAlias and is_subclass(type.__origin__, deque))
or (getattr(type, "__origin__", None) is deque)
)
def is_mutable_set(type: Any) -> bool:
"""A predicate function for (mutable) sets.
Matches built-in sets and sets from the typing module.
"""
return (
type in (TypingSet, TypingMutableSet, set)
or (
type.__class__ is _GenericAlias
and is_subclass(type.__origin__, TypingMutableSet)
)
or (getattr(type, "__origin__", None) in (set, AbcMutableSet, AbcSet))
)
[docs]
def is_frozenset(type: Any) -> bool:
"""A predicate function for frozensets.
Matches built-in frozensets and frozensets from the typing module.
"""
return (
type in (FrozenSet, frozenset)
or (type.__class__ is _GenericAlias and is_subclass(type.__origin__, FrozenSet))
or (getattr(type, "__origin__", None) is frozenset)
)
def is_bare(type):
return isinstance(type, _SpecialGenericAlias) or (
not hasattr(type, "__origin__") and not hasattr(type, "__args__")
)
[docs]
def is_mapping(type: Any) -> bool:
"""A predicate function for mappings."""
return (
type in (dict, Dict, TypingMapping, TypingMutableMapping, AbcMutableMapping)
or (
type.__class__ is _GenericAlias
and is_subclass(type.__origin__, TypingMapping)
)
or is_subclass(
getattr(type, "__origin__", type), (dict, AbcMutableMapping, AbcMapping)
)
)
def is_counter(type):
return (
type in (Counter, TypingCounter) or getattr(type, "__origin__", None) is Counter
)
def is_generic(type) -> bool:
"""Whether `type` is a generic type."""
# Inheriting from protocol will inject `Generic` into the MRO
# without `__orig_bases__`.
return (
isinstance(type, (_GenericAlias, GenericAlias))
or (is_subclass(type, Generic) and hasattr(type, "__orig_bases__"))
or type.__class__ is Union # On 3.14, unions are no longer typing._GenericAlias
)
def copy_with(type, args):
"""Replace a generic type's arguments."""
if is_annotated(type):
# typing.Annotated requires a special case.
return Annotated[args]
if isinstance(args, tuple) and len(args) == 1:
# Some annotations can't handle 1-tuples.
args = args[0]
return type.__origin__[args]
def get_full_type_hints(obj, globalns=None, localns=None):
return get_type_hints(obj, globalns, localns, include_extras=True)
def is_generic_attrs(type) -> bool:
"""Return True for both specialized (A[int]) and unspecialized (A) generics."""
return is_generic(type) and has(type.__origin__)