B
    Bc[                 @   s  d Z ddlZddlZddlZddlZddlmZ ddlmZ ddl	m
Z
mZ ddlZddlZyddlmZ W n ek
r   eZY nX dd ZG d	d
 d
ZG dd deZeddddgZG dd deZdd ZG dd deZG dd deZG dd deZdddZdS )z=Extract reference documentation from the NumPy source tree.

    N)warn)
namedtuple)CallableMapping)cached_propertyc             C   s<   x| r| d   s| d= qW x| r6| d   s6| d= qW | S )z<Remove leading and trailing blank lines from a list of linesr   )strip)l r
   1lib/python3.7/site-packages/numpydoc/docscrape.pystrip_blank_lines   s
    

r   c               @   sj   e Zd ZdZdd Zdd Zdd Zdd	 Zd
d Zdd Z	dd Z
dd Zdd ZdddZdd ZdS )ReaderzA line-based string reader.c             C   s*   t |tr|| _n|d| _|   dS )zs
        Parameters
        ----------
        data : str
           String with lines separated by '\n'.

        
N)
isinstancelist_strsplitreset)selfdatar
   r
   r   __init__"   s    
zReader.__init__c             C   s
   | j | S )N)r   )r   nr
   r
   r   __getitem__1   s    zReader.__getitem__c             C   s
   d| _ d S )Nr   )_l)r   r
   r
   r   r   4   s    zReader.resetc             C   s,   |   s$| | j }|  jd7  _|S dS d S )N    )eofr   )r   outr
   r
   r   read7   s
    
zReader.readc             C   s6   x0| | j d  D ]}| r P q|  j d7  _ qW d S )Nr   )r   r   )r   r	   r
   r
   r   seek_next_non_empty_line?   s    zReader.seek_next_non_empty_linec             C   s   | j t| jkS )N)r   lenr   )r   r
   r
   r   r   F   s    z
Reader.eofc             C   s^   | j }xR| |d  D ]B}||r.| || j  S |  j d7  _ |  r| || j d  S qW g S )Nr   )r   r   )r   Zcondition_funcstartliner
   r
   r   read_to_conditionI   s    zReader.read_to_conditionc             C   s   |    dd }| |S )Nc             S   s
   |    S )N)r   )r"   r
   r
   r   is_emptyV   s    z0Reader.read_to_next_empty_line.<locals>.is_empty)r   r#   )r   r$   r
   r
   r   read_to_next_empty_lineS   s    zReader.read_to_next_empty_linec             C   s   dd }|  |S )Nc             S   s   |   ot|  t| kS )N)r   r    lstrip)r"   r
   r
   r   is_unindented\   s    z:Reader.read_to_next_unindented_line.<locals>.is_unindented)r#   )r   r'   r
   r
   r   read_to_next_unindented_line[   s    z#Reader.read_to_next_unindented_liner   c             C   s*   | j | t| jk r"| | j |  S dS d S )Nr   )r   r    r   )r   r   r
   r
   r   peeka   s    zReader.peekc             C   s   d | j  S )Nr   )joinr   r   )r   r
   r
   r   r$   g   s    zReader.is_emptyN)r   )__name__
__module____qualname____doc__r   r   r   r   r   r   r#   r%   r(   r)   r$   r
   r
   r
   r   r      s   

r   c               @   s   e Zd Zdd ZdS )
ParseErrorc             C   s(   | j d }t| dr$| d| j}|S )Nr   	docstringz in )argshasattrr0   )r   messager
   r
   r   __str__l   s    

zParseError.__str__N)r+   r,   r-   r4   r
   r
   r
   r   r/   k   s   r/   	Parameternametypedescc               @   s  e Zd ZdZddgg g g g g g g g g g g g g ddi dZdOddZdd Zd	d
 Zdd Zdd Z	dd Z
dd Zdd Zdd ZdPddZdZdZdZde e d e d Zed d!Zed"d#Zd$Zed%e d& Zed'e d( e d) d d* e Zd+Zd,d- Zd.d/ Zd0d1 Zd2d3 Zed4d5 Z dQd7d8Z!dRd:d;Z"dSd=d>Z#d?d@ Z$dAdB Z%dCdD Z&dEdF Z'dGdH Z(dIdJ Z)dKdL Z*dTdMdNZ+dS )UNumpyDocStringzParses a numpydoc string to an abstract representation

    Instances define a mapping from section title to structured data.

    r   )	SignatureSummaryzExtended Summary
ParametersReturnsYieldsReceivesRaisesWarnszOther Parameters
AttributesMethodszSee AlsoNotesWarnings
ReferencesExamplesindexNc          
   C   sh   |}t |d}t|| _t| j| _y| 	  W n* t
k
rb } z||_ W d d }~X Y nX d S )Nr   )textwrapdedentr   r   _doccopydeepcopysections_parsed_data_parser/   r0   )r   r0   configZorig_docstringer
   r
   r   r      s    
zNumpyDocString.__init__c             C   s
   | j | S )N)rO   )r   keyr
   r
   r   r      s    zNumpyDocString.__getitem__c             C   s.   || j kr | jd| dd n
|| j |< d S )NzUnknown section F)error)rO   _error_location)r   rS   valr
   r
   r   __setitem__   s    
zNumpyDocString.__setitem__c             C   s
   t | jS )N)iterrO   )r   r
   r
   r   __iter__   s    zNumpyDocString.__iter__c             C   s
   t | jS )N)r    rO   )r   r
   r
   r   __len__   s    zNumpyDocString.__len__c             C   s   | j   | j  rdS | j   }|dr4dS | j d }t|dkrt|dhdhfkrt|t|krd| j j	d d	 d
 }| j
d| d| d| dd |dt| p|dt| S )NFz
.. index::Tr      -=r      z...z'potentially wrong underline length... 
z 
z in 
)rT   )rK   r   r   r)   r   
startswithr    setr*   r   rU   )r   l1l2Zsnipr
   r
   r   _is_at_section   s    


0zNumpyDocString._is_at_sectionc             C   sf   d}d}xt |D ]\}}| rP qW x(t |d d d D ]\}}| r<P q<W ||t||  S )Nr   r   )	enumerater   r    )r   docijr"   r
   r
   r   _strip   s    zNumpyDocString._stripc             C   sN   | j  }x>|  sH| j  sH| j d s8|dg7 }|| j  7 }qW |S )Nr   r   )rK   r%   rc   r   r)   r   )r   sectionr
   r
   r   _read_to_next_section   s    

z$NumpyDocString._read_to_next_sectionc             c   sr   xl| j  sl|  }|d  }|dr>||dd  fV  qt|dk rRtV  q|| |dd  fV  qW d S )Nr   z..r   r^   )rK   r   rj   r   r_   r    StopIterationrh   )r   r   r6   r
   r
   r   _read_sections   s    
zNumpyDocString._read_sectionsFc       	      C   s   t |}t|}g }x| s|  }d|krF|jddd\}}n0|dr\|d d }|rld| }}n
|d }}| }t |}t|}|	t
||| qW |S )Nz : r   )maxsplitz :r   )dedent_linesr   r   r   r   r   endswithr(   r   appendr5   )	r   contentsingle_element_is_typerparamsheaderZarg_nameZarg_typer8   r
   r
   r   _parse_param_list   s"    


z NumpyDocString._parse_param_listz:(?P<role>(py:)?\w+):z'`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_\.-]+)`z(?P<name2>[a-zA-Z0-9_\.-]+)(|)roleZrolenextr6   Znamenextz/(?P<description>\s*:(\s+(?P<desc>\S+.*))?)?\s*$z^\s*z\s*z^\s*(?P<allfuncs>z(?P<morefuncs>([,]\s+z)*)z(?P<trailing>[,\.])?z..c                sD  t |}g } fdd}g }x|D ]   s6q&j }d}|r~|d}|dr~|r~jd|d f dd |s d	r|   q&|r,g }|d
}xZ| sP ||\}	}
}||	|
f ||d  }|r|d dkr|dd  }qW t	t
d|g}|||f q&d  q&W |S )z
        func_name : Descriptive text
            continued text
        another_func_name : Descriptive text
        func_name1, func_name2, :meth:`func_name`, func_name3

        c                sP   j | }|s d  |d}|r8|dn|d}||| fS )zMatch ':role:`name`' or 'name'.zError parsing See Also entry r{   r6   Zname2)	_func_rgxmatchrU   groupend)textmr{   r6   )r"   r   r
   r   parse_item_name5  s    
z7NumpyDocString._parse_see_also.<locals>.parse_item_nameNr8   ZtrailingzGUnexpected comma or period after function list at index %d of line "%s"F)rT    Zallfuncsr   ,r   zError parsing See Also entry )ro   r   	_line_rgxr}   r~   rU   r   r_   rq   r   filter)r   rr   itemsr   restZ
line_matchdescriptionfuncsr   r6   r{   Z	match_endr
   )r"   r   r   _parse_see_also(  sB    		

zNumpyDocString._parse_see_alsoc             C   s~   dd }i }| d}t|dkr<||d  dd |d< x<|D ]4}| d}t|d	krB||d	  d||d < qBW |S )
zT
        .. index: default
           :refguide: something, else, and more

        c             S   s   dd | D S )Nc             S   s   g | ]}|  qS r
   )r   ).0sr
   r
   r   
<listcomp>h  s    zFNumpyDocString._parse_index.<locals>.strip_each_in.<locals>.<listcomp>r
   )Zlstr
   r
   r   strip_each_ing  s    z2NumpyDocString._parse_index.<locals>.strip_each_inz::r   r   r   default:r^   )r   r    )r   ri   rr   r   r   r"   r
   r
   r   _parse_index`  s    


zNumpyDocString._parse_indexc             C   s   |   rdS xN| j }ddd |D  }td}||rV|| d< |   sVqP qW |dk	rl|| d< |   s|  | d< dS )	z%Grab signature (if given) and summaryNr   c             S   s   g | ]}|  qS r
   )r   )r   r   r
   r
   r   r   |  s    z1NumpyDocString._parse_summary.<locals>.<listcomp>z^([\w., ]+=)?\s*[\w\.]+\(.*\)$r:   r;   zExtended Summary)	rc   rK   r%   r*   r   recompiler}   rj   )r   ZsummaryZsummary_strZcompiledr
   r
   r   _parse_summaryt  s    


zNumpyDocString._parse_summaryc             C   s@  | j   |   t|  }dd |D }d|k}d|k}|rP|rPd}t||shd|krhd}t|x|D ]\}}|dsd	d
 |dD }d|}| 	|r| 
d|d| j jf  |dkr| || |< qn|dkr| j|dd| |< qn|dr| ||| d< qn|dkr0| || d< qn|| |< qnW d S )Nc             S   s   h | ]\}}|qS r
   r
   )r   ri   rr   r
   r
   r   	<setcomp>  s    z(NumpyDocString._parse.<locals>.<setcomp>r=   r>   z5Docstring contains both a Returns and Yields section.r?   z5Docstring contains a Receives section but not Yields.z..c             s   s   | ]}|  V  qd S )N)
capitalize)r   r   r
   r
   r   	<genexpr>  s    z(NumpyDocString._parse.<locals>.<genexpr>r   z#The section %s appears twice in  %sr   )r<   zOther ParametersrB   rC   )r=   r>   r@   rA   r?   T)rs   z
.. index::rH   zSee Also)rK   r   r   r   rl   
ValueErrorr_   r   r*   getrU   r   rw   r   r   )r   rN   Zsection_namesZhas_returnsZ
has_yieldsmsgri   rr   r
   r
   r   rP     s<    




zNumpyDocString._parsec             C   s$   t | dr| jS t | dr | jS d S )N_cls_f)r2   r   r   )r   r
   r
   r   _obj  s
    

zNumpyDocString._objTc             C   s   | j d k	ryt| j }W n tk
r2   d }Y nX t| j dd }|d kr`tt| j dd dd }|d k	rv|d| 7 }||rd| dnd7 }|rt|nt| d S )Nr+   	__class__z in the docstring of z in .r   )r   inspectZgetsourcefile	TypeErrorgetattrr   r   )r   r   rT   filenamer6   r
   r
   r   rU     s    


zNumpyDocString._error_locationr\   c             C   s   |t || gS )N)r    )r   r6   symbolr
   r
   r   _str_header  s    zNumpyDocString._str_header   c                s    fdd|D S )Nc                s   g | ]}d   | qS )r   r
   )r   r"   )indentr
   r   r     s    z.NumpyDocString._str_indent.<locals>.<listcomp>r
   )r   re   r   r
   )r   r   _str_indent  s    zNumpyDocString._str_indentc             C   s&   | d r | d  ddgdg S dgS )Nr:   *z\*r   )replace)r   r
   r
   r   _str_signature  s    zNumpyDocString._str_signaturec             C   s   | d r| d dg S g S )Nr;   r   r
   )r   r
   r
   r   _str_summary  s    zNumpyDocString._str_summaryc             C   s   | d r| d dg S g S )NzExtended Summaryr   r
   )r   r
   r
   r   _str_extended_summary  s    z$NumpyDocString._str_extended_summaryc             C   s   g }| | r||  |7 }xn| | D ]b}g }|jr>||j |jrP||j |d|g7 }|jr$d|j r$|| |j7 }q$W |dg7 }|S )Nz : r   )r   r6   rq   r7   r*   r8   r   r   )r   r6   r   Zparampartsr
   r
   r   _str_param_list  s    
zNumpyDocString._str_param_listc             C   s4   g }| | r0||  |7 }|| | 7 }|dg7 }|S )Nr   )r   )r   r6   r   r
   r
   r   _str_section  s    
zNumpyDocString._str_sectionc       
      C   s  | d sg S g }||  d7 }|dg7 }d}x| d D ]\}}t|tsLtg }xV|D ]N\}}|rvd| d| d}	n$|rd| d| d}	nd| d}	||	 qVW d|}	||	g7 }|r|| d	|g7 }d}q6d
}|| | jg7 }q6W |r|dg7 }|dg7 }|S )NzSee Alsor   Tr   z:``z`_z, r   F)r   r   r   AssertionErrorrq   r*   r   empty_description)
r   	func_roler   Zlast_had_descr   r8   Zlinksfuncr{   linkr
   r
   r   _str_see_also  s6    




zNumpyDocString._str_see_alsoc             C   s   | d }g }d}| dd}|r$d}|d| g7 }x>| D ]2\}}|dkrPq>d}|d| dd	| g7 }q>W |r||S dS )
NrH   Fr   r   Tz.. index:: z   :z: z, )r   r   r*   )r   idxr   Zoutput_indexZdefault_indexri   Z
referencesr
   r
   r   
_str_index  s     zNumpyDocString._str_indexc             C   s   g }||   7 }||  7 }||  7 }xdD ]}|| |7 }q.W || d7 }|| |7 }xdD ]}|| |7 }qfW xdD ]}|| |7 }qW ||  7 }d|S )N)r<   r=   r>   r?   zOther Parametersr@   rA   rE   )rD   rF   rG   )rB   rC   r   )r   r   r   r   r   r   r   r*   )r   r   r   Z
param_listr   r
   r
   r   r4   .  s    

zNumpyDocString.__str__)N)F)T)r\   )r   )r   ),r+   r,   r-   r.   rN   r   r   rW   rY   rZ   rc   rh   rj   rl   rw   _roleZ_funcbacktickZ
_funcplainZ	_funcnamer   Z_funcnamenextZ_descriptionr   r   r|   r   r   r   r   r   rP   propertyr   rU   r   r   r   r   r   r   r   r   r   r4   r
   r
   r
   r   r9   v   sp   

+	"8(


 r9   c             C   s   t d| dS )z"Deindent a list of lines maximallyr   )rI   rJ   r*   r   )linesr
   r
   r   ro   G  s    ro   c                   s.   e Zd Zd	ddZdd Z fddZ  ZS )
FunctionDocr   Nc             C   sP   || _ || _|d kr2|d kr$tdt|p0d}|d kr>i }t| || d S )NzNo function or docstring givenr   )r   r   r   r   getdocr9   r   )r   r   r{   re   rQ   r
   r
   r   r   M  s    zFunctionDoc.__init__c             C   s@   t | jd| jj}t| jr2t | jd| jj}n| j}||fS )Nr+   __call__)r   r   r   r+   r   isclassr   )r   	func_namer   r
   r
   r   get_funcY  s
    zFunctionDoc.get_funcc                sr   d}|   \}}ddd}| jrZ| j|kr:td| j  |d|| jd d| d7 }|t j| jd	7 }|S )
Nr   functionmethod)r   methzWarning: invalid role z.. z:: z
    

)r   )r   r   printr   superr4   )r   r   r   r   Zroles)r   r
   r   r4   a  s    

 zFunctionDoc.__str__)r   NN)r+   r,   r-   r   r   r4   __classcell__r
   r
   )r   r   r   L  s   
r   c               @   s   e Zd ZdddZdS )ObjDocNc             C   s&   || _ |d kri }tj| ||d d S )N)rQ   )r   r9   r   )r   objre   rQ   r
   r
   r   r   r  s    zObjDoc.__init__)NN)r+   r,   r-   r   r
   r
   r
   r   r   q  s   r   c               @   sD   e Zd ZdgZddedfddZedd Zedd	 Zd
d Z	dS )ClassDocr   Nr   c          
   C   s  t |s |d k	r td||| _dtjkr>ddlm} nt }|d krPi }|	dd| _
|rt|dst|d7 }|| _|d kr|d krtdt|}t| | |	d	g }||krd }|	d
g }|	ddr||k	rdd }	xd| jfd| jfgD ]\}
}| |
 sg }xtt|D ]h}||ks"|rD||krDq"y,tt| j|}|t|d|	| W n tk
r   Y nX q"W || |
< qW d S )Nz"Expected a class or None, but got Zsphinxr   )ALLZshow_inherited_class_membersTr   z&No class or documentation string givenmemberszexclude-membersZshow_class_membersc             S   s   | sg S |   S d S )N)
splitlines)r   r
   r
   r   splitlines_x  s    z'ClassDoc.__init__.<locals>.splitlines_xrC   rB   r   )r   r   r   r   sysmodulesZsphinx.ext.autodocr   objectr   show_inherited_membersrp   Z_modpydocr   r9   r   methods
propertiessortedr   rq   r5   AttributeError)r   clsre   Z
modulenamefunc_docrQ   r   Z_membersZ_excluder   Zfieldr   Zdoc_listr6   Zdoc_itemr
   r
   r   r   }  sJ    


zClassDoc.__init__c                s(    j d krg S  fddt j D S )Nc                s<   g | ]4\}}| d r | jkrt|tr |r|qS )_)r_   extra_public_methodsr   r   _is_show_member)r   r6   r   )r   r
   r   r     s   
z$ClassDoc.methods.<locals>.<listcomp>)r   r   
getmembers)r   r
   )r   r   r     s    

zClassDoc.methodsc                s(    j d krg S  fddt j D S )Nc                sH   g | ]@\}}| d s|dks6t|ttfs6t|r |r|qS )r   N)r_   r   r   r   r   Zisdatadescriptorr   )r   r6   r   )r   r
   r   r     s   

z'ClassDoc.properties.<locals>.<listcomp>)r   r   r   )r   r
   )r   r   r     s    

zClassDoc.propertiesc             C   s   | j r
dS || jjkrdS dS )NTF)r   r   __dict__)r   r6   r
   r
   r   r     s
    zClassDoc._is_show_member)
r+   r,   r-   r   r   r   r   r   r   r   r
   r
   r
   r   r   y  s
   6r   c             C   s   |d kr<t | rd}n$t | r(d}nt| tr8d}nd}|d krHi }|dkr`t| t||dS |dkrvt| ||dS |d krt| }t	| ||dS d S )	Nclassmoduler   r   )r   re   rQ   )r   r   )re   rQ   )rQ   )
r   r   Zismoduler   r   r   r   r   r   r   )r   Zwhatre   rQ   r
   r
   r   get_doc_object  s"    



r   )NNN)r.   r   rI   r   r   warningsr   collectionsr   Zcollections.abcr   r   rL   r   	functoolsr   ImportErrorr   r   r   	Exceptionr/   r5   r9   ro   r   r   r   r   r
   r
   r
   r   <module>   s4   
	L   T%b