o jZ@sUdZddlmZddlZddlZddlmZddlmZddl m Z m Z m Z ddl mZmZmZmZmZddlmZmZmZd d lmZd Zejd krRd?ddZnd?ddZeeBeBeBe Bej BZ!d@ddZ"dAddZ#ddddBd#d$Z$ed%Z%d&e&d'< e'ee%Z(d(e&d)<Gd*d+d+e Z)Gd,d-d-e*Z+Gd.d/d/e Z,e,j-Z- ee,j-Z.d&e&d0< Gd1d2d2eZ/d3d4dCd6d7Z0dDd;d<Z1dd4dEd=d>Z2dS)FzEHigh-level introspection utilities, used to inspect type annotations.) annotationsN) Generator)InitVar)EnumIntEnumauto)AnyLiteral NamedTuple TypeAliascast) assert_neverget_args get_origin)typing_objects)AnnotationSourceForbiddenQualifierInspectedAnnotation Qualifierget_literal_valuesinspect_annotationis_union_origin)objrreturnboolcCs t|SaReturn whether the provided origin is the union form. ```pycon >>> is_union_origin(typing.Union) True >>> is_union_origin(get_origin(int | str)) True >>> is_union_origin(types.UnionType) True ``` !!! note Since Python 3.14, both `Union[, , ...]` and ` | | ...` forms create instances of the same [`typing.Union`][] class. As such, it is recommended to not use this function anymore (provided that you only support Python 3.14 or greater), and instead use the [`typing_objects.is_union()`][typing_inspection.typing_objects.is_union] function directly: ```python from typing import Union, get_origin from typing_inspection import typing_objects typ = int | str # Or Union[int, str] origin = get_origin(typ) if typing_objects.is_union(origin): ... ``` )ris_unionrr!R/opt/steambot/venv/lib/python3.10/site-packages/typing_inspection/introspection.pyrs rcCst|p |tjuSr)rrtypes UnionTyper r!r!r"r>svalueNonecCs*t|ts|tjurt|ddSdS)zCType check the provided literal value against the legal parameters.zK is not a valid literal value, must be one of: int, bytes, str, Enum, None.N) isinstance_literal_allowed_typesrNoneType TypeError)r%r!r!r"_literal_type_checkasr+aliascCs|j}t|r t|S|SN) __value__ris_typealiastype_unpack_type_alias_chain)r,r%r!r!r"r0gsr0Feager type_checkunpack_type_aliases annotationr3r4#Literal['skip', 'lenient', 'eager']Generator[Any]c cs|dkr)d}|jD]}|rt||dus|tjur#|s dVd}q |Vq dS|jD]}|tjus8t|r:nq,|rG|jD]}t|q@|jEdHdSg}|jD]Z}t|rzt|}Wnty~|dkrm|rst|||t|fYqTwt |||d}| dd|DqT|rt||tjur|dtjfqT||t|fqTzt |}Wnt yd d|DEdHYdSwd d|DEdHdS) a=Yield the values contained in the provided [`Literal`][typing.Literal] [special form][]. Args: annotation: The [`Literal`][typing.Literal] [special form][] to unpack. type_check: Whether to check if the literal values are [legal parameters][literal-legal-parameters]. Raises a [`TypeError`][] otherwise. unpack_type_aliases: What to do when encountering [PEP 695](https://peps.python.org/pep-0695/) [type aliases][type-aliases]. Can be one of: - `'skip'`: Do not try to parse type aliases. Note that this can lead to incorrect results: ```pycon >>> type MyAlias = Literal[1, 2] >>> list(get_literal_values(Literal[MyAlias, 3], unpack_type_aliases="skip")) [MyAlias, 3] ``` - `'lenient'`: Try to parse type aliases, and fallback to `'skip'` if the type alias can't be inspected (because of an undefined forward reference). - `'eager'`: Parse type aliases and raise any encountered [`NameError`][] exceptions (the default): ```pycon >>> type MyAlias = Literal[1, 2] >>> list(get_literal_values(Literal[MyAlias, 3], unpack_type_aliases="eager")) [1, 2, 3] ``` Note: While `None` is [equivalent to][none] `type(None)`, the runtime implementation of [`Literal`][typing.Literal] does not de-duplicate them. This function makes sure this de-duplication is applied: ```pycon >>> list(get_literal_values(Literal[NoneType, None])) [None] ``` Example: ```pycon >>> type Ints = Literal[1, 2] >>> list(get_literal_values(Literal[1, Ints], unpack_type_alias="skip")) ["a", Ints] >>> list(get_literal_values(Literal[1, Ints])) [1, 2] >>> list(get_literal_values(Literal[1.0], type_check=True)) Traceback (most recent call last): ... TypeError: 1.0 is not a valid literal value, must be one of: int, bytes, str, Enum, None. ``` skipFNTr1r2css|] }|t|fVqdSr-)type).0ar!r!r" sz%get_literal_values..cs|]\}}|VqdSr-r!r:p_r!r!r"r<csr=r-r!r>r!r!r"r<rA)__args__r+rr)r/r0 NameErrorappendr9rextenddictfromkeysr*) r5r3r4 _has_noneargvalues_and_type alias_valuesub_argsdctr!r!r"rls`:           r)required not_required read_only class_varinit_varfinalr rset[Qualifier]_all_qualifiersc@s^eZdZdZeZ eZ eZ eZ eZ eZ eZ eZ e dddZdS)rzThe source of an annotation, e.g. a class or a function. Depending on the source, different [type qualifiers][type qualifier] may be (dis)allowed. rrTcCsz|tjurdhS|tjurddhS|tjurhdS|tjur#hdS|tjtjtjfvr0tS|tj ur7t St |dS)zIThe allowed [type qualifiers][type qualifier] for this annotation source.rSrQ>rSrRrQ>rNrPrON) rASSIGNMENT_OR_VARIABLECLASS DATACLASS TYPED_DICT NAMED_TUPLEFUNCTIONBAREsetANYrUr selfr!r!r"allowed_qualifiersMs      z#AnnotationSource.allowed_qualifiersN)rrT)__name__ __module__ __qualname____doc__rrVrWrXrYrZr[r^r\propertyrar!r!r!r"rs(      rc@s&eZdZUdZded< d ddZdS) rz-The provided [type qualifier][] is forbidden.r qualifierrr&cCs ||_dSr-)rg)r`rgr!r!r"__init__gs zForbiddenQualifier.__init__N)rgrrr&)rbrcrdre__annotations__rhr!r!r!r"ras rc@s&eZdZeZdddZdddZdS) _UnknownTypeEnumrstrcCdS)NUNKNOWNr!r_r!r!r"__str__nz_UnknownTypeEnum.__str__cCrl)Nz r!r_r!r!r"__repr__qroz_UnknownTypeEnum.__repr__N)rrk)rbrcrdrrmrnrpr!r!r!r"rjks rj _UnknownTypec@s.eZdZUdZded< ded< ded<dS) rz'The result of the inspected annotation.zAny | _UnknownTyper9rT qualifiersz list[Any]metadataN)rbrcrdrerir!r!r!r"r|s  rr8r4annotation_sourcecCs|j}t}g} t||d\}}|r||}qt|}|durt|r8d|vr-td|d|jd}n{t |rPd|vrEtd|d|jd}nct |rhd|vr]td|d|jd}nKt |rd|vrutd|d|jd}n3t |rd |vrtd|d |jd}nnt |trd |vrtd |d tt|j}nnq t |rd|vrtd|dt}n(t|rd|vrtd|dt}n|turd |vrtd |d t}t|||S) a Inspect an [annotation expression][], extracting any [type qualifier][] and metadata. An [annotation expression][] is a [type expression][] optionally surrounded by one or more [type qualifiers][type qualifier] or by [`Annotated`][typing.Annotated]. This function will: - Unwrap the type expression, keeping track of the type qualifiers. - Unwrap [`Annotated`][typing.Annotated] forms, keeping track of the annotated metadata. Args: annotation: The annotation expression to be inspected. annotation_source: The source of the annotation. Depending on the source (e.g. a class), different type qualifiers may be (dis)allowed. To allow any type qualifier, use [`AnnotationSource.ANY`][typing_inspection.introspection.AnnotationSource.ANY]. unpack_type_aliases: What to do when encountering [PEP 695](https://peps.python.org/pep-0695/) [type aliases][type-aliases]. Can be one of: - `'skip'`: Do not try to parse type aliases (the default): ```pycon >>> type MyInt = Annotated[int, 'meta'] >>> inspect_annotation(MyInt, annotation_source=AnnotationSource.BARE, unpack_type_aliases='skip') InspectedAnnotation(type=MyInt, qualifiers={}, metadata=[]) ``` - `'lenient'`: Try to parse type aliases, and fallback to `'skip'` if the type alias can't be inspected (because of an undefined forward reference): ```pycon >>> type MyInt = Annotated[Undefined, 'meta'] >>> inspect_annotation(MyInt, annotation_source=AnnotationSource.BARE, unpack_type_aliases='lenient') InspectedAnnotation(type=MyInt, qualifiers={}, metadata=[]) >>> Undefined = int >>> inspect_annotation(MyInt, annotation_source=AnnotationSource.BARE, unpack_type_aliases='lenient') InspectedAnnotation(type=int, qualifiers={}, metadata=['meta']) ``` - `'eager'`: Parse type aliases and raise any encountered [`NameError`][] exceptions. Returns: The result of the inspected annotation, where the type expression, used qualifiers and metadata is stored. Example: ```pycon >>> inspect_annotation( ... Final[Annotated[ClassVar[Annotated[int, 'meta_1']], 'meta_2']], ... annotation_source=AnnotationSource.CLASS, ... ) ... InspectedAnnotation(type=int, qualifiers={'class_var', 'final'}, metadata=['meta_1', 'meta_2']) ``` TrtNrQrrSrNrOrPrR)rar]_unpack_annotatedrr is_classvarraddrBis_final is_requiredis_notrequired is_readonlyr'rr rr9rmr)r5rur4rarrrs_metaoriginr!r!r"rsv8                  -     rLiteral['lenient', 'eager']check_annotatedtuple[Any, list[Any]]c Cs.t|}|r$t|r$|j}t|j}t||dd\}}||}||fSt|rSz|j}Wnt y?|dkr:Y|gfSwt||dd\}}|rO||fS|gfSt|rz|j}Wnt yn|dkriY|gfSwz||j }Wn t yYnwt||dd\}}|r||fS|gfS|gfS)NFr4rr1T) rr is_annotated __origin__list __metadata___unpack_annotated_innerr/r.rCrBr*) r5r4rr~annotated_typerssub_metar%typr!r!r"rsZ     +       rcCs<|dkrtt|r|jt|jfS|gfSt||ddS)Nr8Tr)rrrrrrr)r5r4r!r!r"rvSs rv)rrrr)r%rrr&)r,rrr)r5rr3rr4r6rr7)r5rrurr4r6rr)r5rr4rrrrr)r5rr4r6rr)3re __future__rsysr#collections.abcr dataclassesrenumrrrtypingrr r r r typing_extensionsr rrr__all__ version_inforintbytesrkrr)r(r+r0rrrir]rUr Exceptionrrjrmrqrrrrvr!r!r!r"sH      "   |q   |D