
    gY                        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 Z G d d      Z G d	 d
e      Z edg d      Z G d de      Zd Z G d de      Z G d de      Z G d de      ZddZy)z=Extract reference documentation from the NumPy source tree.

    N)warn)
namedtuple)CallableMappingc                     | 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)ls    O/var/www/openai/venv/lib/python3.12/site-packages/pyarrow/vendored/docscrape.pystrip_blank_linesr      sU    
AaDJJLaD AaDJJL
AbEKKMbE AbEKKMH    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)zs
        Parameters
        ----------
        data : str
           String with lines separated by '\n'.

        
N)
isinstancelist_strsplit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__2   s    yy|r   c                     d| _         y )Nr   )_lr   s    r   r   zReader.reset5   s	    r   c                 p    | j                         s&| | j                     }| xj                  dz  c_        |S y)N    )eofr!   )r   outs     r   readzReader.read8   s-    xxztww-CGGqLG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@   s/    dgghAwwy1	  r   c                 F    | j                   t        | j                        k\  S r   r!   lenr   r"   s    r   r&   z
Reader.eofG   s    ww#dii.((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 r*   )r!   r&   )r   condition_funcstartlines       r   read_to_conditionzReader.read_to_conditionJ   sf    LDd#E$''**GGqLGxxzE$''!),, ! 	r   c                 J    | j                          d }| j                  |      S )Nc                 $    | j                          S r   r	   r2   s    r   is_emptyz0Reader.read_to_next_empty_line.<locals>.is_emptyW   s    zz|##r   )r+   r3   )r   r7   s     r   read_to_next_empty_linezReader.read_to_next_empty_lineT   s&    %%'	$ %%h//r   c                 *    d }| j                  |      S )Nc                 p    | j                         xr% t        | j                               t        |       k(  S r   )r
   r.   lstripr6   s    r   is_unindentedz:Reader.read_to_next_unindented_line.<locals>.is_unindented]   s'    JJLFc$++-&8CI&EGr   )r3   )r   r<   s     r   read_to_next_unindented_linez#Reader.read_to_next_unindented_line\   s    	H%%m44r   c                 r    | j                   |z   t        | j                        k  r| | j                   |z      S yNr%   r-   r   s     r   peekzReader.peeka   s0    77Q;TYY'!$$r   c                 V    dj                  | j                        j                          S r?   )joinr   r
   r"   s    r   r7   zReader.is_emptyg   s!    77499%++---r   N)r   )__name__
__module____qualname____doc__r   r   r   r(   r+   r&   r3   r8   r=   r@   r7    r   r   r   r      s>    )05
.r   r   c                       e Zd Zd Zy)
ParseErrorc                 ^    | j                   d   }t        | d      r|d| j                  }|S )Nr   	docstring in )argshasattrrK   )r   messages     r   __str__zParseError.__str__l   s,    ))A,4%$+T^^<Gr   N)rC   rD   rE   rP   rG   r   r   rI   rI   k   s    r   rI   	Parameter)nametypedescc                   2   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dBdZd Zd Zd Zd Z	d Z
d Zd Zd ZdCd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   d0z   ez         Zd1Zd2 Zd3 Zd4 Zd5 Zed6        Z dDd7Z!dEd8Z"dFd9Z#d: Z$d; Z%d< Z&d= Z'd> Z(d? Z)d@ Z*dGdAZ+y)H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indexNc                    |}t        j                  |      j                  d      }t        |      | _        t        j                  | j                        | _        	 | j                          y # t        $ r}||_         d }~ww xY w)Nr   )textwrapdedentr   r   _doccopydeepcopysections_parsed_data_parserI   rK   )r   rK   config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   )rp   )r   keys     r   r   zNumpyDocString.__getitem__   s      %%r   c                 l    || j                   vr| j                  d|z  d       y || j                   |<   y )NzUnknown section %sFerror)rp   _error_location)r   rv   vals      r   __setitem__zNumpyDocString.__setitem__   s9    d'''  !5!;5 I%(Dc"r   c                 ,    t        | j                        S r   )iterrp   r"   s    r   __iter__zNumpyDocString.__iter__   s    D%%&&r   c                 ,    t        | j                        S r   )r.   rp   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	                         }t        |      dk\  rot        |      dhdhfv r^t        |      t        |      k7  rGdj                  | j                   j                  d d	       d
z   }| j                  d|d|d|d       |j                  dt        |      z        xs |j                  dt        |      z        S )NF
.. index::Tr$      -=r      z...z'potentially wrong underline length... 
z 
z in 
rx   )rl   r+   r&   r@   r
   
startswithr.   setrB   r   rz   )r   l1l2snips       r   _is_at_sectionzNumpyDocString._is_at_section   s   		**,99==?YY^^##%==&YY^^A$$&r7a<SW#6CGs2w<N99TYY^^BQ/06D  $&D"29> ! @}}SR[)GR]]3s2w;-GGr   c                     d}d}t        |      D ]  \  }}|j                         s n t        |d d d         D ]  \  }}|j                         s n ||t        |      |z
   S )Nr   r   )	enumerater
   r.   )r   docijr2   s        r   _stripzNumpyDocString._strip   sj     ~GAtzz| & !TrT+GAtzz| , 1SXaZ  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%   )rl   r8   r   r&   r@   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$   r   )rl   r&   r   r
   r   r.   StopIterationr   )r   r   rR   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                    t        |      }t        |      }g }|j                         s|j                         j	                         }d|v r7|j                  dd      \  }}|j	                         |j	                         }}n|rd|}}n|d}}|j                         }t        |      }t        |      }|j                  t        |||             |j                         s|S )Nz :r$   )maxsplitr%   )
dedent_linesr   r&   r(   r
   r   r=   r   appendrQ   )	r   contentsingle_element_is_typerparamsheaderarg_namearg_typerT   s	            r   _parse_param_listz NumpyDocString._parse_param_list   s    w'7O%%'VVX^^%Fv~%+\\$\%C"(%-^^%5x~~7G())+VhH)/hH113D%D$T*DMM)Hh=> %%'" r   z:(?P<role>(py:)?\w+):z'`(?P<name>(?:~\w+\.)?[a-zA-Z0-9_\.-]+)`z(?P<name2>[a-zA-Z0-9_\.-]+)(|)rolerolenextrR   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                     t        |      }g } fd}g }|D ]g  j                         s j                  j                        }d}|rK|j	                  d      }|j	                  d      r)|r' j                  d|j                  d      fz  d       |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       T j                  d       j |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j                  d       |j                  d      }|r|j                  d      n|j                  d      }|||j	                         fS )zMatch ':role:`name`' or 'name'.Error parsing See Also entry r   rR   name2)	_func_rgxmatchrz   groupend)textmr   rR   r2   r   s       r   parse_item_namez7NumpyDocString._parse_see_also.<locals>.parse_item_name-  sj    $$T*A$$'DTH%MN776?D&*1776?0@Dquuw&&r   NrT   trailingzGUnexpected comma or period after function list at index %d of line "%s"Frx    allfuncsr   ,r$   r   )r   r
   	_line_rgxr   r   rz   r   r   r   r   filter)r   r   itemsr   rest
line_matchdescriptionfuncsr   rR   r   	match_endr2   s   `           @r   _parse_see_alsozNumpyDocString._parse_see_also   s    w'	' D::<--d3JK(..v6##J/K(($'1~~j'A4&HI# ) % 4??3#7DJJL)!''
3::<,;D,A)D$	LL$.	
+113DQ3#ABx~~/  F4+78eT]+$$'DTH%MN; < 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 )	zT
        .. 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_in]  s     '*+s!AGGIs+++s   z::r$   r   r   default:r   )r   r.   )r   r   r   r   r'   r2   s         r   _parse_indexzNumpyDocString._parse_indexW  s    	, --%w<!*71:+;+;C+@A!DC	ND::c?D4y1},T!W]]3-?@DG  
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\.]+\(.*\)$rW   rX   rY   )	r   rl   r8   rB   r
   recompiler   r   )r   summaryr   summary_strcompileds        r   _parse_summaryzNumpyDocString._parse_summaryj  s      ii779G((w#?w!AGGIw#?@FFHKzz"CDH~~k*$/[!**,%DO""$'+'A'A'CD#$ % $@s   Cc           	      B   | j                   j                          | j                          t        | j	                               }t        |D cg c]  \  }}|	 c}}      }d|v }d|v }|r|rd}t        |      |sd|v rd}t        |      |D ]  \  }}|j                  d      std |j                  d      D        }dj                  |      }| j                  |      r:| j                  d	|d
dj                  | j                   j                               |dv r| j                  |      | |<   |dv r| j                  |d      | |<   |j                  d      r| j                  ||      | d<   |dk(  r| j                  |      | d<   || |<   	 y c c}}w )Nr[   r\   z5Docstring contains both a Returns and Yields section.r]   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     F3Ea1<<>3Es   r   zThe section z appears twice in  r   )rZ   r`   ra   rb   )r[   r\   r^   r_   r]   T)r   r   rh   rc   )rl   r   r   r   r   r   
ValueErrorr   r   rB   getrz   r   r   r   r   )r   ro   r   r   section_nameshas_returns
has_yieldsmsgs           r   rq   zNumpyDocString._parse  s   		++-.XFX)9'WXFG=0.
:ICS/!jM9ICS/!"*Wg%%d+F7==3EF((7+88G$((,3TYYtyy~~5N*P Q  & & $ 6 6w ?WPP $ 6 6D !7 !:W##L1 $ 1 1'7 CWJ&#'#7#7#@Z  'W' #+ Gs   F
c                 d    t        | d      r| j                  S t        | d      r| j                  S y )N_cls_f)rN   r   r   r"   s    r   _objzNumpyDocString._obj  s,    4 99T4 77Nr   c                     | j                   I	 t        j                  | j                         }|d| j                   j                   z  }||rd| dndz  }|rt        |      t        |       y # t        $ r d }Y Ow xY w)Nz in the docstring of rL   .r%   )r   inspectgetsourcefile	TypeErrorrC   r   r   )r   r   ry   filenames       r   rz   zNumpyDocString._error_location  s    99  "00; *499+=+=*>??CT(1%r9CS/!I    s   A/ /A=<A=c                 "    |t        |      |z  gS r   )r.   )r   rR   symbols      r   _str_headerzNumpyDocString._str_header  s    c$i&''r   c                 8    |D cg c]
  }d|z  |z    c}S c c}w )Nr   rG   )r   r   indentr2   s       r   _str_indentzNumpyDocString._str_indent  s#    .12cdF
T!c222s   c                 F    | d   r| d   j                  dd      gdgz   S dgS )NrW   *z\*r%   )replacer"   s    r   _str_signaturezNumpyDocString._str_signature  s3    %--c59:bTAAtr   c                 "    | d   r	| d   dgz   S g S )NrX   r%   rG   r"   s    r   _str_summaryzNumpyDocString._str_summary  s    	?	?bT))	r   c                 "    | d   r	| d   dgz   S g S )NrY   r%   rG   r"   s    r   _str_extended_summaryz$NumpyDocString._str_extended_summary  s#    "#*+rd22	r   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 )Nz : r%   )r   rR   r   rS   rB   rT   r
   r   )r   rR   r'   parampartss        r   _str_param_listzNumpyDocString._str_param_list  s    :4##D))Cd::LL,::LL,

5)**::"''%**"5";";"=4++EJJ77C $ B4KC
r   c                 X    g }| |   r"|| j                  |      z  }|| |   z  }|dgz  }|S r?   )r   )r   rR   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g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  }|dgz  }|S )Nrc   r%   Tr   z:``z`%s`_, r   F)r   r   r   r   rB   r   empty_description)
r   	func_roler'   last_had_descr   rT   linksfuncr   links
             r   _str_see_alsozNumpyDocString._str_see_also  s$   JIt
++t
+KE4eT***E#
d)-t4D)2D9D"T>DT" $ 99U#DD6MCt''$(899 $ %t'')?)?(@AA% ,( B4KCt
r   c                     | d   }g }d}|j                  dd      }|rd}|d|z  gz  }|j                         D ](  \  }}|dk(  rd}|d|dd	j                  |      gz  }* |r|S y)
Nrh   Fr   r%   Tz.. index:: %sz   :z: r   )r   r   rB   )r   idxr'   output_indexdefault_indexr   
referencess          r   
_str_indexzNumpyDocString._str_index  s    7m	2.L-/00#&99;GZ)#LGTYYz-BCDDC	 $/
 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)rZ   r[   r\   r]   r`   r^   r_   re   )rd   rf   rg   )ra   rb   r   )r   r   r   r   r   r  r  rB   )r   r  r'   
param_listr   s        r   rP   zNumpyDocString.__str__  s    t""$$t  ""t))++BJ4''
33CB 	t  ,,t!!),,4A4$$Q''C 53J4''
33C 4t  yy~r   r   )F)T)r   )   )r%   ),rC   rD   rE   rF   ro   r   r   r|   r   r   r   r   r   r   r   _role_funcbacktick
_funcplain	_funcnamer   _funcnamenext_descriptionr   r   r   r   r   r   r   r   rq   propertyr   rz   r   r   r   r   r   r   r   r  r  rP   rG   r   r   rV   rV   v   sM   RB4 	B 	b	
 	2 	" 	B 	" 	 	B 	b 	2 	B 	 	B  	b!" 	B#$ 	%H*&)'&H$!	
2N %E>M/Ju},t3j@4GI%%fj9M!))&*=MEL

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

		 	!	! $1	1 4:	: 			 	 	  		I 5n&D,$(L   (3


 @"r   rV   c                 h    t        j                  dj                  |             j                  d      S )z"Deindent a list of lines maximallyr   )rj   rk   rB   r   )liness    r   r   r   .  s%    ??499U+,22488r   c                   ,     e Zd ZddZd Z fdZ xZS )FunctionDocc                     || _         || _        |&|t        d      t        j                  |      xs d}|i }t
        j                  | ||       y )NzNo function or docstring givenr%   )r   r  r   r   getdocrV   r   )r   r  r   r   rr   s        r   r   zFunctionDoc.__init__4  sU    
;| !ABB..&,"C>Fc62r   c                    t        | j                  d| j                  j                        }t	        j
                  | j                        r/t        | j                  d| j                  j                        }||fS | j                  }||fS )NrC   __call__)getattrr   	__class__rC   r   isclassr   )r   	func_namer  s      r   get_funczFunctionDoc.get_func@  sk    DGGZ1H1HI	??477#477J0@0@AD Y 77DYr   c                 &   d}| j                         \  }}ddd}| j                  rL| j                  |vrt        d| j                  z         |d|j                  | j                  d      d|dz  }|t        |   | j                  	      z  }|S )
Nr%   functionmethod)r  methzWarning: invalid role %sz.. z:: z
    

)r  )r#  r  printr   superrP   )r   r'   r  r"  rolesr   s        r   rP   zFunctionDoc.__str__H  s    --/i#!# ::zz&04::=>UYYtzz2-F-68 8C 	uw44
r   )r  NN)rC   rD   rE   r   r#  rP   __classcell__)r   s   @r   r  r  3  s    
3 r   r  c                       e Zd ZddZy)ObjDocNc                 J    || _         |i }t        j                  | ||       y )Nrr   )r   rV   r   )r   objr   rr   s       r   r   zObjDoc.__init__[  s(    >Fc&9r   )NN)rC   rD   rE   r   rG   r   r   r-  r-  Z  s    :r   r-  c                   H    e Zd ZdgZddedfdZed        Zed        Zd Z	y)ClassDocr  Nr%   c                 b   t        j                  |      s|t        d|z        || _        dt        j
                  v rddlm} n
t               }|i }|j                  dd      | _
        |r|j                  d      s|dz  }|| _        |"|t        d      t        j                  |      }t        j!                  | |       |j                  d	g       }||u rd }|j                  d
g       }|j                  dd      r||urd }	d| j"                  fd| j$                  ffD ]y  \  }
}| |
   rg }t'        |      D ]Y  }||v s|r||vr	 t        j                  t)        | j                  |            }|j+                  t-        |d |	|                   [ || |
<   { y y y # t.        $ r Y qw xY w)Nz$Expected a class or None, but got %rsphinxr   )ALLshow_inherited_class_membersTr   z&No class or documentation string givenmemberszexclude-membersshow_class_membersc                 *    | sg S | j                         S r   )
splitlines)r   s    r   splitlines_xz'ClassDoc.__init__.<locals>.splitlines_x  s    I<<>)r   rb   ra   r%   )r   r!  r   r   sysmodulessphinx.ext.autodocr5  objectr   show_inherited_membersendswith_modpydocr  rV   r   methods
propertiessortedr  r   rQ   AttributeError)r   clsr   
modulenamefunc_docrr   r5  _members_excluder;  fieldr   doc_listrR   doc_items                  r   r   zClassDoc.__init__f  s   s#CcIJJ	s{{".(C>F&,jj*D'2# j11#6#J	;{ !IJJ,,s#Cc*::i,s?H::/4::*D1hc6I*
 #,T\\!:".!@!BuE{!H &u H,!)d(.B$!',||GDIIt4L'MH$OO )$L4J KM !. #+DK!B 7J1$  . ! !s   AF""	F.-F.c                    | j                   g S t        j                  | j                         D cg c]G  \  }}|j                  d      r|| j                  v r#t        |t              r| j                  |      r|I c}}S c c}}w N_)r   r   
getmembersr   extra_public_methodsr   r   _is_show_memberr   rR   r  s      r   rD  zClassDoc.methods  s{    99I'.'9'9$))'D 1'Dt-T666tX.((.	 'D 1 	1 1s   ABc                     | j                   g S t        j                  | j                         D cg c]P  \  }}|j                  d      s:|%t	        |t
              st        j                  |      r| j                  |      r|R c}}S c c}}w rQ  )r   r   rS  r   r   r  isdatadescriptorrU  rV  s      r   rE  zClassDoc.properties  s    99I'.'9'9$))'D 1'Dt,\Zh%?--d3((.	 'D 1 	1 1s   AB
c                 P    | j                   ry|| j                  j                  vryy)NTF)r@  r   __dict__)r   rR   s     r   rU  zClassDoc._is_show_member  s&    &&tyy)))r   )
rC   rD   rE   rT  r  r   r  rD  rE  rU  rG   r   r   r2  r2  b  sG    &< $k4+l 1 1 1 1r   r2  c                 6   |Et        j                  |       rd}n-t        j                  |       rd}nt        | t              rd}nd}|i }|dk(  rt        | t        ||      S |dv rt        | ||      S |t        j                  |       }t        | ||      S )	Nclassmoduler%  r?  )rJ  r   rr   )r%  r&  )r   rr   r/  )
r   r!  ismoduler   r   r2  r  rC  r  r-  )r0  whatr   rr   s       r   get_doc_objectr`    s    |??3Dc"DX&DD~wks6JJ	'	'3C77;,,s#Cc3v..r   )NNN)rF   r   rj   r   rC  warningsr   collectionsr   collections.abcr   r   rm   r<  r   r   	ExceptionrI   rQ   rV   r   r  r-  r2  r`  rG   r   r   <module>re     s      	   " -  
J. J.Z  {$<=	uW up9
$. $N:^ :S~ Sl/r   