-Ph_GUdZddlmZddlZddlmZmZddlmZddl m Z ddl m Z ddl mZdd lmZervdd lmZmZdd lmZmZdd lmZdd lmZddlmZddlmZedZee e!efZ"de#d<e$e e!efZ%de#d<ede"e!e"zefZ&de#d<ej'e(Z)d"dZ*GddZ+Gdde+Z,Gdde,Z-Gd d!Z.dS)#zUtility code for "Doc fields". "Doc fields" are reST field lists in object descriptions that will be domain-specifically transformed to a more appealing presentation. ) annotationsN) TYPE_CHECKINGcast)nodes)addnodes)__)logging) get_node_line) TypeAliasTypeVar)ElementNode)Inliner)ObjectDescription)BuildEnvironment) TextlikeNodeObjDescTr _FieldEntry _FieldTypesField_EntriesTriplenodenodes.field_bodyreturnboolct|dkrdSt|dkr*|ddD]}t|tjsdS t|dtjS)zCTrue if the node only contains one paragraph (and system messages).rFN)len isinstancersystem_message paragraph)rsubnodes U/var/www/html/test/jupyter/venv/lib/python3.11/site-packages/sphinx/util/docfields.py_is_single_paragraphr$%ss 4yyA~~u TQABBx  Ggu';<< uu  d1gu / //ceZdZdZdZdZ d,d-dZejddddfd.d Z ejddddfd/d"Z d0d&Z d1d2d+Z dS)3raA doc field that is never grouped. It can have an argument or not, the argument can be linked using a specified *rolename*. Field should be used for doc fields that usually don't occur more than once. The body can be linked using a specified *bodyrolename* if the content is just a single inline or text node. Example:: :returns: description of the return value :rtype: description of the return type FTnamestrnamestuple[str, ...]labelhas_argrrolename bodyrolenamerNonecZ||_||_||_||_||_||_dSN)r)r+r-r.r/r0)selfr)r+r-r.r/r0s r#__init__zField.__init__As5      (r%Ndomaintarget innernodetype[TextlikeNode]contnode Node | NoneenvBuildEnvironment | NoneinlinerInliner | NonelocationElement | Nonerc |J|du|duks J||f|s|p |||S|||} | || <|:td} tt| |||t jd|d||} | |p |||z } ||| | Sd} |@tj t5t|} dddn #1swxYwY| |||| |ig\} }tj |dg| RS)Nz]Problem in %s domain: field is supposed to use role '%s', but that role is not in the domain.)r@r(F) refdomain refexplicitreftype reftarget) get_domainrolerloggerwarningr pending_xrefprocess_field_xref contextlibsuppress ValueErrorr rinline)r4r/r6r7r8r:r<r>r@rImsgrefnodelinenonsmessagess r# make_xrefzField.make_xrefQs4X%5666(8K666 98yy88 8~~f%%**844 <7?| 3Lr#ww8LLL+ !  G x<99VV#<#< > >N  $Z00 1 1&x00 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1tHfffgr2NN H|FB,,,,,sD""D&)D& list[Node]c <|||||||||gSr3)rW) r4r/r6r7r8r:r<r>r@s r# make_xrefszField.make_xrefs|s0 NN&&)XsGX    r%fieldargcontentrc ||fSr3r')r4r[r\s r# make_entryzField.make_entrys   r%typesritem nodes.fieldc |\}}tjd|j} |rU| tjdz } | ||j||tj|||t|dkrt|dtjs_t|dtj r~t|ddkret|ddtjr?||j ||d |d|||}tj dtj ddg|R} tjd| | S)Nr( r<r>r@rr)r:r<r>r@)r field_namer-TextextendrZr/rrrQr0astext field_bodyr!field) r4r_r6r`r<r>r@r[r\ fieldname fieldbodys r# make_fieldzField.make_fields}!'$R44   C (I   MJ#%     w<<1   wqz5: . . 71:u|44  OOq((wqz!}ej99)oo! !!## !&G$RR)J')J)J)JKK {2y)444r%)r'r(Tr(r()r)r*r+r,r-r*r.rr/r*r0r*rr1)r/r*r6r*r7r*r8r9r:r;r<r=r>r?r@rArr)r/r*r6r*r7r*r8r9r:r;r<r=r>r?r@rArrX)r[r*r\rXrrNNN)r_rr6r*r`rr<r=r>r?r@rArra) __name__ __module__ __qualname____doc__ is_groupedis_typedr5rliteral_emphasisrWrZr^rmr'r%r#rr0s  JH "$)))))*)1(A $'+"&#')-)-)-)-)-`)1(A $'+"&#'     "!!!!(,"&#'+5+5+5+5+5+5+5r%cPeZdZdZdZejZ dd fd Z d!d"dZ xZ S)# GroupedFieldaA doc field that is grouped; i.e., all fields of that type will be transformed into one field with its body being a bulleted list. It always has an argument. The argument can be linked using the given *rolename*. GroupedField should be used for doc fields that can occur more than once. If *can_collapse* is true, this field will revert to a Field if only used once. Example:: :raises ErrorClass: description when it is raised Tr'r(Fr)r*r+r,r-r/ can_collapserrr1c`t|||d|||_dS)NT)superr5rx)r4r)r+r-r/rx __class__s r#r5zGroupedField.__init__s3 ueT8<<<(r%Nr_rr6itemslist[_FieldEntry]r<r=r>r?r@rArac tjd|j}|}|D]\} } tj} | ||j|| tj |||| tj dz } | | z } |tj d| z }t|dkrN|j rGtd|d} tjd| d} tjd|| Stjd|} tjd|| S)Nr(rd -- rznodes.list_itemr)rrer- list_typer!rgrZr/rliteral_strongrf list_itemrrxrrirj)r4r_r6r|r<r>r@rklistnoder[r\parrrls r#rmzGroupedField.make_fields?$R44 >>##!& 1 1 Hg/##C JJM+#%     5:f%% %C 7NC C00 0HH u::??t0?. <r?r@rArra) rorprqrrrsr bullet_listrr5rm __classcell__r{s@r#rwrws  J!I "$" ) ) ) ) ) ) ) (,"&#'"5"5"5"5"5"5"5"5"5r%rwcFeZdZdZdZ d!d"fd Z d#d$d ZxZS)% TypedFielda\A doc field that is grouped and has type information for the arguments. It always has an argument. The argument can be linked using the given *rolename*, the type using the given *typerolename*. Two uses are possible: either parameter and type description are given separately, using a field from *names* and one from *typenames*, respectively, or both are given using a field from *names*, see the example. Example:: :param foo: description of parameter foo :type foo: SomeClass -- or -- :param SomeClass foo: description of parameter foo Tr'r(Fr)r*r+r, typenamesr-r/ typerolenamerxrrr1cnt|||||||_||_dSr3)rzr5rr) r4r)r+rr-r/rrxr{s r#r5zTypedField.__init__s: ueX|DDD"(r%Nr_rr6r|r}r<r=r>r?r@rArac d fd }tjdj}t|d krjr|d \} } || | } n>} |D]'\} } | tjd|| | z } (tjd| } tjd|| S) Nr[r*r\rXrnodes.paragraphc tj}|  j|t j| vr|tjdz } |}t|dkryt|dtjrY|d }|  j |t j  n||z }|tjdz }td|D}|r|tjdz }||z }|S) N)r<z (rrrd)c3bK|]*}|V+dSr3)rhstrip).0cs r# z=TypedField.make_field..handle_item..Gs6BBQahhjj..00BBBBBBr%r)rr!rgrZr/rrrfpoprrrhrruany) r[r\r fieldtypetypename has_contentr6r<r>r@r4r_s r# handle_itemz*TypedField.make_field..handle_item*sl/##C JJM68X5LRU     5  uz$'''"IIh// y>>Q&&:ilEJ+O+O&(|2244HJJ -"$$5 #$+%-(    9$Cuz#&BB'BBBBBK uz&)))wJr%r(rr)r[r*r\rXrr) rrer-rrxrrrirj) r4r_r6r|r<r>r@rrkr[r\bodynoderls ``` ``` r#rmzTypedField.make_field!s! ! ! ! ! ! ! ! ! ! ! F$R44 u::??t0? %a Hg([7;;HH~~''H%* P P!'EOB Hg0N0NOOO$R22 {2y)444r%)r'r'r(r(r(F)r)r*r+r,rr,r-r*r/r*rr*rxrrr1rnr)rorprqrrrtr5rmrrs@r#rrs$H "$%'" ) ) ) ) ) ) )&(,"&#'555555555555555555r%rcFeZdZUdZded<ddZdd Zdd ZddZddZ dS)DocFieldTransformerzTransforms field lists in "doc field" syntax into better-looking equivalents, using the field type definitions given on a domain. zdict[str, tuple[Field, bool]]typemap directiveObjectDescription[ObjDescT]rr1cF||_||_dSr3)rget_field_type_mapr)r4rs r#r5zDocFieldTransformer.__init__`s " 3355 r%raddnodes.desc_contentcn|D]1}t|tjr||2dS)z,Transform all field list children of a node.N)rr field_list transform)r4rchilds r# transform_allz!DocFieldTransformer.transform_allesE & &E%!122 &u%%% & &r%nodes.field_listcg}i}i}td|D]}||||||||}||dS)z%Transform a single field list *node*.zlist[nodes.field]N)r_transform_step_1_transform_step_2 replace_self)r4rentries groupindicesr_rjnew_lists r#rzDocFieldTransformer.transformls{68') (*-t44 H HE  " "5'5, G G G G))'599 (#####r%rjrar"list[nodes.field | _EntriesTriple]r_dict[str, _FieldTypes] group_indicesdict[str, int]c2t|dksJtd|d}td|d} |dd\}}n&#t$r|d}}YnwxYw|j|d\} } t|rtd|d} | j} n|j} | | j t|kry|dd |ddz} |r| d |zz } tj | |d<||| r| r| rt| dkrt| dtj rtd | }| d}||j|jjpd|| d|jj }t|r@td|d} | | |n*||tjddg|Rz }dS| j}| r)d | D} | r| ||i|<dS| jrY |dd\}}tj |g||i|<|}n#t$rYnwxYwtj|jd }|jj|_|jj |_ |jj!|_!|| z }| j"r||vrtd|||}n,t|||<| g|f}||| #||g}|d|dS| #||g}|| ||fdS)Nznodes.field_namerrrr()NNrrcr)r:r<c`g|]+}t|tjtjz)|,Sr')rrInlinerf)rns r# z9DocFieldTransformer._transform_step_1..s0VVVQZ5<%*;T-U-UVqVVVr%T) translatablez%tuple[Field, list[_FieldEntry], Node])$rrrhsplitrPrgetr$childrenr.rupperrrfappendrrZrrr6r<clearrgr!r) setdefaultrtrsplitrQ rawsourceparentdocumentsourcelinersr^)r4rjrr_rrerifieldtype_namer[typedesc is_typefieldr!r\ new_fieldname typed_fieldr7xrefsrargtypeargnametranslatable_contentgroup new_entrys r#rz%DocFieldTransformer._transform_step_1ys5zzQ,eAh77 ,eAh77  ?'1'8'8':':'@'@q'I'I $NHH ? ? ?'1'8'8':':BHNNN ?"&!1!1.,!O!O, + + *. 1 >>I(GG )G  x/4>>AA+1Q3/5577.:LLM 0x/ !J}55JqM NN5 ! ! ! B  B BLLA%%wqz5:66&#<::  **,,#..,N)/R$QZ* /( 33B $%6 1 F FIOO%%%$$U++++$$&&&%/"b"A5"A"A"AAJ F=  WV'VVVG C;B  2..x8 F   # ##+??4#;#; #$.$5$:!'   9=((;M(34 +.g,, h'!2u-u%%% ++H7K6LMMI !HOOI & & & & & ++H7K6LMMI NNHi7 8 8 8 8 8s$+A// BB5K== L  L c Jtj}|D]}t|tjr||z }"|\}}}||ji}|jj} |jjj } |jj pd} || || || | |z }|S)Nr(rd) rrrrjrr)rr<stater>r6rm) r4rr_rentryrr|r@ fieldtypesr<r>r6s r#rz%DocFieldTransformer._transform_step_2s #%%  E%-- E!-2* 5("YYy~r:: n(..6.4"I00#% 1r%N)rrrr1)rrrr1)rrrr1) rjrarrr_rrrrr1)rrr_rrr) rorprqrr__annotations__r5rrrrr'r%r#rrYs+***6666 &&&& $ $ $ $i9i9i9i9Vr%r)rrrr)/rr __future__rrNtypingrrdocutilsrsphinxr sphinx.localer sphinx.utilr sphinx.util.nodesr r r docutils.nodesr rdocutils.parsers.rst.statesrsphinx.directivesrsphinx.environmentrsphinx.util.typingrrtupler*listrrdictrr getLoggerrorJr$rrwrrr'r%r#rs #"""""&&&&&&&&++++++ Y)))))))),,,,,,,,333333333333333333//////wz""H"3T ?3K3333!#tDz/2K2222 %g{T+=N/NPW&W XNXXXX  8 $ $0000K5K5K5K5K5K5K5K5\=5=5=5=5=55=5=5=5@X5X5X5X5X5X5X5X5veeeeeeeeeer%