
    hp>              	          S r SSKrSSKrSSKrSSKrSSKJr  SSKJ	r	J
r
JrJrJrJrJrJrJr  SYS\R$                  S\R$                  4S jjrS	\S\R*                  \   4S
 jr\R.                  " S\R0                  S9r\R.                  " S5      r\R.                  " S5      r\R.                  " S5      r\R.                  " S5      r " S S5      r " S S\5      r " S S\5      r  " S S\5      r! " S S\5      r" " S S\5      r# " S S\#5      r$ " S S \ 5      r% " S! S"\5      r&/ \!" S#S$5      P\!" S%S$5      P\!" S&S$5      P\!" S'S$5      P\!" S(S)5      P\!" S*S)5      P\!" S+S)5      P\!" S,S)5      P\!" S-S.5      P\!" S/S.5      P\"" S0S15      P\"" S2S15      P\"" S3S45      P\"" S5S45      P\!" S6S75      P\!" S8S75      P\#" S9S:5      P\#" S;S:5      P\$" S<S=5      P\$" S>S=5      P\&" S?S@5      P\&" SAS@5      P\" SBSC5      P\" SDSC5      P\" SESF5      P\" SGSF5      P\" SHSI5      P\" SJSI5      P\" SKSL5      P\" SMSL5      P\%" SNSO5      Pr' " SP SQ5      r(SR\S\	4SS jr)\RT                  ST4SU\	SV\SW\S\4SX jjr+g)Zz_Numpydoc-style docstring parsing.

:see: https://numpydoc.readthedocs.io/en/latest/format.html
    N)dedent   )		DocstringDocstringDeprecatedDocstringExampleDocstringMetaDocstringParamDocstringRaisesDocstringReturnsDocstringStyleRenderingStyleiterablereturnc                 t    [         R                  " U 5      u  p#[        US 5        [         R                  " X#US9$ )N)	fillvalue)	itertoolsteenextzip_longest)r   endleftrights       S/home/james-whalen/.local/lib/python3.13/site-packages/docstring_parser/numpydoc.py	_pairwiser      s/    --)KD  <<    stringc                 F    U R                  5       n [        U 5      S:  a  U $ g )Nr   )striplen)r   s    r   
_clean_strr       s     \\^F
6{Qr   z	^[^\s].*$flagsz(^(?P<name>.*?)(?:\s*:\s*(?P<type>.*?))?$z)(?P<type>.*?)(?:, optional|\(optional\))$z@(?<!\S)[Dd]efault(?: is | = |: |s to |)\s*(?P<value>[\w\-\.]*\w)z(^(?:(?P<name>.*?)\s*:\s*)?(?P<type>.*?)$c                   r    \ rS rSrSrS\S\SS4S jr\S\4S j5       rS	\S\	R                  \   4S
 jrSrg)Section3   ao  Numpydoc 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.
titlekeyr   Nc                     Xl         X l        g N)r&   r'   )selfr&   r'   s      r   __init__Section.__init__=   s    
r   c                 X    S[        U R                  5      -  nSU R                   SU S3$ )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*$)r   r&   )r*   dashess     r   title_patternSection.title_patternA   s/     s4::&TZZLxt44r   textc              #   L   #    [        U R                  /[        U5      S9v   g7f)zParse ``DocstringMeta`` objects from the body of this section.

:param text: section body text. Should be cleaned with
             ``inspect.cleandoc`` before parsing.
)descriptionN)r   r'   r    )r*   r2   s     r   parseSection.parseK   s      TXXJJt4DEEs   "$)r'   r&   )__name__
__module____qualname____firstlineno____doc__strr+   propertyr0   TIterabler   r5   __static_attributes__ r   r   r$   r$   3   s[    c    5s 5 5F# F!**]"; Fr   r$   c                   Z    \ rS rSrSrS\S\S\4S jrS\S\R                  \   4S jr
S	rg
)
_KVSectionT   zBase 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'   valuer   c                     g r)   rA   r*   r'   rE   s      r   _parse_item_KVSection._parse_item_   s    r   r2   c              #     #    [        [        R                  U5      5       Hb  u  p#UR                  5       nUb  UR	                  5       OS nXU nU R                  UR                  5       [        R                  " U5      S9v   Md     g 7f)N)r'   rE   )	r   KV_REGEXfinditerr   startrH   groupinspectcleandoc)r*   r2   match
next_matchrM   r   rE   s          r   r5   _KVSection.parseb   sz     !*8+<+<T+B!CEIIKE(2(>*""$DCsOE""KKM)9)9%)@ #  	 "Ds   BBrA   N)r7   r8   r9   r:   r;   r<   r   rH   r>   r?   r5   r@   rA   r   r   rC   rC   T   s=    s 3 = # !**]"; r   rC   c                   0    \ rS rSrSr\S\4S j5       rSrg)_SphinxSectionl   zBase parser for numpydoc sections with sphinx-style syntax.

E.g. sections that look like this:
    .. title:: something
        possibly over multiple lines
r   c                 "    SU R                    S3$ )Nz	^\.\.\s*(z)\s*::)r&   r*   s    r   r0   _SphinxSection.title_patternt   s    DJJ<v..r   rA   N)	r7   r8   r9   r:   r;   r=   r<   r0   r@   rA   r   r   rU   rU   l   s"     /s / /r   rU   c                   .    \ rS rSrSrS\S\S\4S jrSrg)	ParamSectiony   zParser 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'   rE   r   c           	         [         R                  U5      nS =n=pVUbS  UR                  S5      nUR                  S5      nUb.  [        R                  U5      nUb  UR                  S5      nSnOSnS n[	        U5      S:  a)  [
        R                  U5      n	U	b  U	R                  S5      n[        U R                  U/[        U5      UUUUS9$ )NnametypeTFr   rE   )argsr4   arg_name	type_nameis_optionaldefault)
PARAM_KEY_REGEXrQ   rN   PARAM_OPTIONAL_REGEXr   PARAM_DEFAULT_REGEXsearchr	   r'   r    )
r*   r'   rE   rQ   ra   rb   rc   optional_matchrd   default_matchs
             r   rH   ParamSection._parse_item   s    %%c*-1119{{6*HF+I$!5!;!;I!F!- . 4 4V <I"&K"'Ku:>/66u=M('--g6((H%"5)#
 	
r   rA   N)	r7   r8   r9   r:   r;   r<   r	   rH   r@   rA   r   r   r[   r[   y   s!    
s 
3 
> 
r   r[   c                   .    \ rS rSrSrS\S\S\4S jrSrg)	RaisesSection   zParser for numpydoc raises sections.

E.g. any section that looks like this:
    ValueError
        A description of what might raise ValueError
r'   rE   r   c                 h    [        U R                  U/[        U5      [        U5      S:  a  US9$ S S9$ )Nr   )r`   r4   rb   )r
   r'   r    r   rG   s      r   rH   RaisesSection._parse_item   s>    ((C"5) X\c
 	
 04
 	
r   rA   N)	r7   r8   r9   r:   r;   r<   r
   rH   r@   rA   r   r   rm   rm      s!    
s 
3 
? 
r   rm   c                   2    \ rS rSrSrSrS\S\S\4S jrSr	g	)
ReturnsSection   zParser 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'   rE   r   c                     [         R                  U5      nUb#  UR                  S5      nUR                  S5      nOS nS n[        U R                  /[        U5      UU R                  US9$ )Nr^   r_   )r`   r4   rb   is_generatorreturn_name)RETURN_KEY_REGEXrQ   rN   r   r'   r    ru   )r*   r'   rE   rQ   rv   rb   s         r   rH   ReturnsSection._parse_item   sk     &&s+++f-KF+IKI(("5)**#
 	
r   rA   N)
r7   r8   r9   r:   r;   ru   r<   r   rH   r@   rA   r   r   rr   rr      s)     L
s 
3 
3C 
r   rr   c                       \ rS rSrSrSrSrg)YieldsSection   z0Parser for numpydoc generator "yields" sections.TrA   N)r7   r8   r9   r:   r;   ru   r@   rA   r   r   rz   rz      s
    :Lr   rz   c                   D    \ rS rSrSrS\S\R                  \   4S jr	Sr
g)DeprecationSection   z3Parser for numpydoc "deprecation warning" sections.r2   r   c              #      #    UR                  SSS9S S /-   tp#nUb  [        [        R                  " U5      5      n[	        U R
                  /U[        U5      S9v   g 7f)N
r   )sepmaxsplit)r`   r4   version)splitr    rO   rP   r   r'   )r*   r2   r   desc_s        r   r5   DeprecationSection.parse   s_      JJ4!J<d|Kg..t45D!((z'7J
 	
s   AArA   N)r7   r8   r9   r:   r;   r<   r>   r?   r   r5   r@   rA   r   r   r}   r}      s"    =
# 
!**-@"A 
r   r}   c                   D    \ rS rSrSrS\S\R                  \   4S jr	Sr
g)ExamplesSection   a  Parser 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]])
r2   r   c              #   *  #    [        U5      R                  5       R                  5       nU(       a  / n/ nU(       aC  US   R                  S5      (       d  O)UR	                  UR                  S5      5        U(       a  MC  U(       aC  US   R                  S5      (       a  O)UR	                  UR                  S5      5        U(       a  MC  [        U R                  /U(       a  SR                  U5      OSSR                  U5      S9v   U(       a  M  gg7f)zParse ``DocstringExample`` objects from the body of this section.

:param text: section body text. Should be cleaned with
             ``inspect.cleandoc`` before parsing.
r   z>>>r   N)snippetr4   )	r   r   
splitlines
startswithappendpopr   r'   join)r*   r2   linessnippet_linesdescription_liness        r   r5   ExamplesSection.parse   s      t""$//1M "Qx**511$$UYYq\2 % 8&&u--!((16 % #
4A		-0t II&78  es   A;D?AD	ADDrA   N)r7   r8   r9   r:   r;   r<   r>   r?   r   r5   r@   rA   r   r   r   r      s#    
# !**]"; r   r   
ParametersparamParams	ArgumentsArgsOther Parametersother_paramzOther ParamszOther Argumentsz
Other ArgsReceivesreceivesReceiveRaisesraisesRaiseWarnswarnsWarn
Attributes	attribute	AttributeReturnsreturnsReturnYieldsyieldsYieldExamplesexamplesExampleWarningswarningsWarningzSee Alsosee_alsoRelatedNotesnotesNote
References
references	Reference
deprecateddeprecationc                       \ rS rSrSrSS\R                  \R                  \\	4      4S jjr
S rS\	4S jrS	\S
\4S jrSrg)NumpydocParseri-  z%Parser for numpydoc-style docstrings.Nsectionsc                     U=(       d    [         nU Vs0 s H  o"R                  U_M     snU l        U R                  5         gs  snf )zKSetup sections.

:param sections: Recognized sections or None to defaults.
N)DEFAULT_SECTIONSr&   r   _setup)r*   r   ss      r   r+   NumpydocParser.__init__0  s9    
 //-56X!X6 7s   Ac                     [         R                  " SR                  S U R                  R	                  5        5       5      [         R
                  S9U l        g )N|c              3   8   #    U  H  oR                   v   M     g 7fr)   )r0   ).0r   s     r   	<genexpr>(NumpydocParser._setup.<locals>.<genexpr>;  s     F/E!oo/Es   r!   )recompiler   r   valuesM	titles_rerX   s    r   r   NumpydocParser._setup9  s8    IIFt}}/C/C/EFF$$
r   sectionc                 T    XR                   UR                  '   U R                  5         g)z<Add or replace a section.

:param section: The new section.
N)r   r&   r   )r*   r   s     r   add_sectionNumpydocParser.add_section?  s     (/gmm$r   r2   r   c                 |   [        [        R                  S9nU(       d  U$ [        R                  " U5      nU R
                  R                  U5      nU(       a&  USUR                  5        nXR                  5       S nOUnSnUR                  SS5      nUS   =(       d    SUl	        [        U5      S:  aX  US   =(       d    SnUR                  S5      Ul        UR                  S5      Ul        UR                  5       =(       d    SUl        [#        U R
                  R%                  U5      5       H  u  p8['        S UR)                  5        5       5      n	U R*                  U	   n
UR-                  5       nUb  UR                  5       OSnUR.                  R1                  U
R3                  X[U 5      5        M     U$ )	QParse the numpy-style docstring into its components.

:returns: parsed docstring
)styleN r   r   r   z

c              3   .   #    U  H  oc  M  Uv   M     g 7fr)   rA   )r   gs     r   r   'NumpydocParser.parse.<locals>.<genexpr>i  s     DNqNs   	)r   r   NUMPYDOCrO   rP   r   rh   rM   r   short_descriptionr   r   blank_after_short_descriptionendswithblank_after_long_descriptionr   long_descriptionr   rL   r   groupsr   r   metaextendr5   )r*   r2   retrQ   
desc_chunk
meta_chunkpartslong_desc_chunk	nextmatchr&   factoryrM   r   s                r   r5   NumpydocParser.parseH  s|   
 n556J % %%d+o.Jkkmo.JJJ   q) %a 0Du:>#Ahn"O0?0J0J1C- 0?/G/G/OC,#2#8#8#:#BdC  )$..*A*A**M NEDELLNDDEmmE*G IIKE'0'<)//#$CHHOOGMM*3*?@A !O 
r   )r   r   r)   )r7   r8   r9   r:   r;   r>   OptionalDictr<   r$   r+   r   r   r   r5   r@   rA   r   r   r   r   -  sK    /AFF3<,@!A 
7 *# *) *r   r   r2   c                 4    [        5       R                  U 5      $ )r   )r   r5   )r2   s    r   r5   r5   u  s    
 !!$''r   z    	docstringrendering_styleindentc                 
  ^^
^ S[         R                  [        [        [        4   4UU
4S jjmS[
        S[         R                  [         R                     4U
U4S jjn/ m
U R                  (       a  T
R                  U R                  5        U R                  (       a  T
R                  S5        U R                  (       a  SnU R                  R                  (       a  USU R                  R                   3-  nU R                  R                  (       a%  U R                  R                  R                  5       nO/ nS	T 3nT
R                  UR                  U/U-   5      5        U R                   (       a  T
R                  U R                   5        U R"                  (       a  T
R                  S5        U" S
U R$                  =(       d    /  Vs/ s H  owR&                  S   S:X  d  M  UPM     sn5        U" SU R$                  =(       d    /  Vs/ s H  nUR&                  S   S:X  d  M  UPM     sn5        U" SU R(                  =(       d    /  Vs/ s H  nUR*                  (       a  M  UPM     sn5        U" SU R(                  =(       d    /  Vs/ s H  owR*                  (       d  M  UPM     sn5        U R,                  (       a_  U R(                  (       dN  U R,                  nT
R                  U(       a  SOS5        T
R                  S[/        T
S   5      -  5        T" U5        U" SU R$                  =(       d    /  Vs/ s H  nUR&                  S   S:X  d  M  UPM     sn5        U" SU R$                  =(       d    /  Vs/ s H  nUR&                  S   S:X  d  M  UPM     sn5        U" SU R0                  =(       d    /  Vs/ s H  owR&                  S   S:X  d  M  UPM     sn5        U" SU R0                  =(       d    /  Vs/ s H  owR&                  S   S:X  d  M  UPM     sn5        U R2                   H  n	[5        U	[6        [        [        [        45      (       a  M*  T
R                  S5        T
R                  U	R&                  S   R9                  SS5      R;                  5       5        T
R                  S[/        U	R&                  S   5      -  5        U	R                  (       d  M  T
R                  U	R                  5        M     S	R                  T
5      $ s  snf s  snf s  snf s  snf s  snf s  snf s  snf s  snf )zRender 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  > [        U [        5      (       a  U R                  nO$[        U [        5      (       a  U R                  nOS nU R
                  (       a  U(       a  USU R
                   3-  nO'U R
                  (       a  U R
                  nO	U(       d  Sn[        U [        5      (       a  U R                  (       a  US-  nU R                  (       aB  ST 3R                  U/U R                  R                  5       -   5      nTR                  U5        g TR                  U5        g )Nz : r   z
, optionalr   )
isinstancer	   ra   r   rv   rb   rc   r4   r   r   r   )r   headbodyr   r   s      r   process_onecompose.<locals>.process_one  s     c>**<<D-..??DD==Tc#--))D]]==DDc>**sL D??x=%%tfs/I/I/K&KLDLLLLr   r^   r`   c                    > U(       aT  TR                  S5        TR                  U 5        TR                  S[        TS   5      -  5        U H  nT" U5        M     g g )Nr   r.   )r   r   )r^   r`   argr   r   s      r   process_sectcompose.<locals>.process_sect  sN    LLLLLLs59~-.C  	 r   r   z.. deprecated:: r   r   r   r   r   r   r   r   r.   r   r   r   r   r   r   r   r   r   r   )r>   Unionr	   r   r
   r<   ListAnyr   r   r   r   r   r4   r   r   r   r   paramsr`   many_returnsru   r   r   r   r   r   r   replacer&   )r   r   r   r   firstrestr   itemr   r   r   r   s     `       @@r   composer  }  ss   WW^%5FG 4!3 !affQUUm ! ! E""Y001..R!  ((q..66788E  ,,((44??ADD6(mSXXugn-.!!Y//0--R#**0b0L0$IIaLG4K0L
  "((.B.	
.yy|{* .	
  "..4"4	
4$$ 4	
 #006B6L6$:K:K6L
 !7!7X)4S3uRy>)*C "((.B.	
.yy|z) .	
  "((.B.	
.yy|}, .	
 #**0b0M0$IIaLH4L0M
 #**0b0L0$IIaLG4K0L
 # 	
 
 RTYYq\))#r288:;S3tyy|,,-LL))*# & 99U_ 	M
	
	
 	M	
	
 	N
 	Ms`   T
&T
T
(T
T$
(T$
T)
'T)
>T.
T.
 T3
T3
T8
T8
T=
T=
r)   ),r;   rO   r   r   typingr>   textwrapr   commonr   r   r   r   r	   r
   r   r   r   r?   r   r<   r   r    r   r   rK   re   rf   rg   rw   r$   rC   rU   r[   rm   rr   rz   r}   r   r   r   r5   COMPACTr  rA   r   r   <module>r     s  
   	  
 
 
=

 = =s qzz#  ::l"$$/**HIzz"NO  jjG  ::IJ F FB 0
/W 
/&
: &
R
J 
 
Z 
<N 
 
#g #L w' 7#  g&  !	 
 #]3  /  "M2  }-  Z(  J'  (H%  '8$  '7#  &'"  {+   k*! " 9i(# $ 8Y'% & (H%' ( '8$) * J
++ , Iz*- . J
#/ 0 Iz"1 2 J
#3 4 Iz"5 6 GW7 8 FG9 : L,'; < K&= > |]3?  FE EP( (	 ( '5&<&<	WW $W 	W
 	Wr   