a
    ÷£Be`&  ã                   @   sú   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 d	ej¡e d
ej¡gZe d¡Zdadd„ Zdd„ Zdd„ Zdd„ Zdd„ Zdd„ Zdd„ Zdd„ Zdd„ Ze	ƒ dd„ ƒZe	ƒ ed d!„ ƒƒZ dS )"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                  C   s&   t tttfƒrt‚ddlm}  | atS )Nr   ©ÚNumpyDocString)Ú
isinstanceÚ_numpy_doc_string_cacheÚImportErrorÚSyntaxErrorZnumpydoc.docscraper   r
   © r   ú\/home/yuhw/wc/wire-cell-python/wcpy/lib/python3.9/site-packages/jedi/inference/docstrings.pyÚ_get_numpy_doc_string_cls/   s
    r   c              	   C   s²   t  ¡ �T t  d¡ ztƒ | ƒjd }W n$ tyL   g  Y W  d  ƒ S 0 W d  ƒ n1 sb0    Y  |D ]<\}}}||krpt d|¡}|rœ| d¡}t	t
|ƒƒ  S qpg S )zASearch `docstr` (in numpydoc format) for type(-s) of `param_str`.ÚignoreZ
ParametersNz"([^,]+(,[^,]+)*?)(,[ ]*optional)?$é   )ÚwarningsÚcatch_warningsÚsimplefilterr   Ú_parsed_dataÚ	ExceptionÚreÚmatchÚgroupÚlistÚ_expand_typestr)ÚdocstrÚ	param_strÚparamsZp_nameÚp_typeZp_descrÚmr   r   r   Ú_search_param_in_numpydocstr8   s    

6
r$   c              	   c   s¾   t  ¡ �J t  d¡ ztƒ | ƒ}W n  tyB   Y W d  ƒ dS 0 W d  ƒ n1 sX0    Y  z|jd }||jd 7 }W n ty’   Y dS 0 |D ] \}}}|sª|}t|ƒE dH  q˜dS )zP
    Search `docstr` (in numpydoc format) for type(-s) of function returns.
    r   NZReturnsZYields)r   r   r   r   r   r   r   )r   ÚdocÚreturnsZr_nameZr_typeZr_descrr   r   r   Ú_search_return_in_numpydocstrK   s    

2
r'   c                 c   sä   t  d| ¡r2|  d¡D ]}| d¡d  ¡ V  qn®t  d| ¡rP|  d¡d V  n�|  d¡rÚt| dd�jd }|jd	kràt|jd
 dg ƒD ]N}|jdkr°d|j	v r¨dV  qÖdV  qˆ|jdkrˆd|j
 ¡ v rÐdV  qˆdV  qˆn| V  dS )z@
    Attempts to interpret the possible types in `type_str`
    z\bor\bÚorZ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ÚvalueZstring_prefixÚlower)Útype_strÚtÚnodeÚleafr   r   r   r   c   s$    





r   c                    sH   ‡ fdd„t D ƒ}|D ]&}| | ¡}|rt| d¡ƒg  S qt| ˆ ƒS )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']

    c                    s    g | ]}t  |t  ˆ ¡ ¡‘qS r   )r   ÚcompileÚescape©Ú.0Úp©r    r   r   Ú
<listcomp>–   s   ÿz+_search_param_in_docstr.<locals>.<listcomp>r   )ÚDOCSTRING_PARAM_PATTERNSr5   Ú_strip_rst_roler   r$   )r   r    ÚpatternsÚpatternr   r   rF   r   Ú_search_param_in_docstr„   s    
ÿ
rL   c                 C   s    t  | ¡}|r| d¡S | S d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   N)ÚREST_ROLE_PATTERNr   r   )r=   r   r   r   r   rI       s    

rI   c           	   	   C   sä   |d u rg S t  d|¡}d dd„ |D ƒ¡}|› d|› �}tjd|dd� | jj}z|j|dd	�}W n tyz   g  Y S 0 z|j	d
 }W n t
tfy¤   g  Y S 0 |jdvr´g S ddlm} || | j|g d�}tt| ¡ |ƒƒS )Nz((?:\w+\.)*\w+)\.Ú
c                 s   s   | ]}d |› �V  qdS )zimport Nr   rC   r   r   r   Ú	<genexpr>½   ó    z._infer_for_statement_string.<locals>.<genexpr>zParse docstring code %sÚBLUE©ÚcolorF)Zerror_recoveryéþÿÿÿ)Únamer+   Z	atom_exprr   )ÚDocstringModule)Zin_module_contextÚinference_stateZmodule_nodeZ
code_lines)r   ÚfindallÚjoinr   ÚdbgrW   Úgrammarr   r   r,   ÚAttributeErrorÚ
IndexErrorr9   Zjedi.inference.docstring_utilsrV   r   Ú_execute_types_in_stmtZ
as_context)	Úmodule_contextr1   Zpotential_importsZimportsr[   ÚmoduleÚstmtrV   r#   r   r   r   Ú_infer_for_statement_string¶   s2    


ürb   c                    s"   ˆ   |¡}t ‡ fd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   s   | ]}t ˆ j|ƒV  qd S ©N)Ú_execute_array_valuesrW   )rD   Úd©r_   r   r   rO   â   s   ÿz)_execute_types_in_stmt.<locals>.<genexpr>)Z
infer_noder   Ú	from_sets)r_   ra   Zdefinitionsr   rf   r   r^   Û   s    
þr^   c           	         sŽ   ddl m}m}m} t||ƒr‚|jdv r‚g }| ¡ D ].}t ‡ fdd„| 	¡ D ƒ¡}| 
t|ƒ¡ q4|jdkrr|n|}|ˆ |ƒhS | ¡ S 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   s   | ]}t ˆ |ƒV  qd S rc   )rd   )rD   Útyp©rW   r   r   rO   ñ   s   ÿz(_execute_array_values.<locals>.<genexpr>rk   N)Zjedi.inference.value.iterablerh   ri   rj   r   Z
array_typeZ
py__iter__r   rg   ZinferÚappendr	   Zexecute_annotation)	rW   Úarrayrh   ri   rj   ÚvaluesZ
lazy_valueÚobjectsÚclsr   rm   r   rd   è   s    þrd   c                    sr   ‡ ‡fdd„}|   ¡ ‰ ˆ ¡ }|jdkr,tS ||  ¡ ƒ}|  ¡ r^|  ¡ dkr^||| j ¡ ƒO }tj	d|dd� |S )Nc                    s    t ‡ fdd„t| ˆjjƒD ƒƒS )Nc                 3   s"   | ]}t ˆ |ƒD ]
}|V  qqd S rc   )rb   )rD   r    rE   rf   r   r   rO   ÿ   s   þz7infer_param.<locals>.infer_docstring.<locals>.<genexpr>)r   rL   rU   r;   )Ú	docstring©r_   Úparamr   r   Úinfer_docstringþ   s    þz$infer_param.<locals>.infer_docstringZlambdefÚ__init__z#Found param types for docstring: %srQ   rR   )
Úget_root_contextZget_parent_functionr9   r   Ú	py__doc__Zis_bound_methodZ
py__name__Zclass_contextr   rZ   )Úfunction_valueru   rv   ÚfuncÚtypesr   rt   r   Úinfer_paramü   s    

ÿr}   c                 c   s2   dd„ }||   ¡ ƒD ]}t|  ¡ |ƒE d H  qd S )Nc                 s   s:   t D ]"}| | ¡}|rt| d¡ƒV  qt| ƒE d H  d S )Nr   )ÚDOCSTRING_RETURN_PATTERNSr5   rI   r   r'   )ÚcoderE   r   r   r   r   Úsearch_return_in_docstr  s
    
z3infer_return_types.<locals>.search_return_in_docstr)ry   rb   rx   )rz   r€   r=   r   r   r   Úinfer_return_types  s    r�   )!Ú__doc__r   r   Zparsor   r   Zjedir   Zjedi.inference.cacher   Zjedi.inference.base_valuer   r   r   Zjedi.inference.lazy_valuer	   rH   rA   ÚMr~   rM   r   r   r$   r'   r   rL   rI   rb   r^   rd   r}   r�   r   r   r   r   Ú<module>   s6   þ
	!%
