bg1edZddlmZddlZddlmZddlZddlmZddlm Z ddlm Z ddl m Z dd lmZdd lmZerdd lmZGd d e ZddZdS)zHPylint plugin for checking in Sphinx, Google, or Numpy style docstrings.) annotationsN) TYPE_CHECKING)nodes) BaseChecker)utils)_check_docs_utils) Docstring)HIGH)PyLintercheZdZdZdZddddddd d d gifd d ddd dgifddddd dgifdddd dgifddddddZd d!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.d/eejd0d1ffZ d2d3hZ d4d5hZ dad:Z e Z dbd=Zdbd>Zdbd?ZdcdAZdddCZdedEZeZdfdNZdfdOZdgdQZ dhdidYZdjd^Zdkd`ZdRS)lDocstringParameterCheckeraChecker 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 ``MAIN`` section of your ``.pylintrc``. 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.)z!Missing any documentation in "%s"missing-any-param-docz/Please add parameter and/or type documentation.)W9005W9006W9008W9010W9011W9012W9013W9014W9015W9016W9017W9018W9019W9020W9021zaccept-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-typechoicer3zzRIf the docstring type cannot be guessed the specified docstring type will be used.)r4r3r5choicesr6__init____new__selfclsnodenodes.FunctionDefreturnNonectj|j|jjj}|jjj}|rtj||j rdStj ||j z }|jjj }|dkr||krdS|||||||||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` N)r docstringifydoc_nodelinterconfigdefault_docstring_typeno_docstring_rgxrematchname checker_utilsget_node_last_linenolinenodocstring_min_lengthcheck_functiondef_paramscheck_functiondef_returnscheck_functiondef_yields)r;r=node_docrHlines max_liness l/builddir/build/BUILD/cloudlinux-venv-1.0.7/venv/lib/python3.11/site-packages/pylint/extensions/docparams.pyvisit_functiondefz+DocstringParameterChecker.visit_functiondefs % M4;-D    ;->  )949 E E  F24884;FK&; r>>ei// F %%dH555 &&tX666 %%dH55555rSr cd}|j|jvrtj|}|t j|j|jjj }| |||| p| pd}| p| pd}| ||j||| ||j||dSN)rKconstructor_namesrLnode_frame_classrrCrDrErFrGcheck_single_constructor_params has_paramsparams_documented_elsewherecheck_arguments_in_docstringargs)r;r=rSnode_allow_no_param class_node class_docclass_allow_no_params rVrPz2DocstringParameterChecker.check_functiondef_paramss&# 9. . .&7==J%!.');)R 44Y*UUU ((** <<>>$ ''));;==% 11ty*6J )) di':     rXcj|js|s|rdS|tj}|s|r:td|Ds| d|tdSdSdS)Nc3>K|]}tj|VdSrZ)rreturns_something).0ret_nodes rV zFDocstringParameterChecker.check_functiondef_returns..sFH H 2:E #H - -H H H H H H rXrr= confidence) supports_yields is_generator is_abstractnodes_of_classastroidReturn has_returns has_rtypeany add_messager )r;r=rS return_nodess rVrQz3DocstringParameterChecker.check_functiondef_returnss( T->->-@-@ TEUEUEWEW  F**7>::  " " Rh&8&8&:&: RCH H >JH H H E E  R   44D  Q Q Q Q Q R R R RrXc|jr|rdS|s|r/|s|d|dSdSdS)Nr)r=)rnrp has_yieldshas_yields_typerorw)r;r=rSs rVrRz2DocstringParameterChecker.check_functiondef_yields s' 4+;+;+=+=  F    ! ! @%-%=%=%?%? @##%% @   3$  ? ? ? ? ? @ @ @ @rX nodes.Raisec |d}t|tjsdS|jjj}|rtj||j rdStj |}|sdS|j stj |}|r|}tj|j |jjj}|jjjr|sdS|s+|jr"d|D}|||dS|}d|D} t+} |D]]} | D]> | j krnJt- fd| Drn?| | j ^|| |dS)NTfuturech|] }|j SrKriexcs rV z8DocstringParameterChecker.visit_raise..3s===38===rXcDh|]}|ddS).rB)splitrs rVrz8DocstringParameterChecker.visit_raise..:s'!V!V!V#))C.."4!V!V!VrXc3.K|]}|jkVdSrZr)riancestor found_excs rVrkz8DocstringParameterChecker.visit_raise..As*WWhyHM1WWWWWWrX)frame isinstancerr FunctionDefrErFrHrIrJrKrpossible_exc_typesrDget_setters_propertyrCrGaccept_no_raise_doc exceptionsmatching_sectionsdoc_add_raise_messagesetrv ancestorsadd) r;r= func_noderH expected_excs property_rmissingfound_excs_full_namesfound_excs_class_names missing_excsexpectedrs @rV visit_raisez%DocstringParameterChecker.visit_raisesJJdJ++ )W%899  F ;->  )99> J J  F066   F! &29==I &%    2 I   ;  1 #..:J:J  F$$&& w <==}==='';;; F # 0 0"W!V@U!V!V!Vuu % 0 0H3 0 0  --EWWWW(BTBTBVBVWWWWWE  ///  i88888rX nodes.Returnctj|sdS|jjjrdS|d}|jjj}|rtj||j rdStj |j |jjj }tj|}|s3|r|s|d|t$|jrdS|s5|r|s!|d|t$dSdSdS)NTr~rrlr)rrhrErFaccept_no_return_docrrHrIrJrKrCrDrGrLdecorated_with_propertyrthas_property_returnsrwr returnsruhas_property_type)r;r=rrHr is_propertys rV visit_returnz&DocstringParameterChecker.visit_returnHsl&t,,  F ;  2  F)-4)@)@  ;->  )99> J J  F   2 I  $;IFF !! Tc&>&>&@&@ T[ T   1 d  S S S    F  YC$9$9$;$; Y  Y   6YSW  X X X X X Y Y Y YrXnodes.Yield | nodes.YieldFromcJ|jjjrdS|d}|jjj}|rt j||jrdStj |j |jjj }|j r)| }|}n(|}|}|s|d|t$|s&|js!|d|t$dSdSdS)NTr~rrlr)rErFaccept_no_yields_docrrHrIrJrKrrCrDrGrnrzr{rtrurwr r)r;r=rrHrdoc_has_yieldsdoc_has_yields_types rV visit_yieldz%DocstringParameterChecker.visit_yieldesA ;  2  F)-4)@)@  ;->  )99> J J  F   2 I     2 ^^--N"%"5"5"7"7   __..N"%--//  S   0yT  R R R# Xy'8 X   5IRV  W W W W W X X X XrXfound_argument_namesset[str] message_idstrnot_needed_namesexpected_argument_names warning_node nodes.NodeNGc||z |z }t}|D]0}|dd|vr||1|rA||dt |f|t dSdS)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 :param message_id: pylint message id :param not_needed_names: names that may be omitted :param expected_argument_names: Expected argument names :param warning_node: The node to be analyzed *, rar=rmNrreplacerrwjoinsortedr ) r;rrrrr potential_missing_argument_namesmissing_argument_namesrKs rV_compare_missing_argsz/DocstringParameterChecker._compare_missing_argss, $&: : ,( "%4 - -D||C$$(<<< " & &t , , , , !    ii'= > >??A!        rXcvt}|D]Y}|dd|vr*||ddD||Z||z |z |z }|rA||dt |f|t dSdS)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 :param message_id: pylint message id :param not_needed_names: names that may be omitted :param expected_argument_names: Expected argument names :param warning_node: The node to be analyzed rrrrNr) r;rrrrr modified_expected_argument_namesrKdiffering_argument_namess rV_compare_different_argsz1DocstringParameterChecker._compare_different_argss,69UU(+ ; ;D||C$$(<<<044T\\#r5J5JKKKK044T::::.0D D % & ! $    ii'? @ @AAC!        rXignored_argument_namesc||z}|rA||dt|f|tdSdS)aqCompare 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 :param message_id: pylint message id :param ignored_argument_names: Expected argument names :param warning_node: The node to be analyzed rrN)rwrrr )r;rrrrexisting_ignored_argument_namess rV_compare_ignored_argsz/DocstringParameterChecker._compare_ignored_argssn+ACW*W' *    ii'F G GHHJ!        rXNrarguments_nodeastroid.Argumentsastroid.NodeNGaccept_no_param_doc bool | Nonec|jsdS||jjj}|}d|jD}|d|jD|d|jD|j }t}|jjj rfd|D}|j :|d|j |d|j |j:|d|j|d|j|\} } | s| s|rd}|| d ||t%|jD],\} } |j| r| | j-t%|jD],\} } |j| r| | j-t%|jD],\} } |j| r| | j-|s|| z |j |zz } || z ||zz }| |cxkr|kr;nn8t/|d kr%|d |jf|t2 n=|| d |j |z|||| d||z|||| d|j |||| d||||| d||dS)a;Check that all parameters are consistent with the parameters mentioned in the parameter documentation (e.g. the Sphinx tags 'param' and 'type'). * 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 white-space) 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 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 Nch|] }|j Srrriargs rVrzIDocstringParameterChecker.check_arguments_in_docstring..s"K"K"K38"K"K"KrXc3$K|] }|jV dSrZrrs rVrkzIDocstringParameterChecker.check_arguments_in_docstring..s$&U&UCsx&U&U&U&U&U&UrXc3$K|] }|jV dSrZrrs rVrkzIDocstringParameterChecker.check_arguments_in_docstring.. s$&V&VCsx&V&V&V&V&V&VrXc>h|]}||Sr)rJ)rirrs rVrzIDocstringParameterChecker.check_arguments_in_docstring..&s=333)//443333rXrz**Tr!rr"rrrrrr )rrErFrr_raupdate kwonlyargs posonlyargsnot_needed_param_in_docstringcopyrrvarargrkwargmatch_param_docsr enumeraterrKkwonlyargs_annotationsposonlyargs_annotationslenrwr rr)r;rrrrtolerate_missing_paramsrnot_needed_type_in_docstring#expected_but_ignored_argument_namesparams_with_docparams_with_typeindexarg_namemissing_param_docmissing_type_docrs @rVr`z6DocstringParameterChecker.check_arguments_in_docstringsUNw  F  &"&+"4"H "%"A"A"C"C#L"K~7J"K"K"K&&&U&U>;T&U&U&UUUU&&&V&V>;U&V&V&VVVV'+'I'N'N'P'P$.1ee+!%!3!J ! 33332333 /  , # ' '(CN,A(C(C D D D ( , ,-H1F-H-H I I I   + # ' '(C^-A(C(C D D D ( , ,-H.2F-H-H I I I,/,@,@,B,B)) +'7 +r?r@)r=r>rSr r?r@)r=r|r?r@)r=rr?r@)r=rr?r@) rrrrrrrrrrr?r@) rrrrrrrrr?r@rZ) rr rrrrrrr?r@)rdr rr rcrr?r@)rrr=r>r?r@)__name__ __module__ __qualname____doc__rKmsgslistrDOCSTRING_TYPESoptionsr[rrWvisit_asyncfunctiondefrPrQrRrrrvisit_yieldfromrrrr`r]rrrXrVr r s( %D    + F ?@ A    *  H >? @    6  C => ?   ;  H <= >       _T T Dp "%     "%'     #%'     #%A     % $-4 566=    Y7Gr$Y/%+UO!66662/    B R R R R @ @ @ @29292929hYYYY:XXXX8"O&&&&P))))V<,0 P P P P P d    rXr rEr r?r@cJ|t|dSrZ)register_checkerr )rEs rVregisterrs% 5f==>>>>>rX)rEr r?r@)r __future__rrItypingrrrrpylint.checkersrrrLpylint.extensionsr#pylint.extensions._check_docs_utilsr pylint.interfacesr pylint.lintr r rrrXrVr s ON"""""" ''''''222222888888999999""""""%$$$$$$F F F F F  F F F R??????rX