o
    i ]                     @   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mZ ddl	m
Z
mZ ddlmZ ddlmZ dd ZG d	d
 d
ZG dd deZedg d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eeefddZdS )z;Extract reference documentation from the NumPy source tree.    N)
namedtuple)CallableMapping)cached_property)warnc                 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   O/home/kim/smarthome/.venv/lib/python3.10/site-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 )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   
   | 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   read1   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_line9   s
   zReader.seek_next_non_empty_linec                 C   s   | j t| jkS r   r   lenr   r   r   r   r   r"   @      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_conditionC   s   zReader.read_to_conditionc                 C   s   |    dd }| |S )Nc                 S   s
   |    S r   r   r+   r   r   r   is_emptyP   r   z0Reader.read_to_next_empty_line.<locals>.is_empty)r&   r,   )r   r.   r   r   r   read_to_next_empty_lineM   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_unindentedV   s   z:Reader.read_to_next_unindented_line.<locals>.is_unindented)r,   )r   r1   r   r   r   read_to_next_unindented_lineU   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 r3   )joinr   r	   r   r   r   r   r.   a      zReader.is_emptyN)r   )__name__
__module____qualname____doc__r   r   r   r$   r&   r"   r,   r/   r2   r4   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   	docstring in )argshasattrr<   )r   messager   r   r   __str__f   s   

zParseError.__str__N)r7   r8   r9   rA   r   r   r   r   r;   e   s    r;   	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d`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dad)d*Zd+Zd,Zd-Zd.e e d/ e d0 Zed1d2Zed3d4Zd5Zed6e d7 Zed8e d9 e d: d0 d; e Zd<Zd=d> Zd?d@ ZdAdB ZdCdD ZedEdF Z dbdHdIZ!dcdKdLZ"dddNdOZ#dPdQ Z$dRdS Z%dTdU Z&dVdW Z'dXdY Z(dZd[ Z)d\d] Z*ded^d_Z+dS )fNumpyDocStringzParses a numpydoc string to an abstract representation

    Instances define a mapping from section title to structured data.

    	Signaturer!   SummaryExtended Summary
Parameters
AttributesMethodsReturnsYieldsReceivesOther ParametersRaisesWarnsWarningsSee AlsoNotes
ReferencesExamplesindexNc              
   C   s\   |}t |d}t|| _t| j| _z| 	  W d S  t
y- } z||_ d }~ww )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   r   r   )r_   )r   keyr   r   r   r      r   zNumpyDocString.__getitem__c                 C   s0   || j vr| jd| dd d S || j |< d S )NzUnknown section Ferror)r_   _error_location)r   rc   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   ri   r   )r(   r_   r   r   r   r   __len__   r   zNumpyDocString.__len__c                 C   s   | j   | j  rdS | j   }|drdS | j d }t|dkrWt|dhdhfv rWt|t|krWd| j j	d d	 d
 }| j
d| d| d| dd |dt| ph|dt| S )NF
.. index::Tr       -=r      z...z'potentially wrong underline length... 
z 
z in 
rd   )r[   r&   r"   r4   r	   
startswithr(   setr5   r   rf   )r   l1l2Zsnipr   r   r   _is_at_section   s   


0$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!   )r[   r/   rv   r"   r4   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    rq   )r[   r"   r}   r	   rr   r(   StopIterationr{   )r   r   rC   r   r   r   _read_sections   s   

zNumpyDocString._read_sectionsFc           	      C   s   t |}t|}g }| sS|  }d|v r"|jddd\}}n|dr-|d d }|r5d|}}n|d}}| }t |}t|}|	t
||| | r|S )N : r    )maxsplitz :r!   )dedent_linesr   r"   r$   r	   r   endswithr2   r   appendrB   )	r   contentsingle_element_is_typerparamsheaderZarg_nameZarg_typerE   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rolenextrC   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>[,\.])?r~   c                    s8  t |}g } fdd}g }|D ]   sqj }d}|r<|d}|dr<|r<jd|d f dd |sK d	rK|   q|rg }|d
}	 | sZn'||\}	}
}||	|
f ||d  }|r|d dkr|dd  }qUt	t
d|g}|||f qd  q|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}|r|dn|d}||| fS )zMatch ':role:`name`' or 'name'.Error parsing See Also entry r   rC   Zname2)	_func_rgxmatchrf   groupend)textmr   rC   r+   r   r   r   parse_item_name/  s   
z7NumpyDocString._parse_see_also.<locals>.parse_item_nameNrE   ZtrailingzGUnexpected comma or period after function list at index %d of line "%s"Frd    ZallfuncsTr   ,r    r   )r   r	   	_line_rgxr   r   rf   r   rr   r   r   filter)r   r   itemsr   restZ
line_matchdescriptionfuncsr   rC   r   Z	match_endr   r   r   _parse_see_also"  sH   		

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 )
zU
        .. 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>b      zFNumpyDocString._parse_index.<locals>.strip_each_in.<locals>.<listcomp>r   )lstr   r   r   strip_each_ina  s   z2NumpyDocString._parse_index.<locals>.strip_each_inz::r    r   r   default:rq   )r   r(   )r   r|   r   r   r#   r+   r   r   r   _parse_indexZ  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   v  r   z1NumpyDocString._parse_summary.<locals>.<listcomp>z^([\w., ]+=)?\s*[\w\.]+\(.*\)$rG   rH   rI   )	rv   r[   r/   r5   r	   recompiler   r}   )r   summaryZsummary_strcompiledr   r   r   _parse_summaryn  s    


zNumpyDocString._parse_summaryc                 C   s  | j   |   t|  }dd |D }d|v }|s&d|v r&d}t||D ]c\}}|dsSdd |d	D }d	|}| 	|rS| 
d
|d| j jf  |dv r_| || |< q(|dv rm| j|dd| |< q(|dr{| ||| d< q(|dkr| || d< q(|| |< q(d S )Nc                 S   s   h | ]\}}|qS r   r   )r   r|   r   r   r   r   	<setcomp>  r   z(NumpyDocString._parse.<locals>.<setcomp>rN   rO   z5Docstring contains a Receives section but not Yields.r~   c                 s   s    | ]}|  V  qd S r   )
capitalizer   r   r   r   	<genexpr>  s    z(NumpyDocString._parse.<locals>.<genexpr>r   z#The section %s appears twice in  %sr   )rJ   rP   rK   rL   )rM   rN   rQ   rR   rO   T)r   rm   rX   rT   )r[   r   r   r   r   
ValueErrorrr   r   r5   getrf   r   r   r   r   )r   r^   Zsection_namesZ
has_yieldsmsgr|   r   r   r   r   r`     s<   





zNumpyDocString._parsec                 C   s$   t | dr| jS t | dr| jS d S )N_cls_f)r?   r   r   r   r   r   r   _obj  s
   

zNumpyDocString._objTc                 C   s   | j d urFzt| j }W n ty   d }Y nw t| j dd }|d u r/tt| j dd dd }|d ur:|d| 7 }||rCd| dnd7 }|rLt|t|dd d S )	Nr7   	__class__z in the docstring of r=   .r!   rn   )
stacklevel)r   inspectgetsourcefile	TypeErrorgetattrr   r   )r   r   re   filenamerC   r   r   r   rf     s   
zNumpyDocString._error_locationro   c                 C   s   |t || gS r   )r(   )r   rC   symbolr   r   r   _str_header  r)   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   rx   r   r   r   r   _str_indent  r6   zNumpyDocString._str_indentc                 C   s&   | d r| d  ddgdg S dgS )NrG   *z\*r!   )replacer   r   r   r   _str_signature  s   zNumpyDocString._str_signaturec                 C      | d r| d dg S g S )NrH   r!   r   r   r   r   r   _str_summary     zNumpyDocString._str_summaryc                 C   r   )NrI   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   rC   r   rD   r5   rE   r	   r   )r   rC   r#   parampartsr   r   r   _str_param_list  s   
zNumpyDocString._str_param_listc                 C   s4   g }| | r||  |7 }|| | 7 }|dg7 }|S r3   )r   )r   rC   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s%J g }|D ]'\}}|r9d| d| d}	n|rEd| d| d}	nd| d}	||	 q)d|}	||	g7 }|rk|| d	|g7 }d}qd
}|| | jg7 }q|r~|dg7 }|dg7 }|S )NrT   r!   Tr   z:``z`_, r   F)r   r   r   r   r5   r   empty_description)
r   	func_roler#   Zlast_had_descr   rE   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 }| D ]\}}|dkr'qd}|d| dd	| g7 }q|r<|S dS )
NrX   Fr   r!   Tz.. index:: z   :z: r   )r   r   r5   )r   idxr#   Zoutput_indexZdefault_indexr|   Z
referencesr   r   r   
_str_index  s   zNumpyDocString._str_indexc                 C   s   g }||   7 }||  7 }||  7 }|| d7 }dD ]	}|| |7 }qdD ]	}|| |7 }q)|| d7 }|| |7 }dD ]	}|| |7 }qC||  7 }d|S )NrJ   )rK   rL   )rM   rN   rO   rP   rQ   rR   rS   )rU   rV   rW   r   )r   r   r   r   r   r   r   r5   )r   r   r#   Z
param_listr   r   r   r   rA   $  s   
zNumpyDocString.__str__r   )F)T)ro   )r   )r!   ),r7   r8   r9   r:   r^   r   r   rh   rk   rl   rv   r{   r}   r   r   _roleZ_funcbacktickZ
_funcplainZ	_funcnamer   Z_funcnamenextZ_descriptionr   r   r   r   r   r   r   r   r`   propertyr   rf   r   r   r   r   r   r   r   r   r   rA   r   r   r   r   rF   p   s    	


+8$



 rF   c                 C   s   t d| dS )z"Deindent a list of lines maximallyr   )rY   rZ   r5   r   )linesr   r   r   r   =  s   r   c                       s.   e Zd Zd	ddZdd Z fddZ  ZS )
FunctionDocr   Nc                 C   sP   || _ || _|d u r|d u rtdt|pd}|d u ri }t| || d S )NzNo function or docstring givenr!   )r   r   r   r   getdocrF   r   )r   r   r   rx   ra   r   r   r   r   C  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 )Nr7   __call__)r   r   r   r7   r   isclassr   )r   	func_namer   r   r   r   get_funcO  s   zFunctionDoc.get_funcc                    sr   d}|   \}}ddd}| jr-| j|v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   superrA   )r   r#   r   r   Zrolesr   r   r   rA   W  s   

 zFunctionDoc.__str__)r   NN)r7   r8   r9   r   r   rA   __classcell__r   r   r   r   r   B  s    
r   c                   @   s   e Zd ZdddZdS )ObjDocNc                 C   s&   || _ |d u r	i }tj| ||d d S )Nra   )r   rF   r   )r   objrx   ra   r   r   r   r   h  s   zObjDoc.__init__)NN)r7   r8   r9   r   r   r   r   r   r   g  s    r   c                   @   sP   e Zd ZdgZddedfddZedd Zedd	 Ze	d
d Z
dd ZdS )ClassDocr   Nr!   c              
   C   s  t |s|d urtd||| _dtjv rddlm} nt }|d u r(i }|	dd| _
|r:|ds:|d7 }|| _|d u rN|d u rItdt|}t| | |	d	g }||u r`d }|	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 || |
< q~d S d S 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 r   )
splitlines)r   r   r   r   splitlines_x  s   z'ClassDoc.__init__.<locals>.splitlines_xrL   rK   r!   )r   r   r   r   sysmodulesZsphinx.ext.autodocr   objectr   show_inherited_membersr   _modpydocr   rF   r   methods
propertiessortedr   r   rB   AttributeError)r   clsrx   
modulenamefunc_docra   r   Z_membersZ_excluder   fieldr   Zdoc_listrC   Zdoc_itemr   r   r   r   r  sR   

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 )_)rr   extra_public_methodsr   r   _is_show_memberr   rC   r   r   r   r   r     s    
z$ClassDoc.methods.<locals>.<listcomp>r   r   
getmembersr   r   r   r   r     
   


zClassDoc.methodsc                    r  )Nc                    sV   g | ]'\}}| d s) | js)|du s"t|ttfs"t|r |r|qS )r  N)	rr   _should_skip_memberr   r   r   r   r   isdatadescriptorr  r	  r   r   r   r     s    z'ClassDoc.properties.<locals>.<listcomp>r
  r   r   r   r   r     r  zClassDoc.propertiesc                 C   s(   t |tot|dot|do| |jv S )N_asdict_fields)
issubclasstupler?   r  )rC   klassr   r   r   r    s   
zClassDoc._should_skip_memberc                 C   s   | j p|| jjv S r   )r   r   __dict__)r   rC   r   r   r   r    s   
zClassDoc._is_show_member)r7   r8   r9   r  r   r   r   r   r   staticmethodr  r  r   r   r   r   r   o  s    6



r   c                 C   s   |d u rt | rd}nt | rd}n
t| trd}nd}|d u r$i }|dkr0|| |||dS |dv r;|| ||dS |d u rDt| }|| ||dS )	Nclassmoduler   r   )r  rx   ra   )r   r   )rx   ra   r   )r   r   ismoduler   r   r   r   )r   whatrx   ra   Z	class_docr  Zobj_docr   r   r   get_doc_object  s"   	



r  )r:   r\   r   r   r   r   rY   collectionsr   collections.abcr   r   	functoolsr   warningsr   r   r   	Exceptionr;   rB   rF   r   r   r   r   r  r   r   r   r   <module>   s<   	L   P%p