L i\$dZddlZddlZddlZddlZddlZddlZddlmZddl m Z m Z ddl m Z ddlmZdZGdd ZGd d eZed gd ZGdde ZdZGddeZGddeZGddeZdddeeefdZy)z;Extract reference documentation from the NumPy source tree.N) namedtuple)CallableMapping)cached_property)warnc|r,|djs|d=|r|djs|r,|djs|d=|r|djs|S)z.is_emptyPszz|# #r)r,r4)rr8s r read_to_next_empty_linezReader.read_to_next_empty_lineMs& %%' $%%h//rc*d}|j|S)Ncp|jxr%t|jt|k(Sr)r r/lstripr7s r is_unindentedz:Reader.read_to_next_unindented_line..is_unindentedVs'::<ES%73t9%D Er)r4)rr=s r read_to_next_unindented_linez#Reader.read_to_next_unindented_lineUs F%%m44rcr|j|zt|jkr||j|zSyNr&r.rs r peekz Reader.peek[s0 77Q;TYY '! $ $rcVdj|jj Sr@)joinrr r#s r r8zReader.is_emptyas!77499%++---rN)r)__name__ __module__ __qualname____doc__rr rr)r,r'r4r9r>rAr8rr rrs<% )05  .rrceZdZdZy) ParseErrorc^|jd}t|dr|d|j}|S)Nr docstring in )argshasattrrL)rmessages r __str__zParseError.__str__fs3))A, 4 % dnn%78GrN)rDrErFrQrHrr rJrJesrrJ Parameter)nametypedescc2eZdZdZiddddgdgdgdgdgd gd gd gd gd gdgdgdgdgdddddiiZdBdZdZdZdZdZ dZ dZ dZ dZ dCdZd Zd!Zd"Zd#ezezd$zezd%zZej'd&d'Zej'd(d)Zd*Zej.d+ezd,zZej.d-ezd.zezd/zd%zd0zezZd1Zd2Zd3Zd4Zd5Zed6Z dDd7Z!dEd8Z"dFd9Z#d:Z$d;Z%d<Z&d=Z'd>Z(d?Z)d@Z*dGdAZ+y)HNumpyDocStringzParses a numpydoc string to an abstract representation Instances define a mapping from section title to structured data. Signaturer&SummaryExtended Summary Parameters AttributesMethodsReturnsYieldsReceivesOther ParametersRaisesWarnsWarningsSee AlsoNotes ReferencesExamplesindexNc |}tj|jd}t||_t j |j|_ |jy#t$r }||_ d}~wwxYw)Nr) textwrapdedentrr_doccopydeepcopysections _parsed_data_parserJrL)rrLconfigorig_docstringes r rzNumpyDocString.__init__si"OOI.44T: 9%  MM$--8  KKM (AK  sA-- B6A>>Bc |j|Sr)rq)rkeys r r zNumpyDocString.__getitem__s  %%rcl||jvr|jd|dy||j|<y)NzUnknown section Ferror)rq_error_location)rrwvals r __setitem__zNumpyDocString.__setitem__s; d'' '  #3C5!9 G%(D  c "rc,t|jSr)iterrqr#s r __iter__zNumpyDocString.__iter__sD%%&&rc,t|jSr)r/rqr#s r __len__zNumpyDocString.__len__s4$$%%rc|jj|jjry|jjj }|j dry|jjdj }t |dk\rot|dhdhfvr^t |t |k7rGdj|jjdd d z}|jd |d |d |d|j dt |zxs|j dt |zS)NF .. index::Tr%-=rz...z'potentially wrong underline length... z z in ry) rmr,r'rAr startswithr/setrCrr{)rl1l2snips r _is_at_sectionzNumpyDocString._is_at_sections **, 99==? YY^^  # # % == & YY^^A  $ $ & r7a>"%++-B4 tyy88: :G %%'  rc#RK|jjs|j}|dj}|j dr ||ddfn/t |dkr t n||j|ddf|jjsyyw)Nr..r%r)rmr'rr rr/ StopIterationr)rrrSs r _read_sectionszNumpyDocString._read_sectionss))--/--/D7==?Dt$DHn$TQ##DKKQR111))--/s B"B'%B'ct|}t|}g}|js|jj }d|vr|j dd\}}n!|j dr|dd}|rd|}}n|d}}|j}t|}t|}|jt||||js|S)N : r%)maxsplitz :r&) dedent_linesrr'r)r rendswithr>rappendrR) rcontentsingle_element_is_typerparamsheaderarg_namearg_typerUs r _parse_param_listz NumpyDocString._parse_param_listsw' 7O%%'VVX^^%F%+\\%!\%D"( ??4(#CR[F))+VhH)/hH113D%D$T*D MM)Hh= >'%%'* rz:(?P(py:)?\w+):z'`(?P(?:~\w+\.)?[a-zA-Z0-9_\.-]+)`z(?P[a-zA-Z0-9_\.-]+)(|)rolerolenextrSnamenextz/(?P\s*:(\s+(?P\S+.*))?)?\s*$z^\s*z\s*z^\s*(?Pz(?P([,]\s+z)*)z(?P[,\.])?rc t|}g} fd}g}|D]g jsjj }d}|rK|j d}|j dr)|r'j d|j d fzd|s1 jdr |j j|rg}|j d } |jsnP||\} } } |j| | f|| dj}|r|d d k(r|d dj}attd|g}|j||fTj d j|S)z func_name : Descriptive text continued text another_func_name : Descriptive text func_name1, func_name2, :meth:`func_name`, func_name3 cjj|}|sjd|jd}|r|jdn|jd}|||j fS)zMatch ':role:`name`' or 'name'.Error parsing See Also entry rrSname2) _func_rgxmatchr{groupend)textmrrSr3rs r parse_item_namez7NumpyDocString._parse_see_also..parse_item_name/sj$$T*A$$'DTH%MN776?D&*1776?0@Dquuw& &rNrUtrailingzGUnexpected comma or period after function list at index %d of line "%s"Fry allfuncsr,r%r) rr _line_rgxrrr{rrrrfilter) rritemsrrest line_match descriptionfuncsrrSr match_endr3s ` @r _parse_see_alsozNumpyDocString._parse_see_also"sw' ' OD::<--d3JK(..v6 ##J/K(($'1~~j'A4&HI#) 4??3#7 DJJL)!'' 3::<,;D,A)D$ LL$. +113DQ3#ABx~~/F4+78 eT]+$$'DTH%MN= O> rcd}i}|jd}t|dkDr ||djdd|d<|D]B}|jd}t|dkDs#||djd||d<D|S) zU .. index:: default :refguide: something, else, and more cH|Dcgc]}|jc}Scc}wrr )lstss r strip_each_inz2NumpyDocString._parse_index..strip_each_inas'*+!AGGI+ ++sz::r%rrdefault:r)rr/)rrrrr(r3s r _parse_indexzNumpyDocString._parse_indexZs ,--% wz(NumpyDocString._parse..sFa1<<>Fsrz The section z appears twice in r)r[rar\r])r^r_rbrcr`T)rrrire)rmrrrr ValueErrorrrrCgetr{rrrr)rrprr section_names has_yieldsmsgs r rrzNumpyDocString._parsesz  ++-.9AB%5WgB B. jM9ICS/ ! ( ( GW%%d+F7==3EF((7+88G$(("DIIdiinn$=? UU $ 6 6w ?W PP $ 6 6D!7!W ##L1 $ 1 1'7 CW J&#'#7#7#@Z 'W + (Cs E<cdt|dr |jSt|dr |jSy)N_cls_f)rOrrr#s r _objzNumpyDocString._objs, 4 99  T4 77NrcV|jr tj|j}t |jdd}|"t t |jdddd}||d|z }||rd|dndz }|r t |t |dy#t$rd}YzwxYw) NrD __class__z in the docstring of rM.r&r) stacklevel)rinspect getsourcefile TypeErrorgetattrrr)rrrzfilenamerSs r r{zNumpyDocString._error_locations 99  "00; 499j$7D|wtyy+tDjRVW.tf55 T(1%r 9C S/ !  #  sB B('B(c"|t||zgSr)r/)rrSsymbols r _str_headerzNumpyDocString._str_headersc$i&())rc8|Dcgc] }d|z|z c}Scc}w)NrrH)rrindentr3s r _str_indentzNumpyDocString._str_indents034f t#444scF|dr|djddgdgzSdgS)NrX*z\*r&)replacer#s r _str_signaturezNumpyDocString._str_signatures3  %--c59:bTA At rc"|dr |ddgzSgS)NrYr&rHr#s r _str_summaryzNumpyDocString._str_summarys  ? ?bT) ) rc"|dr |ddgzSgS)NrZr&rHr#s r _str_extended_summaryz$NumpyDocString._str_extended_summarys# " #*+rd2 2 rcg}||r||j|z }||D]}g}|jr|j|j|jr|j|j|dj |gz }|j sudj |j j s||j|j z }|dgz }|S)Nrr&)rrSrrTrCrUr r)rrSr(parampartss r _str_param_listzNumpyDocString._str_param_lists : 4##D) )Cd 8::LL,::LL, 5)**::"''%**"5";";"=4++EJJ77C 8 B4KC rcXg}||r"||j|z }|||z }|dgz }|Sr@)r)rrSr(s r _str_sectionzNumpyDocString._str_sectionsA : 4##D) )C 4: C B4KC rc|dsgSg}||jdz }|dgz }d}|dD]\}}t|tsJg}|D]4\}}|r d|d|d} n|r d|d|d} nd|d} |j| 6dj |} || gz }|r'||j d j |gz }d}d }||j |j gz }|r|dgz }|dgz }|S) Nrer&Trz:``z`_, rF)rrrrrCrempty_description) r func_roler( last_had_descrrUlinksfuncrlinks r _str_see_alsozNumpyDocString._str_see_alsosHJI t ++ t   + BKE4eT* **E# # dtfBtfA.DykD63DtfB >C  ? Jrcg}||jz }||jz }||jz }||jdz }dD]}||j|z }dD]}||j|z }||j dz }||j |z }dD]}||j |z }||j z }dj|S)Nr[)r\r])r^r_r`rarbrcrd)rfrgrhr)rrrrrr rrC)rrr( param_listrs r rQzNumpyDocString.__str__$s t""$$ t  "" t))++ t##L113 4J 4'' 3 3C 4  4J 4'' 3 3C 4 t  ,, t!!),,4 (A 4$$Q' 'C ( t  yy~rr)F)T)r))r&),rDrErFrGrprr r}rrrrrrr_role _funcbacktick _funcplain _funcnamer _funcnamenext _descriptionrrrrrrrrrrpropertyrr{rrrrrrrr rrQrHrr rWrWpsM RB4 B b  b  2  2 " B B "  B B  b!" B#$ %H* &) '&L( %  2V %E>M/Ju },t3j@4GI%%fj9M!))&*=MEL 7Y.78I     # #          " "   I6p(D,"(H$,*5    @"rrWchtjdj|jdS)z"Deindent a list of lines maximallyr)rkrlrCr)liness r rr=s% ??499U+ , 2 24 88rc,eZdZddZdZfdZxZS) FunctionDocc||_||_|&| tdtj|xsd}|i}t j |||y)NzNo function or docstring givenr&)rrrrgetdocrWr)rr rrrss r rzFunctionDoc.__init__CsU ;| !ABB..&,"C >Fc62rct|jd|jj}t j |jr/t|jd|jj }||fS|j}||fS)NrD__call__)rrrrDrisclassr)r func_namer s r get_funczFunctionDoc.get_funcOskDGGZ1H1HI ??477 #477J0@0@ADY77DYrc&d}|j\}}ddd}|jrL|j|vrtd|j|d|j|jdd|dz }|t||j z }|S) Nr&functionmethod)r methzWarning: invalid role z.. z:: z )r)r'rprintrsuperrQ)rr(r r&rolesrs r rQzFunctionDoc.__str__Ws--/i#X6 ::zz&.tzzl;< S4::r233ykL LC uw44 r)r NN)rDrErFrr'rQ __classcell__)rs@r r r Bs 3  rr ceZdZddZy)ObjDocNcJ||_|i}tj|||y)Nrs)rrWr)robjrrss r rzObjDoc.__init__hs( >Fc&9r)NN)rDrErFrrHrr r1r1gs:rr1cXeZdZdgZddedfdZedZedZe dZ dZ y) ClassDocr$Nr&c btj|s|td|||_dtj vrddlm}n t}|i}|jdd|_ |r|jds|dz }||_ |"| tdtj|}tj!|||jd g}||urd}|jd g}|jd dr||urd } d |j"fd|j$ffD]y\} } || r g} t'| D]Y} | |vs|r| |vr tjt)|j| }| j+t-| d| |[| || <{yyy#t.$rYqwxYw)Nz"Expected a class or None, but got sphinxr)ALLshow_inherited_class_membersTrz&No class or documentation string givenmemberszexclude-membersshow_class_membersc*|sgS|jSr) splitlines)rs r splitlines_xz'ClassDoc.__init__..splitlines_xsI<<>)rr]r\r&)rr%rrsysmodulessphinx.ext.autodocr9objectrshow_inherited_membersr_modpydocr"rWrmethods propertiessortedrrrRAttributeError)rclsr modulenamefunc_docrsr9_members_excluder?fieldrdoc_listrSdoc_items r rzClassDoc.__init__rss#A#IJ J s{{ " .(C >F&,jj1OQU&V# j11#6 # J ;{ !IJJ,,s#Cc*::i, s?H::/4 ::*D 1hc6I *DLL)t/! + uE{!H &u !8+T=Q$!',||GDIIt4L'MH$OOIdB X@V,WX !#+DK +7J 1( .! !s A F"" F.-F.c|jgStj|jDcgc]G\}}|jdr||jvr#t |t r|j|r|Ic}}Scc}}wN_)rr getmembersrextra_public_methodsrr_is_show_memberrrSr s r rGzClassDoc.methodssw 99 I&00; d__S)TT5N5N-NtX.((.    sA Bc f|jgStj|jDcgc]s\}}|jds]|j ||jsA|,t |t tzstj|r|j|r|uc}}Scc}}wrT) rrrVr_should_skip_memberrrrisdatadescriptorrXrYs r rHzClassDoc.propertiess 99 I&00;  dOOC(00tyyAL!$?(BC//5((.    sA8B-czt|txr*t|dxrt|dxr||jvS)N_asdict_fields) issubclasstuplerOr_)rSklasss r r[zClassDoc._should_skip_membersD ue $ &y) &y) & %  rcN|jxs||jjvSr)rDr__dict__)rrSs r rXzClassDoc._is_show_members)  ' ' *tyy)))  r) rDrErFrWr rrrGrH staticmethodr[rXrHrr r6r6os[&< $kRV4+l      $   rr6c|Etj|rd}n-tj|rd}nt|trd}nd}|i}|dk(r |||||S|dvr ||||S|t j |}||||S) Nclassmoduler)rC)rMrrs)r)r*)rrsr3)rr%ismodulerrrFr")r4whatrrs class_docrMobj_docs r get_doc_objectrms | ??3 D   c "D X &DD ~ wxSHH ' 'V44 ;,,s#CsC//r)rGrnrrFrr@rk collectionsrcollections.abcrr functoolsrwarningsrrr ExceptionrJrRrWrr r1r6rmrHrr rssA  "-% I.I.X {$< = JWJZ9 "."J:^:k ~k `    0r