o
    0GfU                     @   s   d Z ddlmZ ddl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 Zdd	 ZG d
d dZedg dZG dd deZG dd dZdd ZdddZdS )z,
Substantially copied from NumpyDoc 1.0pre.
    )
namedtuple)MappingN)
ParseErrorc                 C   s   t d| dS )z"Deindent a list of lines maximally
)textwrapdedentjoinsplit)lines r   ;lib/python3.10/site-packages/statsmodels/tools/docstring.pydedent_lines   s   r   c                 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liner   r   r   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 )zq
        Parameters
        ----------
        data : str
           String with lines separated by '
'.
        r   N)
isinstancelist_strr	   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   )	_line_numr   r   r   r   r   2   r!   zReader.resetc                 C   s(   |   s| | j }|  jd7  _|S dS )N    )eofr"   )r   outr   r   r   read5   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&   D      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startr   r   r   r   read_to_conditionG   s   zReader.read_to_conditionc                 C   s   |    dd }| |S )Nc                 S   s
   |    S r   r   r   r   r   r   is_emptyT   r!   z0Reader.read_to_next_empty_line.<locals>.is_empty)r*   r/   )r   r0   r   r   r   read_to_next_empty_lineQ   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_unindentedZ   s   z:Reader.read_to_next_unindented_line.<locals>.is_unindented)r/   )r   r3   r   r   r   read_to_next_unindented_lineY   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 r5   )r   r   r   r#   r   r   r   r0   e   s   zReader.is_emptyNr   )__name__
__module____qualname____doc__r   r    r   r(   r*   r&   r/   r1   r4   r6   r0   r   r   r   r   r      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 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dDdE Zd^dGdHZ d_dJdKZ!dLdM Z"dNdO Z#dPdQ Z$dRdS Z%dTdU Z&dVdW Z'dXdY Z(d`dZd[Z)d\S )a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   )r   r   r	   r   _doccopydeepcopysections_parsed_data_parser   	docstring)r   rY   Zorig_docstringer   r   r   r      s   
zNumpyDocString.__init__c                 C   r   r   )rW   )r   keyr   r   r   r       r!   zNumpyDocString.__getitem__c                 C   s*   || j vr| d|  d S || j |< d S )NzUnknown section %s)rW   _error_location)r   r[   valr   r   r   __setitem__   s   
zNumpyDocString.__setitem__c                 C   
   t | jS r   )iterrW   r#   r   r   r   __iter__   r!   zNumpyDocString.__iter__c                 C   r_   r   )r,   rW   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$   -=)rS   r*   r&   r6   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%   )rS   r1   ri   r&   r6   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$      )rS   r&   rp   r   rf   r,   StopIterationrn   )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 : rr   r%   )
r   r&   r(   r   r	   r4   r   r   appendr<   )	r   contentsingle_element_is_typerparamsheaderZarg_nameZarg_typer?   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>[,\.])?rq   c                    s&  g } fdd}g }|D ]}|  sq j|}d}|r5|d}|dr5|r5 d|d|f  |sD|drD||   q|rg }|d}		 |	  sSn'||	\}
}}||
|f |	|d   }	|	ry|	d
 dkry|	dd   }	qNt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                    sN    j | }|st|  d|d}|r|dn|d}||| fS )zMatch ':role:`name`' or 'name'. is not a item namer   r=   Zname2)	_func_rgxmatchr   groupend)textmr   r=   r#   r   r   parse_item_name  s   
z7NumpyDocString._parse_see_also.<locals>.parse_item_nameNr?   ZtrailingzGUnexpected comma or period after function list at index %d of line "%s" ZallfuncsTr   ,r$   r   )r   	_line_rgxr   r   r\   r   rf   rv   r   filterr   )r   rw   itemsr   restr   Z
line_matchdescriptionfuncsr   r=   r   Z	match_endr   r#   r   _parse_see_also  sD   	

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 )
zS
        .. 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>O      zFNumpyDocString._parse_index.<locals>.strip_each_in.<locals>.<listcomp>r   )Zlstr   r   r   strip_each_inN  s   z2NumpyDocString._parse_index.<locals>.strip_each_inz::r$   r   r   default:rr   )r	   r,   )r   ro   rw   r   r'   r   r   r   r   _parse_indexH  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   c  r   z1NumpyDocString._parse_summary.<locals>.<listcomp>z^([\w., ]+=)?\s*[\w\.]+\(.*\)$rA   rB   rC   )	ri   rS   r1   r   r   recompiler   rp   )r   ZsummaryZsummary_strZcompiledr   r   r   _parse_summary[  s    


zNumpyDocString._parse_summaryc                 C   s*  | j   |   t|  }dd |D }d|v }d|v }|r(|r(d}t||s4d|v r4d}t||D ]\\}}|dsZd	d
 |dD }d|}| 	|rZ| 
d|  |dv rf| || |< q6|dv rt| j|dd| |< q6|dr| ||| d< q6|dkr| || d< q6|| |< q6d S )Nc                 S   s   h | ]\}}|qS r   r   )r   ro   rw   r   r   r   	<setcomp>v  r   z(NumpyDocString._parse.<locals>.<setcomp>rE   rF   z5Docstring contains both a Returns and Yields section.rG   z5Docstring contains a Receives section but not Yields.rq   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)rD   rJ   rK   rL   )rE   rF   rH   rI   rG   T)rx   rc   rR   rM   )rS   r   r   r   rt   
ValueErrorrf   r	   r   getr\   r|   r   r   )r   rV   Zsection_namesZhas_returnsZ
has_yieldsmsgro   rw   r   r   r   rX   q  s@   





zNumpyDocString._parsec                 C   sL   t | dr"zt| j}W n ty   d }Y nw |d| j| }t|)N_objz in the docstring of {} in {}.)hasattrinspectZgetsourcefiler   	TypeErrorformatr   )r   r   filenamer   r   r   r\     s   
zNumpyDocString._error_locationrd   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   rk   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 )NrA   *z\*r%   )replacer#   r   r   r   _str_signature  s   zNumpyDocString._str_signaturec                 C      | d r| d dg S g S )NrB   r%   r   r#   r   r   r   _str_summary     zNumpyDocString._str_summaryc                 C   r   )NrC   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 )Nru   r%   )r   r=   rv   r>   r   r?   r   r   )r   r=   r'   parampartsr   r   r   _str_param_list  s   
zNumpyDocString._str_param_listc                 C   s4   g }| | r||  |7 }|| | 7 }|dg7 }|S r5   )r   )r   r=   r'   r   r   r   _str_section  s   
zNumpyDocString._str_sectionc           
      C   s   | d sg S g }||  d7 }d}| d D ]T\}}t|ts J g }|D ]\}}|r1d||}	n|r:d||}	nd| }	||	 q$d|}	||	g7 }|r^|| d|g7 }d}qd}|| | jg7 }q|rq|dg7 }|S )	NrM   Tz:{}:`{}`z%s, r   Fr%   )r   r   r   r   rv   r   r   empty_description)
r   	func_roler'   Zlast_had_descr   r?   Zlinksfuncr   linkr   r   r   _str_see_also  s2   


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|g7 }q|r9|S dS )	NrR   Fr   r%   Tz.. index:: %sz
   :{}: {}r   )r   r   r   r   )r   idxr'   Zoutput_indexZdefault_indexro   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)rD   rE   rF   rG   rJ   rH   rI   rO   )rN   rP   rQ   )rK   rL   r   )r   r   r   r   r   r   r   r   )r   r   r'   Z
param_listr   r   r   r   __str__  s   	
zNumpyDocString.__str__N)F)rd   )r   )r%   )*r8   r9   r:   r;   rV   r   r    r^   ra   rb   ri   rn   rp   rt   r|   Z_roleZ_funcbacktickZ
_funcplainZ	_funcnamer   Z_funcnamenextZ_descriptionr   r   r   r   r   r   r   r   rX   r\   r   r   r   r   r   r   r   r   r   r   r   r   r   r   r@   l   s    	

%	
52

r@   c                   @   sB   e Zd ZdZdd Zdd Zdd Zdd	 ZdddZdd Z	dS )	Docstringzu
    Docstring modification.

    Parameters
    ----------
    docstring : str
        The docstring to modify.
    c                 C   s&   d | _ || _|d u rd S t|| _ d S r   )_ds
_docstringr@   )r   rY   r   r   r   r   8  s
   zDocstring.__init__c                    sj   | j du rdS t tr g  fdd| jd D }t|t  t| jd kr.td|| jd< dS )z
        Parameters
        ----------
        parameters : str, list[str]
            The names of the parameters to remove.
        Nc                    s   g | ]	}|j  vr|qS r   r=   r   r   
parametersr   r   r   K  s
    
z/Docstring.remove_parameters.<locals>.<listcomp>rD   z&One or more parameters were not found.)r   r   strr   r,   r   )r   r   replr   r   r   remove_parameters?  s   


zDocstring.remove_parametersc                 C   s   | j du rdS t|tr|g}|du r|| jd  | jd< dS d}t| jd D ]\}}|j|kr7|d } nq(|dk r?t | jd d| | }|| jd |d 7 }|| jd< dS )a  
        Parameters
        ----------
        after : {None, str}
            If None, inset the parameters before the first parameter in the
            docstring.
        parameters : Parameter, list[Parameter]
            A Parameter of a list of Parameters.
        NrD   r   r$   r   )r   r   r<   r   rj   r=   r   )r   Zafterr   locrl   r   rz   r   r   r   insert_parametersT  s"   



zDocstring.insert_parametersc                 C   sl   | j du rdS dttj|d}|| jvrtd|t	|t
s/t	| j| t
r/|g}|| j|< dS )a&  
        Parameters
        ----------
        block_name : str
            Name of the block to replace, e.g., 'Summary'.
        block : object
            The replacement block. The structure of the replacement block must
            match how the block is stored by NumpyDocString.
        Nr   z"{} is not a block in the docstring)r   r   mapr   r   r	   r   r   r   r   r   )r   Z
block_nameblockr   r   r   replace_blockq  s   



zDocstring.replace_blockr   c                    s   | j d u rd S t|tr|g}dd | jd D  t|  }|r.tdd	| fdd|D }t
| j}|D ]}|dkrP|dkrKg ni ||< q?|||< q?t| }|ret|d	| }d
	|d
dd  }|S )Nc                 S   s   i | ]}|j |qS r   r   r   r   r   r   
<dictcomp>  r   z0Docstring.extract_parameters.<locals>.<dictcomp>rD   z"{} were not found in the docstringr   c                    s   g | ]} | qS r   r   r   Z	ds_paramsr   r   r     r   z0Docstring.extract_parameters.<locals>.<listcomp>rR   r   r   rr   )r   r   r   r   set
differencekeysr   r   r   rT   rU   r   r   r   r	   )r   r   r   missingfinaldsr[   r'   r   r   r   extract_parameters  s,   


zDocstring.extract_parametersc                 C   r_   r   )r   r   r#   r   r   r   r     r!   zDocstring.__str__Nr7   )
r8   r9   r:   r;   r   r   r   r   r   r   r   r   r   r   r   .  s    	
r   c                 C   s&   | du rdS t | }|| t|S )z
    Parameters
    ----------
    docstring : str
        The docstring to modify.
    parameters : str, list[str]
        The names of the parameters to remove.

    Returns
    -------
    str
        The modified docstring.
    N)r   r   r   )rY   r   r   r   r   r   r     s
   
r   c                 C   s   | du rdS t j| ||dS )a  
    Non-protected indent

    Parameters
    ----------
    text : {None, str}
        If None, function always returns ""
    prefix : str
        Prefix to add to the start of each line
    predicate : callable, optional
        If provided, 'prefix' will only be added to the lines
        where 'predicate(line)' is True. If 'predicate' is not provided,
        it will default to adding 'prefix' to all non-empty lines that do not
        consist solely of whitespace characters.

    Returns
    -------

    Nr%   )	predicate)r   r   )r   prefixr   r   r   r   r     s   r   r   )r;   collectionsr   Zcollections.abcr   rT   r   r   r   Zstatsmodels.tools.sm_exceptionsr   r   r   r   r<   r@   r   r   r   r   r   r   r   <module>   s&    	M   Ez