
    cXS                        d Z ddlZddlZddlZddlZddlZddlZddlZddlm	Z	 g dZ
 ej        d                    d                    e
                    ej        ej        z            Zg dZi d	d
dddddddddddddddddddddd d!d"d#d$d%d&d'd(d)d*i d+d,d-d.d/d0d1d2d3d4d5d6d7d8d9d:d;d<d=d>d?d@dAdBdCdDdEdFdGdHdIdJdKdLdMdNdOdPZdQZdR Z G dS dT          ZdU ZdV ZdS )Wz
Analyze docstrings to detect errors.

Call ``validate(object_name_to_validate)`` to get a dictionary
with all the detected errors.
    N   )get_doc_object)versionaddedversionchanged
deprecatedz^\s*\.\. ({})(?!::)|)
Parameters
AttributesMethodsReturnsYieldsOther ParametersRaisesWarnsWarningsSee AlsoNotes
ReferencesExamplesGL01zDocstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)GL02zClosing quotes should be placed in the line after the last text in the docstring (do not close the quotes in the same line as the text, or leave a blank line between the last text and the quotes)GL03zDouble line break found; please use only one blank line to separate sections or paragraphs, and do not leave blank lines at the end of docstringsGL05zNTabs found at the start of line "{line_with_tabs}", please use whitespace onlyGL06zKFound unknown section "{section}". Allowed sections are: {allowed_sections}GL07zESections are in the wrong order. Correct order is: {correct_sections}GL08z$The object does not have a docstringGL09z3Deprecation warning should precede extended summaryGL10z;reST directives {directives} must be followed by two colonsSS01zgNo summary found (a short summary in a single line should be present at the beginning of the docstring)SS02z,Summary does not start with a capital letterSS03z"Summary does not end with a periodSS04z$Summary contains heading whitespacesSS05zfSummary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")SS06z#Summary should fit in a single lineES01No extended summary foundPR01z*Parameters {missing_params} not documentedPR02z#Unknown parameters {unknown_params}PR03zPWrong parameters order. Actual: {actual_params}. Documented: {documented_params}PR04z$Parameter "{param_name}" has no typePR05z8Parameter "{param_name}" type should not finish with "."PR06zQParameter "{param_name}" type should use "{right_type}" instead of "{wrong_type}"PR07z+Parameter "{param_name}" has no descriptionPR08zGParameter "{param_name}" description should start with a capital letterPR09z;Parameter "{param_name}" description should finish with "."PR10zaParameter "{param_name}" requires a space before the colon separating the parameter name and typeRT01zNo Returns section foundRT02zmThe first line of the Returns section should contain only the type, unless multiple values are being returnedRT03zReturn value has no descriptionRT04z;Return value description should start with a capital letterRT05z/Return value description should finish with "."YD01zNo Yields section foundSA01zSee Also section not foundSA02zNMissing period at end of description for See Also "{reference_name}" referencezKDescription should be capitalized for See Also "{reference_name}" referencez=Missing description for See Also "{reference_name}" referencezNo examples section found)SA03SA04EX01) z* z- c                 4    | t          |          j        di |fS )a   
    Return a tuple with the error code and the message with variables replaced.

    This is syntactic sugar so instead of:
    - `('PR02', ERROR_MSGS['PR02'].format(doctest_log=log))`

    We can simply use:
    - `error('PR02', doctest_log=log)`

    Parameters
    ----------
    code : str
        Error code.
    **kwargs
        Values for the variables in the error messages

    Returns
    -------
    code : str
        Error code.
    message : str
        Error message with variables replaced.
     )
ERROR_MSGSformat)codekwargss     1lib/python3.11/site-packages/numpydoc/validate.pyerrorrD   i   s%    0 *T")33F3344    c                   r   e Zd Zd Zed             Zed             Zed             Zed             Z	ed             Z
ed             Zed             Zed	             Zed
             Zed             Zed             Zed             Zed             Zed             Zd Zed             Zed             Zed             Zed             Zed             Zed             Zd Zed             Zed             Zed             Zed             Zed             Z ed             Z!ed             Z"dS ) 	Validatorc                     || _         | j         j        | _        t          j        | j                  | _        | j        j        pd| _        t          j	        | j                  | _
        d S N )doc_objobjinspectunwrapcode_obj__doc__raw_docpydocgetdoc	clean_doc)self
doc_objects     rC   __init__zValidator.__init__   sO    8=tx00x'-2dh//rE   c                 X    d                     | j        j        | j        j        g          S )N.)joinrM   
__module____name__rV   s    rC   namezValidator.name   s#    xx,dh.?@AAArE   c                 $   t          d|                     d          dz             D ]@}|                     d|          ^}}	 t          j        |          } n## t
          $ r Y =w xY wt          d|  d          |D ]}t          ||          }|S )a  
        Import Python object from its name as string.

        Parameters
        ----------
        name : str
            Object name to import (e.g. pandas.Series.str.upper)

        Returns
        -------
        object
            Python object that can be a class, method, function...

        Examples
        --------
        >>> Validator._load_obj('datetime.datetime')
        <class 'datetime.datetime'>
        r   rZ   r   z No module can be imported from "")rangecountrsplit	importlibimport_moduleImportErrorgetattr)r_   maxsplitmodule
func_partsrM   parts         rC   	_load_objzValidator._load_obj   s    ( aC1!455 		J 		JH"&++c8"<"<FZ-f55     
 HHHHIII 	% 	%D#t$$CC
s   A
A%$A%c                 4    t          | j                  j        S N)typerM   r]   r^   s    rC   rp   zValidator.type   s    DH~~&&rE   c                 4    t          j        | j                  S ro   )rN   
isfunctionrM   r^   s    rC   is_function_or_methodzValidator.is_function_or_method   s    !$(+++rE   c                 4    t          j        | j                  S ro   )rN   isgeneratorfunctionrM   r^   s    rC   is_generator_functionzValidator.is_generator_function   s    *48444rE   c                 \    	 t          j        | j                  }|S # t          $ r Y dS w xY w)zX
        File name where the object is implemented (e.g. pandas/core/frame.py).
        N)rN   getsourcefilerP   	TypeError)rV   fnames     rC   source_file_namezValidator.source_file_name   sF    
	)$-88E L  	 	 	 DD		s    
++c                 r    	 t          j        | j                  d         S # t          t          f$ r Y dS w xY w)zI
        Number of line where the object is defined in its file.
        N)rN   getsourcelinesrP   OSErrorry   r^   s    rC   source_file_def_linezValidator.source_file_def_line   sH    
	)$-88<<# 	 	 	 DD		s   ! 66c                     d }| j         rCt          | j                             d                    D ]\  }}|                                r n|S N
)rR   	enumeratesplitstriprV   irows      rC   start_blank_lineszValidator.start_blank_lines   s[    < 	#DL$6$6t$<$<==  399;; ErE   c                     d }| j         rPt          t          | j                             d                              D ]\  }}|                                r n|S r   )rR   r   reversedr   r   r   s      rC   end_blank_lineszValidator.end_blank_lines   sc    < 	#HT\-?-?-E-E$F$FGG  399;; ErE   c                     d}| j                             d          D ]/}|s|                                s dS |                                }0dS )NTr   F)rR   r   r   )rV   prevr   s      rC   double_blank_lineszValidator.double_blank_lines   sX    <%%d++ 	 	C 		 tt99;;DDurE   c                    g }| j         j                                         | j         j                                        s| j                                         }t          |          dk    rat          |d                   t          |d                   k    r5t          |d                   dhk    r|                    |d                    | j         j                                        |S )Nr   r   -)rK   _docreseteof_read_to_next_sectionlensetappend)rV   sectionscontents      rC   section_titleszValidator.section_titles   s    (-##%% 	,h4466GGq ,
OOs71:6, 
OOu,,
 
+++ (-##%% 	, rE   c                 B    d                     | j        d                   S )Nr<   Summary)r[   rK   r^   s    rC   summaryzValidator.summary  s    xx+,,,rE   c                 6    t          | j        d                   S )Nr   )r   rK   r^   s    rC   num_summary_lineszValidator.num_summary_lines	  s    48I&'''rE   c                     | j         d         s>t          | j         d                   dk    r d                    | j         d                   S d                    | j         d                   S )NzExtended Summaryr   r   r<   )rK   r   r[   r^   s    rC   extended_summaryzValidator.extended_summary  s`    x*+ 	1DHY4G0H0H10L 	188DHY/000xx!34555rE   c                     t          j                    }|D ]5}| j        |         D ]%\  }}}|                    d          D ]	}||f||<   
&6|S )N, )collectionsOrderedDictrK   r   )rV   r   
parameterssectionnamestype_descr_   s           rC   _doc_parameterszValidator._doc_parameters  sz     ,..
 	5 	5G&*hw&7 5 5"ud!KK-- 5 5D(-t}Jt$$55 rE   c                 .    |                      dg          S )Nr	   r   r^   s    rC   doc_parameterszValidator.doc_parameters  s    ##\N333rE   c                 .    |                      dg          S )Nr   r   r^   s    rC   doc_other_parameterszValidator.doc_other_parameters  s    ##%7$8999rE   c                 0    |                      ddg          S )Nr	   r   r   r^   s    rC   doc_all_parameterszValidator.doc_all_parameters#  s    ##\3E$FGGGrE   c                    d t          j        | j                  rOt          | j        d          r:| j                            d          d         | j        j        v rt                      S 	 t          j        | j                  n%# t          t          f$ r t                      cY S w xY wt          fdj        D                       }|r|d         dv r
|dd          S |S )	Nc                     |j         t          j        j        k    rd|  S |j         t          j        j        k    rd|  S | S )zD
            Add stars to *args and **kwargs parameters
            *z**)kindrN   	ParameterVAR_POSITIONALVAR_KEYWORD)
param_nameinfos     rC   	add_starsz1Validator.signature_parameters.<locals>.add_stars)  sP     yG-<< "':'''g/;; "(J(((!!rE   
_accessorsrZ   r}   c              3   F   K   | ]} |j         |                   V  d S ro   )r   ).0	parameterr   sigs     rC   	<genexpr>z1Validator.signature_parameters.<locals>.<genexpr>A  sJ       
 
 Ii	!:;;
 
 
 
 
 
rE   r   )rV   clsr   )rN   isclassrM   hasattrr_   r   r   tuple	signaturery   
ValueErrorr   )rV   paramsr   r   s     @@rC   signature_parameterszValidator.signature_parameters'  s    		" 		" 		" ?48$$ 	tx.. 	$$R(DH,?? ww	#DH--CC:& 	 	 	 77NNN	
  
 
 
 
 
 ^
 
 
 
 
  	fQi?2 	!"":s   /B	 	B+*B+c                    g }| j         }t          d | j        D                       }t          |          t          |          z
  }|r1|                    t          dt          |                               t          |          t          |          z
  }|r1|                    t          dt          |                               |s1|s/||k    r)|s|r%|                    t          d||                     |S )Nc              3   B   K   | ]}|                     d d          V  dS )\rJ   N)replace)r   params     rC   r   z1Validator.parameter_mismatches.<locals>.<genexpr>M  s0      XXu5==r22XXXXXXrE   r'   )missing_paramsr(   )unknown_paramsr)   )actual_paramsdocumented_params)r   r   r   r   r   rD   str)rV   errssignature_params
all_paramsmissingextras         rC   parameter_mismatcheszValidator.parameter_mismatchesI  s)   4XX@WXXXXX
&''#j//9 	DKKfS\\BBBCCCJ#&6"7"77 	BKKfSZZ@@@AAA
	
	 !J.
	 *	
	 3=	
	 KK*:j     rE   c                 @    t                               | j                  S ro   )DIRECTIVE_PATTERNfindallrR   r^   s    rC   directives_without_two_colonsz'Validator.directives_without_two_colonsb  s     ((666rE   c                 (    | j         |         d         S )Nr   )r   )rV   r   s     rC   parameter_typezValidator.parameter_typef  s    &u-a00rE   c                     t          j                    }| j        d         D ]%\  }}|D ]\  }}d                    |          ||<   &|S )Nr   rJ   )r   r   rK   r[   )rV   resultfuncsr   func_s         rC   see_alsozValidator.see_alsoi  s^    (**8J/ 	- 	-KE4  - -a!wwt}}t- rE   c                     | j         d         S )Nr   rK   r^   s    rC   exampleszValidator.examplesr  s    x
##rE   c                     | j         d         S )Nr   r   r^   s    rC   returnszValidator.returnsv  s    x	""rE   c                     | j         d         S )Nr   r   r^   s    rC   yieldszValidator.yieldsz  s    x!!rE   c                     	 t          j        | j                  }n# t          $ r Y dS w xY wt	          j        |          S rI   )rN   	getsourcerM   ry   textwrapdedent)rV   sources     rC   method_sourcezValidator.method_source~  sM    	&tx00FF 	 	 	22	v&&&s    
**c                     fdt          j        | j                  j        }|rg |d                   }d |D             }t	          |          D ]+\  }}t          |t           j                  r|j        d||<   ,t          |          S dS )a  
        Check if the docstrings method can return something.

        Bare returns, returns valued None and returns from nested functions are
        disconsidered.

        Returns
        -------
        bool
            Whether the docstrings method can return something.
        c                     t          | t          j                  r| gng }t          j        |           D ]<}t          |t          j                  s  |          }|                    |           =|S ro   )
isinstanceastReturniter_child_nodesFunctionDefextend)noder   childchild_returns#get_returns_not_on_nested_functionss       rC   r  zOValidator.method_returns_something.<locals>.get_returns_not_on_nested_functions  su     *4 < <Dtff"G-d33 2 2!%99 2$G$G$N$NMNN=111NrE   r   c                     g | ]	}|j         
S r>   )value)r   rs     rC   
<listcomp>z6Validator.method_returns_something.<locals>.<listcomp>  s    666QW666rE   NF)	r   parser   bodyr   r   NameConstantr  any)rV   treer   return_valuesr   vr  s         @rC   method_returns_somethingz"Validator.method_returns_something  s    	 	 	 	 	 y+,,1 		99$q'BBG66g666M!-00 , ,1a!122 ,qw ,'+M!$}%%%5rE   c                 $    d| j         | j        z   v S )N.. deprecated:: )r   r   r^   s    rC   r   zValidator.deprecated  s    !dlT5J&JKKrE   N)#r]   r\   __qualname__rX   propertyr_   staticmethodrm   rp   rs   rv   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>   rE   rC   rG   rG      s(       0 0 0 B B XB     \ D ' ' X' , , X, 5 5 X5   X 
 
 X
   X   X   X   X - - X- ( ( X( 6 6 X6
   4 4 X4 : : X: H H XH   XB   X0 7 7 X71 1 1   X $ $ X$ # # X# " " X" ' ' X'     X D L L XL L LrE   rG   c                    d                     |           } t          D ];}d| }|| v r0| d |                     |                                       d          } <|                     d          } t                      }d                     |           s!|                    t          |fi |           n| d         d                                         r@| d         d         	                                s |                    t          |fi |           | d         
                    d          s@| d                             t                    s |                    t          |fi |           |S )Nr   z.. rJ   r   r}   rZ   )r[   
DIRECTIVESindexrstripr   listr   rD   isalphaisupperendswith
startswithIGNORE_STARTS)r   code_no_desccode_no_uppercode_no_periodrB   	directivefull_directiver   s           rC   _check_descr"    sn   99T??D C C	*y**T! 	C4$**^4445<<TBBD::dD66D774== 9E,11&11222271: 	8Q
(:(:(<(< 	8KKm66v66777 Bx  %% 	9d2h.A.A-.P.P 	9KKn7777888KrE   c           
      :   t          | t                    r5t          t          t                              |                               nt          |           g }j        sE|                    t          d                     j        j	        j
        j        j        |ddS j        dk    r+dj        v r"|                    t          d                     j        dk    r+dj        v r"|                    t          d                     j        r"|                    t          d                     j                                        D ]M}t#          j        d	|          r6|                    t          d
|                                                     Nd j        D             }|D ]?}|                    t          d|d                    t,                                         @fdt,          D             }|j        k    r7|                    t          dd                    |                               j
        r<j                            d          s"|                    t          d                     j        }|r$|                    t          d|                     j        s$|                    t          d                     nXj        d                                         rAj        d                                         s"|                    t          d                     j        d         dk    r"|                    t          d                     j        j                                        k    r#|                    t          d                     nSj        rLj                            d          d         d         dk    r"|                    t          d                      j        dk    r"|                    t          d!                     j        s|                    d"           |j         z  }j!        "                                D ]i\  }}|                    d#          s #                    |          sgd$|v r>|                    t          d%|                    d$          d         &                     n|                    t          d'|&                     n#                    |          d         dk    r$|                    t          d(|&                     d)#                    |          v rg d*}	|	D ]B\  }
}|
#                    |          v r&|                    t          d+|||
,                     C|$                    tK          |d         d-d.d/|&                     kj        rj&        s*j'        r"|                    t          d0                     ntQ          j&                  dk    r4j&        d         j)        r"|                    t          d1                     j&        D ]+\  }}}|$                    tK          |d2d3d4                     ,j*        s)j+        r"|                    t          d5                     j,        s#|                    t          d6                     n׉j,        "                                D ]\  }}|r|-                    d          s$|                    t          d7|8                     |d                                         r>|d                                         s$|                    t          d9|8                     |                    t          d:|8                     j.        s"|                    t          d;                     j        j	        j
        j        j        |d<S )=a  
    Validate the docstring.

    Parameters
    ----------
    obj_name : str
        The name of the object whose docstring will be evaluated, e.g.
        'pandas.read_csv'. The string must include the full, unabbreviated
        package/module names, i.e. 'pandas.read_csv', not 'pd.read_csv' or
        'read_csv'.

    Returns
    -------
    dict
        A dictionary containing all the information obtained from validating
        the docstring.

    Notes
    -----
    The errors codes are defined as:
    - First two characters: Section where the error happens:
       * GL: Global (no section, like section ordering errors)
       * SS: Short summary
       * ES: Extended summary
       * PR: Parameters
       * RT: Returns
       * YD: Yields
       * RS: Raises
       * WN: Warns
       * SA: See Also
       * NT: Notes
       * RF: References
       * EX: Examples
    - Last two characters: Numeric error code inside the section

    For example, PR02 is the second codified error in the Parameters section
    (which in this case is assigned to the error when unknown parameters are documented).

    The error codes, their corresponding error messages, and the details on how
    they are validated, are not documented more than in the source code of this
    function.
    r   rJ   )rp   	docstringr   file	file_lineerrorsexamples_errorsr   r   r   r   r   z^ *	r   )line_with_tabsc                 $    g | ]}|t           v|S r>   )ALLOWED_SECTIONS)r   r   s     rC   r  zvalidate.<locals>.<listcomp>  s3       WDT5T  rE   r   r   )r   allowed_sectionsc                 &    g | ]}|j         v |S r>   )r   )r   r   rK   s     rC   r  zvalidate.<locals>.<listcomp>  s6       7c>P3P  rE   r   )correct_sectionsr  r   r   )
directivesr   r   r    r}   rZ   r!   r"   r<   sr#   r$   )r%   r&   r   :r0   )r   r*   r+   {))integerint)booleanbool)stringr   r,   )r   
right_type
wrong_typer-   r.   r/   r1   r2   r3   r4   r5   r6   r7   r8   )reference_namer9   r:   r;   )rp   r$  r   r%  r&  r'  )/r   r   rG   r   rm   rR   r   rD   rp   rU   r   r{   r   r   r   r   
splitlinesrematchlstripr   r[   r+  r   r  r   r   r  r  rs   r   r   r   r   itemsr   r   r"  r   r  r   r_   r   rv   r   r  r   )obj_namer   lineunexpected_sectionsr   correct_orderr   r   	kind_desccommon_type_errorsr9  r8  name_or_typer   r   rel_namerel_descrK   s                    @rC   validaterI    s'   V (C   "y':':8'D'DEEFF!!D; 

E&MM"""H.(1!
 
 	
 ! #dck&9 #E&MM"""
a #DCK$7 #E&MM"""
 #E&MM"""&&(( E E8GT"" 	EKKfT[[]]CCCDDD "1   ' 
 
&'DIIFV<W<WXXX	
 	
 	
 	
   /  M ** NE&499]3K3KLLLMMM
~ #c2==>PQQ #E&MM"""$'$E!$ ME&-JKKKLLL; 'E&MM"""";q>!!## 	'CKN,B,B,D,D 	'KKf&&&;r?c! 	'KKf&&&;#+,,... 	'KKf&&&&& 	'3;+<+<S+A+A!+DR+HC+O 	'KKf&&& 1$ 	'KKf&&& ;9:::
 	C$$D288:: Y Yy$$ 	%%e,, %< AKKfS9I9I!9L M M MNNNNKKf ? ? ?@@@@%%e,,R0C7 AKKf ? ? ?@@@ #,,U333 & & &"
 /A 	 	*J
!S%7%7%>%>> ! &+0+5+5	     	K	!fffQVWWWXXXX
  '{ 	G+ +E&MM***3;1$ +Q)< +E&MM***-0[ G G)eTKfffEEFFFFz 	'c7 	'KKf&&&< 
DE&MM"""""%,"4"4"6"6 	D 	DHh D((-- HKKfX F F FGGGA;&&(( H!1D1D1F1F HKKfX F F FGGGE&BBBCCCC< #E&MM"""]n$-  rE   )rQ   r   r   re   rN   rS   r<  r   	docscraper   r  compiler@   r[   IMr   r+  r?   r  rD   rG   r"  rI  r>   rE   rC   <module>rN     s\    


           				  % % % % % % >==
BJ!!#((:"6"677     $8
 8  	8  8  8  8 S8  2!8" A#8$ I%8&  1'8* :+8, 0-8. 2/80  3184 1586 '788 898 8: 1;8<  &=8@ 2A8B FC8D  E8H 9I8J  K8N IO8P  -Q8T &U8V  6W8Z -[8\ I]8^ =_8` %a8b (c8d  #e8 8h#K'o8 8 8
| "5 5 56gL gL gL gL gL gL gL gLT	  .s s s s srE   