㎒j#G dZddlZddlZddlZddlZddlmZddlm Z m Z m Z m Z m Z mZmZmZmZdZdejdejfdZd edejefd Zejd ej Zejd ZejdZejdZejdZejdZGddZGddeZ 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)dSejede fdTZ*ej+dUfdVe dWedXedefdYZ,dS)[z_Numpydoc-style docstring parsing. :see: https://numpydoc.readthedocs.io/en/latest/format.html N)dedent) DocstringDocstringDeprecatedDocstringExample DocstringMetaDocstringParamDocstringRaisesDocstringReturnsDocstringStyleRenderingStyleiterablereturnc~tj|\}}t|dtj|||S)N) fillvalue) itertoolsteenext zip_longest)rendleftrights GC:\Projects\DSCons\.venv\Lib\site-packages\docstring_parser\numpydoc.py _pairwisers=-))KD%  u < < <<stringcX|}t|dkr|SdS)Nr)striplen)rs r _clean_strr s( \\^^F 6{{Q 4rz ^[^\s].*$flagsz(^(?P.*?)(?:\s*:\s*(?P.*?))?$z)(?P.*?)(?:, optional|\(optional\))$zI(?P.*?)(?:, default|\(default\))(?: | |=| = |= |: |)*(?P.*)$z`(?(?:['\"]).*?(?:['\"])|[\w\-\.]*\w)z(^(?:(?P.*?)\s*:\s*)?(?P.*?)$cheZdZdZdededdfdZedefdZdedej e fd Z dS) 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"||_||_dSN)r%r&)selfr%r&s r__init__zSection.__init__Is rcLdt|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_patternMs1s4:&4TZ444444rtextc#VKt|jgt|VdS)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.parseWs3 TXJJt4D4DEEEEEEEEr) __name__ __module__ __qualname____doc__strr*propertyr.TIterablerr2rrr$r$?sc5s555X5F#F!*]";FFFFFFrr$cLeZdZdZdededefdZdedejefdZ dS) _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&valuercdSr(r;r)r&r>s r _parse_itemz_KVSection._parse_itemks rr/c#JKtt|D]x\}}|}||nd}|||}||tj|VydS)N)r&r>) rKV_REGEXfinditerrstartrAgroupinspectcleandoc)r)r/match next_matchrErr>s rr2z_KVSection.parsens!*8+<+*""$$$DCsOE""KKMM)9%)@)@#       rN) r3r4r5r6r7rrAr9r:r2r;rrr=r=`sp s 3 =    #!*]";rr=c.eZdZdZedefdZdS)_SphinxSectionzBase parser for numpydoc sections with sphinx-style syntax. E.g. sections that look like this: .. title:: something possibly over multiple lines rcd|jdS)Nz ^\.\.\s*(z)\s*::r%r)s rr.z_SphinxSection.title_patterns.DJ....rN)r3r4r5r6r8r7r.r;rrrLrLxsE/s///X///rrLc&eZdZdZdededefdZdS) ParamSectionzParser for numpydoc parameter sections. E.g. any section that looks like this: arg_name arg_description arg_2 : type, optional descriptions can also span... ... multiple lines r&r>rc|t|}dx}x}x}}||d}|d}|~t|}||d}d}nd}t|} | ,d}| d}| d}t |dkr3|1t |} | | d}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>rIrVrWrXrYoptional_match default_matchs rrAzParamSection._parse_itemsL%%c**7;;;9;{W  {{6**H F++I$!5!;!;I!F!F!- . 4 4V < >go7>>uEEM('--g66(H%"5))#     rN)r3r4r5r6r7r rAr;rrrQrQsG" s" 3" >" " " " " " rrQc&eZdZdZdededefdZdS) RaisesSectionzParser for numpydoc raises sections. E.g. any section that looks like this: ValueError A description of what might raise ValueError r&r>rcxt|j|gt|t|dkr|ndS)Nr)rUr1rW)r r&r rr@s rrAzRaisesSection._parse_itemsB(C"5)) XX\\cct    rN)r3r4r5r6r7r rAr;rrrbrbsG s 3 ?      rrbc*eZdZdZdZdededefdZdS)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>rct|}|+|d}|d}nd}d}t|jgt |||j|S)NrSrT)rUr1rW is_generator return_name)RETURN_KEY_REGEXrIrFr r&r rg)r)r&r>rIrhrWs rrAzReturnsSection._parse_items~ &&s++  ++f--K F++IIKI("5))*#     rN)r3r4r5r6rgr7r rAr;rrreresOL s 3 3C      rreceZdZdZdZdS) YieldsSectionz0Parser for numpydoc generator "yields" sections.TN)r3r4r5r6rgr;rrrkrks::LLLrrkc8eZdZdZdedejefdZdS)DeprecationSectionz3Parser for numpydoc "deprecation warning" sections.r/rc#K|ddddgz^}}}|!ttj|}t |jg|t|VdS)N r)sepmaxsplit)rUr1version)splitr rGrHrr&)r)r/rrdesc_s rr2zDeprecationSection.parses JJ4!J<<d|K  g.t4455D!(z'7J7J        rN) r3r4r5r6r7r9r:rr2r;rrrmrmsD== # !*-@"A      rrmc8eZdZdZdedejefdZdS)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|}|rg}g}|rF|ddsn*||d|F|rF|ddrn*||d|Ft |jg|rd|ndd|V|dSdS)zParse ``DocstringExample`` objects from the body of this section. :param text: section body text. Should be cleaned with ``inspect.cleandoc`` before parsing. rz>>>roN)snippetr1) rr splitlines startswithappendpoprr&join)r)r/lines snippet_linesdescription_liness rr2zExamplesSection.parsesK t ""$$//11 M "  3Qx**511$$UYYq\\222 3 78&&u--!((1666 7# 4AK -000t II&788        rN) r3r4r5r6r7r9r:rr2r;rrrwrwsG  #!*]";rrw ParametersparamParams ArgumentsArgsOther Parameters other_paramz Other ParamszOther Argumentsz Other ArgsReceivesreceivesReceiveRaisesraisesRaiseWarnswarnsWarn Attributes attribute AttributeReturnsreturnsReturnYieldsyieldsYieldExamplesexamplesExampleWarningswarningsWarningzSee Alsosee_alsoRelatedNotesnotesNote References references Reference deprecated deprecationceZdZdZd dejejeeffdZ dZ defdZ dejed e fd Z dS) NumpydocParserz%Parser for numpydoc-style docstrings.Nsectionscb|pt}d|D|_|dS)z[Setup sections. :param sections: Recognized sections or None to defaults. ci|] }|j| Sr;rN.0ss r z+NumpydocParser.__init__..Is666!666rN)DEFAULT_SECTIONSr_setup)r)rs rr*zNumpydocParser.__init__Cs5 //66X666  rctjdd|jDtj|_dS)N|c3$K|] }|jV dSr()r.rs r z(NumpydocParser._setup..Ns$FF!aoFFFFFFrr!)recompiler~rvaluesM titles_rerOs rrzNumpydocParser._setupLsO IIFFt}/C/C/E/EFFF F F$   rsectioncL||j|j<|dS)zLAdd or replace a section. :param section: The new section. N)rr%r)r)rs r add_sectionzNumpydocParser.add_sectionRs# (/ gm$ rr/rcttj}|s|Stj|}|j|}|r9|d|}||d}n|}d}|dd}|dpd|_ t|dkrY|dpd}| d|_ | d|_|pd|_t#|j|D]\}}t'd|D} |j| } |} ||nd} |j| || | |S) zaParse the numpy-style docstring into its components. :returns: parsed docstring )styleNrorrz c3K|]}||V dSr(r;)rgs rrz'NumpydocParser.parse..|s"DDqammmmmDDr)rr NUMPYDOCrGrHrr^rErsshort_descriptionrr{blank_after_short_descriptionendswithblank_after_long_descriptionrlong_descriptionrrDrgroupsrrmetaextendr2) r)r/retrI desc_chunk meta_chunkpartslong_desc_chunk nextmatchr%factoryrErs rr2zNumpydocParser.parse[s n5666 J%%%%d++  o o.Jekkmmoo.JJJJ  q)) %a 0D u::>>#Ahn"O0?0J0J11C -0?/G/G/O/OC ,#2#8#8#:#:#BdC )$.*A*A**M*M N N B B E9DDELLNNDDDDDEmE*GIIKKE'0'<)//###$C HOOGMM*U3Y*?@@ A A A A rr()r3r4r5r6r9OptionalDictr7r$r*rrrr2r;rrrr@s//AF3<,@!A   7*!*S/*i******rrr/cDt|S)zYParse the numpy-style docstring into its components. :returns: parsed docstring )rr2)r/s rr2r2s    ! !$ ' ''rz docstringrendering_styleindentc  dtjtttff fd dt dtjtjf fd }g |jr |j|j r d|j r~d}|j j r|d|j j z }|j j r|j j }ng}d } ||g|z|jr |j|jr d|d d |jpgD|d d |jpgD|dd|jpgD|dd|jpgD|jr]|jsV|j} |rdnd dt+ dz ||dd|jpgD|dd|jpgD|dd|jpgD|dd|jpgDt+|jdkr d d d|jD]D}|jr |j|j r |j E|jD]} t5| t6tttt8fr1 d | jddd dt+| jdz| j r | j d  S) 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 onec&t|tr|j}nt|tr|j}nd}|jr|r|d|jz }n|jr|j}n|sd}t|tr.|jdvr|d|jz }n|js |jdkr|dz }|jrJd |g|j z} |dS |dS)Nz : r)NNonez , default=rz , optionalro) isinstancer rVr rhrWrYrXr1r~rzr|)rheadbodyrrs r process_onezcompose..process_onesI c> * * 
* * %{.002S[222 %CK6$9$9 $ ?  ==%%tfs/I/I/K/K&KLLD LL      LL     rrSrUc|red|dtdz|D]}|dSdS)Nrr,)r|r)rSrUargrrs r process_sectzcompose..process_sects  ! LL    LL    LLs59~~- . . . ! ! C     ! ! ! !rrz.. deprecated:: rorc4g|]}|jddk|S)rrrUritems r zcompose..(LLL$DIaLG4K4K4K4K4Krrc4g|]}|jddk|S)rrrrs rrzcompose..s3   y|{** ***rrc g|] }|j | Sr;rgrs rrzcompose..s1   $    rrc g|] }|j | Sr;rrs rrzcompose..s LLL$$:KLLLLrr,rrc4g|]}|jddk|S)rrrrs rrzcompose..s3   y|z)) )))rrc4g|]}|jddk|S)rrrrs rrzcompose.. s3   y|},, ,,,rrc4g|]}|jddk|S)rrrrs rrzcompose..s(MMM$DIaLH4L4L4L4L4Lrrc4g|]}|jddk|S)rrrrs rrzcompose..rrrrz--------ru) r9Unionr r r r7ListAnyrr|rrrrr1rzr~rrparams many_returnsrrrrryrrrrrUreplacer%) rrrrfirstrestrprexamplerrrs ` @@rcomposers+ W^%5F G@!3!afQUm!!!!!!!E"2 Y0111. R /!  ( 9 8.688 8E  , (4??AADDD6mm SXXugn--...!1 Y/000- RLLL)*0bLLL L  !(.B   L  !.4"   LLL)06BLLL !7 3XX)444 S3uRy>>)*** CL  !(.B   L  !(.B   LMM)*0bMMM LLL)*0bLLL  9 "" R Z    Z    ) 2 2G . W_---" 2 W0111++  #      R TYq\))#r2288::;;; S3ty|,,,---   + LL) * * * 99U  rr()-r6rGrrtypingr9textwraprcommonrrrrr r r r r r:rr7rr rrrCrZr[r\r]rir$r=rLrQrbrerkrmrwrrr2COMPACTrr;rrrs                        == ===== sqz# 2:l"$ / / /"*HII!rz"NOO!bjP)bjg2:IJJFFFFFFFFB0 / / / / /W / / /- - - - - :- - - `      J         Z   <N          #####g###L Lw'' L7## Lg&& L!!  L#]33  L// L"M22 L}-- LZ(( LJ'' M(H%% M'8$$ M'7## M&'"" L{++  Lk**! "N9i((# $N8Y''% &M(H%%' (M'8$$) *OJ +++ ,OIz**- . GJ ##/ 0 GIz""1 2 GJ ##3 4 GIz""5 6 GGW7 8 GFG9 : GL,''; < GK&&= >|]33? FEEEEEEEEP( 3(I(((('5&< hhh$h  h  hhhhhhr