
    f`&                     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    T/var/www/cvtools/html/venv/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ElSF $* 1Y>GA/001 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5C ""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      rt        | 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.7)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    
 
yyH%% 	+A''$-"((**	+ 
9h	'nnT"1%%			S	!Xu-66q999a 0*bA 
$99(djj(%#YY(*d006688%#
$   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 

1ryy334 3H 3 5v&#EKKN3445
 (	::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!'!As   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@ iiA/@AAGy6(#F	II'v>,,44Gve<r" yy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&       	n<<a@s    #)
infer_noder   	from_sets)rw   r{   definitionss   `  r   ru   ru      s5     !++D1K   r   c                 `    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                         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       ) &os;)s   r   )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%-.53C3CGX3X**, 	4J(( )%++-) G MM/'23	4 !++w6iHOV,--''))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>   s5      
0K
  

s    )r   rY   rg   rJ   )	docstringrw   params    r   infer_docstringz$infer_param.<locals>.infer_docstring   s.     
4Y

@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6N$$&DyyIN4467E%%'))+z9!=!=!G!G!IJJ	II3U&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  sH     * 	6AHHTNE%ekk!n55	6
 1666s   A,AAA)r   r|   r   )r   r   rM   s      r   infer_return_typesr     sI     7 ,N,D,D,FG \.~/N/N/PRZ[[[\[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  BJJ'.BJJ'. 
 BJJ23   #&+0B;8,">J
*(   * 
\   
\r   