
    'YHhU                         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 Zd Z G d d	      Z ed
g d      Z G d de      Z G d d      Zd ZddZy)z,
Substantially copied from NumpyDoc 1.0pre.
    )
namedtuple)MappingN)
ParseErrorc                 h    t        j                  dj                  |             j                  d      S )z"Deindent a list of lines maximally
)textwrapdedentjoinsplit)liness    T/var/www/html/planif/env/lib/python3.12/site-packages/statsmodels/tools/docstring.pydedent_linesr      s%    ??499U+,22488    c                     | r,| d   j                         s| d= | r| d   j                         s| r,| d   j                         s| d= | r| d   j                         s| S )z<Remove leading and trailing blank lines from a list of linesr   striplines    r   strip_blank_linesr      sW    
tAw}}G tAw}}
tBx~~'H tBx~~'Kr   c                   T    e Zd ZdZd Zd Zd Zd Zd Zd Z	d Z
d	 Zd
 ZddZd Zy)Readerz%
    A line-based string reader.
    c                     t        |t              r|| _        n|j                  d      | _        | j	                          y)zq
        Parameters
        ----------
        data : str
           String with lines separated by '
'.
        r   N)
isinstancelist_strr   reset)selfdatas     r   __init__zReader.__init__!   s.     dD!DI

4(DI

r   c                      | j                   |   S N)r   r   ns     r   __getitem__zReader.__getitem__/   s    yy|r   c                     d| _         y )Nr   )	_line_numr   s    r   r   zReader.reset2   s	    r   c                 p    | j                         s&| | j                     }| xj                  dz  c_        |S y)N    )eofr'   )r   outs     r   readzReader.read5   s/    xxzt~~&CNNaNJr   c                 z    | | j                   d  D ])  }|j                         r y | xj                   dz  c_         + y Nr*   )r'   r   )r   r   s     r   seek_next_non_empty_linezReader.seek_next_non_empty_line=   s7    )* 	$Dzz|!#		$r   c                 F    | j                   t        | j                        k\  S r"   r'   lenr   r(   s    r   r,   z
Reader.eofD   s    ~~TYY//r   c                     | j                   }| |d  D ]T  } ||      r| || j                    c S | xj                   dz  c_         | j                         sB| || j                   dz    c S  g S r0   )r'   r,   )r   condition_funcstartr   s       r   read_to_conditionzReader.read_to_conditionG   sm    L 	8Dd#EDNN33NNaNxxzEDNNQ$677	8 	r   c                 J    | j                          d }| j                  |      S )Nc                 $    | j                          S r"   r   r   s    r   is_emptyz0Reader.read_to_next_empty_line.<locals>.is_emptyT   s    zz|##r   )r1   r8   )r   r;   s     r   read_to_next_empty_linezReader.read_to_next_empty_lineQ   s&    %%'	$ %%h//r   c                 *    d }| j                  |      S )Nc                 p    | j                         xr% t        | j                               t        |       k(  S r"   )r   r4   lstripr   s    r   is_unindentedz:Reader.read_to_next_unindented_line.<locals>.is_unindentedZ   s'    ::<ES%73t9%DEr   )r8   )r   r@   s     r   read_to_next_unindented_linez#Reader.read_to_next_unindented_lineY   s    	F %%m44r   c                 r    | j                   |z   t        | j                        k  r| | j                   |z      S yNr+   r3   r#   s     r   peekzReader.peek_   s2    >>ADII.*++r   c                 V    dj                  | j                        j                          S rC   )r
   r   r   r(   s    r   r;   zReader.is_emptye   s!    77499%++---r   Nr   )__name__
__module____qualname____doc__r    r%   r   r.   r1   r,   r8   r<   rA   rD   r;    r   r   r   r      s>    $005.r   r   	Parameter)nametypedescc                      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 Zd Zd Zd Zd Z	d Z
d Zd Zd ZdAdZdZd Zd!Zd"ez   ez   d#z   ez   d$z   Zej'                  d%d&      Zej'                  d'd(      Zd)Z ej.                  d*ez   d+z         Z ej.                  d,ez   d-z   ez   d.z   d$z   d/z   ez         Zd0Zd1 Zd2 Zd3 Zd4 Zd5 ZdBd6Z dCd7Z!d8 Z"d9 Z#d: Z$d; Z%d< Z&d= Z'd> Z(dDd?Z)y@)E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                    |}t        j                  |      j                  d      }t        |      | _        t        j                  | j                        | _        	 | j                          y # t        $ r}||_         d }~ww xY w)Nr   )r   r	   r   r   _doccopydeepcopysections_parsed_data_parser   	docstring)r   rk   orig_docstringes       r   r    zNumpyDocString.__init__   si    "OOI.44T:	9%	 MM$--8	KKM 	(AK	s   A- -	B6A>>Bc                      | j                   |   S r"   )ri   )r   keys     r   r%   zNumpyDocString.__getitem__   s      %%r   c                 h    || j                   vr| j                  d|z         y || j                   |<   y )NzUnknown section %s)ri   _error_location)r   ro   vals      r   __setitem__zNumpyDocString.__setitem__   s4    d'''  !5!;<%(Dc"r   c                 ,    t        | j                        S r"   )iterri   r(   s    r   __iter__zNumpyDocString.__iter__   s    D%%&&r   c                 ,    t        | j                        S r"   )r4   ri   r(   s    r   __len__zNumpyDocString.__len__   s    4$$%%r   c                    | j                   j                          | j                   j                         ry| j                   j                         j	                         }|j                  d      ry| j                   j                  d      j	                         }|j                  dt        |      z        xs |j                  dt        |      z        S )NF
.. index::Tr*   -=)re   r1   r,   rD   r   
startswithr4   )r   l1l2s      r   _is_at_sectionzNumpyDocString._is_at_section   s    		**,99==?YY^^##%==&YY^^A$$&}}S3r7]+Kr}}S3r7]/KKr   c                     d}d}t        |      D ]  \  }}|j                         s n t        |d d d         D ]  \  }}|j                         s n ||t        |      |z
   S )Nr   r   )	enumerater   r4   )r   docijr   s        r   _stripzNumpyDocString._strip   st     ~ 	GAtzz|	 !TrT+ 	GAtzz|	 1s3x!|$$r   c                 |   | j                   j                         }| j                         s| j                   j                         sw| j                   j	                  d      j                         s|dgz  }|| j                   j                         z  }| j                         s| j                   j                         sw|S )Nr   r+   )re   r<   r   r,   rD   r   )r   sections     r   _read_to_next_sectionz$NumpyDocString._read_to_next_section   s    ))335%%'		99>>"%++-B4tyy88::G	 %%'		 r   c              #   R  K   | j                   j                         s| j                         }|d   j                         }|j	                  d      r
||dd  f n/t        |      dk  r	t         n|| j                  |dd        f | j                   j                         sy y w)Nr   ..r*      )re   r,   r   r   r}   r4   StopIterationr   )r   r   rM   s      r   _read_sectionszNumpyDocString._read_sections   s     ))--/--/D7==?Dt$DHn$TQ##DKKQR111 ))--/s   B"B'%B'c                 p   t        |      }g }|j                         s|j                         j                         }d|v r|j	                  d      d d \  }}n|rd|}}n|d}}|j                         }t        |      }t        |      }|j                  t        |||             |j                         s|S )N : r   r+   )
r   r,   r.   r   r   rA   r   r   appendrL   )	r   contentsingle_element_is_typerparamsheaderarg_namearg_typerO   s	            r   _parse_param_listz NumpyDocString._parse_param_list   s    7O%%'VVX^^%F%+\\%%8!%<"())+VhH)/hH113D%D$T*DMM)Hh=> %%'  r   z:(?P<role>\w+):z'`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_\.-]+)`z(?P<name2>[a-zA-Z0-9_\.-]+)(|)rolerolenextrM   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                     g } fd}g }|D ]]  }|j                         s j                  j                  |      }d}|rI|j                  d      }|j                  d      r'|r% j	                  d|j                  d      |fz         |s1|j                  d      r |j                  |j                                |rg }|j                  d      }		 |	j                         snP ||	      \  }
}}|j                  |
|f       |	|d j                         }	|	r|	d   d	k(  r|	d
d j                         }	at        t        d|g            }|j                  ||f       Rt        | d       |S )z
        func_name : Descriptive text
            continued text
        another_func_name : Descriptive text
        func_name1, func_name2, :meth:`func_name`, func_name3
        c                     j                   j                  |       }|st        |  d      |j                  d      }|r|j                  d      n|j                  d      }|||j	                         fS )zMatch ':role:`name`' or 'name'. is not a item namer   rM   name2)	_func_rgxmatchr   groupend)textmr   rM   r   s       r   parse_item_namez7NumpyDocString._parse_see_also.<locals>.parse_item_name  sg    $$T*A D6)<!=>>776?D&*1776?0@Dquuw&&r   NrO   trailingzGUnexpected comma or period after function list at index %d of line "%s" allfuncsr   ,r*   r   )r   	_line_rgxr   r   rq   r   r}   r   r   filterr   )r   r   itemsr   restr   
line_matchdescriptionfuncsr   rM   r   	match_ends   `            r   _parse_see_alsozNumpyDocString._parse_see_also  sy    	'  	?D::<--d3JK(..v6##J/K((",.."<d!CD
 4??3#7DJJL)!''
3::<,;D,A)D$	LL$.	
+113DQ3#ABx~~/  F4+78eT]+ D6)<!=>>=	?> r   c                    d }i }|j                  d      }t        |      dkD  r  ||d   j                  d            d   |d<   |D ]B  }|j                  d      }t        |      dkD  s# ||d   j                  d            ||d   <   D |S )	zS
        .. index: default
           :refguide: something, else, and more
        c                 H    | D cg c]  }|j                          c}S c c}w r"   r   )lstss     r   strip_each_inz2NumpyDocString._parse_index.<locals>.strip_each_inN  s    '*+!AGGI+++s   z::r*   r   r   default:r   )r   r4   )r   r   r   r   r-   r   s         r   _parse_indexzNumpyDocString._parse_indexH  s    	, --%w<!*71:+;+;C+@A!DC	N 	AD::c?D4y1},T!W]]3-?@DG	A 
r   c                    | j                         ry	 | j                  j                         }dj                  |D cg c]  }|j	                          c}      j	                         }t        j                  d      }|j                  |      r|| d<   | j                         s	 ||| d<   | j                         s| j                         | d<   yyc c}w )z%Grab signature (if given) and summaryNr   z^([\w., ]+=)?\s*[\w\.]+\(.*\)$rR   rS   rT   )	r   re   r<   r
   r   recompiler   r   )r   summaryr   summary_strcompileds        r   _parse_summaryzNumpyDocString._parse_summary[  s      ii779G((w#?!AGGI#?@FFHKzz"CDH~~k*$/[!**,%DO""$'+'A'A'CD#$ % $@s   Cc                    | j                   j                          | j                          t        | j	                               }|D ch c]  \  }}|	 }}}d|v }d|v }|r|rd}t        |      |sd|v rd}t        |      |D ]  \  }}|j                  d      sNd |j                  d      D        }dj                  |      }| j                  |      r| j                  d	|z         |d
v r| j                  |      | |<   ~|dv r| j                  |d      | |<   |j                  d      r| j                  ||      | d<   |dk(  r| j                  |      | d<   || |<    y c c}}w )NrV   rW   z5Docstring contains both a Returns and Yields section.rX   z5Docstring contains a Receives section but not Yields.r   c              3   <   K   | ]  }|j                           y wr"   )
capitalize).0r   s     r   	<genexpr>z(NumpyDocString._parse.<locals>.<genexpr>  s     Fa1<<>Fs   r   zThe section %s appears twice)rU   r[   r\   r]   )rV   rW   rY   rZ   rX   T)r   rz   rc   r^   )re   r   r   r   r   
ValueErrorr}   r   r
   getrq   r   r   r   )r   rh   r   r   section_nameshas_returns
has_yieldsmsgs           r   rj   zNumpyDocString._parseq  s   		++-.9AB%5WgBB=0.
:ICS/!jM9ICS/!"* 	(Wg%%d+F7==3EF((7+88G$((6@    !% 6 6w ?W   !% 6 6D !7 !W ##L1 $ 1 1'7 CWJ&#'#7#7#@Z  'W?	( Cs   	E(c                     t        | d      r6	 t        j                  | j                        }|d| j                   d| dz   }t        |      # t        $ r d }Y .w xY w)N_objz in the docstring of z in .)hasattrinspectgetsourcefiler   	TypeErrorr   )r   r   filenames      r   rq   zNumpyDocString._error_location  si    4  "00; '		{$xjBC o    s   A AAc                 "    |t        |      |z  gS r"   )r4   )r   rM   symbols      r   _str_headerzNumpyDocString._str_header  s    c$i&())r   c                 0    g }|D ]  }|d|z  |z   gz  } |S )Nr   rK   )r   r   indentr-   r   s        r   _str_indentzNumpyDocString._str_indent  s1     	)DC&L4'((C	)
r   c                 F    | d   r| d   j                  dd      gdgz   S dgS )NrR   *z\*r+   )replacer(   s    r   _str_signaturezNumpyDocString._str_signature  s3    %--c59:bTAA4Kr   c                 "    | d   r	| d   dgz   S g S )NrS   r+   rK   r(   s    r   _str_summaryzNumpyDocString._str_summary  s    	?	?bT))Ir   c                 "    | d   r	| d   dgz   S g S )NrT   r+   rK   r(   s    r   _str_extended_summaryz$NumpyDocString._str_extended_summary  s#    "#*+rd22Ir   c                    g }| |   r|| j                  |      z  }| |   D ]  }g }|j                  r|j                  |j                         |j                  r|j                  |j                         |dj	                  |      gz  }|j
                  sudj	                  |j
                        j                         s|| j                  |j
                        z  } |dgz  }|S )Nr   r+   )r   rM   r   rN   r
   rO   r   r   )r   rM   r-   parampartss        r   _str_param_listzNumpyDocString._str_param_list  s    :4##D))Cd 8::LL,::LL,

5)**::"''%**"5";";"=4++EJJ77C8 B4KC
r   c                 X    g }| |   r"|| j                  |      z  }|| |   z  }|dgz  }|S rC   )r   )r   rM   r-   s      r   _str_sectionzNumpyDocString._str_section  sA    :4##D))C4:CB4KC
r   c                    | d   sg S g }|| j                  d      z  }d}| d   D ]  \  }}t        |t              sJ g }|D ]3  \  }}|r
d| d| d}	n|r
d| d| d}	nd|z  }	|j                  |	       5 dj	                  |      }	||	gz  }|r'|| j                  dj	                  |      g      z  }d}d	}|| j                  | j                  g      z  } |r|d
gz  }|S )Nr^   Tr   z:``z%s, r   Fr+   )r   r   r   r   r
   r   empty_description)
r   	func_roler-   last_had_descr   rO   linksfuncr   links
             r   _str_see_alsozNumpyDocString._str_see_also  s.   JIt
++
+ 	BKE4eT***E# #
dtfBtfA.DykD63D$;DT"# 99U#DD6MCt''$(899 $ %t'')?)?(@AA%	B( B4KC
r   c                     | d   }g }d}|j                  dd      }|rd}|d|z  gz  }|j                         D ]2  \  }}|dk(  rd}|dj                  |dj                  |            gz  }4 |r|S y)	Nrc   Fr   r+   Tz.. index:: %sz
   :{}: {}r   )r   r   formatr
   )r   idxr-   output_indexdefault_indexr   
referencess          r   
_str_indexzNumpyDocString._str_index  s    7m	2.L-/00#&99; 	IGZ)#LL'':1FGHHC		I
 Jr   c                    g }|| j                         z  }|| j                         z  }|| j                         z  }dD ]  }|| j                  |      z  } || j	                  d      z  }|| j                  |      z  }dD ]  }|| j	                  |      z  } dD ]  }|| j                  |      z  } || j                         z  }dj                  |      S )N)rU   rV   rW   rX   r[   rY   rZ   r`   )r_   ra   rb   )r\   r]   r   )r   r   r   r   r   r   r   r
   )r   r   r-   
param_listr   s        r   __str__zNumpyDocString.__str__  s    t""$$t  ""t))++
 		4J 4''
33C		4 	t  ,,t!!),,4 	(A4$$Q''C	(3 	4J4''
33C	4t  yy~r   N)F)r{   )   )r+   )*rG   rH   rI   rJ   rh   r    r%   rs   rv   rx   r   r   r   r   r   _role_funcbacktick
_funcplain	_funcnamer   _funcnamenext_descriptionr   r   r   r   r   r   r   r   rj   rq   r   r   r   r   r   r   r   r   r   r  rK   r   r   rQ   rQ   l   s8   
RB4 	B 	b	
 	2 	" 	B 	" 	 	B 	b 	2 	B 	 	B  	b!" 	B#$ 	%H*&)'&L%	
2J E>M/Ju},t3j@4GI%%fj9M!))&*=MEL

7Y.78I

	
	 #	# 		
 	 	 	 		  
	I 3j&D,0(d* <$r   rQ   c                   6    e Zd ZdZd Zd Zd Zd Zd	dZd Z	y)
	Docstringzu
    Docstring modification.

    Parameters
    ----------
    docstring : str
        The docstring to modify.
    c                 F    d | _         || _        |y t        |      | _         y r"   )_ds
_docstringrQ   )r   rk   s     r   r    zDocstring.__init__8  s%    #!),r   c                 6   | j                   yt        |t              r|g}| j                  d   D cg c]  }|j                  |vr| }}t        |      t        |      z   t        | j                  d         k7  rt        d      || j                  d<   yc c}w )z
        Parameters
        ----------
        parameters : str, list[str]
            The names of the parameters to remove.
        NrU   z&One or more parameters were not found.)r  r   strr  rM   r4   r   )r   
parametersr   repls       r   remove_parameterszDocstring.remove_parameters?  s     ??"j#&$J ,/
zz+ 
 

 t9s:&#dhh|.D*EEEFF!%
s   Bc                    | j                   yt        |t              r|g}| || j                  d   z   | j                  d<   yd}t	        | j                  d         D ]  \  }}|j
                  |k(  s|dz   } n |dk  r
t               | j                  d   d| |z   }|| j                  d   |d z  }|| j                  d<   y)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.
        NrU   r   r*   r   )r  r   rL   r  r   rM   r   )r   afterr  locr   r   r   s          r   insert_parameterszDocstring.insert_parametersT  s     ??"j),$J=%/$((<2H%HDHH\"C%dhh|&<= 5::&a%C Qw l"XXl+DS1J>Fdhh|,ST22F%+DHH\"r   c                 \   | j                   ydj                  t        t        j                  |j                  d                  }|| j                  vrt        dj                  |            t        |t              s t        | j                  |   t              r|g}|| j                  |<   y)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   
block_nameblocks      r   replace_blockzDocstring.replace_blockq  s     ??"XXc#..*2B2B32GHI
TXX%7>>zJ  %&:HHZ $,
 GE$r   c                    | j                   y t        |t              r|g}| j                  d   D ci c]  }|j                  | }}t        |      j                  |j                               }|r)t        dj                  dj                  |                  |D cg c]  }||   	 }}t        j                  | j                        }|D ]  }|dk7  r|dk7  rg ni ||<   |||<    t        |      j                         }	|rt        j                  |	d|z        }	dj                  |	j!                  d      dd        }	|	S c c}w c c}w )NrU   z"{} were not found in the docstringr   rc   r   r   r   )r  r   r  r  rM   set
differencekeysr   r   r
   rf   rg   r   r   r   r   )
r   r  r   r   	ds_paramsmissingfinaldsro   r-   s
             r   extract_parameterszDocstring.extract_parameters  s:   ??"j#&$J48HH\4JK5UZZ&K	Kj/,,Y^^-=>"F388G#45  0::e5!::]]488$ 	 Cl" #w"B33		 
 "gmmo//#sV|4Cii		$+,
' L ;s   EEc                 ,    t        | j                        S r"   )r  r  r(   s    r   r  zDocstring.__str__  s    488}r   NrF   )
rG   rH   rI   rJ   r    r  r  r  r$  r  rK   r   r   r
  r
  .  s%    -&*,:%06r   r
  c                 V    | yt        |       }|j                  |       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  )rk   r  r#  s      r   r  r    s.     	9	B$r7Nr   c                 8    | yt        j                  | ||      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
    -------

    r+   )	predicate)r   r   )r   prefixr(  s      r   r   r     s    ( |??49==r   r"   )rJ   collectionsr   collections.abcr   rf   r   r   r   statsmodels.tools.sm_exceptionsr   r   r   r   rL   rQ   r
  r  r   rK   r   r   <module>r-     sm    # #   	  69
J. J.Z {$<=	W Dw wt*>r   