
    c1e                        d Z ddlmZ ddlZddlmZ ddlZddlmZ ddlm	Z	 ddlm
Z ddlmZ
 dd	lmZ dd
lmZ erddlmZ  G d de	          ZddZdS )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 Zd ZdZdZddddddd	d
dgifddddd
dgifddddd
dgifdddd
dgifddddddZd d!d"d#d$d%fd&d!d"d#d'd%fd(d!d"d#d)d%fd*d!d"d#d+d%fd,d-d.d/ eej                  d0d1ffZ	d2d3hZ
d4d5hZdad:ZeZdbd=Zdbd>Zdbd?ZdcdAZdddCZdedEZeZdfdNZdfdOZdgdQZ	 dhdidYZdjd^Zdkd`ZdRS )l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 ``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 raisedmissing-raises-docz:Please document exceptions for all raised exception types.)zRedundant returns documentationredundant-returns-docz>Please remove the return/rtype documentation from this method.)zRedundant yields documentationredundant-yields-docz8Please remove the yields documentation from this method.zMissing return documentationmissing-return-docz8Please add documentation about what this method returns.	old_names)W9007zold-missing-returns-doc)z!Missing return type documentationmissing-return-type-docz1Please document the type returned by this method.zMissing yield documentationmissing-yield-docz:Please add documentation about what this generator yields.)W9009zold-missing-yields-doc)z Missing yield type documentationmissing-yield-type-docz0Please document the type yielded by this method.z'"%s" missing in parameter documentationmissing-param-docz5Please add parameter declarations for all parameters.)W9003zold-missing-param-docz,"%s" missing in parameter type documentationmissing-type-docz:Please add parameter type declarations for all parameters.)W9004zold-missing-type-doc)z)"%s" differing in parameter documentationdiffering-param-docz-Please check parameter names in declarations.)z."%s" differing in parameter type documentationdiffering-type-docz2Please check parameter names in type declarations.)z,"%s" useless ignored parameter documentationuseless-param-docz2Please remove the ignored parameter documentation.)z1"%s" useless ignored parameter type documentationuseless-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.)W9005W9006W9008W9010W9011W9012W9013W9014W9015W9016W9017W9018W9019W9020W9021zaccept-no-param-docTynz<y or n>zmWhether to accept totally missing parameter documentation in the docstring of a function that has parameters.)defaulttypemetavarhelpzaccept-no-raise-doczoWhether to accept totally missing raises documentation in the docstring of a function that raises an exception.zaccept-no-return-doczoWhether to accept totally missing return documentation in the docstring of a function that returns a statement.zaccept-no-yields-doczWWhether to accept totally missing yields documentation in the docstring of a generator.zdefault-docstring-typechoicer3   z<docstring type>zRIf the docstring type cannot be guessed the specified docstring type will be used.)r4   r3   r5   choicesr6   __init____new__selfclsnodenodes.FunctionDefreturnNonec                   t          j        |j        | j        j        j                  }| j        j        j        }|rt          j        ||j	                  rdS t          j        |          |j        z
  }| j        j        j        }|dk    r||k     rdS |                     ||           |                     ||           |                     ||           dS )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   docstringifydoc_nodelinterconfigdefault_docstring_typeno_docstring_rgxrematchnamechecker_utilsget_node_last_linenolinenodocstring_min_lengthcheck_functiondef_paramscheck_functiondef_returnscheck_functiondef_yields)r;   r=   node_docrH   lines	max_liness         ;lib/python3.11/site-packages/pylint/extensions/docparams.pyvisit_functiondefz+DocstringParameterChecker.visit_functiondef   s     %M4;-D
 

  ;-> 	)949 E E 	F 24884;FK&;	r> 	ei/ 	F%%dH555&&tX666%%dH55555    rS   r	   c                   d }|j         | j        v rt          j        |          }|t	          j        |j        | j        j        j	                  }| 
                    |||           |                                p|                                pd }|                                p|                                pd }|                     ||j        ||           |                     ||j        ||           d S N)rK   constructor_namesrL   node_frame_classr   rC   rD   rE   rF   rG   check_single_constructor_params
has_paramsparams_documented_elsewherecheck_arguments_in_docstringargs)r;   r=   rS   node_allow_no_param
class_node	class_docclass_allow_no_params          rV   rP   z2DocstringParameterChecker.check_functiondef_params   s*    #9.. 	&7==J !.');)R 	 44Y*UUU
 ((**  <<>> $ '')) ;;== % 11ty*6J   	))di':	
 	
 	
 	
 	
rX   c                j   |j         s|                                s|                                rd 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).0ret_nodes     rV   	<genexpr>zFDocstringParameterChecker.check_functiondef_returns.<locals>.<genexpr>  sF       H
 H
2:E#H--H
 H
 H
 H
 H
 H
rX   r   r=   
confidence)supports_yieldsis_generatoris_abstractnodes_of_classastroidReturnhas_returns	has_rtypeanyadd_messager
   )r;   r=   rS   return_nodess       rV   rQ   z3DocstringParameterChecker.check_functiondef_returns   s     ( 	T->->-@-@ 	TEUEUEWEW 	F**7>::  "" 	Rh&8&8&:&: 	RC H
 H
>JH
 H
 H
 E
 E
 	R 44DQQQQQ	R 	R 	R 	RrX   c                    |j         r|                                rd S |                                s|                                r/|                                s|                     d|           d S d S d S )Nr   )r=   )rn   rp   
has_yieldshas_yields_typero   rw   )r;   r=   rS   s      rV   rR   z2DocstringParameterChecker.check_functiondef_yields	  s     ' 	4+;+;+=+= 	F !!	@%-%=%=%?%?	@##%%	@ 3$?????	@ 	@ 	@ 	@rX   nodes.Raisec                   |                     d          }t          |t          j                  sd S | j        j        j        }|rt          j        ||j	                  rd S t          j        |          }|sd S |j        st          j        |          }|r|}t          j        |j        | j        j        j                  }| j        j        j        r|                                sd S |                                s+|j        r"d |D             }|                     ||           d S |                                }d |D             }	t+                      }
|D ]]}|	D ]>|j	        k    r nJt-          fd|                                D                       r n?|
                    |j	                   ^|                     |
|           d S )NTfuturec                    h | ]	}|j         
S  rK   ri   excs     rV   	<setcomp>z8DocstringParameterChecker.visit_raise.<locals>.<setcomp>3  s    ===38===rX   c                D    h | ]}|                     d           d         S ).rB   )splitr   s     rV   r   z8DocstringParameterChecker.visit_raise.<locals>.<setcomp>:  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.<locals>.<genexpr>A  s*      WWhyHM1WWWWWWrX   )frame
isinstancerr   FunctionDefrE   rF   rH   rI   rJ   rK   r   possible_exc_typesrD   get_setters_propertyrC   rG   accept_no_raise_doc
exceptionsmatching_sectionsdoc_add_raise_messagesetrv   	ancestorsadd)r;   r=   	func_noderH   expected_excs	property_r   missingfound_excs_full_namesfound_excs_class_namesmissing_excsexpectedr   s               @rV   visit_raisez%DocstringParameterChecker.visit_raise  s   JJdJ++	)W%899 	F  ;-> 	)99> J J 	F066 	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	- EWWWW(BTBTBVBVWWWWW E   ///i88888rX   nodes.Returnc                   t          j        |          sd S | j        j        j        rd S |                    d          }| j        j        j        }|rt          j        ||j	                  rd S t          j
        |j        | j        j        j                  }t          j        |          }|                                s3|                                r|s|                     d|t$                     |j        rd 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
 
 $;IFF!! 	Tc&>&>&@&@ 	T[ 	T1	dSSS 	F 	YC$9$9$;$; 	Y 	Y6YSWXXXXX	Y 	Y 	Y 	YrX   nodes.Yield | nodes.YieldFromc                J   | j         j        j        rd S |                    d          }| j         j        j        }|rt          j        ||j                  rd 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_yieldsdoc_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# 	Xy'8 	X5IRVWWWWW	X 	X 	X 	XrX   found_argument_namesset[str]
message_idstrnot_needed_namesexpected_argument_nameswarning_nodenodes.NodeNGc                   ||z
  |z
  }t                      }|D ]0}|                    dd          |v r|                    |           1|rA|                     |d                    t          |                    f|t                     dS dS )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   Nr   replacer   rw   joinsortedr
   )	r;   r   r   r   r   r    potential_missing_argument_namesmissing_argument_namesrK   s	            rV   _compare_missing_argsz/DocstringParameterChecker._compare_missing_args  s    , $&::,(
 "%4 	- 	-D||C$$(<< "&&t,,,,! 	ii'= > >??A!	      	 	rX   c                v   t                      }|D ]Y}|                    dd          |v r*|                    |                    dd                     D|                    |           Z||z  |z
  |z
  }|rA|                     |d                    t          |                    f|t                     dS dS )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$$(<< ;044T\\#r5J5JKKKK044T:::: .0DD%& 	! $ 	ii'? @ @AAC!	      	 	rX   ignored_argument_namesc                    ||z  }|rA|                      |d                    t          |                    f|t                     dS dS )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     +ACW*W'* 	ii'F G GHHJ!	      	 	rX   Nr   arguments_nodeastroid.Argumentsastroid.NodeNGaccept_no_param_docbool | Nonec                   |j         sdS || j        j        j        }|                                }d |j        D             }|                    d |j        D                        |                    d |j        D                        | j	        
                                }t                      }| j        j        j        rfd|D             }|j        :|                    d|j                    |                    d|j                    |j        :|                    d|j                    |                    d|j                    |                                \  }	}
|	s|
s|rd}|                     |
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
  }||cxk    r|k    r;n n8t/          |          d
k    r%|                     d|j        f|t2                     n=|                     |	d| j	        |z  ||           |                     |
d||z  ||           |                     |	d| j	        ||           |                     |
d|||           |                     |	d||           dS )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 ``*<args>``
          and ``**<kwargs>`` 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.<locals>.<setcomp>  s    "K"K"K38"K"K"KrX   c              3  $   K   | ]}|j         V  d S rZ   r   r   s     rV   rk   zIDocstringParameterChecker.check_arguments_in_docstring.<locals>.<genexpr>  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.<locals>.<genexpr>   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.<locals>.<setcomp>&  s=     3 3 3)//4433 3 3rX   r   z**Tr!   r   r"   r   r   r   r   r   r    )r   rE   rF   r   r_   ra   update
kwonlyargsposonlyargsnot_needed_param_in_docstringcopyr   r   varargr   kwargmatch_param_docsr   	enumerater   rK   kwonlyargs_annotationsposonlyargs_annotationslenrw   r
   r   r   )r;   r   r   r   r   tolerate_missing_paramsr   not_needed_type_in_docstring#expected_but_ignored_argument_namesparams_with_docparams_with_typeindexarg_namemissing_param_docmissing_type_docr   s                  @rV   r`   z6DocstringParameterChecker.check_arguments_in_docstring  st   N w 	F 	I"&+"4"H"%"A"A"C"C #L"K~7J"K"K"K&&&U&U>;T&U&U&UUUU&&&V&V>;U&V&V&VVVV'+'I'N'N'P'P$.1ee+!%!3!J! 	3 3 3 323 3 3/   	J#''(CN,A(C(CDDD(,,-H1F-H-HIII 	J#''(C^-A(C(CDDD(,,-H.2F-H-HIII,/,@,@,B,B)) 	+'7 	+<O 	+&*#
 	""/		
 	
 	
  ))<== 	4 	4OE8)%0 4 $$X]333()BCC 	4 	4OE84U; 4 $$X]333()CDD 	4 	4OE85e< 4 $$X]333&  	!8?!J25XX! !8:J J,/RR  "%<   @P    /00A5   +&+-%#	 !     **#'69:+    **$&03VV+    	$$!.#	
 	
 	
 	$$ (#	
 	
 	
 	""/		
 	
 	
 	
 	
rX   rd   init_docrc   nodes.ClassDefc                    |                                 r:|                                 r(|                     d|j        f|t                     d S d S d S )Nr   r   )r^   rw   rK   r
   )r;   rd   r   rc   s       rV   r]   z9DocstringParameterChecker.check_single_constructor_params  sw     !! 	h&9&9&;&; 	* o'	      	 	 	 	rX   missing_exceptionsc                   |                                 r'	 |                    d           n# t          $ r Y nw xY w|rA|                     dd                    t          |                    f|t                     dS dS )zAdds a message on :param:`node` for the missing exception type.

        :param missing_exceptions: A list of missing exception types.
        :param node: The node show the message on.
        NotImplementedErrorr   r   r   N)rp   removeKeyErrorrw   r   r   r
   )r;   r   r=   s      rV   r   z,DocstringParameterChecker._add_raise_message  s      	"))*?@@@@    	$ii'9 : :;;=	      	 	s   , 
99)r=   r>   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   msgslistr   DOCSTRING_TYPESoptionsr[   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 566= 
	
Y7Gr $Y/%+UO!6 6 6 62 /
 
 
 
B
R 
R 
R 
R	@ 	@ 	@ 	@29 29 29 29hY Y Y Y:X X X X8 "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   <module>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   