U nu f`&@sdZddlZddlZddlmZmZddlmZddlm Z ddl m Z m Z m Z ddlmZdd d gZed ejed ejgZed ZdaddZddZddZddZddZddZddZddZddZe d d!Ze e d"d#Z dS)$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 `_ - `Epydoc `_ - `Numpydoc `_ 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)parseParserSyntaxError)debug)inference_state_method_cache)iterator_to_value_setValueSet NO_VALUES)LazyKnownValuesz\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:[^`]+:`([^`]+)`cCs&ttttfrtddlm}|atS)NrNumpyDocString) isinstance_numpy_doc_string_cache ImportError SyntaxErrorZnumpydoc.docscraper r r=/tmp/pip-unpacked-wheel-ol4ehs9f/jedi/inference/docstrings.py_get_numpy_doc_string_cls/s  rc CstJtdzt|jd}Wn$tk rLgYW5QRSXW5QRX|D]<\}}}||kr\td|}|r|d}t t |Sq\gS)zASearch `docstr` (in numpydoc format) for type(-s) of `param_str`.ignoreZ Parametersz"([^,]+(,[^,]+)*?)(,[ ]*optional)?$) warningscatch_warnings simplefilterr _parsed_data Exceptionrematchgrouplist_expand_typestr)docstr param_strparamsZp_nameZp_typeZp_descrmrrr_search_param_in_numpydocstr8s     r#c cst@tdzt|}Wn tk rBYW5QRdSXW5QRXz|jd}||jd7}Wntk rYdSX|D] \}}}|s|}t|EdHqdS)zP Search `docstr` (in numpydoc format) for type(-s) of function returns. rNZReturnsZYields)rrrrrrr)rdocZreturnsZr_nameZr_typeZr_descrrrr_search_return_in_numpydocstrKs   r%ccstd|r2|dD]}|ddVqntd|rP|ddVn|drt|ddjd}|jd krt|jd d gD]N}|jd krd |j krdVqdVq|jdkrd|j krdVqdVqn|VdS)z@ Attempts to interpret the possible types in `type_str` z\bor\borZofrz\bof\b{z3.7)versionatomrchildrennumber.floatintstringbbytesstrN) rsearchsplitstrip startswithrr*typegetattrvalueZ string_prefixlower)type_strtnodeZleafrrrrcs$        rcsHfddtD}|D]&}||}|rt|dgSqt|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'] cs g|]}t|tqSr)rcompileescape.0pr rr sz+_search_param_in_docstr..r)DOCSTRING_PARAM_PATTERNSr3_strip_rst_rolerr#)rr patternspatternrrrCr_search_param_in_docstrs  rIcCs t|}|r|dS|SdS)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 rN)REST_ROLE_PATTERNrr)r;rrrrrFs  rFc Cs|dkr gStd|}ddd|D}|d|}tjd|dd|jj}z|j|dd }Wntk r|gYSXz|j d }Wnt t fk rgYSX|j d krgSd d l m}|||j|gd}tt||S)Nz((?:\w+\.)*\w+)\. css|]}d|VqdS)zimport Nrr@rrr sz._infer_for_statement_string..zParse docstring code %sBLUEcolorF)Zerror_recovery)namer)Z atom_exprr)DocstringModule)Zin_module_contextinference_stateZ module_nodeZ code_lines)rfindalljoinrdbgrSgrammarrrr*AttributeError IndexErrorr7Zjedi.inference.docstring_utilsrRr_execute_types_in_stmtZ as_context) module_contextr/Zpotential_importsZimportsrWmodulestmtrRr"rrr_infer_for_statement_strings2     r^cs"|}tfdd|DS)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). c3s|]}tj|VqdSN)_execute_array_valuesrS)rAdr[rrrLsz)_execute_types_in_stmt..)Z infer_noder from_sets)r[r]Z definitionsrrbrrZs rZc sddlm}m}m}t||r|jdkrg}|D].}tfdd| D}| t |q4|jdkrr|n|}||hS| SdS)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 FakeTupleFakeList)tuplerc3s|]}t|VqdSr_)r`)rAtyprSrrrLsz(_execute_array_values..rgN) Zjedi.inference.value.iterablerdrerfr Z array_typeZ py__iter__rrcZinferappendr Zexecute_annotation) rSarrayrdrerfvaluesZ lazy_valueZobjectsclsrrirr`s  r`csrfdd}|}|jdkr,tS||}|r^|dkr^|||jO}tj d|dd|S)Ncs tfddt|jjDS)Nc3s"|]}t|D] }|VqqdSr_)r^)rAr rBrbrrrLs z7infer_param..infer_docstring..)rrIrQr9)Z docstringr[paramrrinfer_docstrings  z$infer_param..infer_docstringZlambdef__init__z#Found param types for docstring: %srMrN) get_root_contextZget_parent_functionr7r py__doc__Zis_bound_methodZ py__name__Z class_contextrrV)function_valuerorpfunctypesrrnr infer_params   rwccs2dd}||D]}t||EdHqdS)Ncss:tD]"}||}|rt|dVqt|EdHdS)Nr)DOCSTRING_RETURN_PATTERNSr3rFrr%)coderBrrrrsearch_return_in_docstrs  z3infer_return_types..search_return_in_docstr)rsr^rr)rtrzr;rrrinfer_return_typessr{)!__doc__rrZparsorrZjedirZjedi.inference.cacherZjedi.inference.base_valuerrrZjedi.inference.lazy_valuer rEr>MrxrJr rr#r%rrIrFr^rZr`rwr{rrrrs<       !%