U
    KvfàU  ã                   @   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dddgƒ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   ú?/tmp/pip-unpacked-wheel-2v6byqio/statsmodels/tools/docstring.pyÚdedent_lines   s    r   c                 C   s4   | r| d   ¡ s| d= q | r0| d   ¡ s0| d= q| 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   s
   | j | S ©N)r   ©r   Únr   r   r   Ú__getitem__/   s    zReader.__getitem__c                 C   s
   d| _ d S )Nr   )Ú	_line_num©r   r   r   r   r   2   s    zReader.resetc                 C   s,   |   ¡ s$| | j }|  jd7  _|S dS d S )Né   Ú )Úeofr    )r   Úoutr   r   r   Úread5   s
    
zReader.readc                 C   s4   | | j d … D ] }| ¡ r  q0q|  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   s    z
Reader.eofc                 C   sb   | j }| |d … D ]J}||ƒr0| || 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   s    z0Reader.read_to_next_empty_line.<locals>.is_empty)r(   r,   )r   r-   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   r0   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 d S ©Nr#   r)   r   r   r   r   Úpeek_   s    zReader.peekc                 C   s   d  | j¡ ¡  S r2   )r   r   r   r!   r   r   r   r-   e   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   Ú	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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dLd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d/d0„ Zd1d2„ Zd3d4„ ZdMd6d7„Z dNd9d:„Z!d;d<„ Z"d=d>„ Z#d?d@„ Z$dAdB„ Z%dCdD„ Z&dEdF„ Z'dGdH„ Z(dOdIdJ„Z)dKS )PÚNumpyDocStringz‚Parses a numpydoc string to an abstract representation

    Instances define a mapping from section title to structured data.
    r#   )Ú	SignatureÚSummaryúExtended SummaryÚ
ParametersÚReturnsÚYieldsÚReceivesÚRaisesÚWarnsúOther ParametersÚ
AttributesÚMethodsúSee AlsoÚNotesÚWarningsÚ
ReferencesÚExamplesÚindexc              
   C   sh   |}t  |¡ d¡}t|ƒ| _t | j¡| _z|  	¡  W n* t
k
rb } z||_‚ W 5 d }~X Y nX d S )Nr   )r   r   r	   r   Ú_docÚcopyÚdeepcopyÚsectionsÚ_parsed_dataÚ_parser   Ú	docstring)r   rU   Zorig_docstringÚer   r   r   r   ‡   s    
zNumpyDocString.__init__c                 C   s
   | j | S r   )rS   )r   Úkeyr   r   r   r   ”   s    zNumpyDocString.__getitem__c                 C   s(   || j kr|  d| ¡ n
|| j |< d S )NzUnknown section %s)rS   Ú_error_location)r   rW   Úvalr   r   r   Ú__setitem__—   s    
zNumpyDocString.__setitem__c                 C   s
   t | jƒS r   )ÚiterrS   r!   r   r   r   Ú__iter__   s    zNumpyDocString.__iter__c                 C   s
   t | jƒS r   )r*   rS   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 )NFú
.. index::Tr"   ú-ú=)rO   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 q&qt |d d d… ƒD ]\}}| ¡ r8 qNq8||t|ƒ| … S )Nr   r   )Ú	enumerater   r*   )r   ÚdocÚiÚjr   r   r   r   Ú_strip±   s    zNumpyDocString._stripc                 C   sJ   | j  ¡ }|  ¡ sF| j  ¡ sF| j  d¡ ¡ s6|dg7 }|| j  ¡ 7 }q
|S )Nr   r#   )rO   r.   rd   r$   r3   r   )r   Úsectionr   r   r   Ú_read_to_next_section¾   s    

z$NumpyDocString._read_to_next_sectionc                 c   sn   | j  ¡ sj|  ¡ }|d  ¡ }| d¡r<||dd … fV  q t|ƒdk rPtV  q ||  |dd … ¡fV  q d S )Nr   ú..r"   é   )rO   r$   rk   r   ra   r*   ÚStopIterationri   )r   r   r9   r   r   r   Ú_read_sectionsÉ   s    

zNumpyDocString._read_sectionsFc           	      C   sŠ   t |ƒ}g }| ¡ s†| ¡  ¡ }d|kr@| d¡d d… \}}n|rPd| }}n
|d }}| ¡ }t|ƒ}t|ƒ}| t	|||ƒ¡ q|S )Nú : rm   r#   )
r   r$   r&   r   r	   r1   r   r   Úappendr8   )	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rolenextr9   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>[,\.])?rl   c                    s*  g }‡ fdd„}g }|D ]
}|  ¡ s(qˆ j |¡}d}|rl| d¡}| d¡rl|rlˆ  d| d¡|f ¡ |sŠ| d¡rŠ| |  ¡ ¡ q|rg }| d¡}	|	  ¡ s¨qö||	ƒ\}
}}| |
|f¡ |	|d…   ¡ }	|	rž|	d	 d
krž|	dd…   ¡ }	qžtt	d|gƒƒ}| ||f¡ qt
|› 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                    sN   ˆ j  | ¡}|st| › dƒ‚| d¡}|r6| d¡n| d¡}||| ¡ fS )zMatch ':role:`name`' or 'name'.ú is not a item namer{   r9   Zname2)Ú	_func_rgxÚmatchr   ÚgroupÚend)ÚtextÚmr{   r9   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allfuncsr   ú,r"   r|   )r   Ú	_line_rgxr~   r   rX   r€   ra   rq   r   Úfilterr   )r   rr   Úitemsrƒ   Úrestr   Z
line_matchÚdescriptionÚfuncsr   r9   r{   Z	match_endr   r!   r   Ú_parse_see_also  s@    	

þÿ
zNumpyDocString._parse_see_alsoc                 C   sz   dd„ }i }|  d¡}t|ƒdkr<||d   d¡ƒd |d< |D ]4}|  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   s   g | ]}|  ¡ ‘qS r   r   ©Ú.0Úsr   r   r   Ú
<listcomp>O  s     zFNumpyDocString._parse_index.<locals>.strip_each_in.<locals>.<listcomp>r   )Úlstr   r   r   Ústrip_each_inN  s    z2NumpyDocString._parse_index.<locals>.strip_each_inz::r"   r…   r   Údefaultú:rm   )r	   r*   )r   rj   rr   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¡}| |¡rX|| d< |   ¡ sXqqXq|dk	rh|| 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   c  s     z1NumpyDocString._parse_summary.<locals>.<listcomp>z^([\w., ]+=)?\s*[\w\.]+\(.*\)$r=   r>   r?   )	rd   rO   r.   r   r   ÚreÚcompiler~   rk   )r   ÚsummaryZsummary_strZcompiledr   r   r   Ú_parse_summary[  s    


zNumpyDocString._parse_summaryc                 C   s2  | j  ¡  |  ¡  t|  ¡ ƒ}tdd„ |D ƒƒ}d|k}d|k}|rT|rTd}t|ƒ‚|sld|krld}t|ƒ‚|D ]¼\}}| d¡s¸d	d
„ | d¡D ƒ}d 	|¡}|  
|¡r¸|  d| ¡ |dkrÐ|  |¡| |< qp|dkrì| j|dd| |< qp| d¡r
|  ||¡| d< qp|dkr$|  |¡| d< qp|| |< qpd S )Nc                 S   s   g | ]\}}|‘qS r   r   )rŽ   rj   rr   r   r   r   r   v  s     z)NumpyDocString._parse.<locals>.<listcomp>rA   rB   z5Docstring contains both a Returns and Yields section.rC   z5Docstring contains a Receives section but not Yields.rl   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)r@   rF   rG   rH   )rA   rB   rD   rE   rC   T)rs   r^   rN   rI   )rO   r   r™   r   ro   ÚsetÚ
ValueErrorra   r	   r   ÚgetrX   rw   r•   rŒ   )r   rR   Zsection_namesZhas_returnsZ
has_yieldsÚmsgrj   rr   r   r   r   rT   q  s@    



ÿ ÿ
zNumpyDocString._parsec                 C   sR   t | dƒrFzt | j¡}W n tk
r2   d }Y nX |d| j|f  }t|ƒ‚d S )NÚ_objz in the docstring of %s in %s.)ÚhasattrÚinspectÚgetsourcefiler    Ú	TypeErrorr   )r   rŸ   Úfilenamer   r   r   rX   £  s    

ÿzNumpyDocString._error_locationr_   c                 C   s   |t |ƒ| gS r   )r*   )r   r9   Úsymbolr   r   r   Ú_str_header²  s    zNumpyDocString._str_headeré   c                 C   s$   g }|D ]}|d| | g7 }q|S )Nr„   r   )r   rf   Ú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 )Nr=   Ú*z\*r#   )Úreplacer!   r   r   r   Ú_str_signature»  s    zNumpyDocString._str_signaturec                 C   s   | d r| d dg S g S d 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 d S )Nr?   r#   r   r!   r   r   r   Ú_str_extended_summaryÇ  s    z$NumpyDocString._str_extended_summaryc                 C   s”   g }| | r||   |¡7 }| | D ]b}g }|jr<| |j¡ |jrN| |j¡ |d |¡g7 }|jr"d |j¡ ¡ r"||  |j¡7 }q"|dg7 }|S )Nrp   r#   )r§   r9   rq   r:   r   r;   r   rª   )r   r9   r%   ÚparamÚpartsr   r   r   Ú_str_param_listÍ  s    
zNumpyDocString._str_param_listc                 C   s4   g }| | r0||   |¡7 }|| | 7 }|dg7 }|S r2   )r§   )r   r9   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ƒs@t‚g }|D ]>\}}|rbd||f }	n|rtd||f }	nd| }	| |	¡ qHd |¡}	||	g7 }|r¼||  d |¡g¡7 }d}q*d}||  | jg¡7 }q*|râ|dg7 }|S )	NrI   Tz:%s:`%s`z%sú, r„   Fr#   )r§   r   r   ÚAssertionErrorrq   r   rª   Úempty_description)
r   Ú	func_roler%   Zlast_had_descr‹   r;   ÚlinksÚfuncr{   Úlinkr   r   r   Ú_str_see_alsoå  s2    


zNumpyDocString._str_see_alsoc                 C   sz   | d }g }d}|  dd¡}|r$d}|d| g7 }| ¡ D ].\}}|dkrLq:d}|d|d |¡f g7 }q:|rr|S dS d S )	NrN   Fr“   r#   Tz.. index:: %sz
   :%s: %sr´   )rž   rˆ   r   )r   Úidxr%   Zoutput_indexZdefault_indexrj   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 }q`dD ]}||  |¡7 }qx||  ¡ 7 }d |¡S )N)r@   rA   rB   rC   rF   rD   rE   rK   )rJ   rL   rM   )rG   rH   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)r_   )r¨   )r#   )*r4   r5   r6   r7   rR   r   r   rZ   r\   r]   rd   ri   rk   ro   rw   Z_roleZ_funcbacktickZ
_funcplainZ	_funcnamer¬   Z_funcnamenextZ_descriptionr–   r—   r}   r†   r¶   rŒ   r•   r™   rT   rX   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 krd S t|ƒ| _ d S r   )Ú_dsÚ
_docstringr<   )r   rU   r   r   r   r   8  s
    zDocstring.__init__c                    sj   | j dk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 ˆ kr|‘qS r   ©r9   ©rŽ   r°   ©Ú
parametersr   r   r   K  s   
þz/Docstring.remove_parameters.<locals>.<listcomp>r@   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krdS t|tƒr|g}|dkr<|| jd  | jd< nvd}t| jd ƒD ]\}}|j|krN|d } qnqN|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.
        Nr@   r   r"   r   )rÁ   r   r8   rÀ   re   r9   r   )r   ÚafterrÅ   Úlocrg   r°   ru   r   r   r   Úinsert_parametersT  s     



zDocstring.insert_parametersc                 C   sl   | j dkrdS d ttj| d¡ƒ¡}|| jk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#{0} is not a block in the docstring)rÁ   r   ÚmaprÆ   rš   r	   rÀ   r   Úformatr   r   )r   Z
block_nameÚblockr   r   r   Úreplace_blockq  s    


ÿ ÿzDocstring.replace_blockr   c                    sæ   | j d k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r |dkr–g ni ||< q~|||< q~t|ƒ ¡ }|rÊt |d	| ¡}d
 	| d
¡dd … ¡}|S )Nc                 S   s   i | ]}|j |“qS r   rÂ   rÃ   r   r   r   Ú
<dictcomp>  s      z0Docstring.extract_parameters.<locals>.<dictcomp>r@   z#{0} were not found in the docstringr…   c                    s   g | ]}ˆ | ‘qS r   r   rÃ   ©Z	ds_paramsr   r   r   –  s     z0Docstring.extract_parameters.<locals>.<listcomp>rN   r„   r   rm   )rÁ   r   rÆ   rÀ   rœ   Ú
differenceÚkeysr   rÍ   r   rP   rQ   r   r   r©   r	   )r   rÅ   r©   ÚmissingÚfinalÚdsrW   r%   r   rÑ   r   Úextract_parameters‰  s.    

ÿÿ
zDocstring.extract_parametersc                 C   s
   t | jƒS r   )rÆ   rÀ   r!   r   r   r   r¾   ¤  s    zDocstring.__str__N)r   )
r4   r5   r6   r7   r   rÈ   rË   rÏ   r×   r¾   r   r   r   r   r¿   .  s   	
r¿   c                 C   s&   | dk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Æ   )rU   rÅ   rÖ   r   r   r   rÈ   ¨  s
    
rÈ   c                 C   s   | dk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©   )N)r7   Úcollectionsr   Úcollections.abcr   rP   r¢   r–   r   Zstatsmodels.tools.sm_exceptionsr   r   r   r   r8   r<   r¿   rÈ   r©   r   r   r   r   Ú<module>   s$   	M   Ez