iay d Z ddlmZ ddlZddlmZ ddlZddlmZ ddlm Z ddlm
Z ddl m
Z
dd lmZ dd
lmZ erdd lmZ G d 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)PyLinterc h e Zd ZdZdZddddddd d
d gifd d
ddd
dgifddddd
dgifdddd
dgifddd d d d Zd 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/ eej d0d1ffZ d2d3hZ
d4d5hZ dad:Z e Z
dbd=Zdbd>Zdbd?ZdcdAZdddCZdedEZeZdfdNZdfdOZdgdQZ dhdidYZdjd^Zdkd`ZdRS )lDocstringParameterCheckera 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 ``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.)z Redundant returns documentationredundant-returns-docz>Please remove the return/rtype documentation from this method.)z Redundant yields documentationredundant-yields-docz8Please remove the yields documentation from this method.z Missing 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-typechoicer3 zzRIf the docstring type cannot be guessed the specified docstring type will be used.)r4 r3 r5 choicesr6 __init____new__selfclsnodenodes.FunctionDefreturnNonec t j |j | j j j }| j j j }|r t j ||j rdS t j | |j z
}| j j j
}|dk r||k rdS | || | || | || 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_docrH lines max_liness m/builddir/build/BUILD/cloudlinux-venv-1.0.10/venv/lib/python3.11/site-packages/pylint/extensions/docparams.pyvisit_functiondefz+DocstringParameterChecker.visit_functiondef s % M4;-D
;-> )949 E E F 24884;FK&; r>>ei / / F %%dH555 &&tX666 %%dH55555 rS r c d }|j | j v rt j | }|t j |j | j j j }|
||| | p| pd }| p| pd }|
||j || |
||j || d S N)rK constructor_namesrL node_frame_classr rC rD rE rF rG check_single_constructor_params
has_paramsparams_documented_elsewhere check_arguments_in_docstringargs)r; r= rS node_allow_no_param
class_node class_docclass_allow_no_params rV rP z2DocstringParameterChecker.check_functiondef_params s& # 9. . .&7==J% ! . ');)R 44Y*UUU
((** <<>> $ '')) ;;== % 11 ty*6J
)) di':
rX c j |j s| s| rd S | t j }| s| r:t d |D s | d|t d S d S d S )Nc 3 > K | ]}t j | V d S rZ )r returns_something).0ret_nodes rV zFDocstringParameterChecker.check_functiondef_returns.. sF H
H
2:E #H - -H
H
H
H
H
H
rX r r=
confidence) supports_yields is_generator is_abstractnodes_of_classastroidReturn has_returns has_rtypeany add_messager
)r; r= rS return_nodess rV rQ z3DocstringParameterChecker.check_functiondef_returns s ( T->->-@-@ TEUEUEWEW F**7>:: " " Rh&8&8&:&: RC H
H
>JH
H
H
E
E
R
44D Q Q Q Q Q R R R RrX c |j r| rd S | s| r/| s| d| d S d S d S )Nr )r= )rn rp
has_yieldshas_yields_typero rw )r; r= rS s rV rR z2DocstringParameterChecker.check_functiondef_yields s ' 4+;+;+=+= F
! ! @%-%=%=%?%? @##%% @
3$ ? ? ? ? ? @ @ @ @rX nodes.Raisec | d }t |t j sd S | j j j }|r t j ||j rd S t j | }|sd S |j st j
| }|r|}t j |j | j j j }| j j j r| sd S | s+|j r"d |D }| || d S | }d |D } t+ }
|D ]]} | D ]> | j k r nJt- fd| D r n?|
| j ^| |
| d S )NTfuturec h | ] }|j
S rK ri excs rV z8DocstringParameterChecker.visit_raise..3 s ===38===rX c D h | ] }| d d S ).rB )splitr s rV r z8DocstringParameterChecker.visit_raise..: s' !V!V!V#))C.."4!V!V!VrX c 3 . K | ]}|j k V d S rZ r )ri ancestor found_excs rV rk z8DocstringParameterChecker.visit_raise..A s* WWhyHM1WWWWWWrX )frame
isinstancerr FunctionDefrE rF rH rI rJ rK r possible_exc_typesrD get_setters_propertyrC rG accept_no_raise_doc
exceptionsmatching_sectionsdoc_add_raise_messagesetrv ancestorsadd)
r; r= func_noderH
expected_excs property_r missingfound_excs_full_namesfound_excs_class_names missing_excsexpectedr s
@rV visit_raisez%DocstringParameterChecker.visit_raise s JJdJ++ )W%899 F ;-> )99> J J F 066
F! & 29==I
& % 2 I
; 1 #..:J:J F$$&& w
<==}==='';;; F # 0 0 "W!V@U!V!V!V uu % 0 0H 3
0
0
--EWWWW(BTBTBVBVWWWWW E /// i88888rX nodes.Returnc t j | sd S | j j j rd S | d }| j j j }|r t j ||j rd S t j
|j | j j j }t j | }| s3| r|s | d|t$ |j rd S | s5| r|s!| d|t$ d S d S d S )NTr~ r rl r )r rh rE rF accept_no_return_docr rH rI rJ rK rC rD rG rL decorated_with_propertyrt has_property_returnsrw r
returnsru has_property_type)r; r= r rH r is_propertys rV visit_returnz&DocstringParameterChecker.visit_returnH sl &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 YrX nodes.Yield | nodes.YieldFromc J | j j j rd S | d }| j j j }|r t j ||j rd S t j |j
| j j j }|j r)|
}| }n(| }| }|s | d|t$ |s&|j s!| d|t$ d S d S d S )NTr~ r rl r )rE rF accept_no_yields_docr rH rI rJ rK r rC rD rG rn rz r{ rt ru rw r
r )r; r= r rH r doc_has_yieldsdoc_has_yields_types rV visit_yieldz%DocstringParameterChecker.visit_yielde sA ; 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 XrX found_argument_namesset[str]
message_idstrnot_needed_namesexpected_argument_names warning_node nodes.NodeNGc ||z
|z
}t }|D ]0}| dd |v r| | 1|rA| |d t | f|t dS dS )a Compare 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
* , ra r= rm Nr replacer rw joinsortedr
) r; r r r r r potential_missing_argument_namesmissing_argument_namesrK s rV _compare_missing_argsz/DocstringParameterChecker._compare_missing_args s ,
$&: : , (
"% 4 - -D||C$$(<<< " & &t , , , , ! ii'= > >??A!
rX c v t }|D ]Y}| dd |v r*| | dd D| | Z||z |z
|z
}|rA| |d t | f|t dS dS )a Compare 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
r r r r Nr ) r; r r r r r modified_expected_argument_namesrK differing_argument_namess rV _compare_different_argsz1DocstringParameterChecker._compare_different_args s , 69UU(+ ; ;D||C$$(<<<044T\\#r5J5JKKKK044T:::: .0D
D
%
& ! $ ii'? @ @AAC!
rX ignored_argument_namesc ||z }|rA| |d t | f|t dS dS )aq 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
:param message_id: pylint message id
:param ignored_argument_names: Expected argument names
:param warning_node: The node to be analyzed
r r N)rw r r r
)r; r r r r existing_ignored_argument_namess rV _compare_ignored_argsz/DocstringParameterChecker._compare_ignored_args sn +ACW*W' * ii'F G GHHJ!
rX Nr arguments_nodeastroid.Argumentsastroid.NodeNGaccept_no_param_doc bool | Nonec |j sdS || j j j }| }d |j D }| d |j D | d |j D | j
}t }| j j j rfd|D }|j
:| d|j
| d|j
|j :| d|j | d|j | \ } }
| s|
s|rd}| |
d || t% |j D ],\ } } |j | r|
| j -t% |j D ],\ } } |j | r|
| j -t% |j D ],\ } } |j | r|
| j -|s|| z
| j |z z
}
||
z
||z z
}|
|cxk r|k r;n n8t/ | d
k r%| d |j f|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
Nc h | ] }|j
S r r ri args rV r zIDocstringParameterChecker.check_arguments_in_docstring.. s "K"K"K38"K"K"KrX c 3 $ K | ] }|j V d S rZ r r s rV rk zIDocstringParameterChecker.check_arguments_in_docstring.. s$ &U&UCsx&U&U&U&U&U&UrX c 3 $ K | ] }|j V d S rZ r r s rV rk zIDocstringParameterChecker.check_arguments_in_docstring.. s$ &V&VCsx&V&V&V&V&V&VrX c > h | ]} | |S r )rJ )ri r r s rV r zIDocstringParameterChecker.check_arguments_in_docstring..& s= 3 3 3)//4433 3 3rX r z**Tr! r r" r r r r r r ) r rE rF r r_ ra update
kwonlyargs posonlyargs not_needed_param_in_docstringcopyr r varargr kwargmatch_param_docsr enumerater rK kwonlyargs_annotationsposonlyargs_annotationslenrw r
r r )r; r r r r tolerate_missing_paramsr not_needed_type_in_docstring#expected_but_ignored_argument_namesparams_with_docparams_with_typeindexarg_namemissing_param_docmissing_type_docr s @rV r` z6DocstringParameterChecker.check_arguments_in_docstring sU N w 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 ! 3 3 3 323 3 3 / , # ' '(CN,A(C(C D D D ( , ,-H 1F-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> rS r r? r@ )r= r| r? r@ )r= r r? r@ )r= r r? r@ ) r r r r r r r r r r r? r@ )
r r r r r r r r r? r@ rZ )
r r r r r r r r r? r@ )rd r r r rc r r? r@ )r r r= r> r? r@ )__name__
__module__ __qualname____doc__rK msgslistr DOCSTRING_TYPESoptionsr[ r rW visit_asyncfunctiondefrP rQ rR r r r visit_yieldfromr r r r` r] r r rX rV r
r
s ( %D
+ F
?@ A
* H
>? @
6 C
=> ?
; H
<= >
_T T Dp
" %
" %'
# %'
# %A
% $- 4 566=
Y7Gr $Y/%+UO!6 6 6 62 /
B
R
R
R
R @ @ @ @29 29 29 29hY Y Y Y:X X X X8 "O& & & &P) ) ) )V < ,0 P
P
P
P
P
d rX r
rE r r? r@ c J | t | d S rZ )register_checkerr
)rE s rV registerr s%
5f = =>>>>>rX )rE r r? r@ )r
__future__r rI typingr rr r pylint.checkersr r rL pylint.extensionsr #pylint.extensions._check_docs_utilsr pylint.interfacesr
pylint.lintr r
r r rX rV r
s
O N " " " " " " ' ' ' ' ' ' 2 2 2 2 2 2 8 8 8 8 8 8 9 9 9 9 9 9 " " " " " " %$$$$$$F
F
F
F
F
F
F
F
R? ? ? ? ? ?rX