ÁjXBUdZddlmZddlZddlZddlmZddlmZddl m Z m Z m Z ddl mZmZmZmZmZddlmZmZmZd d lmZd Zej4d k\rd'd Znd'dZeezezeze zej@zZ!d(dZ"ddd d)dZ#edZ$de%d< e&ee$Z'de%d<Gdde Z(Gdde)Z*Gdde Z+e+jXZ, ee+jXZ-de%d< Gd d!eZ.d"d# d*d$Z/ d+d%Z0dd# d,d&Z1y)-zEHigh-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)c,tj|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_unionobjs F/tmp/pip-target-k_scjv0h/lib/python/typing_inspection/introspection.pyrrs:&&s++cTtj|xs|tjuSr)rrtypes UnionTypers r!rr>s#:&&s+Eseoo/EEr"cft|ts!|tjurt |dyy)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)values r!_literal_type_checkr,as6 e3 4nF]F]9]5'!lmnn:^ 4r"Feager type_checkunpack_type_aliasesc#K|dk(rBd}|jD]0}|r t|||tjur |sdd}-|2yg}|jD]}tj|r4 |j }t |||}|jd|DL|r t||tjur"|jdtjf|j|t|f tj|}d|DEd{y#t$r3|dk(r|r t||j|t|fYwxYw7D#t$rd |DEd{7YywxYww) 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. ``` skipFNTr.c36K|]}|t|fywN)type).0as r! z%get_literal_values..s*JAAtAw<*Jsr-c3&K|] \}}| ywr4r6p_s r!r8z%get_literal_values..s*da*c3&K|] \}}| ywr4r:r;s r!r8z%get_literal_values..s6da6r>)__args__r,rr)is_typealiastype __value__rextend NameErrorappendr5dictfromkeysr*) annotationr/r0 _has_noneargvalues_and_type alias_valuesub_argsdcts r!rrgstf$ && C#C({c^%<%<< J   8:&& =C ..s3 K"%--K 2# Pc H$***J*JJ',.111#**D.2I2I+JK#**Cc+;<5 =8 +--0C +c* * *5!=*g5!+C0#**Cc+;< =4 +  76o6 6 6 7sgA.F 1 D+=BF E, F %E*&F +8E'#F &E''F ,F FF F  F  F )required not_required read_only class_varinit_varfinalr rset[Qualifier]_all_qualifiersceZdZdZeZ eZ eZ eZ eZ eZ eZ eZ e ddZy)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. cn|tjurdhS|tjurddhS|tjurhdS|tjurhdS|tj tj tjfvr tS|tjurtSt|y)zIThe allowed [type qualifiers][type qualifier] for this annotation source.rTrR>rTrSrR>rOrQrPN) rASSIGNMENT_OR_VARIABLECLASS DATACLASS TYPED_DICT NAMED_TUPLEFUNCTIONBAREsetANYrVrselfs r!allowed_qualifiersz#AnnotationSource.allowed_qualifiers<s #:: :9  %++ +[) ) %// /5 5 %00 0< < &224D4M4MO_OdOde e5L %)) )" "  r"N)returnrU)__name__ __module__ __qualname____doc__rrYrZr[r\r]r^rar_propertyrdr:r"r!rrs "V FE I J &K vH &C 6D r"rc&eZdZUdZded< ddZy)rz-The provided [type qualifier][] is forbidden.r qualifierc||_yr4)rl)rcrls r!__init__zForbiddenQualifier.__init__Vs "r"N)rlrreNone)rfrgrhri__annotations__rnr:r"r!rrPs7"#r"rc*eZdZeZddZddZy)_UnknownTypeEnumcy)NUNKNOWNr:rbs r!__str__z_UnknownTypeEnum.__str__]sr"cy)Nz r:rbs r!__repr__z_UnknownTypeEnum.__repr__`sr"N)restr)rfrgrhrrtrurwr:r"r!rrrrZsfGr"rr _UnknownTypec4eZdZUdZded< ded< ded<y) rz'The result of the inspected annotation.zAny | _UnknownTyper5rU qualifiersz list[Any]metadataN)rfrgrhrirpr:r"r!rrks$1  J!r"rr2r0c:|j}t}g} t||\}}|r||z}t|}|\t j |r1d|vr t d|jd|jd}nbt j|r1d|vr t d|jd|jd}nt j|r0d|vr t d|jd|jd}nt j|r0d|vr t d|jd|jd}nt j|r0d|vr t d|jd|jd}nMnNt|tr;d|vr t d|jdtt |j"}nnt j|r'd|vr t d|jdt$}njt j |r'd|vr t d|jdt$}n.|tur&d|vr t d|jdt$}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']) ``` r}rRrrTrOrPrQrS)rdr`_unpack_annotatedrr is_classvarraddr@is_final is_requiredis_notrequired is_readonlyr'rr r r5rtr)rHannotation_sourcer0rdr{r|_metaorigins r!rrsup+==!$JH -jNab E x'H J'  ))&1&88,[99{+'003 ((0"44,W55w''003 ++F3%77,Z88z*'003 ..v6!);;,^<<~.'003 ++F3&88,^<<{+'003   G ,!33(44 NN: &c:??3J U Zz* , ,$W- -w  # #J / 0 0$[1 1{# w  / /$Z0 0z" z:x @@r"cVt|}|rPtj|r;|j}t |j }t ||d\}}||z}||fStj|r( |j}t ||d\}}|r||fS|gfStj|r8 |j} ||j}t ||d\}}|r||fS|gfS|gfS#t$r |dk(rY|gfSwxYw#t$rYBwxYw#t$r |dk(rY|gfSwxYw)NFr0check_annotatedTr-) rr is_annotated __origin__list __metadata___unpack_annotated_innerrArBrDr@r*) rHr0rrannotated_typer|sub_metar+typs r!rrs #F>66v>#.. //0 $; 0CUZ$  h&x''  ( ( 4 "((E 4+>PTMCH}$r> !  ( ( 0 "$$E j112 4+>PTMCH}$r> ! r>Y "g-.V r>Y B   "g-.0 r>3 s64 C,1 D>D,DD DDD('D(c|dk(rCtjt|r!|jt |j fS|gfSt ||dS)Nr2Tr)rrrrrrr)rHr0s r!rrBsVf$  & &z*'= >(($z/F/F*GG Gr> ! ":CVhl mmr")r r rebool)r+r rero)rHr r/rr0#Literal['skip', 'lenient', 'eager']rezGenerator[Any])rHr rrr0rrer)rHr r0zLiteral['lenient', 'eager']rrretuple[Any, list[Any]])rHr r0rrer)2ri __future__rsysr$collections.abcr dataclassesrenumrrrtypingr r r r r typing_extensionsrrrr__all__ version_inforintbytesrxrr)r(r,rrrpr`rVr Exceptionrrrrtryrrrrr:r"r!rsK" %$$<<@@ w,DF@us*T1D8>;R;RRo?F m+m+ m+ = m+  m+`hi 9i"%hy&9":: nwnb##t  " "C!"2":":; i;Z"*":@F yAyA( yA = yA  yAx??*E?X\??HW^ n n0S n nr"