o 6WjD @sdZddlZddlZddlZddlZddlmZddlm Z m Z m Z m Z m Z mZmZmZmZd^dejdejfdd Zd edejefd d Zejd ejdZedZedZedZedZedZGdddZGdddeZ GdddeZ!Gddde Z"Gddde Z#Gddde Z$Gd d!d!e$Z%Gd"d#d#e!Z&Gd$d%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"d0d1e"d2d1e#d3d4e#d5d4e#d6d7e#d8d7e"d9d:e"d;d:e$dd=e%d?d@e%dAd@e'dBdCe'dDdCedEdFedGdFedHdIedJdIedKdLedMdLedNdOedPdOe&dQdRZ(GdSdTdTZ)dUejede fdVdWZ*ej+dXfdYe dZed[edefd\d]Z,dS)_z_Numpydoc-style docstring parsing. :see: https://numpydoc.readthedocs.io/en/latest/format.html N)dedent) DocstringDocstringDeprecatedDocstringExample DocstringMetaDocstringParamDocstringRaisesDocstringReturnsDocstringStyleRenderingStyleiterablereturncCs(t|\}}t|dtj|||dS)N) fillvalue) itertoolsteenext zip_longest)r endleftrightrh/home/esfera/Documents/content_generation/venv/lib/python3.10/site-packages/docstring_parser/numpydoc.py _pairwises rstringcCs|}t|dkr |SdS)Nr)striplen)rrrr _clean_strs rz ^[^\s].*$flagsz(^(?P.*?)(?:\s*:\s*(?P.*?))?$z)(?P.*?)(?:, optional|\(optional\))$zI(?P.*?)(?:, default|\(default\))(?: | |=| = |= |: |)*(?P.*)$z`(?(?:['\"]).*?(?:['\"])|[\w\-\.]*\w)z(^(?:(?P.*?)\s*:\s*)?(?P.*?)$c@sPeZdZdZdededdfddZedefdd Zd edej e fd d 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. titlekeyrNcCs||_||_dSN)r!r")selfr!r"rrr__init__Is zSection.__init__cCs"dt|j}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$dashesrrr title_patternMszSection.title_patterntextccst|jgt|dVdS)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)rrrparseWsz Section.parse) __name__ __module__ __qualname____doc__strr%propertyr(TIterablerr+rrrrr ?s   r c@s>eZdZdZdededefddZdedejefdd Z d S) _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"valuercCsdSr#rr$r"r5rrr _parse_itemksz_KVSection._parse_itemr)ccs`tt|D]%\}}|}|dur|nd}|||}|j|t|dVqdS)N)r"r5) rKV_REGEXfinditerrstartr7groupinspectcleandoc)r$r)match next_matchr:rr5rrrr+ns  z_KVSection.parseN) r,r-r.r/r0rr7r2r3r+rrrrr4`s r4c@s"eZdZdZedefddZdS)_SphinxSectionzBase parser for numpydoc sections with sphinx-style syntax. E.g. sections that look like this: .. title:: something possibly over multiple lines rcCsd|jdS)Nz ^\.\.\s*(z)\s*::r!r$rrrr(sz_SphinxSection.title_patternN)r,r-r.r/r1r0r(rrrrr@xsr@c@&eZdZdZdededefddZdS) 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"r5rc Cst|}d}}}}|durG|d}|d}|durGt|}|dur0|d}d}nd}t|} | durGd}| d}| d}t|dkr_|dur_t|} | dur_| d}t|j |gt |||||dS)NnametypeTFr5r)argsr*arg_name type_name is_optionaldefault) PARAM_KEY_REGEXr>r;PARAM_OPTIONAL_REGEXPARAM_DEFAULT_REGEXrPARAM_DEFAULT_REGEX_IN_DESCsearchrr"r) r$r"r5r>rHrIrJrKoptional_match default_matchrrrr7s8          zParamSection._parse_itemN)r,r-r.r/r0rr7rrrrrDs rDc@rC) RaisesSectionzParser for numpydoc raises sections. E.g. any section that looks like this: ValueError A description of what might raise ValueError r"r5rcCs,t|j|gt|t|dkr|dSddS)Nr)rGr*rI)r r"rrr6rrrr7szRaisesSection._parse_itemN)r,r-r.r/r0r r7rrrrrSsrSc@s*eZdZdZdZdededefddZdS) 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"r5rcCsLt|}|dur|d}|d}nd}d}t|jgt|||j|dS)NrErF)rGr*rI is_generator return_name)RETURN_KEY_REGEXr>r;r r"rrU)r$r"r5r>rVrIrrrr7s   zReturnsSection._parse_itemN)r,r-r.r/rUr0r r7rrrrrTs rTc@seZdZdZdZdS) YieldsSectionz0Parser for numpydoc generator "yields" sections.TN)r,r-r.r/rUrrrrrXsrXc@(eZdZdZdedejefddZdS)DeprecationSectionz3Parser for numpydoc "deprecation warning" sections.r)rccsP|jdddddg^}}}|durtt|}t|jg|t|dVdS)N r)sepmaxsplit)rGr*version)splitrr<r=rr")r$r)r^desc_rrrr+s zDeprecationSection.parseN) r,r-r.r/r0r2r3rr+rrrrrZsrZc@rY)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)rccst|}|rOg}g}|r#|ddsn ||d|s|r7|ddr-n ||d|s%t|jg|rBd|ndd|dV|s dSdS)zParse ``DocstringExample`` objects from the body of this section. :param text: section body text. Should be cleaned with ``inspect.cleandoc`` before parsing. rz>>>r[N)snippetr*) rr splitlines startswithappendpoprr"join)r$r)lines snippet_linesdescription_linesrrrr+s* zExamplesSection.parseN) r,r-r.r/r0r2r3rr+rrrrrbs rb ParametersparamParams ArgumentsArgsOther Parameters other_paramz Other ParamszOther Argumentsz Other ArgsReceivesreceivesReceiveRaisesraisesRaiseWarnswarnsWarn Attributes attribute AttributeReturnsreturnsReturnYieldsyieldsYieldExamplesexamplesExampleWarningswarningsWarningzSee Alsosee_alsoRelatedNotesnotesNote References references Reference deprecated deprecationc@s^eZdZdZddejejeeffddZ ddZ defd d Z d ejed e fd dZ dS)NumpydocParserz%Parser for numpydoc-style docstrings.NsectionscCs$|pt}dd|D|_|dS)z[Setup sections. :param sections: Recognized sections or None to defaults. cSsi|]}|j|qSrrA.0srrr Isz+NumpydocParser.__init__..N)DEFAULT_SECTIONSr_setup)r$rrrrr%Cs zNumpydocParser.__init__cCs,tjddd|jDtjd|_dS)N|css|]}|jVqdSr#)r(rrrr Nsz(NumpydocParser._setup..r)recompilerhrvaluesM titles_rerBrrrrLs zNumpydocParser._setupsectioncCs||j|j<|dS)zLAdd or replace a section. :param section: The new section. N)rr!r)r$rrrr add_sectionRs  zNumpydocParser.add_sectionr)rc Cs$ttjd}|s |St|}|j|}|r(|d|}||d}n|}d}|dd}|dp7d|_ t |dkrX|dpDd}| d|_ | d|_|pVd|_t|j|D]/\}}tdd |D} |j| } |} |dur|nd} |j| || | q`|S) zaParse the numpy-style docstring into its components. :returns: parsed docstring )styleNr[rrz css|] }|dur|VqdSr#r)rgrrrr|sz'NumpydocParser.parse..)rr NUMPYDOCr<r=rrPr:r_short_descriptionrreblank_after_short_descriptionendswithblank_after_long_descriptionrlong_descriptionrr9rgroupsrrmetaextendr+) r$r)retr> desc_chunk meta_chunkpartslong_desc_chunk nextmatchr!factoryr:rrrrr+[s4        zNumpydocParser.parser#)r,r-r.r/r2OptionalDictr0r r%rrrr+rrrrr@s    rr)cCs t|S)zYParse the numpy-style docstring into its components. :returns: parsed docstring )rr+)r)rrrr+s r+z docstringrendering_styleindentc sdtjtttfffdd dtdtjtjffdd }g|jr+ |j|j r3 d|j rbd }|j j rE|d |j j 7}|j j rP|j j }ng}d } ||g||jrk |j|jrs d|d d d|jp|gD|ddd|jpgD|ddd|jpgD|ddd|jpgD|jr|js|j} |rdnd dtd||ddd|jpgD|ddd|jpgD|ddd|jpgD|ddd|jpgDt|jdkr. d d  d!|jD]}|jr" |j|j r, |j q|jD]9} t| tttttfr@q1 d | jdd"d dt| jd| j ri | j q1d 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 onecst|tr |j}n t|tr|j}nd}|jr"|r"|d|j7}n |jr)|j}n|s-d}t|trL|jdvr@|d|j7}n |jsH|jdkrL|d7}|jrdd |g|j } |dS |dS)Nz : r)NNonez , default=rz , optionalr[) isinstancerrHr rVrIrKrJr*rhrdrf)rheadbody)rrrr process_ones(     zcompose..process_onerErGcsH|r d|dtd|D]}|qdSdS)Nrr&)rfr)rErGarg)rrrr process_sects   zcompose..process_sectrz.. deprecated:: r[rlcSg|] }|jddkr|qS)rrmrGritemrrr zcompose..r|cSr)rr}rrrrrr rcSsg|]}|js|qSrrUrrrrrs rcSsg|]}|jr|qSrrrrrrrsr&rrscSr)rrtrrrrrrrrqcSr)rrrrrrrrr rrvcSr)rrwrrrrrrrrycSr)rrzrrrrrrrrrz--------ra) r2Unionrr r r0ListAnyrrfrrr^r*rdrhrrparams many_returnsrrrwrrcrrrrrGreplacer!) rrrrfirstrestr\rexamplerr)rrrrcomposes                     rr#)-r/r<rrtypingr2textwraprcommonrrrrrr r r r r3rr0rrrrr8rLrMrNrOrWr r4r@rDrSrTrXrZrbrrr+COMPACTrrrrrs ,     ! 0&     #H