
    h4                     J   S r SSKrSSKrSSKrSSKJrJ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JrJrJrJrJr   " S S\	5      r " S	 S
\" SS5      5      r\R6                  " S5      r\R6                  " S5      r\R6                  " S5      r\" SS\R>                  5      \" SS\R>                  5      \" SS\R>                  5      \" SS\R>                  5      \" SS\R>                  5      \" SS\R>                  5      \" SS\R>                  5      \" SS\R>                  5      \" SS\R@                  5      \" SS\R@                  5      \" SS\RB                  5      \" S S!\RB                  5      /r" " S" S#5      r#S$\$S%\4S& jr%\RL                  S'4S(\S)\S*\$S%\$4S+ jjr'g),zGoogle-style docstring parsing.    N)OrderedDict
namedtuple)IntEnum   )EXAMPLES_KEYWORDSPARAM_KEYWORDSRAISES_KEYWORDSRETURNS_KEYWORDSYIELDS_KEYWORDS	DocstringDocstringExampleDocstringMetaDocstringParamDocstringRaisesDocstringReturnsDocstringStyle
ParseErrorRenderingStylec                   (    \ rS rSrSrSr Sr SrSrg)SectionType   zTypes of sections.r   r       N)	__name__
__module____qualname____firstlineno____doc__SINGULARMULTIPLESINGULAR_OR_MULTIPLE__static_attributes__r       Q/home/james-whalen/.local/lib/python3.13/site-packages/docstring_parser/google.pyr   r      s    H%H#.r#   r   c                       \ rS rSrSrSrg)Section(   zA docstring section.r   N)r   r   r   r   r   r"   r   r#   r$   r&   r&   (   s    r#   r&   SectionBaseztitle key typez\s*(.+?)\s*\(\s*(.*[^\s]+)\s*\)z.*\. Defaults to (.+)\.z(\s*[^:\s]+:)|([^:]*\]:.*)	ArgumentsparamArgs
ParametersParamsRaisesraises
ExceptionsExcept
Attributes	attributeExampleexamplesExamplesReturnsreturnsYieldsyieldsc            	           \ rS rSrSr SS\R                  \R                  \      4S jjr	S r
S\S\S	\4S
 jr\S\S\S	\4S j5       r\S\S\S\S	\4S j5       rS\4S jrS\S	\4S jrSrg)GoogleParser@   z#Parser for Google-style docstrings.Nsectionsc                     U(       d  [         nU Vs0 s H  o3R                  U_M     snU l        X l        U R	                  5         gs  snf )zSetup sections.

:param sections: Recognized sections or None to defaults.
:param title_colon: require colon after section title.
N)DEFAULT_SECTIONStitler>   title_colon_setup)selfr>   rB   ss       r$   __init__GoogleParser.__init__C   s<     'H-56X!X6& 7s   Ac                     U R                   (       a  SnOSn[        R                  " SSR                  S U R                   5       5      -   S-   U-   S-   [        R
                  S9U l        g )	N: z^(|c              3   .   #    U  H  nS U S3v   M     g7f)()Nr   ).0ts     r$   	<genexpr>&GoogleParser._setup.<locals>.<genexpr>X   s     7A1#Qxs   rN   z	[ 	]*$flags)rB   recompilejoinr>   M	titles_re)rD   colons     r$   rC   GoogleParser._setupQ   sh    EEhh7778  	
 $$
r#   textrA   returnc                    U R                   U   nUR                  [        R                  :X  a  [        R                  U5      (       a  UR                  [        R                  :X  a  U R                  X15      $ SU;  a  [        SU< S35      eUR                  SS5      u  pEU(       a3  SU;   a-  UR                  SS5      u  pgU[        R                  " U5      -   nU(       aW  US   S:X  a  USS OUnSU;   a0  UR                  SS5      u  pgUS-   [        R                  " U5      -   nUR                  S5      nU R                  X4U5      $ )	zyBuild docstring element.

:param text: docstring element text
:param title: title of section containing element
:return:
rI   zExpected a colon in .r   
r    N)r>   typer   r!   MULTIPLE_PATTERNmatchr   _build_single_metar   splitinspectcleandocstrip_build_multi_meta)rD   r\   rA   sectionbeforedesc
first_linerests           r$   _build_metaGoogleParser._build_meta_   s*    --& LLK<<<$**400\\[111**799d?3D81=>> zz#q)dfn%||D!4J'"2"24"88F#Aw#~484Dt|#'::dA#6 
!D(7+;+;D+AA::d#D%%gt<<r#   rk   rm   c                    U R                   [        [        -  ;   a(  [        U R                   /US U R                   [        ;   S9$ U R                   [        ;   a  [        U R                   /US S9$ U R                   [        ;   a  [        U R                   /S US9$ U R                   [        ;   a  [        S5      e[        U R                   /US9$ )Nargsdescription	type_nameis_generatorrt   ru   rv   )rt   snippetru   zExpected paramenter name.rt   ru   )keyr
   r   r   r	   r   r   r   r   r   r   )rk   rm   s     r$   re   GoogleParser._build_single_meta   s    ;;*_<<#kk] $[[O;	  ;;/)"kk]  ;;++#kk]Dd  ;;.(8997;;-TBBr#   rl   c           	         U R                   [        ;   a  [        R                  U5      nU(       aS  UR	                  SS5      u  pEUR                  S5      (       a  SnUS S nO&UR                  S5      (       a  SnUS S nOSnOUS pTS n[        R                  U5      nU(       a  UR	                  S5      OS n[        U R                   U/UUUUUS	9$ U R                   [        [        -  ;   a)  [        U R                   U/UUU R                   [        ;   S
9$ U R                   [        ;   a  [        U R                   U/X!S9$ [        U R                   U/US9$ )Nr   r   
, optionalTi?F)rt   ru   arg_namerv   is_optionaldefaultrs   rx   rz   )r{   r   GOOGLE_TYPED_ARG_REGEXrd   groupendswithGOOGLE_ARG_DESC_REGEXr   r
   r   r   r	   r   r   )rk   rl   rm   rd   r   rv   r   r   s           r$   rj   GoogleParser._build_multi_meta   sR    ;;.(*008E&+kk!Q&7#%%l33"&K )$3I'',,"&K )#2I"'K&,d)")//5E(-ekk!n4G!kk6* !#'  ;;*_<<#kk6*  $[[O;	  ;;/)"kk6*  7;;"7TJJr#   c                 T    XR                   UR                  '   U R                  5         g)z<Add or replace a section.

:param section: The new section.
N)r>   rA   rC   )rD   rk   s     r$   add_sectionGoogleParser.add_section   s     (/gmm$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      nU(       d  U$ / n	['        [        U5      S-
  5       H9  n
U	R)                  X   R+                  5       XS-      R                  5       45        M;     U	R)                  US   R+                  5       [        U5      45        [-        5       n[/        U	5       Hp  u  n
u  pX   R1                  S5      nXR2                  ;  a  M,  X\U n[4        R                  " S	U5      nUb  USUR                  5        nUR                  S5      X'   Mr     U(       d  U$ UR7                  5        GH  u  nn[4        R                  " S
U5      nU(       d  [9        SU S35      eUR1                  5       nU R2                  U   R:                  [<        R>                  [<        R@                  4;   aC  [        R                  " U5      nURB                  R)                  U RE                  UU5      5        M  SU-   S-   n[#        [4        R$                  " UU[4        RF                  S95      nU(       d  [9        SU SU S35      e/ n['        [        U5      S-
  5       H;  n
UR)                  UU
   R+                  5       UU
S-      R                  5       45        M=     UR)                  US   R+                  5       [        U5      45        [/        U5       HF  u  n
u  pUX R                  S5      nURB                  R)                  U RE                  UU5      5        MH     GM     U$ )RParse the Google-style docstring into its components.

:returns: parsed docstring
)styleNrJ   r`   r   r   z

r   z\n\Sz^\s*zCan't infer indent from ""^z(?=\S)rS   zNo specification for "z": ")$r   r   GOOGLErg   rh   rY   searchstartrf   short_descriptionlen
startswithblank_after_short_descriptionr   blank_after_long_descriptionri   long_descriptionlistfinditerrangeappendendr   	enumerater   r>   rU   itemsr   rb   r   r   r!   metarp   rX   )rD   r\   retrd   
desc_chunk
meta_chunkpartslong_desc_chunkmatchessplitsjchunksr   r   rA   meta_detailsunknown_metachunkindent_matchindentpart_re	c_matchesc_splitss                           r$   parseGoogleParser.parse   s   
 n334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  t~~..z:;Js7|a'(AMM7:>>+WU^-A-A-CDE )wr{(#j/:;(0OA|J$$Q'EMM) &C0L99Wl;L'+,Bl.@.@.BC(..t4FM  1 J #LLNLE599We4L #=eWA!FGG!'')F }}U#(($$00-  ''. 0 0u => ,*CR[[e244@AI #9%UG1!MNNH3y>A-.1!1!1!3Yq1u5E5K5K5M NO /OOYr]..0#e*=>#,X#6<EU'--d3 0 0u => $73 +: 
r#   )r>   rB   rY   )NT)r   r   r   r   r   TOptionalListr&   rF   rC   strr   rp   staticmethodre   rj   r   r   r   r"   r   r#   r$   r<   r<   @   s    - IM

166'?3
"= "=C "=M "=H CG C3 C= C C( )K)K"%)K-0)K	)K )KV7 X# X) Xr#   r<   r\   r]   c                 4    [        5       R                  U 5      $ )r   )r<   r   )r\   s    r$   r   r   (  s    
 >%%r#   z    	docstringrendering_styler   c                   ^^^	^
 S[         R                  [        [        [        4   4U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  T	R                  U R                  5        U R                  (       a  T	R                  S5        U" SU R                  =(       d    /  Vs/ s H  oDR                  S   S	:X  d  M  UPM     sn5        U" S
U R                  =(       d    /  Vs/ s H  oDR                  S   S:X  d  M  UPM     sn5        U" SU R                  =(       d    /  Vs/ s H  oDR                   (       a  M  UPM     sn5        U" SU R                  =(       d    /  Vs/ s H  oDR                   (       d  M  UPM     sn5        U" SU R"                  =(       d    / 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 R(                   H  n[+        U[        [        [        45      (       a  M%  T	R                  UR                  S   R-                  SS5      R/                  5       S-   5        UR0                  (       aM  UR0                  R3                  5        Vs/ s H  nTU-   PM
     nnT	R                  SR5                  U5      5        T	R                  S5        M     T	(       a-  T	S   (       d#  T	R7                  5         T	(       a  T	S   (       d  M#  SR5                  T	5      $ 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                   > Sn[        U [        5      (       a  XR                  =(       d    S-  nO,[        U [        5      (       a  XR                  =(       d    S-  n[        U [        5      (       a*  U R
                  (       a  T[        R                  :X  a  SOSnOSnU R                  (       a  U(       a  USU R                   U S3-  nO*U R                  (       a  XR                   U S3-  nOUS-  nTU-   nU R                  (       aX  T[        R                  :X  aD  ST T 3R                  U/U R                  R                  5       -   5      nTR                  U5        g U R                  (       aM  U R                  R                  5       tpEST T 3R                  US-   U-   /U-   5      nTR                  U5        g TR                  U5        g )	NrJ   r   r~   z (z):rI   r`   ra   )
isinstancer   r   r   return_namer   r   COMPACTrv   ru   EXPANDEDrW   
splitlinesr   )	r   headoptionalbodyfirstro   r   r   r   s	         r$   process_onecompose.<locals>.process_one=  s    c>**LL&B&D-..OO)r)Dc>**s #n&<&<< !  H==Tbz44D]]}}ohZq11DCKD}??.2I2IIxx(--3355D LL__ __779NUxx(--tczE/A.BT.IJDLLLLr#   namert   c                 |   > U(       a4  TR                  U 5        U H  nT" U5        M     TR                  S5        g g )NrJ   )r   )r   rt   argr   r   s      r$   process_sectcompose.<locals>.process_sectd  s5    LLC  LL	 r#   rJ   zArgs:r   r*   zAttributes:r3   zReturns:zYields:zRaises:-r   _rI   r`   )r   Unionr   r   r   r   r   Anyr   r   r   r   r   paramsrt   many_returnsrw   r/   r8   r   r   r   replacerA   ru   r   rW   pop)r   r   r   r   pr   r   llinesr   r   s    ``      @@r$   composer   0  s   %WW^%5FG% %N3 affQUUm   E""Y001..R!!Y//0--RY--33L3vvayG7K!3L $$**G*qffQi;.F*G
 **0b0G0q0G
 y55;;N;!~~A;N I,,23!7!7#Y:6S3uRy>)*C>#3_E
 
 TYYq\))#r288:S@A)-)9)9)D)D)FG)FAVaZ)FEGLL5)*R  b			 b		 99UO M
 	H
 	H O$ Hs6   N3
3N3
N8
4N8
N=
3N=
O
2O
(O)(r   rg   rU   typingr   collectionsr   r   enumr   commonr   r   r	   r
   r   r   r   r   r   r   r   r   r   r   r   r&   rV   r   r   rc   r    r   r!   r@   r<   r   r   r   r   r   r#   r$   <module>r      s   %  	  /    $
/' 
/j(89  $FG 

#=> ::;<  K+"6"67FG[112L';#7#78Hg{334Hh 4 45L(K$8$89Hh 4 45L+{';';<Iz;#7#78J
K$8$89Iy+"B"BCHh @ @A  e eP& &	 & '5&<&<nn#n n 		nr#   