o
    EbgT                     @   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dd ZG dd	 d	eZG d
d deZedg dZG dd de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.

    N)warn)
namedtuple)CallableMappingc                 C   sP   | r| d   s| d= | r| d   r| r&| d   s&| d= | r&| d   r| S )z<Remove leading and trailing blank lines from a list of linesr   strip)l r
   7/usr/lib/python3/dist-packages/scipy/_lib/_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   
   | j | S N)r   r   nr
   r
   r   __getitem__,      
zReader.__getitem__c                 C   s
   d| _ d S )Nr   )_lr   r
   r
   r   r   /   r   zReader.resetc                 C   s(   |   s| | j }|  jd7  _|S dS )N    )eofr   )r   outr
   r
   r   read2   s
   
zReader.readc                 C   s4   | | j d  D ]}| r d S |  j d7  _ q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 r   r   lenr   r   r
   r
   r   r!   A      z
Reader.eofc                 C   sb   | j }| |d  D ]%}||r| || j    S |  j d7  _ |  r.| || j d    S q	g S r$   )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 r   r   r*   r
   r
   r   is_emptyQ   r   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 r   )r   r'   lstripr,   r
   r
   r   is_unindentedW   s   z:Reader.read_to_next_unindented_line.<locals>.is_unindented)r+   )r   r0   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 Nr    r&   r   r
   r
   r   peek[   s   zReader.peekc                 C   s   d | j  S r2   )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.   r1   r3   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)r5   r6   r7   r>   r
   r
   r
   r   r9   e   s    r9   	Parameter)nametypedescc                   @   s  e Zd ZdZi ddddgdg dg dg dg d	g d
g dg dg dg dg dg dg dg dddddi i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(d)Zd*Zd+Zd,Zd-e e d. e d/ Zed0d1Zed2d3Zd4Zed5e d6 Zed7e d8 e d9 d/ d: e Zd;Zd<d= Zd>d? Zd@dA ZdBdC Zd_dEdFZd`dHdIZ dadKdLZ!dMdN Z"dOdP Z#dQdR Z$dSdT Z%dUdV Z&dWdX Z'dYdZ Z(dbd[d\Z)d]S )cNumpyDocStringzParses a numpydoc string to an abstract representation

    Instances define a mapping from section title to structured data.

    	Signaturer    SummaryExtended Summary
ParametersReturnsYieldsReceivesRaisesWarnsOther Parameters
AttributesMethodsSee AlsoNotesWarnings
ReferencesExamplesindexc              
   C   s\   |}t |d}t|| _t| j| _z| 	  W d S  t
y- } z||_ d }~ww Nr   )textwrapdedentr   r   _doccopyZdeepcopysections_parsed_data_parser9   r:   )r   r:   configZorig_docstringer
   r
   r   r      s   
zNumpyDocString.__init__c                 C   r   r   )r\   )r   keyr
   r
   r   r      r   zNumpyDocString.__getitem__c                 C   s.   || j vr| jd| dd d S || j |< d S )NzUnknown section %sFerror)r\   _error_location)r   r`   valr
   r
   r   __setitem__   s   
zNumpyDocString.__setitem__c                 C   
   t | jS r   )iterr\   r   r
   r
   r   __iter__   r   zNumpyDocString.__iter__c                 C   rf   r   )r'   r\   r   r
   r
   r   __len__   r   zNumpyDocString.__len__c                 C   sh   | j   | j  rdS | j   }|drdS | j d }|dt| p3|dt| S )NF
.. index::Tr   -=)rY   r%   r!   r3   r   
startswithr'   )r   l1l2r
   r
   r   _is_at_section   s   


$zNumpyDocString._is_at_sectionc                 C   sb   d}d}t |D ]
\}}| r nqt |d d d D ]
\}}| r& nq||t||  S )Nr   r   )	enumerater   r'   )r   docijr*   r
   r
   r   _strip   s   zNumpyDocString._stripc                 C   sZ   | j  }|  s+| j  s+| j d s|dg7 }|| j  7 }|  s+| j  r|S )Nr   r    )rY   r.   rp   r!   r3   r   )r   sectionr
   r
   r   _read_to_next_section   s   

z$NumpyDocString._read_to_next_sectionc                 c   s|    | j  s<|  }|d  }|dr||dd  fV  nt|dk r)tV  n|| |dd  fV  | j  rd S d S )Nr   ..r      )rY   r!   rw   r   rm   r'   StopIterationru   )r   r   r@   r
   r
   r   _read_sections   s   

zNumpyDocString._read_sectionsFc           	      C   s   t |}g }| sF|  }d|v r |dd d \}}n|r(d|}}n|d}}| }t|}t|}|t	||| | r
|S )N : ry   r    )
r   r!   r#   r   r   r1   dedent_linesr   appendr?   )	r   contentsingle_element_is_typerparamsheaderZarg_nameZarg_typerB   r
   r
   r   _parse_param_list   s   
z NumpyDocString._parse_param_listz:(?P<role>\w+):z'`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_\.-]+)`z(?P<name2>[a-zA-Z0-9_\.-]+)(|)roleZrolenextr@   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>[,\.])?rx   c                    s(  g } fdd}g }|D ]}|  sq j|}d}|r7|d}|dr7|r7 jd|d|f dd |sF|d	rF||   q|rg }|d
}		 |	  sUn'||	\}
}}||
|f |	|d   }	|	r{|	d dkr{|	dd   }	qPtt	d|g}|||f qt
d| |S )z
        func_name : Descriptive text
            continued text
        another_func_name : Descriptive text
        func_name1, func_name2, :meth:`func_name`, func_name3

        c                    sL    j | }|std|  |d}|r|dn|d}||| fS )zMatch ':role:`name`' or 'name'.%s is not a item namer   r@   Zname2)	_func_rgxmatchr9   groupend)textmr   r@   r   r
   r   parse_item_name  s   
z7NumpyDocString._parse_see_also.<locals>.parse_item_nameNrB   ZtrailingzGUnexpected comma or period after function list at index %d of line "%s"Fra    ZallfuncsTr   ,r   r   )r   	_line_rgxr   r   rc   r   rm   r~   r   filterr9   )r   r   itemsr   restr*   Z
line_matchdescriptionfuncsr   r@   r   Z	match_endr
   r   r   _parse_see_also  sJ   		

zNumpyDocString._parse_see_alsoc                 C   sz   dd }i }| d}t|dkr||d  dd |d< |D ]}| d}t|d	kr:||d	  d||d < q |S )
zT
        .. index: default
           :refguide: something, else, and more

        c                 S   s   dd | D S )Nc                 S      g | ]}|  qS r
   r   .0sr
   r
   r   
<listcomp>Q      zFNumpyDocString._parse_index.<locals>.strip_each_in.<locals>.<listcomp>r
   )Zlstr
   r
   r   strip_each_inP  s   z2NumpyDocString._parse_index.<locals>.strip_each_inz::r   r   r   default:ry   )r   r'   )r   rv   r   r   r"   r*   r
   r
   r   _parse_indexJ  s   

zNumpyDocString._parse_indexc                 C   s   |   rdS 	 | j }ddd |D  }td}||r+|| d< |   s+q	 |dur4|| d< |   s@|  | d	< dS dS )
z%Grab signature (if given) and summaryNTr   c                 S   r   r
   r   r   r
   r
   r   r   e  r   z1NumpyDocString._parse_summary.<locals>.<listcomp>z^([\w., ]+=)?\s*[\w\.]+\(.*\)$rD   rE   rF   )	rp   rY   r.   r4   r   recompiler   rw   )r   ZsummaryZsummary_strZcompiledr
   r
   r   _parse_summary]  s    


zNumpyDocString._parse_summaryc                 C   s.  | j   |   t|  }tdd |D }d|v }d|v }|r*|r*d}t||s6d|v r6d}t||D ]\\}}|ds\d	d
 |dD }d	|}| 
|r\| d|  |dv rh| || |< q8|dv rv| j|dd| |< q8|dr| ||| d< q8|dkr| || d< q8|| |< q8d S )Nc                 S   s   g | ]\}}|qS r
   r
   )r   rv   r   r
   r
   r   r   x  r   z)NumpyDocString._parse.<locals>.<listcomp>rH   rI   z5Docstring contains both a Returns and Yields section.rJ   z5Docstring contains a Receives section but not Yields.rx   c                 s   s    | ]}|  V  qd S r   )
capitalizer   r
   r
   r   	<genexpr>      z(NumpyDocString._parse.<locals>.<genexpr>r   zThe section %s appears twice)rG   rM   rN   rO   )rH   rI   rK   rL   rJ   T)r   rj   rU   rP   )rY   r   r   r   r{   set
ValueErrorrm   r   r4   getrc   r   r   r   )r   r[   Zsection_namesZhas_returnsZ
has_yieldsmsgrv   r   r
   r
   r   r]   s  s@   





zNumpyDocString._parseTc                 C   s\   t | dr"zt| j}W n ty   d }Y nw |d| j|f  }|r(t|t| d S )N_objz in the docstring of %s in %s.)r<   inspectZgetsourcefiler   	TypeErrorr   r   )r   r   rb   filenamer
   r
   r   rc     s   
zNumpyDocString._error_locationrk   c                 C   s   |t || gS r   r'   )r   r@   symbolr
   r
   r   _str_header  r(   zNumpyDocString._str_header   c                 C   s$   g }|D ]}|d| | g7 }q|S )Nr   r
   )r   rr   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 )NrD   *z\*r    )replacer   r
   r
   r   _str_signature  s   zNumpyDocString._str_signaturec                 C      | d r| d dg S g S )NrE   r    r
   r   r
   r
   r   _str_summary     zNumpyDocString._str_summaryc                 C   r   )NrF   r    r
   r   r
   r
   r   _str_extended_summary  r   z$NumpyDocString._str_extended_summaryc                 C   s   g }| | rH||  |7 }| | D ]1}g }|jr||j |jr'||j |d|g7 }|jrBd|j rB|| |j7 }q|dg7 }|S )Nr|   r    )r   r@   r~   rA   r4   rB   r   r   )r   r@   r"   Zparampartsr
   r
   r   _str_param_list  s   
zNumpyDocString._str_param_listc                 C   s4   g }| | r||  |7 }|| | 7 }|dg7 }|S r2   )r   )r   r@   r"   r
   r
   r   _str_section  s   
zNumpyDocString._str_sectionc           
      C   s   | d sg S g }||  d7 }|dg7 }d}| d D ]T\}}t|ts%J g }|D ]\}}|r6d||f }	n|r?d||f }	nd| }	||	 q)d|}	||	g7 }|rc|| d|g7 }d}qd}|| | jg7 }q|rv|dg7 }|dg7 }|S )	NrP   r    Tz:%s:`%s`z`%s`_, r   F)r   r   r   r~   r4   r   empty_description)
r   	func_roler"   Zlast_had_descr   rB   Zlinksfuncr   linkr
   r
   r   _str_see_also  s6   




zNumpyDocString._str_see_alsoc                 C   sv   | d }g }d}| dd}|rd}|d| g7 }| D ]\}}|dkr&qd}|d|d|f g7 }q|r9|S dS )	NrU   Fr   r    Tz.. index:: %sz
   :%s: %sr   )r   r   r4   )r   idxr"   Zoutput_indexZdefault_indexrv   Z
referencesr
   r
   r   
_str_index  s   zNumpyDocString._str_indexc                 C   s   g }||   7 }||  7 }||  7 }dD ]	}|| |7 }q|| d7 }|| |7 }dD ]	}|| |7 }q0dD ]	}|| |7 }q<||  7 }d|S )N)rG   rH   rI   rJ   rM   rK   rL   rR   )rQ   rS   rT   )rN   rO   r   )r   r   r   r   r   r   r   r4   )r   r   r"   Z
param_listr   r
   r
   r   r>     s   
zNumpyDocString.__str__N)F)Trk   r   )r    )*r5   r6   r7   r8   r[   r   r   re   rh   ri   rp   ru   rw   r{   r   _roleZ_funcbacktickZ
_funcplainZ	_funcnamer   Z_funcnamenextZ_descriptionr   r   r   r   r   r   r   r   r]   rc   r   r   r   r   r   r   r   r   r   r>   r
   r
   r
   r   rC   p   s    	

%6
'

 rC   r   c                    s6   d|  | d u r
 S |  d}d fdd|D S )Nr   r   c                 3   s    | ]} | V  qd S r   r
   )r   r	   Z
indent_strr
   r   r   &  r   zindent.<locals>.<genexpr>)r   r4   )strr   linesr
   r   r   r   !  s
   
r   c                 C   s   t d| dS )z"Deindent a list of lines maximallyr   )rW   rX   r4   r   )r   r
   r
   r   r}   )  s   r}   rk   c                 C   s   | d |t |   d S rV   r   )r   Zstyler
   r
   r   r   .  s   r   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   sD   || _ || _|d u r|d u rtdt|pd}t| || d S )NzNo function or docstring givenr    )_fr   r   r   getdocrC   r   )r   r   r   rr   r^   r
   r
   r   r   3  s   zFunctionDoc.__init__c                 C   sF   t | jd| jj}t| jrt | jd| jj}||fS | j}||fS )Nr5   __call__)getattrr   	__class__r5   r   isclassr   )r   	func_namer   r
   r
   r   get_func=  s   zFunctionDoc.get_funcc                    sn   d}|   \}}ddd}| jr)| j|vrtd| j  |d|| jd|f 7 }|tt| j| jd7 }|S )Nr    functionmethod)r   ZmethzWarning: invalid role %sz.. %s:: %s
    

)r   )r   r   printr   superr   r>   )r   r"   r   r   Zrolesr   r
   r   r>   E  s   
zFunctionDoc.__str__)r5   r6   r7   r   r   r>   __classcell__r
   r
   r   r   r   2  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   sz  t |s|d urtd| || _dtjv rddlm} nt }|	dd| _
|r3|ds3|d7 }|| _|d u rG|d u rBtdt|}t| | |	d	g }||u rYd }|	d
g }|	ddr||urdd }	d| jfd| jffD ]C\}
}| |
 sg }t|D ],}||v s|r||vrqztt| j|}|t|d|	| W q ty   Y qw || |
< qwd S d S d S )Nz$Expected a class or None, but got %rZsphinxr   )ALLZshow_inherited_class_membersT.z&No class or documentation string givenmemberszexclude-membersZshow_class_membersc                 S   s   | sg S |   S r   )
splitlines)r   r
   r
   r   splitlines_xz  s   z'ClassDoc.__init__.<locals>.splitlines_xrO   rN   r    )r   r   r   _clssysmodulesZsphinx.ext.autodocr   objectr   show_inherited_membersendswithZ_modpydocr   rC   r   methods
propertiessortedr   r~   r?   AttributeError)r   clsrr   Z
modulenameZfunc_docr^   r   Z_membersZ_excluder   Zfieldr   Zdoc_listr@   Zdoc_itemr
   r
   r   r   [  s^   

zClassDoc.__init__c                    (    j d u rg S  fddt j D S )Nc                    s<   g | ]\}}| d r| jv rt|tr |r|qS )_)rm   extra_public_methodsr   r   _is_show_memberr   r@   r   r   r
   r   r     s    
z$ClassDoc.methods.<locals>.<listcomp>r   r   Z
getmembersr   r
   r   r   r        
zClassDoc.methodsc                    r   )Nc                    sD   g | ]\}}| d s|du st|tst|r |r|qS )r   N)rm   r   propertyr   Zisdatadescriptorr   r   r   r
   r   r     s    
z'ClassDoc.properties.<locals>.<listcomp>r   r   r
   r   r   r     r   zClassDoc.propertiesc                 C   s   | j rdS || jjvrdS dS )NTF)r   r   __dict__)r   r@   r
   r
   r   r     s
   zClassDoc._is_show_member)
r5   r6   r7   r   r   r   r   r   r   r   r
   r
   r
   r   r   W  s    
4
	
	r   r   r   )r8   r   rW   r   r   warningsr   collectionsr   Zcollections.abcr   r   rZ   r   r   r   r   	Exceptionr9   r?   rC   r   r}   r   r   r   r
   r
   r
   r   <module>   s.    	L   
4
%