%^gAUdZddlmZddlZddlZddlZddlZddlZddlm Z m Z m Z m Z m Z mZmZddlmZddlZeeefZded<ej0dZd ed <ej0d Zd ed <d+d ZGddZGdde ZdZd ed<dZd ed<dZ d ed<dZ!d ed<dZ"d ed<dZ#d ed<dZ$d ed<Gd d!Z%d,d"Z&d-d#Z'd.d$Z(d/d%Z)d0d&Z*d1d'Z+d2d(Z,d3d)Z-d4d*Z.y)5zParsing/inferring signatures from documentation. This module provides several functions to generate better stubs using docstrings and Sphinx docs (.rst files). ) annotationsN)AnyFinalMutableMappingMutableSequence NamedTupleSequenceTuple) TypeAlias _TypeAliasSigz4^[a-zA-Z_][\w\[\], .\"\']*(\.[a-zA-Z_][\w\[\], ]*)*$r_TYPE_REz\**[A-Za-z_][A-Za-z0-9_]*$ _ARG_NAME_REcL|dvryd|vrd|vrytj|duS)zCTry to determine whether a string might be a valid type annotation.)TrueFalseretvalF,[N)rmatch)ss ,lib/python3.12/site-packages/mypy/stubdoc.py is_valid_typers2 '' axCqL >>! D ((cVeZdZdZ d ddd d dZd dZd dZdd Zdd Zy)ArgSigz%Signature info for a single argument.NFz...)default default_valuec<||_||_||_||_yN)nametyperr)selfr!r"rrs r__init__zArgSig.__init__'s!   *rct|jjdxr|jjd S)N***r! startswithr#s r is_star_argzArgSig.is_star_arg5s.yy##C(K1E1Ed1K-KKrc8|jjdS)Nr'r(r*s r is_star_kwargzArgSig.is_star_kwarg8syy##D))rcdjt|jt|jt|jS)Nz$ArgSig(name={}, type={}, default={}))formatreprr!r"rr*s r__repr__zArgSig.__repr__;s55<< OT$))_d4<<.@  rct|trj|j|jk(xrO|j|jk(xr4|j|jk(xr|j |j k(Sy)NF) isinstancerr!r"rr)r#others r__eq__z ArgSig.__eq__@sk eV $ UZZ'>II+>LLEMM1>&&%*=*==   rr ) r!strr" str | Nonerboolrr6returnNoner9r8)r9r6)r4rr9r8) __name__ __module__ __qualname____doc__r$r+r-r1r5rrrr$sa/   + " + + +  +  +  +L* rrcveZdZUded<ded<ded<dZded<dd Zdd Zdd Z d dd Zy ) FunctionSigr6r! list[ArgSig]argsr7ret_type type_argsct|jjdxrF|jjdxr)|jxr|jdjdvS)N__rr#cls)r8r!r)endswithrDr*s ris_special_methodzFunctionSig.is_special_methodQsa II  & 5 ""4( 5  5 ! !!_4   rc |jr+|jdjdvr|jdd}n |j}t|dk(xr<td|Dxr(|dj xr|dj S)z=Return if this signature has catchall args: (*args, **kwargs)rrJNc38K|]}|jdvyw))Nobjectr typing.AnyN)r").0as r z0FunctionSig.has_catchall_args..asRTAFFCCTs)rDr!lenallr+r-)r#rDs rhas_catchall_argszFunctionSig.has_catchall_argsYs 991**o=99QR=D99D IN (RTRR (Q##% (Q%%'  rcB|jxr|jdvS)zKReturn if this signature is the catchall identity: (*args, **kwargs) -> Any)NrrS)rYrEr*s ris_catchall_signaturez!FunctionSig.is_catchall_signaturefs %%'XDMM=X,XXrNc g}|jD]}|j}|tjvrd|z}|j.|,|jdvr|jj ds|}n |j}|r'|d|zz }|j r1|d|jz }n|j r|d|jz }|j|d} |jr |jn|} | d| z} |rd nd} || d |j|jd d j|d | d } |r&d|dtjj|} nd} | | S)N_rJr&z: z = =rFz -> zasync zdef (, ): z z ...)rDr!keywordkwlistr"r)rrappendrErGjoinmypyutilquote_docstring)r#indentis_asyncany_val docstringrDargarg_defarg_typeretfieldrEprefixsigsuffixs r format_sigzFunctionSig.format_sigjst99ChhG'..(- 'HHO3++C0'.884(?*;;S%6%6$788GQs00122 KK /2$(MM4==w  (H%2TYYK/?q4@QQRS[R\\]^ &dii&?&? &J%KLFFvhrr;)rFFNN) rkr6rlr8rmr7rnr7r9r6) r<r=r>__annotations__rGrMrYr[rvr@rrrBrBKsp I Is   Y " $ , , ,  ,  , , rrBrO STATE_INITrPSTATE_FUNCTION_NAMESTATE_ARGUMENT_LISTSTATE_ARGUMENT_TYPESTATE_ARGUMENT_DEFAULTSTATE_RETURN_VALUESTATE_OPEN_BRACKETc0eZdZdZddZddZd dZd dZy) DocStringParserz+Parse function signatures in documentation.c||_tg|_d|_d|_d|_d|_d|_d|_g|_ g|_ y)NrFrF) function_namerxstate accumulatorrqarg_name arg_defaultrEfoundrD signatures)r#rs rr$zDocStringParser.__init__sM* \ $(  '+  "$ -/rc |jtjk(rO|j|jk(r6|j dt k(r |j jty |jtjk(rm|jdk(r^|j dtk(rH|j jd|_ d|_ |j jty |j dtk(r|j jy |jtjk(rc|jdvrU|j dt k7r?|xj|jz c_ |j jty |jtjk(r^|jdvrP|j dtk(r:|xj|jz c_ |j jy |jtjk(r]|jdk(rN|j dtk(r8|j|_d|_ |j jt y |jtjk(r|jdk(r|j dtt fvrz|j dt k(r,|j|_|j jn|j|_d|_ |j jt$y |jtjk(r=|jd vr.|j dtt$t fvr |j dt$k(r,|j|_|j jn|j dt k(r,|j|_|j jn|j dtk(rm|j|_|jd k(r|jj)dk(s0t*j-|js|j/y |jd k(r|j j|jr|j"rZt1|j"sE|j2jt5|jd t7|j& nN|j2jt5|j|j"t7|j& d|_d |_d |_d|_ y |jtjk(rL|jd k(r=|j dt k(r'd|_ |j jt8y |jtj:tj<fvr|j dt t8fvr|j dt8k(rXt1|js|j/y |j|_d|_ |j j|jrL|j@jtC|j|j2|j>d|_ g|_d|_y |xj|jz c_ y )z)Process next token from the token stream.r_rFT)rr_{)]ra}rbr^)rraraN)r!r"rz->)r!rDrEFr)"r"tokenizeNAMEstringrrrxrfryOPpoprrr{rrr}rqrrstriprrresetrrDrr8rNEWLINE ENDMARKERrErrB)r#tokens r add_tokenzDocStringParser.add_tokens2 JJ(-- '  2 22 2*, JJ  1 2 JJ(++ % # 2"55 JJNN !D DJ JJ  1 2 ZZ^2 2 JJNN  JJ(++ % / 2*,    ,  JJ  0 1 JJ(++ % / 2"44    ,  JJNN  JJ(++ % # 2"55 ,,DM!D  JJ  1 2 JJ(++ % # 2#68K"LLzz"~!44 $ 0 0   $ 0 0 !D  JJ  4 5 JJ(++ % * 2#%;=PQRzz"~!77#'#3#3   B#66 $ 0 0   B#66 $ 0 0 LLC'D,<,<,B,B,D,J&,,T]];JJL||s"  }}==t}})EII$$DMMd4K[K[F\]II$$!%T]]DQUQaQaLb DM DM#D !D  ZZ8;; &5<<4+?DJJrNV`D`!D  JJ  0 1ZZH,,h.@.@A AdjjQSn  Y G zz"~!33$T%5%56JJL $ 0 0 #%   zz&&T%7%7diiRVR_R_`# DI!DM    , rcFtg|_g|_d|_d|_y)NFrF)rxrrDrrr*s rrzDocStringParser.reset7s! \   rcNdddfd t|jfdS)z:Return sorted copy of the list of signatures found so far.c@tfd|jDS)Nc3<K|]}|jk(ywr )r!)rTxr!s rrVzBDocStringParser.get_signatures..has_arg..As>~!qvv~~s)anyrD)r! signatures` rhas_argz/DocStringParser.get_signatures..has_arg@s>y~~>> >rc,d|xr d|S)Nz*argsz**kwargsr@)rrs r args_kwargsz3DocStringParser.get_signatures..args_kwargsCs7I.Q7:y3Q Qrc|rdSdS)NrOrr@)rrs rz0DocStringParser.get_signatures..Gs+a.Q5Oa5Or)key)r!r6rrBr9r8)rrBr9r8)sortedr)r#rrs @@rget_signatureszDocStringParser.get_signatures=s" ? Rdoo+OPPrN)rr6r9r:)rztokenize.TokenInfor9r:)r9r:)r9zlist[FunctionSig])r<r=r>r?r$rrrr@rrrrs5 0A-F Qrrct|tr|syt|}tjt j 5 t j tj|jdj}|D]}|j| ddd|j}dd}|Dcgc] }||s |c}S#t$r YdddywxYw#1swYMxYwcc}w)a=Convert function signature to list of FunctionSig Look for function signatures of function in docstring. Signature is a string of the format () -> or perhaps without the return type. Returns empty list, when no signature is found, one signature in typical case, multiple signatures, if docstring specifies multiple signatures for overload functions. Return None if the docstring is empty. Arguments: * docstr: docstring * name: name of function for which signatures are to be found Nzutf-8ct|jt|jDchc]}|jc}k(Scc}w)z1return true if function argument names are unique)rWrDr!)rtros ris_unique_argsz0infer_sig_from_docstring..is_unique_argsgs4388}$B#SXX$B CCC$BsA )rtrBr9r8)r3r6r contextlibsuppressr TokenErrorioBytesIOencodereadlinerIndentationErrorr)docstrr!rtokensrsigsrrts rinfer_sig_from_docstringrJs vs # D !E   X00 1 &&rzz&--2H'I'R'RSF&  2    !DD  74C>##6C4 77   2 1   2 1 8s7C*AC> C6 C6 C'C*&C''C**C3cFtd|zd}|r|djSgS)zXConvert signature in form of "(self: TestClass, arg0: str='ada')" to List[TypedArgList].stubr)rrD)rrets r!infer_arg_sig_from_anon_docstringros( "6F?F ;C 1v{{ Irc>t||}|r|djSy)zWConvert signature in form of "func(self: TestClass, arg0) -> int" to their return type.rN)rrE)rr!rs r!infer_ret_type_sig_from_docstringrws" "64 0C 1v rc|jDcgc]5}|jjds#d|jz7}}tdj |dScc}w)zSConvert signature in form of "(self: TestClass, arg0) -> int" to their return type.r_rrF) splitlinesrr)rrg)rlineliness r&infer_ret_type_sig_from_anon_docstringrs[/5/@/@/B c/BtdjjlF]F]^aFbVdjjl "/BE c ,RWWU^V DD ds $A*A*ctjd|}|sy|jd}|jdd}|jd}|j s|ggfS|jdDcgc]}|j }}g}g}d}|t |krk||j d sd ||vrnO|j||jd |dz }||dz jd rn|t |krk|t |krO||}|j d }|jd d}|j||dz }|t |krO|||fScc}w) zSplit function signature into its name, positional an optional arguments. The expected format is "func_name(arg, opt_arg=False)". Return the name of function and lists of positional and optional argument names. z([.a-zA-Z0-9_]+)\(([^)]*)\)NrO.rrPrrrr^z[]) rergroupsplitrrWr)rfrstriprL) rtmr! arg_stringrorD positionaloptionalis rparse_signaturerst /5A  771:D ::c?2 DJ    R|#-#3#3C#8 9#8CCIIK#8D 9JH A c$i- 7  c "cT!Wn $q'..-. Q A;   $  c$i- c$i-1giioiinQ Q c$i- X %%% :s8E2cg}|j||D]9}|jdr|j|&|j|d;ddj|d}|j dd}|S)zNBuild function signature from lists of positional and optional argument names.r&z=...r_r`raz(self)rF)extendr)rfrgreplace)rrrDrorts rbuild_signaturersu!#DKK  >>#  KK  KK3%t %  diio a C ++h #C Jrcg}g}|D]}|j}tjd|}|s,|jddj}t |}|s\|\}}} |j ddk7r|j |t|| f|j |t|| ft|t|fS)ztParse all signatures in a given reST document. Return lists of found signatures for functions and classes. z,\.\. *(function|method|class) *:: *[a-zA-Z_]z::rOclass) rrrrrrrfrr) rr class_sigsrrrtparsedr!fixedrs rparse_all_signaturesrs DJzz| HHDd K **T"1%++-C$S)F(.%eX771:(KKuh'G HI%%t_UH-M&NO $< + ++rci}|D]&\}}|j|gj|(g}|jD]3\}}tt |dk(s|j||df5t |S)z-Remove names with duplicate found signatures.rOr) setdefaultrfitemsrWsetr)rsig_mapr!rtresult name_sigss rfind_unique_signaturesrs}.0G c4$++C0F"==?i s9~ ! # MM41. /+ &>rcb|syd}tj||}|r|jdSdS)agCheck for Google/Numpy style docstring type annotation for a property. The docstring has the format ": ". In the type string, we allow the following characters: * dot: because sometimes classes are annotated using full path * brackets: to allow type hints like List[int] * comma/space: things like Tuple[int, int] Nz^([a-zA-Z0-9_, \.\[\]]*): rO)rrr)rtest_strrs rinfer_prop_type_from_docstringrs4 ,H 6"A1771:$$r)rr6r9r8)rr7r!r6r9zlist[FunctionSig] | None)rr6r9rC)rr6r!r6r9r7)rr6r9r7)rtr6r9z'tuple[str, list[str], list[str]] | None)r Sequence[str]rrr9r6)rrr9ztuple[list[Sig], list[Sig]])rz Sequence[Sig]r9z list[Sig])rr7r9r7)/r? __future__rrrrdrrtypingrrrrrr r typing_extensionsr r mypy.utilrhr6r rwcompilerrrrrBrxryr{r}rrrrrrrrrrrrrr@rrrs #  [[[5S/Z!"**TU%U bjj!>? e?)$$NK *K ^ EUUU !!EEdQdQN"8JE "&J ,.  %r