KiD dZddlZddlZddlZddlZddlmZddlm Z m Z m Z m Z m Z mZmZmZmZdZdej$dej$fdZd edej*efd Zej.d ej0 Zej.d Zej.dZej.dZej.dZej.dZGddZGddeZ GddeZ!Gdde Z"Gdde Z#Gdde Z$Gdde$Z%Gd d!e!Z&Gd"d#eZ'ge"d$d%e"d&d%e"d'd%e"d(d%e"d)d*e"d+d*e"d,d*e"d-d*e"d.d/e"d0d/e#d1d2e#d3d2e#d4d5e#d6d5e"d7d8e"d9d8e$d:d;e$de%d?d>e'd@dAe'dBdAedCdDedEdDedFdGedHdGedIdJedKdJedLdMedNdMe&dOdPZ(GdQdRZ)dSej*ede fdTZ*ejVdUfdVe dWedXedefdYZ,y)[z_Numpydoc-style docstring parsing. :see: https://numpydoc.readthedocs.io/en/latest/format.html N)dedent) DocstringDocstringDeprecatedDocstringExample DocstringMetaDocstringParamDocstringRaisesDocstringReturnsDocstringStyleRenderingStyleiterablereturncztj|\}}t|dtj|||S)N) fillvalue) itertoolsteenext zip_longest)rendleftrights e/home/jay/workspace/scripts/.codegraph-venv/lib/python3.12/site-packages/docstring_parser/numpydoc.py _pairwisers3--)KD%  u <<stringcD|j}t|dkDr|Sy)Nr)striplen)rs r _clean_strr s \\^F 6{Q rz ^[^\s].*$flagsz(^(?P.*?)(?:\s*:\s*(?P.*?))?$z)(?P.*?)(?:, optional|\(optional\))$zI(?P.*?)(?:, default|\(default\))(?: | |=| = |= |: |)*(?P.*)$z`(?(?:['\"]).*?(?:['\"])|[\w\-\.]*\w)z(^(?:(?P.*?)\s*:\s*)?(?P.*?)$cdeZdZdZdededdfdZedefdZdedeje fd Z y) SectionaNumpydoc section parser. :param title: section title. For most sections, this is a heading like "Parameters" which appears on its own line, underlined by en-dashes ('-') on the following line. :param key: meta key string. In the parsed ``DocstringMeta`` instance this will be the first element of the ``args`` attribute list. titlekeyrNc ||_||_yN)r%r&)selfr%r&s r__init__zSection.__init__Is rcXdt|jz}d|jd|dS)zRegular expression pattern matching this section's header. This pattern will match this instance's ``title`` attribute in an anonymous group. -z^(z)\s*?\nz\s*$)rr%)r)dashess r title_patternzSection.title_patternMs/s4::&TZZLxt44rtextc#RKt|jgt|yw)zParse ``DocstringMeta`` objects from the body of this section. :param text: section body text. Should be cleaned with ``inspect.cleandoc`` before parsing. ) descriptionN)rr&r )r)r/s rparsez Section.parseWs TXXJJt4DEEs%') __name__ __module__ __qualname____doc__strr*propertyr.TIterablerr2rrr$r$?s[c5s55F#F!**]";Frr$cNeZdZdZdededefdZdedejefdZ y) _KVSectionzBase parser for numpydoc sections with key-value syntax. E.g. sections that look like this: key value key2 : type values can also span... ... multiple lines r&valuercyr(r;r)r&r>s r _parse_itemz_KVSection._parse_itemks rr/c#Kttj|D]d\}}|j}||j nd}|||}|j |j tj|fyw)N)r&r>) rKV_REGEXfinditerrstartrAgroupinspectcleandoc)r)r/match next_matchrErr>s rr2z_KVSection.parsens!*8+<+*""$DCsOE""KKM)9)9%)@#   sBB N) r3r4r5r6r7rrAr9r:r2r;rrr=r=`s= s 3 = #!**]";rr=c&eZdZdZedefdZy)_SphinxSectionzBase parser for numpydoc sections with sphinx-style syntax. E.g. sections that look like this: .. title:: something possibly over multiple lines rc"d|jdS)Nz ^\.\.\s*(z)\s*::)r%r)s rr.z_SphinxSection.title_patternsDJJrctj|}dx}x}x}}||jd}|jd}|htj|}||jd}d}nd}tj|} | $d}| jd}| jd}t |dkDr*|(t j|} | | jd}t|j|gt|||||S)NnametypeTFr>r)argsr1arg_name type_name is_optionaldefault) PARAM_KEY_REGEXrIrFPARAM_OPTIONAL_REGEXPARAM_DEFAULT_REGEXrPARAM_DEFAULT_REGEX_IN_DESCsearchr r&r ) r)r&r>rIrUrVrWrXoptional_match default_matchs rrAzParamSection._parse_items%%c*7;;;9;{W  {{6*H F+I$!5!;!;I!F!- . 4 4V go7>>uEM('--g6((H%"5)#   rN)r3r4r5r6r7r rAr;rrrPrPs!" s" 3" >" rrPc$eZdZdZdededefdZy) RaisesSectionzParser for numpydoc raises sections. E.g. any section that looks like this: ValueError A description of what might raise ValueError r&r>rcrt|j|gt|t|dkDr|SdS)Nr)rTr1rV)r r&r rr@s rrAzRaisesSection._parse_items>((C"5) X\c  04  rN)r3r4r5r6r7r rAr;rrraras! s 3 ? rrac(eZdZdZdZdededefdZy)ReturnsSectionzParser for numpydoc returns sections. E.g. any section that looks like this: return_name : type A description of this returned value another_type Return names are optional, types are required Fr&r>rctj|}|#|jd}|jd}nd}d}t|jgt |||j |S)NrRrS)rTr1rV is_generator return_name)RETURN_KEY_REGEXrIrFr r&r rf)r)r&r>rIrgrVs rrAzReturnsSection._parse_itemsk &&s+  ++f-K F+IKI(("5)**#   rN)r3r4r5r6rfr7r rAr;rrrdrds)L s 3 3C rrdceZdZdZdZy) YieldsSectionz0Parser for numpydoc generator "yields" sections.TN)r3r4r5r6rfr;rrrjrjs :Lrrjc:eZdZdZdedej efdZy)DeprecationSectionz3Parser for numpydoc "deprecation warning" sections.r/rc#K|jddddgz^}}}|ttj|}t |j g|t|yw)N r)sepmaxsplit)rTr1version)splitr rGrHrr&)r)r/rqdesc_s rr2zDeprecationSection.parsesb JJ4!J<d|K  g..t45D!((z'7J  sA!A#N) r3r4r5r6r7r9r:rr2r;rrrlrls"= # !**-@"A rrlc:eZdZdZdedej efdZy)ExamplesSectionaParser for numpydoc examples sections. E.g. any section that looks like this: >>> import numpy.matlib >>> np.matlib.empty((2, 2)) # filled with random data matrix([[ 6.76425276e-320, 9.79033856e-307], # random [ 7.39337286e-309, 3.22135945e-309]]) >>> np.matlib.empty((2, 2), dtype=int) matrix([[ 6600475, 0], # random [ 6586976, 22740995]]) r/rc#Kt|jj}|rg}g}|r8|djdsn#|j |j d|r8|r8|djdrn#|j |j d|r8t |jg|rdj|nddj||ryyw)zParse ``DocstringExample`` objects from the body of this section. :param text: section body text. Should be cleaned with ``inspect.cleandoc`` before parsing. rz>>>rnN)snippetr1) rr splitlines startswithappendpoprr&join)r)r/lines snippet_linesdescription_liness rr2zExamplesSection.parses t ""$//1M " Qx**51$$UYYq\28&&u-!((16# 4A -0t II&78 sA'C&*9C&$?C&$C&N) r3r4r5r6r7r9r:rr2r;rrrvrvs# #!**]";rrv ParametersparamParams ArgumentsArgsOther Parameters other_paramz Other ParamszOther Argumentsz Other ArgsReceivesreceivesReceiveRaisesraisesRaiseWarnswarnsWarn Attributes attribute AttributeReturnsreturnsReturnYieldsyieldsYieldExamplesexamplesExampleWarningswarningsWarningzSee Alsosee_alsoRelatedNotesnotesNote References references Reference deprecated deprecationceZdZdZd dej ej eeffdZ dZ defdZ dej ed e fd Z y) NumpydocParserz%Parser for numpydoc-style docstrings.Nsectionsc|xst}|Dcic]}|j|c}|_|jycc}w)z[Setup sections. :param sections: Recognized sections or None to defaults. N)DEFAULT_SECTIONSr%r_setup)r)rss rr*zNumpydocParser.__init__Cs7 //-56!6  7s<ctjdjd|jj Dtj |_y)N|c34K|]}|jywr()r.).0rs r z(NumpydocParser._setup..NsF!aooFsr!)recompiler}rvaluesM titles_rerNs rrzNumpydocParser._setupLs8 IIFt}}/C/C/EF F$$ rsectioncV||j|j<|jy)zLAdd or replace a section. :param section: The new section. N)rr%r)r)rs r add_sectionzNumpydocParser.add_sectionRs (/ gmm$ rr/rcLttj}|s|Stj|}|j j |}|r'|d|j}||jd}n|}d}|jdd}|dxsd|_ t|dkDrN|dxsd}|jd|_ |jd|_|jxsd|_t#|j j%|D]\}}t'd|j)D} |j*| } |j-} ||jnd} |j.j1| j3|| | |S) zaParse the numpy-style docstring into its components. :returns: parsed docstring )styleNrnrrz c3&K|] }|| ywr(r;)rgs rrz'NumpydocParser.parse..|sDqamDs)rr NUMPYDOCrGrHrr]rErrshort_descriptionrrzblank_after_short_descriptionendswithblank_after_long_descriptionrlong_descriptionrrDrgroupsrrmetaextendr2) r)r/retrI desc_chunk meta_chunkpartslong_desc_chunk nextmatchr%factoryrErs rr2zNumpydocParser.parse[s n556J%%%d+ o .Jekkmo.JJJ  q) %a 0D u:>#Ahn"O0?0J0J1C -0?/G/G/OC ,#2#8#8#:#BdC )$..*A*A**M N B E9DELLNDDEmmE*GIIKE'0'<)//#$C HHOOGMM*U3*?@ A B rr()r3r4r5r6r9OptionalDictr7r$r*rrrr2r;rrrr@sS/AFF3<,@!A 7*!**S/*i*rrr/c4tj|S)zYParse the numpy-style docstring into its components. :returns: parsed docstring )rr2)r/s rr2r2s   ! !$ ''rz docstringrendering_styleindentc   dtjtttff fd dt dtj tjf fd }g |jr j|j|jr jd|jrd}|jjr|d|jjz }|jjr%|jjj}ng}d } j|j|g|z|j r j|j |j"r jd|d |j$xsgDcgc]}|j&d d k(s|c}|d |j$xsgDcgc]}|j&d dk(r|c}|d|j(xsgDcgc]}|j*s|c}|d|j(xsgDcgc]}|j*s|c}|j,rU|j(sI|j,} j|rdnd jdt/ dz ||d|j$xsgDcgc]}|j&d dk(r|c}|d|j$xsgDcgc]}|j&d dk(r|c}|d|j0xsgDcgc]}|j&d dk(s|c}|d|j0xsgDcgc]}|j&d dk(s|c}t/|j2d kDr jd jd jd|j2D]Q} | j4r j| j4| js7 j| jS|j6D]} t9| t:tttt<fr) jd j| j&d j?ddjA jdt/| j&d z| js j| jd j Scc}wcc}wcc}wcc}wcc}wcc}wcc}wcc}w)aRender a parsed docstring into docstring text. :param docstring: parsed docstring representation :param rendering_style: the style to render docstrings :param indent: the characters used as indentation in the docstring string :returns: docstring text onecZt|tr |j}nt|tr |j}nd}|j r|r|d|j z }n|j r |j }n|sd}t|trA|j dvr|d|j z }n |js|j dk(r|dz }|jrBdj|g|jjz}j|yj|y)Nz : r)NNonez , default=rz , optionalrn) isinstancer rUr rgrVrXrWr1r}ryr{)rheadbodyrrs r process_onezcompose..process_ones c> *< *{{.0*S[[M22CKK6$9 $ ??x=%%tfs/I/I/K&KLD LL  LL rrRrTc|rRjdj|jdtdz|D] }| yy)Nrr,)r{r)rRrTargrrs r process_sectzcompose..process_sectsS  LL  LL  LLs59~- . !C  ! rrz.. deprecated:: rnrrrrrrrr,rrrrrrrrrrz--------rt)!r9Unionr r r r7ListAnyrr{rrrqr1ryr}rrparamsrT many_returnsrfrrrrrxrrrrreplacer%) rrrrfirstrestroitemrexamplerrrs ` @@rcomposers WW^%5F G@!3!affQUUm!E"" Y001.. R!  ( ( q..6678 8E  , ,((44??ADD6(m SXXugn-.!! Y//0-- R#**0bL$DIIaLG4KL "((.B yy|{*  "..4" $$  #006BL$$:K:KL !7!7 X)4 S3uRy>)*C"((.B yy|z)  "((.B yy|},  #**0bM$DIIaLH4LM #**0bL$DIIaLG4KL  9  " R Z  Z  )) 2G W__-"" W001  2 +  #      R TYYq\))#r288:; S3tyy|,,-    LL)) *%+( 99U u M    M   N MsH T. 8T. T3 T8 T= T= U U U U 9U U r()-r6rGrrtypingr9textwraprcommonrrrrr r r r r r:rr7rr rrrCrYrZr[r\rhr$r=rLrPrardrjrlrvrrr2COMPACTrr;rrrs     = == sqzz# 2::l"$$ /"**HI!rzz"NO!bjjP)bjjg2::IJFFB0 /W /- :- `  J   Z <N    #g#L w' 7# g& !  #]3  / "M2 }- Z( J' (H% '8$ '7# &'" {+  k*! "9i(# $8Y'% &(H%' ('8$) *J ++ ,Iz*- . J #/ 0 Iz"1 2 J #3 4 Iz"5 6 GW7 8 FG9 : L,'; < K&= >|]3? FEEP( 3(I('5&<&< hh$h  h  hr