
    O&iR                     L   d Z ddlZddlZddlZddlZddlmZ ddlmZ ddlm	Z	m
Z
mZmZmZmZmZ ddlmZmZ ddlmZmZmZmZmZ ddlmZ dd	lmZmZ  ej        d
          Z ej        d          Z ej        d          Zde de fdZ!dej"        deej#                 fdZ$d"dej"        deej%                 dee          fdZ&de de fdZ' G d d          Z( G d d          Z) G d de)          Z* G d dej+                  Z, G d de)          Z- G d  d!          Z.dS )#z,Utilities parsing and analyzing Python code.    N)OrderedDict)	Signature)DEDENTINDENTNAMENEWLINENUMBEROPSTRING)COMMENTNL)AnyDictListOptionalTuple)ast)parseunparsez^\s*#: ?(.*)?
?$z^\s*$z^\s*(#.*)?$codereturnc                 .    |                      dd          S )N )replace)r   s    a/home/geonatureadmin/si_en_reseau/tutos/venv/lib/python3.11/site-packages/sphinx/pycode/parser.pyfilter_whitespacer      s    <<c"""    nodec                 T    t          | t          j                  r| j        S | j        gS )z3Get list of targets from Assign and AnnAssign node.)
isinstancer   Assigntargetstarget)r   s    r   get_assign_targetsr%      s(    $
## |}r   selfc                 f   |r|j         }| j        j        }|dv rt          d| z            |dk    r'|| j        |k    r| j        gS t          d| z            |dv rBg }| j        D ]6}	 |                    t          ||                     '# t          $ r Y 3w xY w|S |dk    rX| j        j        j        dk    r1|r/| j        j        |k    rdt          | j	        |          d	         z  gS t          d| z            |d
k    r| gS |dk    rt          | j        |          S t          d|z            )zConvert assignment-AST to variable names.

    This raises `TypeError` if the assignment does not create new variable::

        ary[0] = 'foo'
        dic["bar"] = 'baz'
        # => TypeError
    )IndexNumSliceStr	Subscriptz%r does not create new variableNameNz*The assignment %r is not instance variable)r   r   	Attributez%sr   strStarredzUnexpected node name %r)arg	__class____name__	TypeErrorideltsextendget_lvar_namesvalueattrNotImplementedError)r   r&   self_id	node_namememberselts         r   r8   r8       s     ('IAAA9D@AAA	f		<47g--G9H4OPPP	'	'	'9 	 	C~c4889999   	k	!	!:(F22t2
QX@X@X>$)T::1==>>H4OPPP	e		v	i		dj$///!";i"GHHHs   )#B
BBsc                     dd}| |_         t          j        |          }|r(|                    d                              d          S dS )z1Remove common leading indentation from docstring.r   Nc                      d S N rD   r   r   dummyzdedent_docstring.<locals>.dummyL   s    r   z
 r   N)__doc__inspectgetdoclstriprstrip)r@   rE   	docstrings      r   dedent_docstringrN   J   s]        EMu%%I ''..v666rr   c                   ~    e Zd ZdZdededeeef         deeef         deddfd	Zd
ede	fdZ
dede	fdZdefdZdS )Tokenz)Better token wrapper for tokenize module.kindr9   startendsourcer   Nc                 L    || _         || _        || _        || _        || _        d S rC   )rQ   r9   rR   rS   rT   )r&   rQ   r9   rR   rS   rT   s         r   __init__zToken.__init__[   s)    	

r   otherc                 $   t          |t                    r| j        |k    S t          |t                    r| j        |k    S t          |t
          t          f          r| j        | j        gt          |          k    S |dS t          d|z            )NFzUnknown value: %r)r!   intrQ   r/   r9   listtuple
ValueError)r&   rW   s     r   __eq__zToken.__eq__c   s    eS!! 		:9%%s## 	::&&e}-- 	:Itz*d5kk99]5058999r   
conditionsc                 :     t           fd|D                       S )Nc              3   $   K   | ]
}|k    V  d S rC   rD   ).0	candidater&   s     r   	<genexpr>zToken.match.<locals>.<genexpr>p   s(      AA49$AAAAAAr   )any)r&   r^   s   ` r   matchzToken.matcho   s&    AAAAjAAAAAAr   c                 l    dt           j        | j                 d| j                                        dS )Nz<Token kind=z value=>)tokenizetok_namerQ   r9   stripr&   s    r   __repr__zToken.__repr__r   s:     -5->ty-I-I-I-1Z-=-=-?-?-?-?A 	Ar   )r3   
__module____qualname__rH   rY   r   r   r/   rV   boolr]   re   rl   rD   r   r   rP   rP   X   s        33S  U38_ 5QTVYQY? !%   
:C 
:D 
: 
: 
: 
:B B B B B BA# A A A A A Ar   rP   c                   n    e Zd Zdee         ddfdZdedefdZdee	         fdZ
dedee	         fd	ZdS )
TokenProcessorbuffersr   Nc                     t          |          || _        t          j        fd          | _        d | _        d | _        d S )Nc                  "    t                     S rC   )next)liness   r   <lambda>z)TokenProcessor.__init__.<locals>.<lambda>{   s    tE{{ r   )iterrr   rh   generate_tokenstokenscurrentprevious)r&   rr   rv   s     @r   rV   zTokenProcessor.__init__x   sC    W./B/B/B/BCC(,)-r   linenoc                 "    | j         |dz
           S zReturns specified line.   rr   r&   r}   s     r   get_linezTokenProcessor.get_line       |FQJ''r   c                     	 | j         | _        t          t          | j                   | _         n# t
          $ r
 d| _         Y nw xY w| j         S )z_Fetch the next token from source code.

        Returns ``None`` if sequence finished.
        N)r{   r|   rP   ru   rz   StopIterationrk   s    r   fetch_tokenzTokenProcessor.fetch_token   sX    
	  LDM $t{"3"34DLL 	  	  	 DLLL	  |s   ,/ AA	conditionc                    g }|                                  r|                    | j                   | j        |k    rn| j        t          dgk    r ||                     t          dg          z  }nc| j        t          dgk    r ||                     t          dg          z  }n1| j        t          dgk    r||                     t          dg          z  }|                                  |S )zlFetch tokens until specified token appeared.

        .. note:: This also handles parenthesis well.
        (){}[])r   appendr{   r
   fetch_until)r&   r   rz   s      r   r   zTokenProcessor.fetch_until   s    
    		6MM$,'''|y(("c**$**B9555"c**$**B9555"c**$**B9555    		6 r   )r3   rm   rn   r   r/   rV   rY   r   r   rP   r   r   r   rD   r   r   rq   rq   w   s        .S	 .d . . . .(s (s ( ( ( (Xe_    S T%[      r   rq   c                   X     e Zd ZdZdee         ddf fdZdee         fdZddZ	 xZ
S )	AfterCommentParserzPython source code parser to pick up comments after assignments.

    This parser takes code which starts with an assignment statement,
    and returns the comment for the variable if one exists.
    rv   r   Nc                 X    t                                          |           d | _        d S rC   )superrV   commentr&   rv   r2   s     r   rV   zAfterCommentParser.__init__   s&    &*r   c                    g }|                                  r-|                    | j                   | j        t          dgk    r ||                     t          dg          z  }n| j        t          dgk    r ||                     t          dg          z  }n| j        t          dgk    r ||                     t          dg          z  }nh| j        t
          k    r||                     t                    z  }n:| j        t          dgk    rn<| j        j        t          t          t          t          fvrn|                                  -|S )z%Fetch right-hand value of assignment.r   r   r   r   r   r   ;)r   r   r{   r
   r   r   r   rQ   r   r	   r   )r&   rz   s     r   fetch_rvaluezAfterCommentParser.fetch_rvalue   s0      	MM$,'''|Cy(($**B9555"c**$**B9555"c**$**B9555''$**6222"c**"2tVV*DDD    	 r   c                    |                                                      t          dgt          t                    sC| j        sJ |                                                      t          dgt          t                    C| j        t          dgk    r|                                  | j        t          k    r| j        j        | _        dS dS )z3Parse the code and obtain comment after assignment.=N)	r   re   r
   r   r   r{   r   r9   r   rk   s    r   r   zAfterCommentParser.parse   s     ""$$**B9gwGG 	 < ""$$**B9gwGG 	  <B9$$<7""<-DLLL #"r   rG   )r3   rm   rn   rH   r   r/   rV   rP   r   r   __classcell__r2   s   @r   r   r      s         +d3i +D + + + + + +d5k    (. . . . . . . .r   r   c                   V    e Zd ZdZdee         deddf fdZdedeee                  fdZdeddfd	Z	deddfd
Z
dej        ddfdZdededdfdZdedej        ddfdZdeej                 defdZdeej                 defdZdeej                 fdZdedefdZdej        ddf fdZdej        ddfdZdej        ddfdZdej        ddfdZdej         ddfdZ!dej"        ddfdZ#dej$        ddfdZ%dej&        ddfdZ'dej        ddfd Z(dej)        ddfd!Z* xZ+S )"VariableCommentPickerz7Python source code parser to pick up variable comments.rr   encodingr   Nc                 T   t          j                    | _        || _        || _        g | _        g | _        d | _        t                      | _	        i | _
        d | _        i | _        g | _        i | _        d | _        d | _        d | _        t%                                                       d S rC   )	itertoolscountcounterrr   r   contextcurrent_classescurrent_functionr   commentsannotationsr|   	defordersfinals	overloadstypingtyping_finaltyping_overloadr   rV   )r&   rr   r   r2   s      r   rV   zVariableCommentPicker.__init__   s     (( "$*,;?4?MM79+/)+!#57%)+/.2r   namec                     | j         r-| j        r$| j        d         dk    r| j        dd         |gz   S dS | j        |gz   S )z;Get qualified name for given object as a list of string(s).rV   N)r   r   r   )r&   r   s     r   get_qualname_forz&VariableCommentPicker.get_qualname_for   sU      	)# R(8J(F(F|CRC(D611t<4&((r   c                     |                      |          }|r1t          | j                  | j        d                    |          <   d S d S N.)r   ru   r   r   joinr&   r   qualnames      r   	add_entryzVariableCommentPicker.add_entry   sR    ((.. 	D15dl1C1CDN388H--...	D 	Dr   c                     |                      |          }|r/| j                            d                    |                     d S d S r   )r   r   r   r   r   s      r   add_final_entryz%VariableCommentPicker.add_final_entry   sO    ((.. 	3Ksxx1122222	3 	3r   funcc                     ddl m} |                     |j                  }|rN| j                            d                    |          g           }|                     ||                     d S d S )Nr   )signature_from_astr   )sphinx.util.inspectr   r   r   r   
setdefaultr   r   )r&   r   r   r   r   s        r   add_overload_entryz(VariableCommentPicker.add_overload_entry   s    ::::::((33 	711#((82D2DbIII//5566666	7 	7r   r   c                     |                      |          }|r+d                    |d d                   }|| j        ||f<   d S d S Nr   r   )r   r   r   )r&   r   r   r   basenames        r   add_variable_commentz*VariableCommentPicker.add_variable_comment  sW    ((.. 	6xx"..H.5DM8T*+++	6 	6r   
annotationc                     |                      |          }|r8d                    |d d                   }t          |          | j        ||f<   d S d S r   )r   r   r   r   )r&   r   r   r   r   s        r   add_variable_annotationz-VariableCommentPicker.add_variable_annotation	  sc    ((.. 	Exx"..H181D1DDh-...	E 	Er   
decoratorsc                     g }| j         r|                    d| j         z             | j        r|                    | j                   |D ]'}	 t          |          |v r dS # t          $ r Y $w xY wdS )Nz%s.finalTF)r   r   r   r   r;   )r&   r   final	decorators       r   is_finalzVariableCommentPicker.is_final  s    ; 	3LLdk1222 	,LL*+++# 	 	I9%%..44 /&    u   A""
A/.A/c                     g }| j         r|                    d| j         z             | j        r|                    | j                   |D ]'}	 t          |          |v r dS # t          $ r Y $w xY wdS )Nz%s.overloadTF)r   r   r   r   r;   )r&   r   overloadr   s       r   is_overloadz!VariableCommentPicker.is_overload  s    ; 	9OOMDK7888 	2OOD0111# 	 	I9%%1144 2&    ur   c                     | j         r(| j         j        j        r| j         j        j        d         S | j         r2t          | j         j        dd          r| j         j        j        d         S dS )z8Returns the name of the first argument if in a function.r   posonlyargsN)r   argsgetattrr   rk   s    r   get_selfzVariableCommentPicker.get_self/  sq      	T%:%?%D 	(-2155# 	d+0-FF	 (-9!<<4r   r}   c                 "    | j         |dz
           S r   r   r   s     r   r   zVariableCommentPicker.get_line:  r   r   r   c                 X    t                                          |           || _        dS )z(Updates self.previous to the given node.N)r   visitr|   )r&   r   r2   s     r   r   zVariableCommentPicker.visit>  s$    dr   c                    |j         D ]}|                     |j        p|j                   |j        dk    r|j        p|j        | _        B|j        dk    r|j        p|j        | _        a|j        dk    r|j        p|j        | _        dS )8Handles Import node and record the order of definitions.r   ztyping.finalztyping.overloadN)namesr   asnamer   r   r   r   r&   r   r   s      r   visit_Importz"VariableCommentPicker.visit_ImportC  s    J 	@ 	@DNN4;3$)444yH$$"k6TYn,,$(K$<49!!///'+{'?di$	@ 	@r   c                    |j         D ]v}|                     |j        p|j                   |j        dk    r|j        dk    r|j        p|j        | _        M|j        dk    r|j        dk    r|j        p|j        | _        wdS )r   r   r   r   N)r   r   r   r   moduler   r   r   s      r   visit_ImportFromz&VariableCommentPicker.visit_ImportFromO  s    J 	@ 	@DNN4;3$)444{h&&49+?+?$(K$<49!!((TY*-D-D'+{'?di$	@ 	@r   c                 `    	 t          |          }t           fd|D             g           }                     |j                  }n# t          $ r Y dS w xY wt          |d          r(|j        r!|D ]}                     ||j                   n7t          |d          r'|j        r |D ]}                     ||j                   t          ||j
        d         g j        |j        d         z             }|                                 |j        rot                              |j                  rP|D ]K}                     |t                              d|j                                                  |           LdS t&                              |d|j
                           rg }t)          |j        dz
            D ]k}                     |j        dz
  |z
            }	t                              |	          r/|                    t                              d|	                     k |rat-          d                    t1          |                              }
|D ]-}                     ||
                                |           .dS |D ]}                     |           dS )z3Handles Assign node and pick up a variable comment.c                 V    g | ]%}t          |                                           &S )rk   )r8   r   )ra   tr&   s     r   
<listcomp>z6VariableCommentPicker.visit_Assign.<locals>.<listcomp>]  s/    &`&`&`ST~admmoo'N'N'N&`&`&`r   Nr   type_commentz\1r   
)r%   sumr   r}   r4   hasattrr   r   r   r   
col_offsetrr   r   r   
comment_rere   r   subr   	indent_reranger   rN   r   reversed)r&   r   r#   varnamescurrent_linevarnameparsercomment_linesibefore_liner   s   `          r   visit_Assignz"VariableCommentPicker.visit_AssignY  s   	(..G"%&`&`&`&`X_&`&`&`bd"e"eH==55LL 	 	 	FF	 4&& 	I4? 	I# G G,,WdoFFFFGT>** 	It/@ 	I# I I,,Wd6GHHHH $\$/2B2B%C$D$(L$>%? @ @> 	j..v~>> 	# ( ())':>>%3X3XYYYw''''F ??<(8(89:: 	M4;?++  "mmDK!Oa,?@@##K00 !(({)K)KLLLL *499Xm5L5L+M+MNN' , ,G--gw???NN7++++   	$ 	$GNN7####	$ 	$s   AA	 	
AAc                 0    |                      |           dS )z6Handles AnnAssign node and pick up a variable comment.N)r   r&   r   s     r   visit_AnnAssignz%VariableCommentPicker.visit_AnnAssign  s    $r   c                 \   t          | j        t          j        t          j        f          rt          |j        t          j                  r	 t          | j                  }t          |d         | 	                                          }|D ]}t          |j        j
        t                    r|j        j
        }n&|j        j
                            | j        pd          }|                     |t          |                     |                     |           dS # t"          $ r Y dS w xY wdS dS )z2Handles Expr node and pick up a comment if string.r   utf-8N)r!   r|   r   r"   	AnnAssignr9   r+   r%   r8   r   r@   r/   decoder   r   rN   r   r4   )r&   r   r#   r   r   rM   s         r   
visit_Exprz VariableCommentPicker.visit_Expr  s)   t}sz3=&ABB 	4:sw//	,T];;)'!*dmmooFF' , ,G!$*,44 R$(JL		$(JL$7$78P$Q$Q	--g7G	7R7RSSSNN7++++, ,    	 	 	 	s   CD 
D'&D'c                     |j         D ]}|                     |           |j        D ]}|                     |           dS )zHandles Try node and processes body and else-clause.

        .. note:: pycode parser ignores objects definition in except-clause.
        N)bodyr   orelse)r&   r   subnodes      r   	visit_TryzVariableCommentPicker.visit_Try  sZ    
 y 	  	 GJJw{ 	  	 GJJw	  	 r   c                    | j                             |j                   |                     |j                   |                     |j                  r|                     |j                   | j                            |j                   || _        |j	        D ]}| 
                    |           | j                                         | j                                          dS )z&Handles ClassDef node and set context.N)r   r   r   r   r   decorator_listr   r   r|   r  r   popr&   r   childs      r   visit_ClassDefz$VariableCommentPicker.visit_ClassDef  s    ##DI...ty!!!==,-- 	,  +++DI&&&Y 	 	EJJu  """""r   c                    | j         |                     |j                   |                     |j                  r|                     |j                   |                     |j                  r|                     |           | j        	                    |j                   || _         |j
        D ]}|                     |           | j                                         d| _         dS dS )z)Handles FunctionDef node and set context.N)r   r   r   r   r	  r   r   r   r   r   r  r   r
  r  s      r   visit_FunctionDefz'VariableCommentPicker.visit_FunctionDef  s     (NN49%%%}}T011 0$$TY/// 344 .''---L	***$(D! " "

5!!!!L$(D!!! )(r   c                 0    |                      |           dS )z.Handles AsyncFunctionDef node and set context.N)r  r   s     r   visit_AsyncFunctionDefz,VariableCommentPicker.visit_AsyncFunctionDef  s    t$$$$$r   ),r3   rm   rn   rH   r   r/   rV   r   r   r   r   r   FunctionDefr   r   ASTr   exprro   r   r   r1   r   rY   r   r   Importr   
ImportFromr   r"   r   r   r   Exprr  Tryr  ClassDefr  r  AsyncFunctionDefr  r   r   s   @r   r   r      sd       AAS	 S T      $	)S 	)Xd3i-@ 	) 	) 	) 	)Dc Dd D D D D
3C 3D 3 3 3 3
7s 74 7 7 7 76 6s 6t 6 6 6 6EC ESW E E E E E4> d     d38n      	(37+ 	 	 	 	(s (s ( ( ( (#' d      

@ 
@ 
@ 
@ 
@ 
@@S^ @ @ @ @ @.$ .$ .$ .$ .$ .$` CM  d        sx D    $ cg  $        #3< #D # # # #)co )$ ) ) ) )%3+? %D % % % % % % % %r   r   c                   ~     e Zd ZdZdee         ddf fdZdedeeeef         ddfdZ	dd	Z
d
eddfdZddZ xZS )DefinitionFinderzXPython source code parser to detect location of functions,
    classes and methods.
    rv   r   Nc                     t                                          |           d | _        g | _        g | _        i | _        d S rC   )r   rV   r   r   indentsdefinitionsr   s     r   rV   zDefinitionFinder.__init__  s>    *."$GI<>r   r   entryc                 r    | j         r%| j         d         d         dk    r|d         dk    rdS || j        |<   dS )zAdd a location of definition.r   r   defN)r  r  )r&   r   r   s      r   add_definitionzDefinitionFinder.add_definition  sH    < 	+DL,Q/588U1X=N=ND%*DT"""r   c                 J   	 |                                  }|dS |t          k    rn|t          dgk    rG| j        1| j                            t
          t          t          t                    r| j	        || _	        n|                    t          dg          r|                     d           nw|                    t          dg          r|                     d           nE|t          k    r| j                            d           n|t          k    r|                                  #)z1Parse the code to obtain location of definitions.TN@classr"  )rW   NN)r   r   r
   r|   re   r   r   r   r   r   r   parse_definitionr  r   finalize_block)r&   tokens     r   r   zDefinitionFinder.parse  s   	&$$&&E}'!!2s)##)>)-)<)<Wb&RX)Y)Y *?>)%*DNdG_-- &%%g....dE]++ &%%e,,,,&##$9::::&##%%%#	&r   typc                    |                                  }| j                            |j                   d                    | j                  }| j        r| j        j        d         }d| _        n|j        d         }|                     t          dg           |                                  	                    t          t                    r9|                     t                     | j                            |||f           dS |                     ||||j        d         f           | j                                         dS )zParse AST of definition.r   r   N:)r   r   r   r9   r   r   rR   r   r
   re   r   r   r   r  r#  rS   r
  )r&   r*  r   funcname	start_poss        r   r'  z!DefinitionFinder.parse_definition  s   !!DJ'''88DL))> 	&,Q/I!DNN
1I"c#####GW55 	V$$$Lh	 :;;;;; 3	48A;*GHHHLr   c                    | j                                         }|d         dk    r|\  }}}| j        j        d         dz
  }t                              |                     |                    r2|dz  }t                              |                     |                    2|                     ||||f           | j                                         dS dS )zFinalize definition block.r   rW   r   N)	r  r
  r{   rS   emptyline_rere   r   r#  r   )r&   
definitionr*  r-  r.  end_poss         r   r(  zDefinitionFinder.finalize_block  s    \%%''
a=G##'1$C9l&q)A-G$$T]]7%;%;<< 1 $$T]]7%;%;<<  3	7*CDDDL $#r   rG   )r3   rm   rn   rH   r   r/   rV   r   rY   r#  r   r'  r(  r   r   s   @r   r  r    s         ?d3i ?D ? ? ? ? ? ?+3 +uS#s]/C + + + + +& & & &*C D    *
 
 
 
 
 
 
 
r   r  c                   @    e Zd ZdZddededdfdZddZdd	Zdd
ZdS )ParserzyPython source code parser to pick up variable comments.

    This is a better wrapper for ``VariableCommentPicker``.
    r   r   r   r   Nc                     t          |          | _        || _        i | _        i | _        i | _        i | _        g | _        i | _        d S rC   )	r   r   r   r   r   r   r  r   r   )r&   r   r   s      r   rV   zParser.__init__  sH    %d++	 7946)+<>!#57r   c                 V    |                                   |                                  dS )zParse the source code.N)parse_commentsr'  rk   s    r   r   zParser.parse%  s,    r   c                 *   t          | j                  }t          | j                            d          | j                  }|                    |           |j        | _        |j        | _        |j        | _        |j	        | _	        |j
        | _
        dS )z$Parse the code and pick up comments.TN)r   r   r   
splitlinesr   r   r   r   r   r   r   )r&   treepickers      r   r7  zParser.parse_comments*  sy    TY&ty';';D'A'A4=QQT!-)m)r   c                     t          | j                            d                    }|                                 |j        | _        dS )z0Parse the location of definitions from the code.TN)r  r   r9  r   r  )r&   r   s     r   r'  zParser.parse_definition5  s=    !$)"6"6t"<"<==!-r   )r   rG   )	r3   rm   rn   rH   r/   rV   r   r7  r'  rD   r   r   r4  r4    s         
8 8S 8C 8d 8 8 8 8       
	* 	* 	* 	*. . . . . .r   r4  rC   )/rH   rI   r   rerh   collectionsr   r   r)  r   r   r   r   r	   r
   r   r   r   r   r   r   r   r   r   sphinx.pycode.astr   r   r   compiler   r   r0  r/   r   r  r  r%   r1   r8   rN   rP   rq   r   NodeVisitorr   r  r4  rD   r   r   <module>rB     s   2 2      				  # # # # # #       C C C C C C C C C C C C C C C C C C                 3 3 3 3 3 3 3 3 3 3 3 3 3 3 ! ! ! ! ! ! , , , , , , , ,RZ.//
BJx  	rz.))#C #C # # # #SW ch    'I 'I 'I(9 'IT#Y 'I 'I 'I 'IT     A A A A A A A A>* * * * * * * *Z*. *. *. *. *. *. *. *.Zv% v% v% v% v%CO v% v% v%rH H H H H~ H H HV$. $. $. $. $. $. $. $. $. $.r   