
    RiaG                    R   d Z ddlmZ ddlZddlmZmZ ddlmZ ddl	m
Z
 ddlmZ ddlmZ dd	lmZ er5dd
lmZmZ ddlmZ ddlmZ ddlmZ ddlmZ ddd fZddd fZddd fZ ej>                  e       Z!ddZ" G d d      Z# G d de#      Z$ G d de$      Z% d        Z&y)zUtility code for "Doc fields".

"Doc fields" are reST field lists in object descriptions that will
be domain-specifically transformed to a more appealing presentation.
    )annotationsN)TYPE_CHECKINGcast)nodes)addnodes)__)logging)get_node_line)ElementNode)Inliner)ObjectDescription)BuildEnvironment)TextlikeNode_FieldEntryc                 6    t         t        t        t           f   S N)tuplestrlistr        M/home/agent/.friday_env/lib/python3.12/site-packages/sphinx/util/docfields.pyr   r      s    uS$t*_--r   _FieldTypesc                 6    t         t        t        t           f   S r   )dictr   r   r   r   r   r   r   r      s    tCdO,,r   _EntriesTriplec                 N    t         t        t        t        t           z  t        f   S r   )r   Fieldr   r   r   r   r   r   r   r      s    %{T+5F'F OPPr   c                    t        |       dk(  ryt        |       dkD  r&| dd D ]  }t        |t        j                        r y t        | d   t        j                        S )zCTrue if the node only contains one paragraph (and system messages).r   F   N)len
isinstancer   system_message	paragraph)nodesubnodes     r   _is_single_paragraphr(   "   sZ    
4yA~	TQABx 	Ggu';';<	 d1gu//r   c                     e Zd ZdZdZdZ	 	 	 	 	 d		 	 	 	 	 	 	 	 	 	 	 	 	 d
dZej                  ddddf	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 ddZ	ej                  ddddf	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 ddZ
ddZ	 	 	 d	 	 	 	 	 	 	 	 	 	 	 	 	 ddZy)r   a  A doc field that is never grouped.  It can have an argument or not, the
    argument can be linked using a specified *rolename*.  Field should be used
    for doc fields that usually don't occur more than once.

    The body can be linked using a specified *bodyrolename* if the content is
    just a single inline or text node.

    Example::

       :returns: description of the return value
       :rtype: description of the return type
    Fc                X    || _         || _        || _        || _        || _        || _        y r   )namenameslabelhas_argrolenamebodyrolename)selfr+   r,   r-   r.   r/   r0   s          r   __init__zField.__init__>   s/     	

 (r   Nc	           	     X   |J |d u |d u k(  s	J ||f       |s|xs	  |||      S |j                  |      j                  |      }	|	|}|	/|-t        d      }
t        j	                  t        |
      |||       t        j                  d|d||      }||xs	  |||      z  }|j                  |      j                  |       |S d}|-t        j                  t              5  t        |      }d d d         |	|||||i g       \  }}t        j                  |dg| S # 1 sw Y   1xY w)Nz]Problem in %s domain: field is supposed to use role '%s', but that role is not in the domain.)location F)	refdomainrefexplicitreftype	reftarget)
get_domainroler   loggerwarningr   pending_xrefprocess_field_xref
contextlibsuppress
ValueErrorr
   r   inline)r1   r/   domaintarget	innernodecontnodeenvinlinerr4   r<   msgrefnodelinenons	_messagess                  r   	make_xrefzField.make_xrefN   sW    4X%56K(8KK68y88 ~~f%**84<7?| 3L r#w8L++ !  G x<9VV#<<GNN6"55g>N$$Z0 1&x01XvvvwBOI||FB,,,1 1s   $D  D)c	           
     4    | j                  ||||||||      gS r   )rP   )	r1   r/   rE   rF   rG   rH   rI   rJ   r4   s	            r   
make_xrefszField.make_xrefsy   s+     NN&&)XsGX
 	
r   c                
    ||fS r   r   )r1   fieldargcontents      r   
make_entryzField.make_entry   s      r   c                   |\  }}t        j                  d| j                        }	|rW|	t        j                  d      z  }	|	j	                  | j                  | j                  ||t         j                  |||             t        |      dk(  rt        |d   t         j                        sNt        |d   t         j                        rgt        |d         dk(  rVt        |d   d   t         j                        r6| j                  | j                  ||d   j                         |d   |||      }t        j                  dt        j                  ddg|       }
t        j                  d|	|
      S )Nr5    rI   rJ   r4   r!   r   )rH   rI   rJ   r4   )r   
field_namer-   TextextendrR   r/   r"   r#   rD   r0   astext
field_bodyr%   field)r1   typesrE   itemrI   rJ   r4   rT   rU   	fieldname	fieldbodys              r   
make_fieldzField.make_field   sE    !'$$R4	C(IMMJJ#%   
 w<1wqz5::.71:u||4
Oq(wqz!}ejj9 oo!!
!!# ! & G $$RR)J')JK	{{2y)44r   )r   r5   Tr5   r5   )r+   r   r,   tuple[str, ...]r-   r   r.   boolr/   r   r0   r   returnNone)r/   r   rE   r   rF   r   rG   type[TextlikeNode]rH   Node | NonerI   BuildEnvironment | NonerJ   Inliner | Noner4   Element | Nonerg   r   )r/   r   rE   r   rF   r   rG   ri   rH   rj   rI   rk   rJ   rl   r4   rm   rg   
list[Node])rT   r   rU   rn   rg   r   NNN)r`   r   rE   r   ra   r   rI   rk   rJ   rl   r4   rm   rg   nodes.field)__name__
__module____qualname____doc__
is_groupedis_typedr2   r   literal_emphasisrP   rR   rV   rd   r   r   r   r   r   -   s    JH
 "$)) ) 	)
 ) ) ) 
)* )1(A(A $'+"&#')-)- )- 	)-
 &)- )- %)-  )- !)- 
)-` )1(A(A $'+"&#'

 
 	

 &
 
 %
  
 !
 

"! (,"&#'+5+5 +5 	+5
 %+5  +5 !+5 
+5r   r   c                       e Zd ZdZdZej                  Z	 	 	 	 d	 	 	 	 	 	 	 	 	 	 	 d fdZ	 	 	 d	 	 	 	 	 	 	 	 	 	 	 	 	 ddZ	 xZ
S )	GroupedFielda  A doc field that is grouped; i.e., all fields of that type will be
    transformed into one field with its body being a bulleted list.  It always
    has an argument.  The argument can be linked using the given *rolename*.
    GroupedField should be used for doc fields that can occur more than once.
    If *can_collapse* is true, this field will revert to a Field if only used
    once.

    Example::

       :raises ErrorClass: description when it is raised
    Tc                :    t         |   |||d|       || _        y )NT)superr2   can_collapse)r1   r+   r,   r-   r/   r|   	__class__s         r   r2   zGroupedField.__init__   s"     	ueT8<(r   c                   t        j                  d| j                        }| j                         }|D ]  \  }	}
t        j                         }|j                  | j                  | j                  ||	t        j                  |||             |t        j                  d      z  }||
z  }|t        j                  d|      z  } t        |      dk(  rK| j                  r?t        d|d         }t        j                  d|d         }t        j                   d||      S t        j                  d|      }t        j                   d||      S )Nr5   rY    -- r!   znodes.list_itemr   )r   rZ   r-   	list_typer%   r\   rR   r/   r   literal_strongr[   	list_itemr"   r|   r   r^   r_   )r1   r`   rE   itemsrI   rJ   r4   rb   listnoderT   rU   parr   rc   s                 r   rd   zGroupedField.make_field   s)    $$R4	>>#!& 	1Hg//#CJJMM++#%   
 5::f%%C7NCC00H	1" u:?t00.<I((Yq\:I;;r9i88$$R2	{{2y)44r   )r   r5   r5   F)r+   r   r,   re   r-   r   r/   r   r|   rf   rg   rh   ro   r`   r   rE   r   r   zlist[_FieldEntry]rI   rk   rJ   rl   r4   rm   rg   rp   )rq   rr   rs   rt   ru   r   bullet_listr   r2   rd   __classcell__r}   s   @r   ry   ry      s    
 J!!I
 "$"	)	) 	) 		)
 	) 	) 
	)  (,"&#'"5"5 "5 !	"5
 %"5  "5 !"5 
"5r   ry   c                  ~     e Zd ZdZdZ	 	 	 	 	 	 d	 	 	 	 	 	 	 	 	 	 	 	 	 	 	 d fdZ	 	 	 d	 	 	 	 	 	 	 	 	 	 	 	 	 ddZ xZS )	
TypedFielda\  A doc field that is grouped and has type information for the arguments.  It
    always has an argument.  The argument can be linked using the given
    *rolename*, the type using the given *typerolename*.

    Two uses are possible: either parameter and type description are given
    separately, using a field from *names* and one from *typenames*,
    respectively, or both are given using a field from *names*, see the example.

    Example::

       :param foo: description of parameter foo
       :type foo:  SomeClass

       -- or --

       :param SomeClass foo: description of parameter foo
    Tc                H    t         |   |||||       || _        || _        y r   )r{   r2   	typenamestyperolename)	r1   r+   r,   r   r-   r/   r   r|   r}   s	           r   r2   zTypedField.__init__  s)     	ueX|D"(r   c           	         d fd}t        j                  d j                        }t        |      dk(  r j                  r|d   \  }	}
 ||	|
      }n: j                         }|D ]%  \  }	}
|t        j                  d ||	|
            z  }' t        j                  d|      }t        j                  d||      S )Nc                   t        j                         }|j                  
j                  
j                  | t
        j                               | v r|t        j                  d      z  }j                  |       }t        |      dk(  rpt        |d   t         j                        rS|d   j                         }|j                  
j                  
j                  |t
        j                  	             n||z  }|t        j                  d      z  }t        d |D              }|r|t        j                  d      z  }||z  }|S )	N)rI   z (r!   r   rY   )c              3  X   K   | ]"  }|j                         j                          $ y wr   )r]   strip).0cs     r   	<genexpr>z=TypedField.make_field.<locals>.handle_item.<locals>.<genexpr>D  s     BQahhj..0Bs   (*r   )r   r%   r\   rR   r/   r   r   r[   popr"   r#   r]   r   rw   any)rT   rU   r   	fieldtypetypenamehas_contentrE   rI   rJ   r4   r1   r`   s         r   handle_itemz*TypedField.make_field.<locals>.handle_item'  s.   //#CJJMM68X5L5LRU   
 5 uzz$'' "IIh/	y>Q&:ilEJJ+O(|224HJJ --"$$55 #$+%- ( 
 9$Cuzz#&B'BBKuzz&))wJr   r5   r!   r   )rT   r   rU   rn   rg   nodes.paragraph)	r   rZ   r-   r"   r|   r   r   r^   r_   )r1   r`   rE   r   rI   rJ   r4   r   rb   rT   rU   bodynoderc   s   ``` ```      r   rd   zTypedField.make_field  s    !	 !	F $$R4	u:?t00 %aHg(7;H~~'H%* P!'EOOBHg0NOOP$$R2	{{2y)44r   )r   r   r5   r5   r5   F)r+   r   r,   re   r   re   r-   r   r/   r   r   r   r|   rf   rg   rh   ro   r   )rq   rr   rs   rt   rv   r2   rd   r   r   s   @r   r   r      s    $ H
 "$%'")) ) #	)
 ) ) ) ) 
)& (,"&#'5555 55 !	55
 %55  55 !55 
55r   r   c                 0    d x} f G fdd
}|      S )ObjDescTc                  l    e Zd ZW  ZU dZded<   d
dZddZddZ	 	 	 	 	 	 	 	 	 	 ddZ		 	 	 	 	 	 ddZ
y	)DocFieldTransformerzTransforms field lists in "doc field" syntax into better-looking
    equivalents, using the field type definitions given on a domain.
    zdict[str, tuple[Field, bool]]typemapc                <    || _         |j                         | _        y r   )	directiveget_field_type_mapr   )r1   r   s     r   r2   zDocFieldTransformer.__init__]  s    " 335r   c                j    |D ].  }t        |t        j                        s| j                  |       0 y)z,Transform all field list children of a node.N)r#   r   
field_list	transform)r1   r&   childs      r   transform_allz!DocFieldTransformer.transform_allb  s/      	&E%!1!12u%	&r   c                    g }i }i }t        d|      D ]  }| j                  ||||        | j                  ||      }|j                  |       y)z%Transform a single field list *node*.zlist[nodes.field]N)r   _transform_step_1_transform_step_2replace_self)r1   r&   entriesgroupindicesr`   r_   new_lists          r   r   zDocFieldTransformer.transformi  sb    68')(* -t4 	HE""5'5,G	H ))'59(#r   c                   t        |      dk(  sJ t        d|d         }t        d|d         }	 |j                         j                  d d      \  }}| j
                  j                  |d      \  }	}
t        |      rt        d	|d         }|j                  }n|j                  }|	|	j                  t        |      k7  rT|dd j                         |dd  z   }|r|d
|z   z  }t        j                  |      |d<   |j                  |       |	r|
r|rt        |      dk(  rt        |d   t        j                        rt        d|	      }|d   j                         }|j!                  |j"                  | j$                  j&                  xs d||d   | j$                  j(                        }t        |      r1t        d	|d         }|j+                          |j-                  |       y |j+                          |t        j.                  ddg| z  }y |	j0                  }|
rR|D cg c]/  }t        |t        j2                  t        j                  f      s.|1 }}|r||j5                  |i       |<   y |	j6                  rA	 |j9                  d d      \  }}t        j                  |      g|j5                  |i       |<   |}t        j:                  |j<                  d      }|j>                  }|J |j@                  J |j@                  |_         |jB                  |_!        |jD                  |_"        ||z  }|	jF                  rc||v rt        d|||            }n$t        |      ||<   |	g |f}|j                  |       |	jI                  ||g      }|d   j                  |       y |	jI                  ||g      }|j                  |	||f       y # t        $ r |j                         d}}Y w xY wc c}w # t        $ r Y Aw xY w)N   znodes.field_namer   nodes.field_bodyr!   )maxsplitr5   )NNr   rX   r   )rH   rI   T)translatablez%tuple[Field, list[_FieldEntry], Node])%r"   r   r]   splitrC   r   getr(   childrenr.   rf   upperr   r[   appendr#   rR   r   r   rE   rI   clearr\   r%   r+   Inline
setdefaultrv   rsplitrD   	rawsourceparentdocumentsourcelineru   rV   )r1   r_   r   r`   group_indicesrZ   r^   fieldtype_namerT   typedescis_typefieldr%   rU   new_fieldnametyped_fieldrF   xrefsr   nargtypeargnametranslatable_contentr   group	new_entrys                            r   r   z%DocFieldTransformer._transform_step_1v  s    5zQ,eAh7
,eAh7
	?'1'8'8':'@'@PQ'@'R$NH "&!1!1.,!O,  
+.
1>I((G ))G x//4>A +1Q/557.:LLMx/!JJ}5JqMNN5!  LA%wqz5::6"<: **,#..,,NN))/R$QZ** /  (
3 $%6
1 FIOO%$$U+
  $$&%//"b"A5"AAJ==  #*WQZELL%**;U-VqWGW;B  2.x8 ##+??4#;  <A::g;N:O  2.w7"$||J,@,@tT""!!!***(.%&,mm#$*KK!' =(;M(34
 +.g,h'!2u-u% ++H7K6LMI!HOOI& ++H7K6LMINNHi78  	?'1'8'8':BHN	?n X  s/   $O '/O2O2O7 O/.O/7	PPc           
        t        j                         }|D ]  }t        |t         j                        r||z  }#|\  }}}|j	                  |j
                  i       }| j                  j                  }	| j                  j                  j                  }
| j                  j                  xs d}||j                  ||||	|
|      z  } |S )Nr5   rY   )r   r   r#   r_   r   r+   r   rI   staterJ   rE   rd   )r1   r   r`   r   entryr   r   r4   
fieldtypesrI   rJ   rE   s               r   r   z%DocFieldTransformer._transform_step_2  s     ##% 	E%-E!-2*	5("YYy~~r:
nn((....66..4"I00#% 1  	& r   N)r   zObjectDescription[ObjDescT]rg   rh   )r&   zaddnodes.desc_contentrg   rh   )r&   nodes.field_listrg   rh   )
r_   rp   r   "list[nodes.field | _EntriesTriple]r`   dict[str, _FieldTypes]r   zdict[str, int]rg   rh   )r   r   r`   r   rg   r   )rq   rr   rs   __type_params__rt   __annotations__r2   r   r   r   r   ).type_paramss   r   r   r   V  s~      +*6
&$l9l9 4l9 &	l9
 &l9 
l9\3 & 
	r   r   r   )r   .generic_baser   s     @r   +<generic parameters of DocFieldTransformer>r   V  s    ( h h hr   )r&   r   rg   rf   )'rt   
__future__r   rA   typingr   r   docutilsr   sphinxr   sphinx.localer   sphinx.utilr	   sphinx.util.nodesr
   docutils.nodesr   r   docutils.parsers.rst.statesr   sphinx.directivesr   sphinx.environmentr   sphinx.util.typingr   r   r   r   	getLoggerrq   r=   r(   r   ry   r   r   r   r   r   <module>r      s    #  &     +,333/-,P			8	$0K5 K5\=55 =5@X5 X5vh hr   