B
    BcXS              &   @   s  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	 dddgZ
edd	e
ejejB Zd
ddddddddddddgZ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/d0d1d2d3d4d5d6d7d8d9d:d;d<%Zd=Zd>d? ZG d@dA dAZdBdC ZdDdE ZdS )Fz
Analyze docstrings to detect errors.

Call ``validate(object_name_to_validate)`` to get a dictionary
with all the detected errors.
    N   )get_doc_objectZversionaddedZversionchanged
deprecatedz^\s*\.\. ({})(?!::)|
ParametersZ
AttributesZMethodsReturnsYieldszOther ParametersZRaisesZWarnsZWarningszSee AlsoZNotesZ
ReferencesExampleszDocstring text (summary) should start in the line immediately after the opening quotes (not in the same line, or leaving a blank line in between)zClosing 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)zDouble line break found; please use only one blank line to separate sections or paragraphs, and do not leave blank lines at the end of docstringszNTabs found at the start of line "{line_with_tabs}", please use whitespace onlyzKFound unknown section "{section}". Allowed sections are: {allowed_sections}zESections are in the wrong order. Correct order is: {correct_sections}z$The object does not have a docstringz3Deprecation warning should precede extended summaryz;reST directives {directives} must be followed by two colonszgNo summary found (a short summary in a single line should be present at the beginning of the docstring)z,Summary does not start with a capital letterz"Summary does not end with a periodz$Summary contains heading whitespaceszfSummary must start with infinitive verb, not third person (e.g. use "Generate" instead of "Generates")z#Summary should fit in a single linezNo extended summary foundz*Parameters {missing_params} not documentedz#Unknown parameters {unknown_params}zPWrong parameters order. Actual: {actual_params}. Documented: {documented_params}z$Parameter "{param_name}" has no typez8Parameter "{param_name}" type should not finish with "."zQParameter "{param_name}" type should use "{right_type}" instead of "{wrong_type}"z+Parameter "{param_name}" has no descriptionzGParameter "{param_name}" description should start with a capital letterz;Parameter "{param_name}" description should finish with "."zaParameter "{param_name}" requires a space before the colon separating the parameter name and typezNo Returns section foundzmThe first line of the Returns section should contain only the type, unless multiple values are being returnedzReturn value has no descriptionz;Return value description should start with a capital letterz/Return value description should finish with "."zNo Yields section foundzSee Also section not foundzNMissing 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)%GL01GL02GL03GL05GL06GL07GL08GL09GL10SS01SS02SS03SS04SS05SS06ES01PR01PR02PR03PR04PR05PR06PR07PR08PR09PR10RT01RT02RT03RT04RT05YD01SA01SA02SA03SA04EX01) z* z- c             K   s   | t |  jf |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kwargs r4   0lib/python3.7/site-packages/numpydoc/validate.pyerrori   s    r6   c               @   sh  e Zd Zdd Zedd Zedd Zedd Zed	d
 Z	edd Z
edd Zedd Zedd Zedd Zedd Zedd Zedd Zedd Zedd Zdd  Zed!d" Zed#d$ Zed%d& Zed'd( Zed)d* Zed+d, Zd-d. Zed/d0 Zed1d2 Zed3d4 Zed5d6 Zed7d8 Z ed9d: Z!ed;d< Z"d=S )>	Validatorc             C   s>   || _ | j j| _t| j| _| jjp(d| _t	| j| _
d S )N )docZ_objobjinspectZunwrapcode_obj__doc__raw_docpydocZgetdoc	clean_doc)selfZ
doc_objectr4   r4   r5   __init__   s
    
zValidator.__init__c             C   s   d | jj| jjgS )N.)joinr:   
__module____name__)rA   r4   r4   r5   name   s    zValidator.namec          	   C   s   xbt d| dd D ]:}| d|^}}yt|}W n tk
rL   Y qX P qW td|  dx|D ]}t||}qjW |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   rC   r   z No module can be imported from "")rangecountrsplit	importlibimport_moduleImportErrorgetattr)rG   maxsplitmoduleZ
func_partsr:   partr4   r4   r5   	_load_obj   s    
zValidator._load_objc             C   s   t | jjS )N)typer:   rF   )rA   r4   r4   r5   rT      s    zValidator.typec             C   s   t | jS )N)r;   Z
isfunctionr:   )rA   r4   r4   r5   is_function_or_method   s    zValidator.is_function_or_methodc             C   s   t | jS )N)r;   Zisgeneratorfunctionr:   )rA   r4   r4   r5   is_generator_function   s    zValidator.is_generator_functionc             C   s.   yt | j}W n tk
r$   Y nX |S dS )zX
        File name where the object is implemented (e.g. pandas/core/frame.py).
        N)r;   Zgetsourcefiler<   	TypeError)rA   fnamer4   r4   r5   source_file_name   s
    zValidator.source_file_namec          	   C   s.   yt | jd S  ttfk
r(   Y nX dS )zI
        Number of line where the object is defined in its file.
        N)r;   Zgetsourcelinesr<   OSErrorrW   )rA   r4   r4   r5   source_file_def_line   s    zValidator.source_file_def_linec             C   s6   d }| j r2x&t| j dD ]\}}| rP qW |S )N
)r>   	enumeratesplitstrip)rA   irowr4   r4   r5   start_blank_lines   s    zValidator.start_blank_linesc             C   s:   d }| j r6x*tt| j dD ]\}}| r P q W |S )Nr]   )r>   r^   reversedr_   r`   )rA   ra   rb   r4   r4   r5   end_blank_lines   s    zValidator.end_blank_linesc             C   s6   d}x,| j dD ]}|s&| s&dS | }qW dS )NTr]   F)r>   r_   r`   )rA   prevrb   r4   r4   r5   double_blank_lines   s    zValidator.double_blank_linesc             C   st   g }| j j  x^| j j sn| j  }t|dkrt|d t|d krt|d dhkr||d  qW |S )Nr   r   -)r9   Z_docreseteofZ_read_to_next_sectionlensetappend)rA   sectionsZcontentr4   r4   r5   section_titles   s    
zValidator.section_titlesc             C   s   d | jd S )Nr/   Summary)rD   r9   )rA   r4   r4   r5   summary  s    zValidator.summaryc             C   s   t | jd S )Nrp   )rk   r9   )rA   r4   r4   r5   num_summary_lines	  s    zValidator.num_summary_linesc             C   s<   | j d s,t| j d dkr,d| j d S d| j d S )NzExtended Summaryrp   r   r/   )r9   rk   rD   )rA   r4   r4   r5   extended_summary  s    zValidator.extended_summaryc             C   sT   t  }xF|D ]>}x8| j| D ]*\}}}x|dD ]}||f||< q4W qW qW |S )Nz, )collectionsOrderedDictr9   r_   )rA   rn   
parameterssectionnamestype_descrG   r4   r4   r5   _doc_parameters  s    
zValidator._doc_parametersc             C   s   |  dgS )Nr   )r{   )rA   r4   r4   r5   doc_parameters  s    zValidator.doc_parametersc             C   s   |  dgS )NzOther Parameters)r{   )rA   r4   r4   r5   doc_other_parameters  s    zValidator.doc_other_parametersc             C   s   |  ddgS )Nr   zOther Parameters)r{   )rA   r4   r4   r5   doc_all_parameters#  s    zValidator.doc_all_parametersc          	      s   dd  t | jr>t| jdr>| jdd | jjkr>t S yt | jW n t	t
fk
rh   t S X t fddjD }|r|d d	kr|d
d  S |S )Nc             S   s8   |j tjjkrd|  S |j tjjkr0d|  S | S dS )zD
            Add stars to *args and **kwargs parameters
            *z**N)kindr;   Z	ParameterZVAR_POSITIONALZVAR_KEYWORD)
param_nameinfor4   r4   r5   	add_stars)  s
    

z1Validator.signature_parameters.<locals>.add_stars
_accessorsrC   rZ   c             3   s   | ]} |j | V  qd S )N)rv   ).0Z	parameter)r   sigr4   r5   	<genexpr>B  s   z1Validator.signature_parameters.<locals>.<genexpr>r   )rA   clsr   )r;   Zisclassr:   hasattrrG   r_   r   tupleZ	signaturerW   
ValueErrorrv   )rA   paramsr4   )r   r   r5   signature_parameters'  s    zValidator.signature_parametersc             C   s   g }| j }tdd | jD }t|t| }|rH|tdt|d t|t| }|rr|tdt|d |s|s||kr|s|r|td||d |S )	Nc             s   s   | ]}| d dV  qdS )\r8   N)replace)r   paramr4   r4   r5   r   M  s    z1Validator.parameter_mismatches.<locals>.<genexpr>r   )Zmissing_paramsr   )Zunknown_paramsr   )Zactual_paramsZdocumented_params)r   r   r~   rl   rm   r6   str)rA   errsZsignature_paramsZ
all_paramsmissingZextrar4   r4   r5   parameter_mismatchesI  s"    zValidator.parameter_mismatchesc             C   s   t | jS )N)DIRECTIVE_PATTERNfindallr>   )rA   r4   r4   r5   directives_without_two_colonsb  s    z'Validator.directives_without_two_colonsc             C   s   | j | d S )Nr   )r~   )rA   r   r4   r4   r5   parameter_typef  s    zValidator.parameter_typec             C   sD   t  }x6| jd D ](\}}x|D ]\}}d|||< q"W qW |S )NzSee Alsor8   )rt   ru   r9   rD   )rA   resultZfuncsrz   func_r4   r4   r5   see_alsoi  s
    zValidator.see_alsoc             C   s
   | j d S )Nr	   )r9   )rA   r4   r4   r5   examplesr  s    zValidator.examplesc             C   s
   | j d S )Nr   )r9   )rA   r4   r4   r5   returnsv  s    zValidator.returnsc             C   s
   | j d S )Nr   )r9   )rA   r4   r4   r5   yieldsz  s    zValidator.yieldsc             C   s0   yt | j}W n tk
r$   dS X t|S )Nr8   )r;   Z	getsourcer:   rW   textwrapdedent)rA   sourcer4   r4   r5   method_source~  s
    zValidator.method_sourcec                s|    fdd t | jj}|rt |d }dd |D }x2t|D ]&\}}t|t jrB|jdkrBd||< qBW t|S d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                sL   t | tjr| gng }x0t| D ]"}t |tjs" |}|| q"W |S )N)
isinstanceastZReturnZiter_child_nodesZFunctionDefextend)Znoder   ZchildZchild_returns)#get_returns_not_on_nested_functionsr4   r5   r     s    zOValidator.method_returns_something.<locals>.get_returns_not_on_nested_functionsr   c             S   s   g | ]
}|j qS r4   )value)r   rr4   r4   r5   
<listcomp>  s    z6Validator.method_returns_something.<locals>.<listcomp>NF)	r   parser   Zbodyr^   r   ZNameConstantr   any)rA   Ztreer   Zreturn_valuesra   vr4   )r   r5   method_returns_something  s    	z"Validator.method_returns_somethingc             C   s   d| j | j kS )Nz.. deprecated:: )rq   rs   )rA   r4   r4   r5   r     s    zValidator.deprecatedN)#rF   rE   __qualname__rB   propertyrG   staticmethodrS   rT   rU   rV   rY   r\   rc   re   rg   ro   rq   rr   rs   r{   r|   r}   r~   r   r   r   r   r   r   r   r   r   r   r   r4   r4   r4   r5   r7      s<   #			"	#r7   c             K   s   d | } x6tD ].}d| }|| kr| d | | d} qW | d} t }d | sp|t|f| n`| d d  r| d d 	 s|t|f| | d 
ds| d ts|t|f| |S )Nr]   z.. r8   r   rZ   rC   )rD   
DIRECTIVESindexrstripr_   listrm   r6   isalphaisupperendswith
startswithIGNORE_STARTS)rz   Zcode_no_descZcode_no_upperZcode_no_periodr3   Z	directiveZfull_directiver   r4   r4   r5   _check_desc  s    




 r   c          
      s  t | trttt|  nt|  g } js\|td  j j	 j
 j j|ddS  jdkr~d jkr~|td  jdkrd jkr|td  jr|td x4 j D ]&}td	|r|td
| d qW dd  jD }x(|D ] }|td|dtd q W  fddtD }| jkrZ|tdd|d  j
r~ jds~|td  j}|r|td|d  js|td n jd  r jd  s|td  jd dkr |td  j j kr"|td n0 jrR jdd d d krR|td!  jdkrl|td"  js~|d# | j 7 }x j!" D ]\}}|d$sp #|sd%|kr|td&|d%d d' n|td(|d' n~ #|d dkr|td)|d' d* #|kr,qd+d,d-g}	x8|	D ]0\}
}|
 #|kr<|td.|||
d/ q<W |$t%|d d0d1d2|d' qW  jr0 j&s j'r|td3 nXt( j&dkr j&d j)r|td4 x* j&D ] \}}}|$t%|d5d6d7 qW  j*s0 j+r0|td8  j,sH|td9 nx~ j," D ]p\}}|r|-ds|td:|d; |d  r|d  s|td<|d; n|td=|d; qTW  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   r8   )rT   	docstringr   file	file_lineerrorsZexamples_errorsr   r]   r
   r   r   z^ *	r   )Zline_with_tabsc             S   s   g | ]}|t kr|qS r4   )ALLOWED_SECTIONS)r   rw   r4   r4   r5   r     s    zvalidate.<locals>.<listcomp>r   z, )rw   Zallowed_sectionsc                s   g | ]}| j kr|qS r4   )ro   )r   rw   )r9   r4   r5   r     s    r   )Zcorrect_sectionsz.. deprecated:: r   r   )Z
directivesr   r   r   rZ   rC   r   r   r/   sr   r   )r   zNo extended summary foundr   :r#   )r   r   r   {)Zintegerint)Zbooleanbool)stringr   r   )r   
right_type
wrong_typer    r!   r"   r$   r%   r&   r'   r(   r)   r*   r+   )Zreference_namer,   r-   r.   )rT   r   r   r   r   r   )/r   r   r7   r   rS   r>   rm   r6   rT   r@   r   rY   r\   rc   re   rg   
splitlinesrematchlstripro   rD   r   rs   r   r   rq   r   r   rU   r_   rr   r   r~   itemsr   r   r   r   r   rk   rG   r   rV   r   r   r   )Zobj_namer   lineZunexpected_sectionsrw   Zcorrect_orderr   r   Z	kind_descZcommon_type_errorsr   r   Zname_or_typery   rz   Zrel_nameZrel_descr4   )r9   r5   validate  s    +

 "


"r   )r=   r   rt   rL   r;   r?   r   r   Z	docscraper   r   compiler1   rD   IMr   r   r0   r   r6   r7   r   r   r4   r4   r4   r5   <module>   s   
  ,