B A!p\9Kã@srdZddlmZmZmZddlZddlmZddlm Z ddlm Z ddl m mZ Gdd„de ƒZd d „ZdS) zHPylint plugin for checking in Sphinx, Google, or Numpy style docstrings é)Úprint_functionÚdivisionÚabsolute_importN)ÚIAstroidChecker)Ú BaseChecker)Úutilsc@s>eZdZdZeZdZddddddd d d gifd d ddd dgifddddd dgifdddd dgifdddœ Zdddd d!d"œfd#ddd d$d"œfd%ddd d&d"œfd'ddd d(d"œfd)d*d+ee j ƒd,d-œffZ d.Z d/d0hZ d1d2hZd3d4„Zd5d6„Zd7d8„Zd9d:„Zd;d<„Zd=d>„Zd?d@„ZdAdB„ZdLdDdE„ZdFdG„ZdHdI„ZdJdK„ZdCS)MÚDocstringParameterCheckeraÜChecker for Sphinx, Google, or Numpy style docstrings * Check that all function, method and constructor parameters are mentioned in the params and types part of the docstring. Constructor parameters can be documented in either the class docstring or ``__init__`` docstring, but not both. * Check that there are no naming inconsistencies between the signature and the documentation, i.e. also report documented parameters that are missing in the signature. This is important to find cases where parameters are renamed only in the code, not in the documentation. * Check that all explicitly raised exceptions in a function are documented in the function docstring. Caught exceptions are ignored. Activate this checker by adding the line:: load-plugins=pylint.extensions.docparams to the ``MASTER`` section of your ``.pylintrc``. :param linter: linter object :type linter: :class:`pylint.lint.PyLinter` Zparameter_documentation)z@"%s" has constructor parameters documented in class and __init__zmultiple-constructor-doczAPlease remove parameter declarations in the class or constructor.)z#"%s" not documented as being raisedzmissing-raises-docz:Please document exceptions for all raised exception types.)zRedundant returns documentationzredundant-returns-docz>Please remove the return/rtype documentation from this method.)zRedundant yields documentationzredundant-yields-docz8Please remove the yields documentation from this method.zMissing return documentationzmissing-return-docz8Please add documentation about what this method returns.Z old_names)ZW9007zmissing-returns-doc)z!Missing return type documentationzmissing-return-type-docz1Please document the type returned by this method.zMissing yield documentationzmissing-yield-docz:Please add documentation about what this generator yields.)ZW9009zmissing-yields-doc)z Missing yield type documentationzmissing-yield-type-docz0Please document the type yielded by this method.z'"%s" missing in parameter documentationzmissing-param-docz5Please add parameter declarations for all parameters.)ZW9003zmissing-param-docz,"%s" missing in parameter type documentationzmissing-type-docz:Please add parameter type declarations for all parameters.)ZW9004zmissing-type-doc)z)"%s" differing in parameter documentationzdiffering-param-docz-Please check parameter names in declarations.)z."%s" differing in parameter type documentationzdiffering-type-docz2Please check parameter names in type declarations.) ZW9005ZW9006ZW9008ZW9010ZW9011ZW9012ZW9013ZW9014ZW9015ZW9016ZW9017ZW9018zaccept-no-param-docTZynzzmWhether to accept totally missing parameter documentation in the docstring of a function that has parameters.)ÚdefaultÚtypeÚmetavarÚhelpzaccept-no-raise-doczoWhether to accept totally missing raises documentation in the docstring of a function that raises an exception.zaccept-no-return-doczoWhether to accept totally missing return documentation in the docstring of a function that returns a statement.zaccept-no-yields-doczWWhether to accept totally missing yields documentation in the docstring of a generator.zdefault-docstring-typeZchoicer zRIf the docstring type cannot be guessed the specified docstring type will be used.)r r Úchoicesr éþÿÿÿÚ__init__Ú__new__ÚselfÚclscCs:t |j|jj¡}| ||¡| ||¡| ||¡dS)z¿Called for function and method definitions (def). :param node: Node for a function or method definition in the AST :type node: :class:`astroid.scoped_nodes.Function` N)rÚ docstringifyÚdocÚconfigÚdefault_docstring_typeÚcheck_functiondef_paramsÚcheck_functiondef_returnsÚcheck_functiondef_yields)rÚnodeÚnode_doc©rú:lib/python3.7/site-packages/pylint/extensions/docparams.pyÚvisit_functiondef¼s  z+DocstringParameterChecker.visit_functiondefcCs’d}|j|jkr|t |¡}|dk r|t |j|jj¡}|  |||¡|  ¡pT|  ¡pTd}|  ¡ph|  ¡phd}|  ||j ||¡|  ||j ||¡dS)N)ÚnameÚconstructor_namesÚ checker_utilsZnode_frame_classrrrrrÚcheck_single_constructor_paramsÚ has_paramsÚparams_documented_elsewhereÚcheck_arguments_in_docstringÚargs)rrrZnode_allow_no_paramÚ class_nodeÚ class_docZclass_allow_no_paramrrrrÇs"  z2DocstringParameterChecker.check_functiondef_paramscCsZ|js| ¡s| ¡rdS| tj¡}| ¡s6| ¡rVtdd„|DƒƒsV|j d|ddS)Ncss|]}t |¡VqdS)N)rÚreturns_something)Ú.0Zret_noderrrú ìszFDocstringParameterChecker.check_functiondef_returns..zredundant-returns-doc)r) Úsupports_yieldsÚ is_generatorÚ is_abstractZnodes_of_classÚastroidZReturnÚ has_returnsÚ has_rtypeÚanyÚ add_message)rrrZ return_nodesrrrræs  z3DocstringParameterChecker.check_functiondef_returnscCs<|jr| ¡rdS| ¡s"| ¡r8| ¡s8|jd|ddS)Nzredundant-yields-doc)r)r,r.Ú has_yieldsÚhas_yields_typer-r3)rrrrrrrðs z2DocstringParameterChecker.check_functiondef_yieldsc Cs | ¡}t|tjƒsdSt |¡}|s*dS|jsBt |¡}|rB|}t |j|j j ¡}|  ¡sr|jrn|  ||¡dS|  ¡}dd„|Dƒ}||}| ||¡dS)NcSsh|]}| d¡d’qS)Ú.éÿÿÿÿ)Úsplit)r*Úexcrrrú sz8DocstringParameterChecker.visit_raise..)ÚframeÚ isinstancer/Ú FunctionDefrZpossible_exc_typesrZget_setters_propertyrrrÚis_validÚ_handle_no_raise_docÚ exceptionsÚ_add_raise_message) rrÚ func_nodeZ expected_excsZ property_rZfound_excs_full_namesZfound_excs_class_namesÚ missing_excsrrrÚ visit_raiseùs&    z%DocstringParameterChecker.visit_raisecCs¨t |¡sdS| ¡}t|tjƒs&dSt |j|jj ¡}|  ¡sL|jj rLdSt   |¡}| ¡sx| ¡rj|sx|jd|d|jr‚dS| ¡s¤| ¡r–|s¤|jd|ddS)Nzmissing-return-doc)rzmissing-return-type-doc)rr)r;r<r/r=rrrrr>Zaccept_no_return_docr!Zdecorated_with_propertyr0Zhas_property_returnsr3Zreturnsr1Zhas_property_type)rrrBrZ is_propertyrrrÚ visit_returns   z&DocstringParameterChecker.visit_returncCsŽ| ¡}t|tjƒsdSt |j|jj¡}|  ¡s>|jj r>dS|j rV|  ¡}|  ¡}n| ¡}| ¡}|sx|jd|d|sŠ|jd|ddS)Nzmissing-yield-doc)rzmissing-yield-type-doc)r;r<r/r=rrrrrr>Zaccept_no_yields_docr,r4r5r0r1r3)rrrBrZdoc_has_yieldsZdoc_has_yields_typerrrÚ visit_yield.s  z%DocstringParameterChecker.visit_yieldcCs| |¡dS)N)rF)rrrrrÚvisit_yieldfromDsz)DocstringParameterChecker.visit_yieldfromNc s:|js dS|dkrˆjj}| ¡‰dd„|jDƒ‰ˆ dd„|jDƒ¡ˆj ¡}|j dk rtˆ  |j ¡|  |j ¡|j dk r–ˆ  |j ¡|  |j ¡|  ¡\}}|s²|s²|r²d‰‡‡‡‡fdd„}‡‡‡fd d „} ||d ˆjƒx,t |jƒD]\} } |j| rî|  | j¡qîW||d |ƒ| |d ˆjƒ| |d|ƒdS)aªCheck that all parameters in a function, method or class constructor on the one hand and the parameters mentioned in the parameter documentation (e.g. the Sphinx tags 'param' and 'type') on the other hand are consistent with each other. * Undocumented parameters except 'self' are noticed. * Undocumented parameter types except for 'self' and the ``*`` and ``**`` parameters are noticed. * Parameters mentioned in the parameter documentation that don't or no longer exist in the function parameter list are noticed. * If the text "For the parameters, see" or "For the other parameters, see" (ignoring additional whitespace) is mentioned in the docstring, missing parameter documentation is tolerated. * If there's no Sphinx style, Google style or NumPy style parameter documentation at all, i.e. ``:param`` is never mentioned etc., the checker assumes that the parameters are documented in another format and the absence is tolerated. :param doc: Docstring for the function, method or class. :type doc: str :param arguments_node: Arguments node for the function, method or class constructor. :type arguments_node: :class:`astroid.scoped_nodes.Arguments` :param warning_node: The node to assign the warnings to :type warning_node: :class:`astroid.scoped_nodes.Node` :param accept_no_param_doc: Whether or not to allow no parameters to be documented. If None then this value is read from the configuration. :type accept_no_param_doc: bool or None NcSsh|] }|j’qSr)r)r*Úargrrrr:uszIDocstringParameterChecker.check_arguments_in_docstring..css|] }|jVqdS)N)r)r*rHrrrr+vszIDocstringParameterChecker.check_arguments_in_docstring..Tcs4ˆs0ˆ||}|r0ˆj|d t|ƒ¡fˆddS)aCompare the found argument names with the expected ones and generate a message if there are arguments missing. :param set found_argument_names: argument names found in the docstring :param str message_id: pylint message id :param not_needed_names: names that may be omitted :type not_needed_names: set of str z, )r&rN)r3ÚjoinÚsorted)Úfound_argument_namesÚ message_idÚnot_needed_namesZmissing_argument_names)Úexpected_argument_namesrÚtolerate_missing_paramsÚ warning_noderrÚ_compare_missing_args…s zUDocstringParameterChecker.check_arguments_in_docstring.._compare_missing_argscs4ˆ|A|ˆ}|r0ˆj|d t|ƒ¡fˆddS)a”Compare the found argument names with the expected ones and generate a message if there are extra arguments found. :param set found_argument_names: argument names found in the docstring :param str message_id: pylint message id :param not_needed_names: names that may be omitted :type not_needed_names: set of str z, )r&rN)r3rIrJ)rKrLrMZdiffering_argument_names)rNrrPrrÚ_compare_different_argsœs zWDocstringParameterChecker.check_arguments_in_docstring.._compare_different_argszmissing-param-doczmissing-type-doczdiffering-param-doczdiffering-type-doc)rrÚaccept_no_param_docr$r&ÚupdateZ kwonlyargsÚnot_needed_param_in_docstringÚcopyZvarargÚaddZkwargZmatch_param_docsÚ enumerateZ annotationsr) rrZarguments_noderPrSZnot_needed_type_in_docstringZparams_with_docZparams_with_typerQrRÚindexZarg_namer)rNrrOrPrr%Gs<&             z6DocstringParameterChecker.check_arguments_in_docstringcCs(| ¡r$| ¡r$|jd|jf|ddS)Nzmultiple-constructor-doc)r&r)r#r3r)rr(Zinit_docr'rrrr"Èsz9DocstringParameterChecker.check_single_constructor_paramscCs|jjr dS| ||¡dS)N)rZaccept_no_raise_docrA)rZexcsrrrrr?Îsz.DocstringParameterChecker._handle_no_raise_doccCsT| ¡r,y| d¡Wntk r*YnX|s4dS|jdd t|ƒ¡f|ddS)a Adds a message on :param:`node` for the missing exception type. :param missing_excs: A list of missing exception types. :type missing_excs: set(str) :param node: The node show the message on. :type node: astroid.node_classes.NodeNG ÚNotImplementedErrorNzmissing-raises-docz, )r&r)r.ÚremoveÚKeyErrorr3rIrJ)rrCrrrrrAÔs z,DocstringParameterChecker._add_raise_message)N)Ú__name__Ú __module__Ú __qualname__Ú__doc__rZ__implements__rZmsgsÚlistrZDOCSTRING_TYPESZoptionsZpriorityr rUrrrrrDrErFrGr%r"r?rArrrrrsˆ         rcCs| t|ƒ¡dS)zRequired method to auto register this checker. :param linter: Main interface object for Pylint plugins :type linter: Pylint object N)Zregister_checkerr)ZlinterrrrÚregisterìsrb)r`Z __future__rrrr/Zpylint.interfacesrZpylint.checkersrrr!Z#pylint.extensions._check_docs_utilsÚ extensionsZ_check_docs_utilsrrbrrrrÚs   R