B 7r\)@s dZddlZddlmZddlmZmZddlmZddl m Z ddl m Z ddl mZmZmZdd lmZd d d gZed ejedejgZedZdaddZddZddZddZddZddZddZddZ d d!Z!e d"d#Z"e ed$d%Z#dS)&a Docstrings are another source of information for functions and classes. :mod:`jedi.evaluate.dynamic` 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)dedent)parseParserSyntaxError)u) indent_block)evaluator_method_cache)iterator_to_context_set ContextSet NO_CONTEXTS)LazyKnownContextsz\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 CsPtttrtyddlm}|aWn(tk rJ}z |aWdd}~XYnXtS)Nr)NumpyDocString) isinstance_numpy_doc_string_cache ImportErrorZnumpydoc.docscraper )r er7lib/python3.7/site-packages/jedi/evaluate/docstrings.py_get_numpy_doc_string_cls0s  rc Csvyt|jd}Wntttfk r.gSXx@|D]8\}}}||kr6td|}|rb|d}tt |Sq6WgS)zASearch `docstr` (in numpydoc format) for type(-s) of `param_str`.Z Parametersz"([^,]+(,[^,]+)*?)(,[ ]*optional)?$) r _parsed_dataKeyErrorAttributeErrorrrematchgrouplist_expand_typestr)docstr param_strZparamsZp_nameZp_typeZp_descrmrrr_search_param_in_numpydocstr=s  r c csyt|}Wntk r"dSXy|jd}||jd7}Wnttfk rXdSXx2|D]*\}}}|sr|}xt|D] }|Vq|Wq`WdS)zP Search `docstr` (in numpydoc format) for type(-s) of function returns. NZReturnsZYields)rrrrrr)rdocZreturnsZr_nameZr_typeZr_descrtype_rrr_search_return_in_numpydocstrNs r#ccstd|r6x|dD]}|ddVqWntd|rT|ddVn|drt|ddjd}|jd krxf|jd jD]N}|jd krd |jkrd VqdVq|jdkrd|j krdVqdVqWn|VdS)z@ Attempts to interpret the possible types in `type_str` z\bor\borZofrz\bof\b{z3.6)versionatomrZnumber.floatintstringbbytesstrN) rsearchsplitstrip startswithrchildrentypevalueZ string_prefixlower)type_strtZnodeZleafrrrres$        rcsHfddtD}x*|D]"}||}|rt|dgSqWt|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).0p)rrr sz+_search_param_in_docstr..r)DOCSTRING_PARAM_PATTERNSr/_strip_rst_rolerr )rrZpatternspatternrr)rr_search_param_in_docstrs   rAcCs 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)r7rrrrr?s  r?c Csttd}|dkrgSx td|D]}d||}q&W|jj}y|j|t|dd}Wnt k rrgSXy&t | }|j dj dj d}Wnt tfk rgSX|jdkrgSd d lm}||j||} | } tt| |S) Nz def pseudo_docstring_stuff(): ''' Create a pseudo function for docstring statements. Need this docstring so that if the below part is not valid Python this is still a function. ''' {} z((?:\w+\.)*\w+)\.z import %s F)Zerror_recovery)namer'Z atom_exprr)FunctionContext)rrrfindall evaluatorZlatest_grammarrformatrrnextZ iter_funcdefsr3r IndexErrorr4jedi.evaluate.contextrFZget_function_executionr_execute_types_in_stmt) module_contextr+codeelementZgrammarmoduleZfuncdefstmtrFfunction_contextZfunc_execution_contextrrr_evaluate_for_statement_strings2   rTcs"|}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|VqdS)N)_execute_array_valuesrH)r;d)rNrr sz)_execute_types_in_stmt..)Z eval_noder from_sets)rNrRZ definitionsr)rNrrMs  rMcsvddlm}m}t||rjg}x:|D].}tfdd|D}|t |q(W||j |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)SequenceLiteralContext FakeSequencec3s|]}t|VqdS)N)rU)r;typ)rHrrrWsz(_execute_array_values..N) Zjedi.evaluate.context.iterablerYrZr Z py__iter__r rXZinferappendr Z array_typeZexecute_evaluated)rHZarrayrYrZvaluesZ lazy_contextZobjectsr)rHrrUs  rUcsddlm}ddlm}fdd}|}|jdkrDtS||}t ||rt |j |r|j dkr|j j j}|||O}|S)Nr)InstanceArguments)FunctionExecutionContextcs"tfddt|jjDS)Nc3s"|]}t|D] }|VqqdS)N)rT)r;rr<)rNrrrWsz6infer_param..eval_docstring..)r from_iterablerArEr5)Z docstring)rNparamrreval_docstrings z#infer_param..eval_docstringZlambdef__init__)Zjedi.evaluate.context.instancer^rLr_get_root_contextZget_parent_functionr4r py__doc__r Zvar_argsrSZ py__name__instance class_context)Zexecution_contextrar^r_rbfunctypesrgr)rNrar infer_param s       rjccs@dd}x2||D]"}xt||D] }|Vq*WqWdS)NcssHx*tD]"}||}|rt|dVqWxt|D] }|Vq6WdS)Nr)DOCSTRING_RETURN_PATTERNSr/r?rr#)rOr<rr"rrrsearch_return_in_docstr(s   z3infer_return_types..search_return_in_docstr)rerTrd)rSrlr7Z type_evalrrrinfer_return_types%s rm)$__doc__rtextwraprZparsorrZjedi._compatibilityrZjedi.evaluate.utilsrZjedi.evaluate.cacherZjedi.evaluate.base_contextrr r Zjedi.evaluate.lazy_contextr r>r9MrkrBrrr r#rrAr?rTrMrUrjrmrrrrs6        !3