B
    §Ê¾ZK  ã               @   sÖ   d Z ddlmZmZm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ZddlZddlZdd„ ZG dd„ deƒZG d	d
„ d
eƒZG dd„ dejƒZddd„Zdd„ Zddd„ZG dd„ deƒZG dd„ deƒZdS )z=Extract reference documentation from the NumPy source tree.

é    )ÚdivisionÚabsolute_importÚprint_functionN)Úwarnc             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 )zr
        Parameters
        ----------
        data : str
           String with lines separated by '
'.

        Ú
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__,   s    zReader.__getitem__c             C   s
   d| _ d S )Nr   )Ú_l)r   r	   r	   r
   r   /   s    zReader.resetc             C   s,   |   ¡ s$| | j }|  jd7  _|S dS d S )Né   Ú )Úeofr   )r   Úoutr	   r	   r
   Úread2   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   A   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_conditionD   s    zReader.read_to_conditionc             C   s   |   ¡  dd„ }|  |¡S )Nc             S   s
   |   ¡  S )N)r   )r!   r	   r	   r
   Úis_emptyQ   s    z0Reader.read_to_next_empty_line.<locals>.is_empty)r   r"   )r   r#   r	   r	   r
   Úread_to_next_empty_lineN   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_unindentedW   s    z:Reader.read_to_next_unindented_line.<locals>.is_unindented)r"   )r   r&   r	   r	   r
   Úread_to_next_unindented_lineV   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
   Úpeek[   s    zReader.peekc             C   s   d  | j¡ ¡  S )Nr   )Újoinr   r   )r   r	   r	   r
   r#   a   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f }|S )Nr   Ú	docstringz%s in %r)ÚargsÚhasattrr/   )r   Úmessager	   r	   r
   Ú__str__f   s    

zParseError.__str__N)r*   r+   r,   r3   r	   r	   r	   r
   r.   e   s   r.   c               @   s  e Zd ZdZddgg g g g g g g g g g g g ddi dœZi f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„ Ze dej¡Zdd„ Zdd„ Zdd„ Zdd „ Zd;d"d#„Zd<d%d&„Zd=d(d)„Zd*d+„ Zd,d-„ Zd.d/„ Zd0d1„ Zd2d3„ Zd4d5„ Zd6d7„ Z d>d8d9„Z!d:S )?ÚNumpyDocStringzƒParses 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ÚRaisesÚWarnszOther ParametersÚ
AttributesÚMethodszSee AlsoÚNotesÚWarningsÚ
ReferencesÚExamplesÚindexc          
   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.   r/   )r   r/   ÚconfigZorig_docstringÚer	   r	   r
   r   ˆ   s    
zNumpyDocString.__init__c             C   s
   | j | S )N)rI   )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 %sF)Úerror)rI   Ú_error_location)r   rM   Úvalr	   r	   r
   Ú__setitem__˜   s    
zNumpyDocString.__setitem__c             C   s
   t | jƒS )N)ÚiterrI   )r   r	   r	   r
   Ú__iter__ž   s    zNumpyDocString.__iter__c             C   s
   t | jƒS )N)r   rI   )r   r	   r	   r
   Ú__len__¡   s    zNumpyDocString.__len__c             C   sh   | j  ¡  | j  ¡ rdS | j  ¡  ¡ }| d¡r4dS | j  d¡ ¡ }| dt|ƒ ¡pf| dt|ƒ ¡S )NFz
.. index::Tr   ú-ú=)rE   r   r   r(   r   Ú
startswithr   )r   Úl1Úl2r	   r	   r
   Ú_is_at_section¤   s    


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   )rE   r$   rZ   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   é   )rE   r   ra   r   rW   r   ÚStopIterationr_   )r   r   Únamer	   r	   r
   Ú_read_sectionsÊ   s    
zNumpyDocString._read_sectionsc             C   s|   t |ƒ}g }xj| ¡ sv| ¡  ¡ }d|krB| d¡d d… \}}n
|d }}| ¡ }t|ƒ}t|ƒ}| |||f¡ qW |S )Nz : rb   r   )	r   r   r   r   r   r'   Údedent_linesr   Úappend)r   ÚcontentÚrZparamsÚheaderZarg_nameZarg_typeÚdescr	   r	   r
   Ú_parse_param_listÖ   s    

z NumpyDocString._parse_param_listzZ^\s*(:(?P<role>\w+):`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_.-]+)`| (?P<name2>[a-zA-Z0-9_.-]+))\s*c                s:  g ‰ ‡fdd„‰‡ ‡fdd„}d}g }x|D ]ú}|  ¡ s<q.ˆj |¡}|r¶|| ¡ d…   ¡  d¡r¶|||ƒ |d| ¡ … || ¡ d…  }}| dd¡d   ¡ g}|d s´g }q.| d	¡s|||ƒ d}d
|krx4| d
¡D ]}|  ¡ ræ||g ƒ qæW n|  ¡ r(|}q.|dk	r.| |  ¡ ¡ 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  | ¡}|r@| ¡ }|d dkr0|d dfS |d |d fS td|  ƒ‚dS )zMatch ':role:`name`' or 'name'r   Né   rb   z%s is not a item name)Ú	_name_rgxÚmatchÚgroupsr.   )ÚtextÚmÚg)r   r	   r
   Úparse_item_nameö   s    z7NumpyDocString._parse_see_also.<locals>.parse_item_namec                s6   | sd S ˆ| ƒ\} }ˆ   | t|ƒ|f¡ |d d …= d S )N)rg   r   )rd   ÚrestÚrole)Úitemsrt   r	   r
   Ú	push_item  s
    z1NumpyDocString._parse_see_also.<locals>.push_itemNú:r   r   ú ú,)r   rn   ro   ÚendrW   r   rg   )r   rh   rx   Zcurrent_funcru   r!   rr   Úfuncr	   )rw   rt   r   r
   Ú_parse_see_alsoì   s8    
"



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>+  s    zFNumpyDocString._parse_index.<locals>.strip_each_in.<locals>.<listcomp>r	   )Zlstr	   r	   r
   Ústrip_each_in*  s    z2NumpyDocString._parse_index.<locals>.strip_each_inz::r   r{   r   Údefaultry   rb   )r   r   )r   r`   rh   r‚   r   r!   r	   r	   r
   Ú_parse_index$  s    


zNumpyDocString._parse_indexc             C   s€   |   ¡ rdS xJ| j ¡ }d dd„ |D ƒ¡ ¡ }t d¡ |¡rR|| d< |   ¡ sRqP qW |dk	rh|| d< |   ¡ s||  ¡ | d< dS )	z%Grab signature (if given) and summaryNrz   c             S   s   g | ]}|  ¡ ‘qS r	   )r   )r   r€   r	   r	   r
   r   ?  s    z1NumpyDocString._parse_summary.<locals>.<listcomp>z^([\w., ]+=)?\s*[\w\.]+\(.*\)$r5   r6   zExtended Summary)	rZ   rE   r$   r)   r   ÚreÚcompilero   ra   )r   ZsummaryZsummary_strr	   r	   r
   Ú_parse_summary7  s    
zNumpyDocString._parse_summaryc             C   sþ   | j  ¡  |  ¡  t|  ¡ ƒ}tdd„ |D ƒƒ}d|k}d|k}|rT|rTd}t|ƒ‚x¤|D ]œ\}}| d¡s¢dd„ | d	¡D ƒ}d	 	|¡}|  
|¡r¢|  d
| ¡ |dkrº|  |¡| |< qZ| d¡rÖ|  ||¡| d< qZ|dkrî|  |¡| d< qZ|| |< qZW d S )Nc             S   s   g | ]\}}|‘qS r	   r	   )r   r`   rh   r	   r	   r
   r   Q  s    z)NumpyDocString._parse.<locals>.<listcomp>r8   r9   z5Docstring contains both a Returns and Yields section.z..c             s   s   | ]}|  ¡ V  qd S )N)Ú
capitalize)r   r€   r	   r	   r
   ú	<genexpr>\  s    z(NumpyDocString._parse.<locals>.<genexpr>rz   zThe section %s appears twice)r7   r8   r9   r:   r;   zOther Parametersr<   r=   z
.. index::rB   zSee Also)rE   r   r‡   r   re   ÚsetÚ
ValueErrorrW   r   r)   ÚgetrO   rl   r„   r~   )r   rH   Zsection_namesZhas_returnsZ
has_yieldsÚmsgr`   rh   r	   r	   r
   rJ   L  s.    




zNumpyDocString._parseTc             C   s`   t | dƒrFyt | j¡}W n tk
r2   d }Y nX |d| j|f  }|rTt|ƒ‚nt|ƒ d S )NÚ_objz in the docstring of %s in %s.)r1   ÚinspectZgetsourcefilerŽ   Ú	TypeErrorr‹   r   )r   r   rN   Úfilenamer	   r	   r
   rO   m  s    


zNumpyDocString._error_locationrU   c             C   s   |t |ƒ| gS )N)r   )r   rd   Zsymbolr	   r	   r
   Ú_str_header}  s    zNumpyDocString._str_headeré   c             C   s(   g }x|D ]}|d| | g7 }q
W |S )Nrz   r	   )r   r\   Úindentr   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 d S )Nr5   Ú*z\*r   )Úreplace)r   r	   r	   r
   Ú_str_signature†  s    zNumpyDocString._str_signaturec             C   s   | d r| d dg S g S d S )Nr6   r   r	   )r   r	   r	   r
   Ú_str_summaryŒ  s    zNumpyDocString._str_summaryc             C   s   | d r| d dg S g S d S )NzExtended Summaryr   r	   )r   r	   r	   r
   Ú_str_extended_summary’  s    z$NumpyDocString._str_extended_summaryc             C   s‚   g }| | r~||   |¡7 }xX| | D ]L\}}}|rF|d||f g7 }n
||g7 }|r$d |¡ ¡ r$||  |¡7 }q$W |dg7 }|S )Nz%s : %sr   )r’   r)   r   r•   )r   rd   r   ZparamZ
param_typerk   r	   r	   r
   Ú_str_param_list˜  s    

zNumpyDocString._str_param_listc             C   s4   g }| | r0||   |¡7 }|| | 7 }|dg7 }|S )Nr   )r’   )r   rd   r   r	   r	   r
   Ú_str_section¦  s    
zNumpyDocString._str_sectionc             C   sÊ   | d sg S g }||   d¡7 }d}x˜| d D ]Œ\}}}|rHd||f }n|rZd||f }nd| }|sj|r€|dg7 }||g7 }n|d  d| 7  < |r´||  d |¡g¡7 }d}q,d	}q,W |dg7 }|S )
NzSee AlsoTz:%s:`%s`z`%s`_r   r   z, %srz   F)r’   r•   r)   )r   Ú	func_roler   Zlast_had_descr}   rk   rv   Úlinkr	   r	   r
   Ú_str_see_also®  s*    

zNumpyDocString._str_see_alsoc             C   s^   | d }g }|d|  dd¡ g7 }x6| ¡ D ]*\}}|dkr>q,|d|d |¡f g7 }q,W |S )NrB   z.. index:: %srƒ   r   z
   :%s: %sz, )rŒ   rw   r)   )r   Úidxr   r`   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 }q‚W ||  ¡ 7 }d |¡S )N)r7   r8   r9   zOther Parametersr:   r;   r?   )r>   r@   rA   )r<   r=   r   )r˜   r™   rš   r›   rœ   rŸ   r¡   r)   )r   r   r   Z
param_listr€   r	   r	   r
   r3   Ò  s    


zNumpyDocString.__str__N)T)rU   )r“   )r   )"r*   r+   r,   r-   rH   r   r   rQ   rS   rT   rZ   r_   ra   re   rl   r…   r†   ÚXrn   r~   r„   r‡   rJ   rO   r’   r•   r˜   r™   rš   r›   rœ   rŸ   r¡   r3   r	   r	   r	   r
   r4   m   sZ   8!



r4   r“   c                s6   d| ‰ | d krˆ S |   d¡}d ‡ fdd„|D ƒ¡S )Nrz   r   c             3   s   | ]}ˆ | V  qd S )Nr	   )r   r   )Ú
indent_strr	   r
   r‰   é  s    zindent.<locals>.<genexpr>)r   r)   )Ústrr”   Úlinesr	   )r£   r
   r”   ä  s
    
r”   c             C   s   t  d | ¡¡ d¡S )z"Deindent a list of lines maximallyr   )rC   rD   r)   r   )r¥   r	   r	   r
   rf   ì  s    rf   rU   c             C   s   | d |t | ƒ  d S )Nr   )r   )rq   Zstyler	   r	   r
   rj   ñ  s    rj   c                   s4   e Zd Zddi fdd„Zdd„ Z‡ fdd„Z‡  ZS )	ÚFunctionDocr}   Nc          	   C   sö   || _ || _|d kr2|d kr$tdƒ‚t |¡p0d}t | |¡ | d sò|d k	rò|  ¡ \}}yrytt 	|¡ƒ}W nF t
tfk
r´   tjd dkrœt |¡}n
t |¡}tj|Ž }Y nX d|| dd¡f }W n tk
rè   d	| }Y nX || d< d S )
NzNo function or docstring givenr   r5   r   rm   z%s%sr–   z\*z%s())Ú_fÚ_roler‹   r   Úgetdocr4   r   Úget_funcr¤   Ú	signatureÚAttributeErrorÚsysÚversion_infoZgetfullargspecZ
getargspecZformatargspecr—   r   )r   r}   rv   r\   rK   Ú	func_namer«   Zargspecr	   r	   r
   r   ö  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__)Úgetattrr§   Ú	__class__r*   r   Úisclassr   )r   r¯   r}   r	   r	   r
   rª     s
    zFunctionDoc.get_funcc                s~   d}|   ¡ \}}| d  dd¡}dddœ}| jrb| j|krHtd| j ƒ |d	| | jd¡|f 7 }|tt| ƒj| jd
7 }|S )Nr   r5   r–   z\*ZfunctionÚmethod)r}   ÚmethzWarning: invalid role %sz.. %s:: %s
    

)r   )rª   r—   r¨   ÚprintrŒ   Úsuperr¦   r3   )r   r   r}   r¯   r«   Zroles)r²   r	   r
   r3     s    

zFunctionDoc.__str__)r*   r+   r,   r   rª   r3   Ú__classcell__r	   r	   )r²   r
   r¦   õ  s   r¦   c               @   sD   e Zd ZdgZddei 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d¡| _|rH| d¡sH|d7 }|| _|d krp|d krftdƒ‚t 	|¡}t
 | |¡ | dd¡rdd„ }xˆd	| jfd
| jfgD ]p\}}| | s¨g }	xRt|ƒD ]F}
y*t 	t| j|
ƒ¡}|	 |
d||ƒf¡ W qÆ tk
r
   Y qÆX qÆW |	| |< q¨W d S )Nz$Expected a class or None, but got %rZshow_inherited_class_membersTÚ.z&No class or documentation string givenZshow_class_membersc             S   s   | sg S |   ¡ S d S )N)Ú
splitlines)r€   r	   r	   r
   Úsplitlines_xE  s    z'ClassDoc.__init__.<locals>.splitlines_xr=   r<   r   )r   r³   r‹   Ú_clsrŒ   Úshow_inherited_membersÚendswithZ_modÚpydocr©   r4   r   ÚmethodsÚ
propertiesÚsortedr±   rg   r¬   )r   Úclsr\   Z
modulenameZfunc_docrK   r¼   Zfieldrw   Zdoc_listrd   Zdoc_itemr	   r	   r
   r   0  s4    



zClassDoc.__init__c                s(   ˆ j d krg S ‡ fdd„t ˆ j ¡D ƒS )Nc                s>   g | ]6\}}|  d ¡r |ˆ jkrt|tjƒrˆ  |¡r|‘qS )Ú_)rW   Úextra_public_methodsr   ÚcollectionsÚCallableÚ_is_show_member)r   rd   r}   )r   r	   r
   r   [  s
    

z$ClassDoc.methods.<locals>.<listcomp>)r½   r   Ú
getmembers)r   r	   )r   r
   rÁ   W  s    
zClassDoc.methodsc                s(   ˆ j d krg S ‡ fdd„t ˆ j ¡D ƒS )Nc                sD   g | ]<\}}|  d ¡s|dks2t|tƒs2t |¡rˆ  |¡r|‘qS )rÅ   N)rW   r   Úpropertyr   ZisdatadescriptorrÉ   )r   rd   r}   )r   r	   r
   r   e  s
    

z'ClassDoc.properties.<locals>.<listcomp>)r½   r   rÊ   )r   r	   )r   r
   rÂ   a  s    
zClassDoc.propertiesc             C   s   | j r
dS || jjkrdS dS )NTF)r¾   r½   Ú__dict__)r   rd   r	   r	   r
   rÉ   k  s
    zClassDoc._is_show_member)
r*   r+   r,   rÆ   r¦   r   rË   rÁ   rÂ   rÉ   r	   r	   r	   r
   r¹   ,  s   &

r¹   )r“   )rU   )r-   Z
__future__r   r   r   r   rC   r…   rÀ   Úwarningsr   rÇ   rF   r­   r   Úobjectr   Ú	Exceptionr.   ÚMappingr4   r”   rf   rj   r¦   r¹   r	   r	   r	   r
   Ú<module>   s(   	L  y

7