ó '![c@`s“dZddlmZmZmZddlZddlmZddlm Z ddlm Z ddl j jZ de fd„ƒYZd „ZdS( sHPylint plugin for checking in Sphinx, Google, or Numpy style docstrings i(tprint_functiontdivisiontabsolute_importN(tIAstroidChecker(t BaseChecker(tutilstDocstringParameterCheckercB`sóeZdZeZdZi dXd6dYd 6dZd 6d[d6dddid\gd6fd6d]d6dddid^gd6fd"6d_d&6d'd(d)id`gd6fd+6d,d-d.idagd6fd06dbd46dcd86Zd9ied:6d;d<6d=d>6d?d@6fdAied:6d;d<6d=d>6dBd@6fdCied:6d;d<6d=d>6dDd@6fdEied:6d;d<6d=d>6dFd@6ffZdGZ dHdIhZ dJdKhZ dL„Z dM„Z dN„ZdO„ZdP„ZdQ„ZdR„ZdS„ZdddT„ZdU„ZdV„ZdW„ZRS(esÜ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` tparameter_documentations@"%s" has constructor parameters documented in class and __init__smultiple-constructor-docsAPlease remove parameter declarations in the class or constructor.tW9005s#"%s" not documented as being raisedsmissing-raises-docs:Please document exceptions for all raised exception types.tW9006sRedundant returns documentationsredundant-returns-docs>Please remove the return/rtype documentation from this method.tW9008sRedundant yields documentationsredundant-yields-docs8Please remove the yields documentation from this method.tW9010sMissing return documentationsmissing-return-docs8Please add documentation about what this method returns.tW9007smissing-returns-doct old_namestW9011s!Missing return type documentationsmissing-return-type-docs1Please document the type returned by this method.tW9012sMissing yield documentationsmissing-yield-docs:Please add documentation about what this generator yields.tW9009smissing-yields-doctW9013s Missing yield type documentationsmissing-yield-type-docs0Please document the type yielded by this method.tW9014s'"%s" missing in parameter documentationsmissing-param-docs5Please add parameter declarations for all parameters.tW9003tW9015s,"%s" missing in parameter type documentationsmissing-type-docs:Please add parameter type declarations for all parameters.tW9004tW9016s)"%s" differing in parameter documentationsdiffering-param-docs-Please check parameter names in declarations.tW9017s."%s" differing in parameter type documentationsdiffering-type-docs2Please check parameter names in type declarations.tW9018saccept-no-param-doctdefaulttynttypestmetavarsmWhether to accept totally missing parameter documentation in the docstring of a function that has parameters.thelpsaccept-no-raise-docsoWhether to accept totally missing raises documentation in the docstring of a function that raises an exception.saccept-no-return-docsoWhether to accept totally missing return documentation in the docstring of a function that returns a statement.saccept-no-yields-docsWWhether to accept totally missing yields documentation in the docstring of a generator.iþÿÿÿt__init__t__new__tselftclscC`sFtj|jƒ}|j||ƒ|j||ƒ|j||ƒdS(s¿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(Rt docstringifytdoctcheck_functiondef_paramstcheck_functiondef_returnstcheck_functiondef_yields(R tnodetnode_doc((s:lib/python2.7/site-packages/pylint/extensions/docparams.pytvisit_functiondef…scC`sÐd}|j|jkr³tj|ƒ}|dk r³tj|jƒ}|j|||ƒ|j ƒps|j ƒpsd}|j ƒp‘|j ƒp‘d}|j ||j ||ƒq³n|j ||j ||ƒdS(N( tNonetnametconstructor_namest checker_utilstnode_frame_classRR"R#tcheck_single_constructor_paramst has_paramstparams_documented_elsewheretcheck_arguments_in_docstringtargs(R R'R(tnode_allow_no_paramt class_nodet class_doctclass_allow_no_param((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyR$s      cC`s|j r|jƒs"|jƒr&dS|jtjƒ}|jƒsP|jƒr}td„|Dƒƒ r}|j dd|ƒndS(Ncs`s|]}tj|ƒVqdS(N(Rtreturns_something(t.0tret_node((s:lib/python2.7/site-packages/pylint/extensions/docparams.pys ²ssredundant-returns-docR'( tsupports_yieldst is_generatort is_abstracttnodes_of_classtastroidtReturnt has_returnst has_rtypetanyt add_message(R R'R(t return_nodes((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyR%«s cC`sY|j s|jƒrdS|jƒs2|jƒrU|jƒ rU|jdd|ƒndS(Nsredundant-yields-docR'(R;R=t has_yieldsthas_yields_typeR<RD(R R'R(((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyR&·s cC`sÍ|jƒ}t|tjƒs"dStj|ƒ}|s;dS|jsetj|ƒ}|re|}qentj|jƒ}|j ƒs£|jrŸ|j ||ƒndS|j ƒ}||}|j ||ƒdS(N( tframet isinstanceR?t FunctionDefRtpossible_exc_typesR#tget_setters_propertyR"tis_validt_handle_no_raise_doct exceptionst_add_raise_message(R R't func_nodet expected_excst property_R#t found_excst missing_excs((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyt visit_raiseÁs$       cC`sßtj|ƒsdS|jƒ}t|tjƒs5dStj|jƒ}|jƒ rd|j j rddSt j |ƒ}|j ƒpŽ|jƒoŽ|s§|jdd|ƒn|jƒpÂ|jƒoÂ|sÛ|jdd|ƒndS(Nsmissing-return-docR'smissing-return-type-doc(RR8RHRIR?RJR"R#RMtconfigtaccept_no_return_docR-tdecorated_with_propertyRAthas_property_returnsRDRBthas_property_type(R R'RQR#t is_property((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyt visit_returnÛs&    cC`sÉ|jƒ}t|tjƒs"dStj|jƒ}|jƒ rQ|jj rQdS|j ru|j ƒ}|j ƒ}n|j ƒ}|jƒ}|s©|jdd|ƒn|sÅ|jdd|ƒndS(Nsmissing-yield-docR'smissing-yield-type-doc(RHRIR?RJRR"R#RMRWtaccept_no_yields_docR;RFRGRARBRD(R R'RQR#tdoc_has_yieldstdoc_has_yields_type((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyt visit_yield÷s&      cC`s|j|ƒdS(N(Ra(R R'((s:lib/python2.7/site-packages/pylint/extensions/docparams.pytvisit_yieldfromsc `s€|js dS|dkr(ˆjj}n|jƒ‰td„|jDƒƒ‰ˆjd„|jDƒƒˆj j ƒ}|j dk r¨ˆj |j ƒ|j |j ƒn|j dk rÚˆj |j ƒ|j |j ƒn|jƒ\}}| r | r |r t‰n‡‡‡‡fd†}‡‡‡fd†} ||dˆj ƒ||d|ƒ| |dˆj ƒ| |d |ƒdS( sª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 Ncs`s|]}|jVqdS(N(R+(R9targ((s:lib/python2.7/site-packages/pylint/extensions/docparams.pys Cscs`s|]}|jVqdS(N(R+(R9Rc((s:lib/python2.7/site-packages/pylint/extensions/docparams.pys Dsc`sOˆsKˆ||}|rKˆj|ddjt|ƒƒfdˆƒqKndS(sCompare 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 R3s, R'N(RDtjointsorted(tfound_argument_namest message_idtnot_needed_namestmissing_argument_names(texpected_argument_namesR ttolerate_missing_paramst warning_node(s:lib/python2.7/site-packages/pylint/extensions/docparams.pyt_compare_missing_argsUs c`sJˆ|A|ˆ}|rFˆj|ddjt|ƒƒfdˆƒndS(s”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 R3s, R'N(RDRdRe(RfRgRhtdiffering_argument_names(RjR Rl(s:lib/python2.7/site-packages/pylint/extensions/docparams.pyt_compare_different_argsmssmissing-param-docsmissing-type-docsdiffering-param-docsdiffering-type-doc(R#R*RWtaccept_no_param_docR1tsetR3tupdatet kwonlyargstnot_needed_param_in_docstringtcopytvarargtaddtkwargtmatch_param_docstTrue( R R#targuments_nodeRlRptnot_needed_type_in_docstringtparams_with_doctparams_with_typeRmRo((RjR RkRls:lib/python2.7/site-packages/pylint/extensions/docparams.pyR2s8%          cC`s>|jƒr:|jƒr:|jdd|jfd|ƒndS(Nsmultiple-constructor-docR3R'(R0RDR+(R R6tinit_docR5((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyR/s  cC`s$|jjrdS|j||ƒdS(N(RWtaccept_no_raise_docRP(R texcsR'((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyRN–s cC`sm|jƒr4y|jdƒWq4tk r0q4Xn|s>dS|jdddjt|ƒƒfd|ƒdS(s 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 tNotImplementedErrorNsmissing-raises-docR3s, R'(R=tremovetKeyErrorRDRdRe(R RUR'((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyRPœs  (s@"%s" has constructor parameters documented in class and __init__smultiple-constructor-docsAPlease remove parameter declarations in the class or constructor.(s#"%s" not documented as being raisedsmissing-raises-docs:Please document exceptions for all raised exception types.(sRedundant returns documentationsredundant-returns-docs>Please remove the return/rtype documentation from this method.(sRedundant yields documentationsredundant-yields-docs8Please remove the yields documentation from this method.(R smissing-returns-doc(s!Missing return type documentationsmissing-return-type-docs1Please document the type returned by this method.(Rsmissing-yields-doc(s Missing yield type documentationsmissing-yield-type-docs0Please document the type yielded by this method.(Rsmissing-param-doc(Rsmissing-type-doc(s)"%s" differing in parameter documentationsdiffering-param-docs-Please check parameter names in declarations.(s."%s" differing in parameter type documentationsdiffering-type-docs2Please check parameter names in type declarations.N(t__name__t __module__t__doc__Rt__implements__R+tmsgsRztoptionstpriorityR,RtR)R$R%R&RVR]RaRbR*R2R/RNRP(((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyRsŽ            x  cC`s|jt|ƒƒdS(sRequired method to auto register this checker. :param linter: Main interface object for Pylint plugins :type linter: Pylint object N(tregister_checkerR(tlinter((s:lib/python2.7/site-packages/pylint/extensions/docparams.pytregister´s(R‡t __future__RRRR?tpylint.interfacesRtpylint.checkersRRR-t#pylint.extensions._check_docs_utilst extensionst_check_docs_utilsRRŽ(((s:lib/python2.7/site-packages/pylint/extensions/docparams.pyts ÿ›