o
    h͜                     @  s$  U d dl mZ d dlZd dlmZ d dlmZmZ d dlm	Z	 d dl
mZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZmZm Z 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- erd d	lm.Z. d d
lm/Z/m0Z0 d dl1m2Z2 d dl3m4Z4 i de,j5de,j5de,j5de,j5de,j6de,j6de,j6de,j6de,j6de,j6de,j7de,j7de,j7de,j7de,j8de,j8de,j9e,j:e,j;e,j<e,j=e,j>e,j>e,j?e,j@e,jAe,jBe,jBdZCeDeEeFeG f ZHeFeH ZIeDeIeEf ZJeKdejLZMd eNd!< eKd"ZOd eNd#< eKd$ZPd eNd%< eKd&ZQd eNd'< d(d)dd4d5ZRdd7d8ZSd(d(d(d9dd=d>ZTdd@dAZUd(dBddDdEZVd(dBddGdHZWd(d)ddJdKZXd(d)ddMdNZYd(d)ddPdQZZddSdTZ[d(d)ddVdWZ\d(d)ddYdZZ]d(d)dd\d]Z^d(d^dd`daZ_d(d(dbddhdiZ`djd dkddpdqZad(d(d(d(drddvdwZbd(d(d(d(drddydzZcd(d(d(d(d{dddZdd(ddddZedddZfe,j5eUe,j6eVe,j7eWe,j8e]e,jBe^e,j<eee,j=eXe,j>eYe,j?eZe,j@e[e,jAe\e,j9ebe,j:ece,j;ediZgG dd dedjdZhdjd(d(d(djd(d(d(d(d(d
dddZidS )    )annotationsN)suppress)TYPE_CHECKING	TypedDict)warn)DocstringAttributeDocstringClassDocstringFunctionDocstringModuleDocstringParameterDocstringRaiseDocstringReceiveDocstringReturnDocstringSectionDocstringSectionAdmonitionDocstringSectionAttributesDocstringSectionClassesDocstringSectionExamplesDocstringSectionFunctionsDocstringSectionModulesDocstringSectionOtherParametersDocstringSectionParametersDocstringSectionRaisesDocstringSectionReceivesDocstringSectionReturnsDocstringSectionTextDocstringSectionTypeAliasesDocstringSectionTypeParametersDocstringSectionWarnsDocstringSectionYieldsDocstringTypeAliasDocstringTypeParameterDocstringWarnDocstringYield)docstring_warningparse_docstring_annotation)DocstringSectionKindLogLevel)Pattern)AnyLiteral)Expr)	Docstringargs	argumentsparams
parameterszkeyword argszkeyword argumentsz
other argszother argumentszother paramszother parametersz	type argsztype argumentsztype paramsztype parametersraises
exceptionsreturns)yieldsreceivesexamples
attributes	functionsmethodsclassesztype aliasesmoduleswarnswarningsz4^(?P<type>[\w][\s\w-]*):(\s+(?P<title>[^\s].*))?\s*$r(   _RE_ADMONITIONz=^(?:(?P<name>\w+)?\s*(?:\((?P<type>.+)\))?:\s*)?(?P<desc>.*)$_RE_NAME_ANNOTATION_DESCRIPTIONz^\s*<BLANKLINE>\s*$_RE_DOCTEST_BLANKLINEz(\s*#\s*doctest:.+)$_RE_DOCTEST_FLAGST)r=   	docstringr,   offsetintr=   booloptionsr)   return_ItemsBlockc                K  s  | j }|t|krg |fS |}g }t|| r!|d7 }t|| st|| t||   }|dkr9g |d fS ||| |d  gf}|d7 }|t|k r|| }	t|	r^|d d ne|	|d d ru|d |	|d d   nN|	|d d rt|	t|	  }
|d |	|
d   |rt| |d|d  d| d|d  d	|
  n|	|d r|| ||	|d  gf}nn
|d7 }|t|k sN|r|| ||d fS )
N   r        z,Confusing indentation for continuation line z in docstring, should be z * 2 = z spaces, not )lineslen_is_empty_linelstripappend
startswithr$   )rB   rC   r=   rF   rM   
new_offsetitemsindentcurrent_itemlinecont_indent rY   c/var/www/html/openai_agents/venv/lib/python3.10/site-packages/griffe/_internal/docstrings/google.py_read_block_items]   sX   
"
r[   tuple[str, int]c                K  s  | j }|t|krd|d fS |}g }t|| r#|d7 }t|| st|| t||   }|dkr;d|d fS |||   |d7 }|t|k r|| |d s]t|| r||| |d   |d7 }|t|k r|| |d s]t|| s]d|d|d fS )NrJ   rI   r   rL   
)rM   rN   rO   rP   rQ   rR   joinrstrip)rB   rC   rF   rM   rS   blockrU   rY   rY   rZ   _read_block   s$   **ra   )warn_unknown_paramswarn_missing_typesr=   rb   rc   $tuple[list[DocstringParameter], int]c             
   K  s  g }t | f||d|\}}|D ]\}	}
z|
d dd\}}W n ty8   |r6t| |	d|
d  d Y qw d| g|
dd  d}d|v ro|d	ro|dd\}}| }|	d		d
 }t
|| }n|}z	| jj| j}W n ttfy   d }Y nw z	| jj| j}W n ttfy   d }Y nw |r|r|d u rt| |	d| d |r|rtt7 | jj}||vrd| d}d| d| fD ]}||v r|d| d7 } nqt| |	| W d    n1 sw   Y  |t||||d q||fS )NrC   r=   r   :rI   -Failed to get 'name: description' pair from ''r]   ()
, optionalz%No type or annotation for parameter 'zParameter 'z+' does not appear in the function signature***. Did you mean ''?namevalue
annotationdescription)r[   split
ValueErrorr$   r^   rP   r_   endswithstripremovesuffixr%   parentr0   rs   AttributeErrorKeyErrordefaultr   rQ   r   )rB   rC   rb   rc   r=   rF   r0   r`   rS   line_numberparam_linesname_with_typert   rq   rs   r}   r/   messagestarred_namerY   rY   rZ   _read_parameters   s`   	"	

r   -tuple[DocstringSectionParameters | None, int]c                K  s$   t | fd|i|\}}t||fS NrC   )r   r   )rB   rC   rF   r0   rS   rY   rY   rZ   _read_parameters_section  s   r   )rb   2tuple[DocstringSectionOtherParameters | None, int]c                K  s&   t | f|dd|\}}t||fS )NF)rC   rb   )r   r   )rB   rC   rb   rF   r0   rS   rY   rY   rZ   _read_other_parameters_section  s   r   1tuple[DocstringSectionTypeParameters | None, int]c             
   K  s  g }t | fd|i|\}}|D ]\}}z|d dd\}	}
W n ty5   t| |d|d  d Y qw d|
 g|dd  d}
d|	v ri|	dd\}}|d	rc|d
rc|dd }t	|| }n|	}z	| j
j| j}W n ttfy   d }Y nw z	| j
j| j}W n ttfy   d }Y nw |rtt= | j
j}||vrd| d| j
jj d}d| d| fD ]}||v r|d| d7 } nqt| || W d    n1 sw   Y  |t||||
d qt||fS )NrC   r   rf   rI   rg   rh   r]   rL   ri   rj   zType parameter 'z' does not appear in the z
 signaturerl   rm   rn   ro   rp   )r[   ru   rv   r$   r^   rP   r_   rR   rw   r%   rz   type_parametersrs   r{   r|   r}   r   kindrr   rQ   r!   r   )rB   rC   rb   rF   r   r`   rS   r~   type_param_linesname_with_boundrt   rq   boundr}   type_paramsr   r   rY   rY   rZ   _read_type_parameters_section  sh   "

	r   -tuple[DocstringSectionAttributes | None, int]c             
   K  s.  g }t | f||d|\}}d }|D ]}\}}	z|	d dd\}
}W n ty:   |r8t| |d|	d  d Y qw d| g|	dd  d}d|
v rh|
dd\}}|d	}|d
}t	|| }n|
}t
ttt | j| j}W d    n1 sw   Y  |t|||d qt||fS )Nre   r   rf   rI   rg   rh   r]   rL   z()rk   rq   rs   rt   )r[   ru   rv   r$   r^   rP   r_   rx   ry   r%   r   r{   r|   	TypeErrorrz   rs   rQ   r   r   )rB   rC   r=   rF   r7   r`   rS   rs   r~   
attr_linesr   rt   rq   rY   rY   rZ   _read_attributes_section[  s6   "	

r   ,tuple[DocstringSectionFunctions | None, int]c             
   K     g }t | f||d|\}}d }|D ]V\}}	z|	d dd\}
}W n ty:   |r8t| |d|	d  d Y qw d| g|	dd  d}d|
v r[|
ddd }|
}n|
}d }|t|||d	 qt	||fS 
Nre   r   rf   rI   z2Failed to get 'signature: description' pair from 'rh   r]   ri   r   )
r[   ru   rv   r$   r^   rP   r_   rQ   r	   r   )rB   rC   r=   rF   r8   r`   rS   	signaturer~   
func_linesname_with_signaturert   rq   rY   rY   rZ   _read_functions_section  .   "	r   *tuple[DocstringSectionClasses | None, int]c             
   K  r   r   )
r[   ru   rv   r$   r^   rP   r_   rQ   r   r   )rB   rC   r=   rF   r:   r`   rS   r   r~   class_linesr   rt   rq   rY   rY   rZ   _read_classes_section  r   r   .tuple[DocstringSectionTypeAliases | None, int]c          
   
   K  s   g }t | fd|i|\}}|D ]@\}}z|d dd\}}	W n ty5   t| |d|d  d Y qw d|	 g|dd  d}	|t||	d qt	||fS )	NrC   r   rf   rI   rg   rh   r]   rq   rt   )
r[   ru   rv   r$   r^   rP   r_   rQ   r    r   )
rB   rC   rF   type_aliasesr`   rS   r~   type_alias_linesrq   rt   rY   rY   rZ   _read_type_aliases_section  s    "r   *tuple[DocstringSectionModules | None, int]c             
   K     g }t | f||d|\}}|D ]B\}}z|d dd\}	}
W n ty8   |r6t| |d|d  d Y qw d|
 g|dd  d}
|t|	|
d qt	||fS )	Nre   r   rf   rI   rg   rh   r]   r   )
r[   ru   rv   r$   r^   rP   r_   rQ   r
   r   )rB   rC   r=   rF   r;   r`   rS   r~   module_linesrq   rt   rY   rY   rZ   _read_modules_section  "   "	r   )tuple[DocstringSectionRaises | None, int]c             
   K  s   g }t | f||d|\}}|D ]G\}}z|d dd\}	}
W n ty8   |r6t| |d|d  d Y qw d|
 g|dd  d}
t|	| }	|t	|	|
d qt
||fS )	Nre   r   rf   rI   z2Failed to get 'exception: description' pair from 'rh   r]   rs   rt   )r[   ru   rv   r$   r^   rP   r_   r%   rQ   r   r   )rB   rC   r=   rF   r2   r`   rS   r~   exception_linesrs   rt   rY   rY   rZ   _read_raises_section  s$   "	
r   (tuple[DocstringSectionWarns | None, int]c             
   K  r   )	Nre   r   rf   rI   z0Failed to get 'warning: description' pair from 'rh   r]   r   )
r[   ru   rv   r$   r^   rP   r_   rQ   r"   r   )rB   rC   r=   rF   r<   r`   rS   r~   warning_linesrs   rt   rY   rY   rZ   _read_warns_section#  r   r   )multipler   c                K  sB   |rt | fd|i|S t| fd|i|\}}|| fg|fS r   )r[   ra   
splitlines)rB   rC   r   rF   	one_blockrS   rY   rY   rZ   _read_block_items_maybe?  s   r   )namedr=   r~   rM   	list[str]r   tuple[str | None, Any, str]c          	      C  s   |r#t |d }|s|rt| |d|d  d t| \}}}n!d }d|d v r>|d dd\}}|dd}nd }|d }d| g|dd  d}|||fS )	Nr   z4Failed to get name, annotation or description from 'rh   rf   rI   ri   rj   r]   )	r?   matchr$   rv   groupsru   rP   r_   r^   )	rB   r~   rM   r   r=   r   rq   rs   rt   rY   rY   rZ    _get_name_annotation_descriptionL  s&   "
r   F)r   index	gen_indexLiteral[0, 1, 2]r   str | Expr | Nonec                C  s   d }t t< | jj}|jr|jj| }n
|jr|dkr|j}|r2|jr:|jj| }W d    |S W d    |S W d    |S 1 sEw   Y  |S )Nr   )	r   	Exceptionrz   rs   is_generatorsliceelementsis_iteratoris_tuple)rB   r   r   r   rs   rY   rY   rZ   _annotation_from_parentk  s&   




r   )returns_multiple_itemsreturns_named_valuerc   r=   r   r   *tuple[DocstringSectionReturns | None, int]c             	   K     g }t | f||d|\}}	t|D ]X\}
\}}zt| |||d\}}}W n	 ty/   Y qw |r8t|| }n't| dt|dk|
d}|r_|r_|d u r_|rRt|n|
d }t| |d|  |	t
|ped||d qt||	fS )	NrC   r   r   rK   rI   r   r   r   z)No type or annotation for returned value rJ   r   )r   	enumerater   rv   r%   r   rN   reprr$   rQ   r   r   )rB   rC   r   r   rc   r=   rF   r3   r`   rS   r   r~   return_linesrq   rs   rt   returned_valuerY   rY   rZ   _read_returns_section~  8   

r   )tuple[DocstringSectionYields | None, int]c             	   K  r   )	Nr   r   r   rI   r   z(No type or annotation for yielded value rJ   r   )r   r   r   rv   r%   r   rN   r   r$   rQ   r#   r   )rB   rC   r   r   rc   r=   rF   r4   r`   rS   r   r~   yield_linesrq   rs   rt   yielded_valuerY   rY   rZ   _read_yields_section  r   r   )receives_multiple_itemsreceives_named_valuerc   r=   r   r   +tuple[DocstringSectionReceives | None, int]c             	   K  s   g }t | f||d|\}}	t|D ]X\}
\}}zt| |||d\}}}W n	 ty/   Y qw |r8t|| }nt| dt|dk|
d}|r_|r_|d u r_|rRt|n|
d }t| |d|  |	t
|ped||d qt||	fS )Nr   r   rI   r   z)No type or annotation for received value rJ   r   )r   r   r   rv   r%   r   rN   r   r$   rQ   r   r   )rB   rC   r   r   rc   r=   rF   r5   r`   rS   r   r~   receive_linesrq   rs   rt   received_valuerY   rY   rZ   _read_receives_section  r   r   )trim_doctest_flagsr   +tuple[DocstringSectionExamples | None, int]c                K  sp  t | fd|i|\}}g }d}d}g }	g }
|dD ]x}t|r;|r5|
r2|tjd|
f g }
d}q|	| q|rQ|rKtd|}t	d|}|
| q|
dr_| }|	| q|rg|	| q|
dr|	r~|tjd|	df g }	d}|rtd|}|
| q|	| q|	r|tjd|	df n|
r|tjd|
f t||fS )NrC   Fr]   rJ   ```z>>>T)ra   ru   rO   rQ   r&   r6   r^   rA   subr@   rR   textr_   r   )rB   rC   r   rF   r   rS   sub_sectionsin_code_examplein_code_blockcurrent_textcurrent_examplerW   rY   rY   rZ   _read_examples_section  sL   

r   rW   strc                 C  s
   |    S )N)rx   )rW   rY   rY   rZ   rO   C  s   
rO   c                   @  st   e Zd ZU dZded< 	 ded< 	 ded< 	 ded< 	 ded< 	 ded< 	 ded	< 	 ded
< 	 ded< 	 ded< dS )GoogleOptionsz,Options for parsing Google-style docstrings.rE   ignore_init_summaryr   r   r    returns_type_in_property_summaryr   r   rb   rc   r=   N)__name__
__module____qualname____doc____annotations__rY   rY   rY   rZ   r   Y  s,   
 r   )total
r   r   r   r   r   r   r   rb   rc   r=   r   r   list[DocstringSection]c       
   (      K  s  g }g }d}| j }|rtdtdd |||||||||	|
d
}|d o<| jduo<| jjdko<| jjo<| jjduo<| jjj}|rAdnd	}|t|k r||  }|re|	d

dr\d}|||  ny|	d

drxd}|||  nft||  }r| }|d }|d }| tv }|d	k}| pt||d  }|t|d k }|t|d k }|ot||d  }|ot||d  }|o| o||d  
d
}|o| o||d  
d
}|s|s|||  |d7 }qCg } |rdnd}!|s|r|s| d|!  |r|r| d|! d | r@|
r4d| }"t| |d|! d|" tj |||  |d7 }qC|r||rZt|rX|td|d g }tt|   }#|#| fd|d i|\}$}|$r{||$_||$ nbt| |d d\}%}|%r|rt|r|td|d g }|du r|}| d
d}|t||%|d n$tt |||  W d   n	1 sw   Y  n|||  |d7 }|t|k sJ|r|td|d |rJ|rJ| jrJ| jjrJd| jj v rJ|d	 j!	 "d}d|d	 v rJ|d	 "dd\}&}'|'g|dd }d||d	 _!|t#t$ddt%|&| d g |S )!ae  Parse a Google-style docstring.

    This function iterates on lines of a docstring to build sections.
    It then returns this list of sections.

    Parameters:
        docstring: The docstring to parse.
        ignore_init_summary: Whether to ignore the summary in `__init__` methods' docstrings.
        trim_doctest_flags: Whether to remove doctest flags from Python example blocks.
        returns_multiple_items: Whether to parse multiple items in `Yields` and `Returns` sections.
            When true, each item's continuation lines must be indented.
            When false (single item), no further indentation is required.
        returns_named_value: Whether to parse `Yields` and `Returns` section items as name and description, rather than type and description.
            When true, type must be wrapped in parentheses: `(int): Description.`. Names are optional: `name (int): Description.`.
            When false, parentheses are optional but the items cannot be named: `int: Description`.
        receives_multiple_items: Whether to parse multiple items in `Receives` sections.
            When true, each item's continuation lines must be indented.
            When false (single item), no further indentation is required.
        receives_named_value: Whether to parse `Receives` section items as name and description, rather than type and description.
            When true, type must be wrapped in parentheses: `(int): Description.`. Names are optional: `name (int): Description.`.
            When false, parentheses are optional but the items cannot be named: `int: Description`.
        returns_type_in_property_summary: Whether to parse the return type of properties
            at the beginning of their summary: `str: Summary of the property`.
        warn_unknown_params: Warn about documented parameters not appearing in the signature.
        warn_missing_types: Warn about missing types/annotations for parameters, return values, etc.
        warnings: Whether to log warnings at all.
        **options: Swallowing keyword arguments for backward-compatibility.

    Returns:
        A list of docstring sections.
    FzDPassing additional options is deprecated, these options are ignored.rK   )
stacklevelr   r   N__init__r   rL   r   TtitletyperI   section
admonitionzMissing blank line above zExtraneous blank line below z titlez; z	Possible z skipped, reasons: r]   rC   )rC   -)r   r   r   propertyrf   rJ   )rt   rs   )&rM   r   DeprecationWarningrz   rq   is_functionis_classrN   lowerrP   rR   rQ   r>   r   	groupdict_section_kindrO   r^   r$   r'   debuganyr   r_   _section_readerr   ra   replacer   r   
IndexErroris_attributelabelsrr   ru   r   r   r%   )(rB   r   r   r   r   r   r   r   rb   rc   r=   rF   sectionscurrent_sectionr   rM   ignore_summaryrC   
line_lowerr   r   r   admonition_type
is_sectionhas_previous_lineblank_line_abovehas_next_linehas_next_linesblank_line_belowblank_lines_belowindented_line_belowindented_lines_belowreasonsr   reasons_stringreaderr   contentsrs   rW   rY   rY   rZ   parse_googler  s   /

	





Qr  )
rB   r,   rC   rD   r=   rE   rF   r)   rG   rH   )rB   r,   rC   rD   rF   r)   rG   r\   )rB   r,   rC   rD   rb   rE   rc   rE   r=   rE   rF   r)   rG   rd   )rB   r,   rC   rD   rF   r)   rG   r   )
rB   r,   rC   rD   rb   rE   rF   r)   rG   r   )
rB   r,   rC   rD   rb   rE   rF   r)   rG   r   )
rB   r,   rC   rD   r=   rE   rF   r)   rG   r   )
rB   r,   rC   rD   r=   rE   rF   r)   rG   r   )
rB   r,   rC   rD   r=   rE   rF   r)   rG   r   )rB   r,   rC   rD   rF   r)   rG   r   )
rB   r,   rC   rD   r=   rE   rF   r)   rG   r   )
rB   r,   rC   rD   r=   rE   rF   r)   rG   r   )
rB   r,   rC   rD   r=   rE   rF   r)   rG   r   )
rB   r,   rC   rD   r   rE   rF   r)   rG   rH   )rB   r,   r~   rD   rM   r   r   rE   r=   rE   rG   r   )
rB   r,   r   r   r   rE   r   rD   rG   r   )rB   r,   rC   rD   r   rE   r   rE   rc   rE   r=   rE   rF   r)   rG   r   )rB   r,   rC   rD   r   rE   r   rE   rc   rE   r=   rE   rF   r)   rG   r   )rB   r,   rC   rD   r   rE   r   rE   rc   rE   r=   rE   rF   r)   rG   r   )
rB   r,   rC   rD   r   rE   rF   r)   rG   r   )rW   r   rG   rE   )rB   r,   r   rE   r   rE   r   rE   r   rE   r   rE   r   rE   r   rE   rb   rE   rc   rE   r=   rE   rF   r)   rG   r   )j
__future__r   re
contextlibr   typingr   r   r=   r   "griffe._internal.docstrings.modelsr   r   r	   r
   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r    r!   r"   r#   !griffe._internal.docstrings.utilsr$   r%   griffe._internal.enumerationsr&   r'   r(   r)   r*   griffe._internal.expressionsr+   griffe._internal.modelsr,   r0   other_parametersr   r1   r3   r4   r5   r6   r7   r8   r:   r   r;   r<   r  tuplerD   listr   
_BlockItem_BlockItemsrH   compile
IGNORECASEr>   r   r?   r@   rA   r[   ra   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r   rO   r  r   r  rY   rY   rY   rZ   <module>   s   |	

@#
EI.)
% # #222
;