o g_@sdZddlZddlmZddlZddlmZddlmZddlmZ ddl m Zddl m Z dd lmZdd lmZGd d d eZd dZdS)zHPylint plugin for checking in Sphinx, Google, or Numpy style docstrings N)Optional)nodes) BaseChecker)utils)_check_docs_utils) Docstring)IAstroidChecker)get_global_optionc@seZdZdZeZdZddddddd d d gifd d ddd dgifddddd dgifdddd dgifdddddZdd d!d"d#d$fd%d d!d"d&d$fd'd d!d"d(d$fd)d d!d"d*d$fd+d,d-ee j d.d/ffZ d0Z d1d2hZ d3d4hZd5ejd6d7fd8d9ZeZd:d;Zdd?Zd5ejd6d7fd@dAZd5ejd6d7fdBdCZd5ejd6d7fdDdEZd5ejd6d7fdFdGZdHdIZdJdKZdLdMZ 7dZdNe!dOe"j#dPe"j$dQe%e&fdRdSZ'dTdUZ(dVdWZ)dXdYZ*d7S)[DocstringParameterCheckeraChecker 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` parameter_documentation)z@"%s" has constructor parameters documented in class and __init__multiple-constructor-doczAPlease remove parameter declarations in the class or constructor.)z#"%s" not documented as being raisedmissing-raises-docz:Please document exceptions for all raised exception types.)zRedundant returns documentationredundant-returns-docz>Please remove the return/rtype documentation from this method.)zRedundant yields documentationredundant-yields-docz8Please remove the yields documentation from this method.zMissing return documentationmissing-return-docz8Please add documentation about what this method returns. old_names)W9007zold-missing-returns-doc)z!Missing return type documentationmissing-return-type-docz1Please document the type returned by this method.zMissing yield documentationmissing-yield-docz:Please add documentation about what this generator yields.)W9009zold-missing-yields-doc)z Missing yield type documentationmissing-yield-type-docz0Please document the type yielded by this method.z'"%s" missing in parameter documentationmissing-param-docz5Please add parameter declarations for all parameters.)W9003zold-missing-param-docz,"%s" missing in parameter type documentationmissing-type-docz:Please add parameter type declarations for all parameters.)W9004zold-missing-type-doc)z)"%s" differing in parameter documentationdiffering-param-docz-Please check parameter names in declarations.)z."%s" differing in parameter type documentationdiffering-type-docz2Please check parameter names in type declarations.)z,"%s" useless ignored parameter documentationuseless-param-docz2Please remove the ignored parameter documentation.)z1"%s" useless ignored parameter type documentationuseless-type-docz7Please remove the ignored parameter type documentation.)W9005W9006W9008W9010W9011W9012W9013W9014W9015W9016W9017W9018W9019W9020zaccept-no-param-docTynzzmWhether to accept totally missing parameter documentation in the docstring of a function that has parameters.)defaulttypemetavarhelpzaccept-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-typechoicer.zRIf the docstring type cannot be guessed the specified docstring type will be used.)r/r.choicesr1__init____new__selfclsnodereturnNcCst|j|jj}t|d}|rt||jrdSt ||j }t|d}|dkr0||kr0dS| ||| |||||dS)zCalled 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` zno-docstring-rgxNzdocstring-min-length)r docstringifydocconfigdefault_docstring_typer rematchname checker_utilsget_node_last_linenolinenocheck_functiondef_paramscheck_functiondef_returnscheck_functiondef_yields)r7r9node_docno_docstring_rgxlines max_linesrMY/home/ubuntu/cloudmapper/venv/lib/python3.10/site-packages/pylint/extensions/docparams.pyvisit_functiondefs    z+DocstringParameterChecker.visit_functiondefcCsd}|j|jvr>t|}|dur>t|j|jj}| |||| p*| p*d}| p4| p4d}| ||j ||| ||j ||dSN)rBconstructor_namesrCnode_frame_classrr<r=r>r?check_single_constructor_params has_paramsparams_documented_elsewherecheck_arguments_in_docstringargs)r7r9rInode_allow_no_param class_node class_docclass_allow_no_paramrMrMrNrFs0     z2DocstringParameterChecker.check_functiondef_paramscCsb|js|s |r dS|tj}|s|r/tdd|Ds-|j d|ddSdSdS)Ncss|]}t|VqdSrP)rreturns_something).0ret_noderMrMrN s  zFDocstringParameterChecker.check_functiondef_returns..rr9) supports_yields is_generator is_abstractnodes_of_classastroidReturn has_returns has_rtypeany add_message)r7r9rI return_nodesrMrMrNrG s z3DocstringParameterChecker.check_functiondef_returnscCsD|jr|r dS|s|r |s|jd|ddSdSdS)Nrr`)rarc has_yieldshas_yields_typerbrj)r7r9rIrMrMrNrHsz2DocstringParameterChecker.check_functiondef_yieldsc Cs|}t|tjs dSt|}|sdS|js!t|}|r!|}t|j|j j }| s9|jr7| ||dS| }dd|D}||}|||dS)NcSsh|] }|ddqS).r;)split)r]excrMrMrN 8sz8DocstringParameterChecker.visit_raise..)frame isinstancere FunctionDefrpossible_exc_typesr=get_setters_propertyr<r>r?is_valid_handle_no_raise_doc exceptions_add_raise_message) r7r9 func_node expected_excs property_r=found_excs_full_namesfound_excs_class_names missing_excsrMrMrN visit_raises&    z%DocstringParameterChecker.visit_raisecCst|sdS|}t|tjsdSt|j|jj }| s&|jj r&dSt |}|s<|r5|s<|jd|d|jrAdS|sT|rK|sV|jd|ddSdSdS)Nrr`r)rr\rrrsrertr<r=r>r?rwaccept_no_return_docrCdecorated_with_propertyrghas_property_returnsrjreturnsrhhas_property_type)r7r9r{r= is_propertyrMrMrN visit_return<s   z&DocstringParameterChecker.visit_returncCs|}t|tjs dSt|j|jj}| s|jj rdS|j r+| }| }n|}|}|s<|jd|d|sJ|jsL|jd|ddSdSdS)Nrr`r)rrrsrertrr<r=r>r?rwaccept_no_yields_docrarlrmrgrhrjr)r7r9r{r=doc_has_yieldsdoc_has_yields_typerMrMrN visit_yieldSs    z%DocstringParameterChecker.visit_yieldcCs||dSrP)r)r7r9rMrMrNvisit_yieldfromisz)DocstringParameterChecker.visit_yieldfromcCs4|||}|r|j|dt|f|ddSdS)aCompare the found argument names with the expected ones and generate a message if there are arguments missing. :param found_argument_names: argument names found in the docstring :type found_argument_names: set :param message_id: pylint message id :type message_id: str :param not_needed_names: names that may be omitted :type not_needed_names: set :param expected_argument_names: Expected argument names :type expected_argument_names: set :param warning_node: The node to be analyzed :type warning_node: :class:`astroid.scoped_nodes.Node` , rWr9Nrjjoinsorted)r7found_argument_names message_idnot_needed_namesexpected_argument_names warning_nodemissing_argument_namesrMrMrN_compare_missing_argsls z/DocstringParameterChecker._compare_missing_argscCs8||A||}|r|j|dt|f|ddSdS)aCompare the found argument names with the expected ones and generate a message if there are extra arguments found. :param found_argument_names: argument names found in the docstring :type found_argument_names: set :param message_id: pylint message id :type message_id: str :param not_needed_names: names that may be omitted :type not_needed_names: set :param expected_argument_names: Expected argument names :type expected_argument_names: set :param warning_node: The node to be analyzed :type warning_node: :class:`astroid.scoped_nodes.Node` rrNr)r7rrrrrdiffering_argument_namesrMrMrN_compare_different_argss z1DocstringParameterChecker._compare_different_argscCs0||@}|r|j|dt|f|ddSdS)a#Compare the found argument names with the ignored ones and generate a message if there are ignored arguments found. :param found_argument_names: argument names found in the docstring :type found_argument_names: set :param message_id: pylint message id :type message_id: str :param ignored_argument_names: Expected argument names :type ignored_argument_names: set :param warning_node: The node to be analyzed :type warning_node: :class:`astroid.scoped_nodes.Node` rrNr)r7rrignored_argument_namesrexisting_ignored_argument_namesrMrMrN_compare_ignored_argss z/DocstringParameterChecker._compare_ignored_argsr=arguments_noderaccept_no_param_docc s|jsdS|dur |jj}|}dd|jD}|dd|jD|j}t }t |dr<fdd|D}|j durM| |j | |j |j dur^| |j | |j |\} } | sl| sl|rld}|sz|| d |j|B|||| d ||t|jD]\} } |j| r| | jqt|jD]\} } |j| r| | jq|s|| d ||B|||| d |j|||| d ||||| d||dS)aCheck 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: :class:`Docstring` :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|]}|jqSrMrBr]argrMrMrNrqszIDocstringParameterChecker.check_arguments_in_docstring..css|]}|jVqdSrPrrrMrMrNr_ szIDocstringParameterChecker.check_arguments_in_docstring..zignored-argument-namescsh|] }|r|qSrM)rArrrMrNrqs Trrrrrr)r=r>rrUrWupdate kwonlyargsnot_needed_param_in_docstringcopysetr varargaddkwargmatch_param_docsrr enumerate annotationsrBkwonlyargs_annotationsr) r7r=rrrtolerate_missing_paramsrnot_needed_type_in_docstring#expected_but_ignored_argument_namesparams_with_docparams_with_typeindexarg_namerMrrNrVs*                z6DocstringParameterChecker.check_arguments_in_docstringcCs0|r|r|jd|jf|ddSdSdS)Nr r)rTrjrB)r7rZinit_docrYrMrMrNrSXs   z9DocstringParameterChecker.check_single_constructor_paramscCs|jjrdS|||dSrP)r>accept_no_raise_docrz)r7excsr9rMrMrNrx^sz.DocstringParameterChecker._handle_no_raise_doccCsR|rz|dWn tyYnw|sdS|jddt|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: nodes.NodeNG NotImplementedErrorNr rr)rcremoveKeyErrorrjrr)r7rr9rMrMrNrzds   z,DocstringParameterChecker._add_raise_messagerP)+__name__ __module__ __qualname____doc__r__implements__rBmsgslistrDOCSTRING_TYPESoptionspriorityrQrrrtrOvisit_asyncfunctiondefrFrGrHRaiserrfrYieldr YieldFromrrrrrre ArgumentsNodeNGrboolrVrSrxrzrMrMrMrNr *sS    8  $'$  r cCs|t|dS)zRequired method to auto register this checker. :param linter: Main interface object for Pylint plugins :type linter: Pylint object N)register_checkerr )linterrMrMrNregister|sr)rr@typingrrerpylint.checkersrrrCpylint.extensionsr#pylint.extensions._check_docs_utilsrpylint.interfacesr pylint.utilsr r rrMrMrMrNs"         V