Ë
    ¬;jt&  ã                   óx  — d Z ddl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mZmZ ddlmZ g d¢Z ej"                  d	ej$                  «       ej"                  d
ej$                  «      gZ ej"                  d«      Zdad„ Zd„ Zd„ Zd„ Zd„ Zd„ Zd„ Zd„ Zd„ Z e	«       d„ «       Z e	«       ed„ «       «       Z y)a©  
Docstrings are another source of information for functions and classes.
:mod:`jedi.inference.dynamic_params` tries to find all executions of functions,
while the docstring parsing is much easier. There are three different types of
docstrings that |jedi| understands:

- `Sphinx <http://sphinx-doc.org/markup/desc.html#info-field-lists>`_
- `Epydoc <http://epydoc.sourceforge.net/manual-fields.html>`_
- `Numpydoc <https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt>`_

For example, the sphinx annotation ``:type foo: str`` clearly states that the
type of ``foo`` is ``str``.

As an addition to parameter searching, this module also provides return
annotations.
é    N)ÚparseÚParserSyntaxError)Údebug)Úinference_state_method_cache)Úiterator_to_value_setÚValueSetÚ	NO_VALUES)ÚLazyKnownValues)z\s*:type\s+%s:\s*([^\n]+)z\s*:param\s+(\w+)\s+%s:[^\n]*z\s*@type\s+%s:\s*([^\n]+)z\s*:rtype:\s*([^\n]+)z\s*@rtype:\s*([^\n]+)z:[^`]+:`([^`]+)`c                  ó^   — t        t        t        t        f«      rt        ‚ddlm}  | at        S )Nr   ©ÚNumpyDocString)Ú
isinstanceÚ_numpy_doc_string_cacheÚImportErrorÚSyntaxErrorÚnumpydoc.docscraper   r   s    új/workspace/moltex-experiments/.pixi/envs/default/lib/python3.12/site-packages/jedi/inference/docstrings.pyÚ_get_numpy_doc_string_clsr   /   s'   € äÔ)¬K¼Ð+EÔFÜ%Ð%Ý1Ø,ÐÜ"Ð"ó    c                 ó’  — t        j                  «       5  t        j                  d«       	  t        «       | «      j                  d   }	 ddd«       D ]J  \  }}}||k(  sŒt        j                  d|«      }|r|j                  d«      }t        t        |«      «      c S  g S # t
        $ r g cY cddd«       S w xY w# 1 sw Y   ŒtxY w)zASearch `docstr` (in numpydoc format) for type(-s) of `param_str`.ÚignoreÚ
ParametersNz"([^,]+(,[^,]+)*?)(,[ ]*optional)?$é   )ÚwarningsÚcatch_warningsÚsimplefilterr   Ú_parsed_dataÚ	ExceptionÚreÚmatchÚgroupÚlistÚ_expand_typestr)ÚdocstrÚ	param_strÚparamsÚp_nameÚp_typeÚp_descrÚms          r   Ú_search_param_in_numpydocstrr+   8   s½   € ä	×	 Ñ	 Õ	"Ü×Ñ˜hÔ'ð	ð 1Ô.Ó0°Ó8×EÑEÀlÑS‰F÷ 
#ó $*Ñˆ�˜Ø�YÓÜ—‘Ð>ÀÓGˆAÙØŸ™ ›�Üœ¨Ó/Ó0Ò0ð $*ð €Iøô ò 	Ø‰I÷ 
#Ñ	"ð	ú÷ 
#Ð	"ús(   •B=¬B#Â#B:Â.B=Â9B:Â:B=Â=Cc              #   ó„  K  — t        j                  «       5  t        j                  d«       	  t        «       | «      }	 ddd«       	 j
                  d   }||j
                  d   z  }|D ]  \  }}}|s|}t        |«      E d{  –—†  Œ y# t        $ r Y ddd«       yw xY w# 1 sw Y   ŒexY w# t        $ r Y yw xY w7 Œ9­w)zP
    Search `docstr` (in numpydoc format) for type(-s) of function returns.
    r   NÚReturnsÚYields)r   r   r   r   r   r   r#   )r$   ÚdocÚreturnsÚr_nameÚr_typeÚr_descrs         r   Ú_search_return_in_numpydocstrr4   K   sÎ   è ø€ ô 
×	 Ñ	 Õ	"Ü×Ñ˜hÔ'ð	Ø-Ô+Ó-¨fÓ5‰C÷ 
#ðð ×"Ñ" 9Ñ-ˆØ�3×#Ñ# HÑ-Ñ-ˆó $+Ñˆ�˜áØˆFÜ" 6Ó*×*Ñ*ñ	 $+øô ò 	Ø÷ 
#Ð	"ð	ú÷	 
#Ð	"ûô ò Ùðúð 	+úsn   ‚C —B#®B¿C Á!B/ Á)C ÂB>ÂC Â	B ÂB#Â	C ÂB Â B#Â#B,Â(C Â/	B;Â8C Â:B;Â;C c              #   ó~  K  — t        j                  d| «      r;| j                  d«      D ]&  }|j                  d«      d   j                  «       –— Œ( yt        j                  d| «      r| j                  d«      d   –— y| j	                  d«      r¦t        | d¬«      j                  d   }|j                  d	k(  r|t        |j                  d
   dg «      D ]^  }|j                  dk(  rd|j                  v rd–— Œ%d–— Œ*|j                  dk(  sŒ:d|j                  j                  «       v rd–— Œ[d–— Œ` yy| –— y­w)z@
    Attempts to interpret the possible types in `type_str`
    z\bor\bÚorÚofr   z\bof\bÚ{z3.13)ÚversionÚatomr   ÚchildrenÚnumberÚ.ÚfloatÚintÚstringÚbÚbytesÚstrN)r   ÚsearchÚsplitÚstripÚ
startswithr   r;   ÚtypeÚgetattrÚvalueÚstring_prefixÚlower)Útype_strÚtÚnodeÚleafs       r   r#   r#   c   s  è ø€ ô
 
‡y�y�˜HÔ%Ø—‘ Ö%ˆAØ—'‘'˜$“- Ñ"×(Ñ(Ó*Ó*ñ &ô 
�‰�9˜hÔ	'Ø�n‰n˜TÓ" 1Ñ%Ó%à	×	Ñ	˜SÔ	!Ü�X vÔ.×7Ñ7¸Ñ:ˆØ�9‰9˜ÒÜ §¡¨aÑ 0°*¸bÖA�Ø—9‘9 Ò(Ø˜dŸj™jÑ(Ø%›à#›Ø—Y‘Y (Ó*Ø˜d×0Ñ0×6Ñ6Ó8Ñ8Ø%›à#›ñ Bð ð  ‹ùs   ‚DD=Ä.D=c           	      ó
  — t         D �cg c]-  }t        j                  |t        j                  |«      z  «      ‘Œ/ }}|D ]2  }|j	                  | «      }|sŒt        |j                  d«      «      gc S  t        | |«      S c c}w )aä  
    Search `docstr` for type(-s) of `param_str`.

    >>> _search_param_in_docstr(':type param: int', 'param')
    ['int']
    >>> _search_param_in_docstr('@type param: int', 'param')
    ['int']
    >>> _search_param_in_docstr(
    ...   ':type param: :class:`threading.Thread`', 'param')
    ['threading.Thread']
    >>> bool(_search_param_in_docstr('no document', 'param'))
    False
    >>> _search_param_in_docstr(':param int param: some description', 'param')
    ['int']

    r   )ÚDOCSTRING_PARAM_PATTERNSr   ÚcompileÚescaperD   Ú_strip_rst_roler!   r+   )r$   r%   ÚpÚpatternsÚpatternr    s         r   Ú_search_param_in_docstrrY   „   s€   € õ& 2ó3Ù1�Aô —
‘
˜1œrŸy™y¨Ó3Ñ3Õ4Ø1ð ð 3ãˆØ—‘˜vÓ&ˆÚÜ# E§K¡K°£NÓ3Ð4Ò4ð ô
 (¨°	Ó:Ð:ùò3s   ‰2B c                 óV   — t         j                  | «      }|r|j                  d«      S | S )a   
    Strip off the part looks like a ReST role in `type_str`.

    >>> _strip_rst_role(':class:`ClassName`')  # strip off :class:
    'ClassName'
    >>> _strip_rst_role(':py:obj:`module.Object`')  # works with domain
    'module.Object'
    >>> _strip_rst_role('ClassName')  # do nothing when not ReST role
    'ClassName'

    See also:
    http://sphinx-doc.org/domains.html#cross-referencing-python-objects

    r   )ÚREST_ROLE_PATTERNr    r!   )rM   r    s     r   rU   rU       s*   € ô ×#Ñ# HÓ-€EÙØ�{‰{˜1‹~Ðàˆr   c                 ó  — |€g S t        j                  d|«      }dj                  d„ |D «       «      }|› d|› �}t        j                  d|d¬«       | j
                  j                  }	 |j                  |d¬«      }	 |j                  d	   }|j                  d
vrg S ddlm}  || | j
                  |g ¬«      }t        t!        |j#                  «       |«      «      S # t        $ r g cY S w xY w# t        t        f$ r g cY S w xY w)Nz((?:\w+\.)*\w+)\.Ú
c              3   ó&   K  — | ]	  }d |› �–— Œ y­w)zimport N© )Ú.0rV   s     r   Ú	<genexpr>z._infer_for_statement_string.<locals>.<genexpr>½   s   è ø€ ÐAÑ/@¨!˜' ! œÑ/@ùs   ‚zParse docstring code %sÚBLUE©ÚcolorF)Úerror_recoveryéþÿÿÿ)Únamer:   Ú	atom_exprr   )ÚDocstringModule)Úin_module_contextÚinference_stateÚmodule_nodeÚ
code_lines)r   ÚfindallÚjoinr   Údbgrk   Úgrammarr   r   r;   ÚAttributeErrorÚ
IndexErrorrH   Újedi.inference.docstring_utilsri   r"   Ú_execute_types_in_stmtÚ
as_context)	Úmodule_contextr@   Úpotential_importsÚimportsrq   ÚmoduleÚstmtri   r*   s	            r   Ú_infer_for_statement_stringr|   ¶   s  € Ø€~Øˆ	äŸ
™
Ð#7¸Ó@Ðð �i‰iÑAÑ/@ÓAÓA€GØˆy˜˜6˜(Ð#€Fä	‡I�IÐ'¨°vÕ>Ø×,Ñ,×4Ñ4€GðØ—‘˜v°e�Ó<ˆðà�‰˜rÑ"ˆð ‡y�yÐ5Ñ5Øˆ	õ ?ÙØ(Ø&×6Ñ6ØØô		€Aô Ô& q§|¡|£~°tÓ<Ó=Ð=øô) ò ØŠ	ðûô
 œJÐ'ò ØŠ	ðús$   Á)C Á=C, ÃC)Ã(C)Ã,D Ã?D c                 ób   ‡ — ‰ j                  |«      }t        j                  ˆ fd„|D «       «      S )zÒ
    Executing all types or general elements that we find in a statement. This
    doesn't include tuple, list and dict literals, because the stuff they
    contain is executed. (Used as type information).
    c              3   óJ   •K  — | ]  }t        ‰j                  |«      –— Œ y ­w©N)Ú_execute_array_valuesrk   )r`   Údrw   s     €r   ra   z)_execute_types_in_stmt.<locals>.<genexpr>â   s&   øè ø€ ð áˆAô 	˜n×<Ñ<¸a×@Ùùs   ƒ #)Ú
infer_noder   Ú	from_sets)rw   r{   Údefinitionss   `  r   ru   ru   Û   s5   ø€ ð !×+Ñ+¨DÓ1€KÜ×Ñó áóó ð r   c                 ób  ‡ — ddl m}m}m} t	        ||«      rˆ|j
                  dv rzg }|j                  «       D ]H  }t        j                  ˆ fd„|j                  «       D «       «      }|j                  t        |«      «       ŒJ |j
                  dk(  r|n|} |‰ |«      hS |j                  d«      S )z—
    Tuples indicate that there's not just one return value, but the listed
    ones.  `(str, int)` means that it returns a tuple with both types.
    r   )ÚSequenceLiteralValueÚ	FakeTupleÚFakeList)Útupler"   c              3   ó6   •K  — | ]  }t        ‰|«      –— Œ y ­wr   )r€   )r`   Útyprk   s     €r   ra   z(_execute_array_values.<locals>.<genexpr>ñ   s    øè ø€ ð )á-�Cô & o°s×;Ù-ùs   ƒr‰   N)Újedi.inference.value.iterabler†   r‡   rˆ   r   Ú
array_typeÚ
py__iter__r   rƒ   ÚinferÚappendr
   Úexecute_annotation)	rk   Úarrayr†   r‡   rˆ   ÚvaluesÚ
lazy_valueÚobjectsÚclss	   `        r   r€   r€   è   s­   ø€ ÷
 XÑWÜ�%Ð-Ô.°5×3CÑ3CÐGXÑ3XØˆØ×*Ñ*Ö,ˆJÜ×(Ñ(ó )à%×+Ñ+Ô-ó)ó ˆGð �M‰Mœ/¨'Ó2Õ3ð -ð !×+Ñ+¨wÒ6‰i¸HˆÙ�O VÓ,Ð-Ð-à×'Ñ'¨Ó-Ð-r   c                 óh  ‡‡— ˆˆfd„}| j                  «       Š‰j                  «       }|j                  dk(  rt        S  || j	                  «       «      }| j                  «       r6| j                  «       dk(  r#| || j                  j	                  «       «      z  }t        j                  d|d¬«       |S )Nc                 óh   •— t        ˆfd„t        | ‰j                  j                  «      D «       «      S )Nc              3   óD   •K  — | ]  }t        ‰|«      D ]  }|–— Œ Œ y ­wr   )r|   )r`   r%   rV   rw   s      €r   ra   z7infer_param.<locals>.infer_docstring.<locals>.<genexpr>ÿ   s-   øè ø€ ð 
áQ�	Ü0°ÀÖK�ô àKð ÙQùs   ƒ )r   rY   rg   rJ   )Ú	docstringrw   Úparams    €€r   Úinfer_docstringz$infer_param.<locals>.infer_docstringþ   s.   ø€ Üó 
ä4°YÀÇ
Á
×@PÑ@PÔQó
ó 
ð 	
r   ÚlambdefÚ__init__z#Found param types for docstring: %srb   rc   )
Úget_root_contextÚget_parent_functionrH   r	   Ú	py__doc__Úis_bound_methodÚ
py__name__Úclass_contextr   rp   )Úfunction_valuer›   rœ   ÚfuncÚtypesrw   s    `   @r   Úinfer_paramr¨   ü   sœ   ù€ õ
ð $×4Ñ4Ó6€NØ×$Ñ$Ó&€DØ‡y�y�IÒÜÐá˜N×4Ñ4Ó6Ó7€EØ×%Ñ%Ô'Ø×)Ñ)Ó+¨zÒ9Ø‘ ×!=Ñ!=×!GÑ!GÓ!IÓJÑJˆä	‡I�IÐ3°UÀ&ÕIØ€Lr   c              #   ó�   K  — d„ } || j                  «       «      D ]$  }t        | j                  «       |«      E d {  –—†  Œ& y 7 Œ­w)Nc              3   ó¬   K  — t         D ]2  }|j                  | «      }|sŒt        |j                  d«      «      –— Œ4 t	        | «      E d {  –—†  y 7 Œ­w)Nr   )ÚDOCSTRING_RETURN_PATTERNSrD   rU   r!   r4   )ÚcoderV   r    s      r   Úsearch_return_in_docstrz3infer_return_types.<locals>.search_return_in_docstr  sC   è ø€ ß*ˆAØ—H‘H˜T“NˆEÚÜ% e§k¡k°!£nÓ5Ó5ð +ô
 1°Ó6×6Ò6ús   ‚A ,AÁAÁA)r¡   r|   rŸ   )r¥   r­   rM   s      r   Úinfer_return_typesr®     sC   è ø€ ò7ñ ,¨N×,DÑ,DÓ,FÖGˆÜ.¨~×/NÑ/NÓ/PÐRZÓ[×[Ñ[ñ HØ[ús   ‚:A¼A½A)!Ú__doc__r   r   Úparsor   r   Újedir   Újedi.inference.cacher   Újedi.inference.base_valuer   r   r	   Újedi.inference.lazy_valuer
   rR   rS   ÚMr«   r[   r   r   r+   r4   r#   rY   rU   r|   ru   r€   r¨   r®   r_   r   r   Ú<module>r¶      sç   ðñó" 
Û ç *å Ý =÷ñ å 5òÐ ð €B‡J�JÐ'¨¯©Ó.Ø€B‡J�JÐ'¨¯©Ó.ðÐ ð
 �B—J‘JÐ2Ó3Ð ð Ð ò#òò&+ò0òB;ò8ò,">òJ
ò.ñ( Óñó  ðñ* ÓØñ
\ó ó  ñ
\r   