}c?HdZddlmZmZmZmZmZmZmZm Z ddl m Z ddl m Z ddlmZddlmZddlmZddlmZdd lmZdd lmZerdd lmZejeZd e jd e fdZ!GddZ"Gdde"Z#Gdde#Z$GddZ%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. ) TYPE_CHECKINGAnyDictListTupleTypeUnioncast)nodes)Node)Inliner)addnodes)BuildEnvironment)__)logging) TextlikeNode)ObjectDescriptionnodereturnct|dkrdSt|dkr*|ddD]}t|tjsdS t|dtjrdSdS)zCTrue if the node only contains one paragraph (and system messages).rFNT)len isinstancer system_message paragraph)rsubnodes 5lib/python3.11/site-packages/sphinx/util/docfields.py_is_single_paragraphrs 4yyA~u TQABBx  Ggu';<< uu $q'5?++t 5ceZdZdZdZdZ ddedeedfd ed ed ed ed dfdZ e j ddddfd ededede e dedededed efdZe j ddddfd ededede e dedededed eefdZdedeed eeeeffdZ ddeeeefdededededed ejfdZdS) FieldaA 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 FNTnamenames.labelhas_argrolename bodyrolenamercZ||_||_||_||_||_||_dSN)r#r$r%r&r'r()selfr#r$r%r&r'r(s r__init__zField.__init__5s3      (rdomaintarget innernodecontnodeenvinlinerlocationc T|J|du|duks J||f|s|p |||S|||} | || <|:td} tt| |||t jd|d||} | |p |||z } ||| | Stj |d} | |||| |ig\} }tj |dg| RS)Nz]Problem in %s domain: field is supposed to use role '%s', but that role is not in the domain.)r3F) refdomain refexplicitreftype reftargetr) get_domainrolerloggerwarningr pending_xrefprocess_field_xrefrget_source_liner inline)r+r'r-r.r/r0r1r2r3r;msgrefnodelinenonsmessagess r make_xrefzField.make_xref>s 4X%56KK(8KKKK 98yy88 8~~f%%**844  7  M MQRRr#ww8LLL+B&e4<PPPG x<99VV#<#< > >N(2215tHfffgr2NN H|FB,,,,,rc <|||||||||gSr*)rG) r+r'r-r.r/r0r1r2r3s r make_xrefszField.make_xrefsXs0xH"GX778 8rfieldargcontentc ||fSr*r")r+rJrKs r make_entryzField.make_entry_s '""rtypesitemc |\}}tjd|j} |rU| tjdz } | ||j||tj|||t|dkrt|dtjs_t|dtj r~t|ddkret|ddtjr?||j ||d |d|||}tj dtj ddg|R} tjd| | S)Nr5 r1r2r3rr)r0r1r2r3)r field_namer%TextextendrIr'rrrAr(astext field_bodyrfield) r+rNr-rOr1r2r3rJrK fieldname fieldbodys r make_fieldzField.make_fieldbs!'$R44  [ C (I   T__T]F-5uz14gPX-ZZ [ [ [ w<<1  S71:uz22 SGAJ 55 S:=gaj//Q:N SGAJqM5:66 Sood&7&-aj&7&7&9&9GAJ*-w&SSG$RR)J')J)J)JKK {2y)444r)r"NTNNNNN)__name__ __module__ __qualname____doc__ is_groupedis_typedstrrboolr,rliteral_emphasisrrr rr rGrrIrMrr rXr[r"rrr!r!%s%  JHLPQU))S)sCx)c))14)KN)Z^))))3;2K#'%)D--#-s-C-!,/- -.>-#-6:-FJ----64<3L$($&*T88388S8"<08!8/?8$87;8GK4j8888#3#d#c4PT:o@V####9==A55S$t*_ 55s55%55#56:5FKk555555rr!ceZdZdZdZejZ ddede edfd ed ed e d df fd Z dde ee efdede dededed ejfdZxZS) GroupedFielda A 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"NFr#r$.r%r' can_collapserc`t|||d|||_dS)NT)superr,rh)r+r#r$r%r'rh __class__s rr,zGroupedField.__init__s1 ueT8<<<(rrNr-itemsr1r2r3c tjd|j}|}|D]\} } tj} | ||j|| tj |||| tj dz } | | z } |tj d| z }t|dkrX|j rQttj |d} tjd| d} tjd|| Stjd|} tjd|| S)Nr5rR -- rr)r rSr% list_typerrUrIr'rliteral_strongrT list_itemrrhr rWrX)r+rNr-rlr1r2r3rYlistnoderJrKparrqrZs rr[zGroupedField.make_fieldsE$R44 >>##!& 1 1 Hg/##C JJtt}fh'/'>+.('TT U U U 5:f%% %C 7NC C00 0HH u::? 9t0 9U_hqk::I(Yq\::I;r9i88 8$R22 {2y)444r)r"NNFr\)r]r^r_r`rar bullet_listrorcrrdr,rrr rr rXr[ __classcell__rks@rrgrgxs  J!ILP=A55S$t*_ 55s55&65#56:5FKk55555555rrgceZdZdZdZ ddedeedfd eedfd ed ed ed eddffd Z dde ee e fdedede de de dejfdZxZS) TypedFieldaa 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"NFr#r$. typenamesr%r' typerolenamerhrcnt|||||||_||_dSr*)rjr,ryrz) r+r#r$ryr%r'rzrhrks rr,zTypedField.__init__s: ueX|DDD"(rrNr-rlr1r2r3c dtdtdtjffd }tjdj}t |dkrjr|d\} } || | } n>} |D]'\} } | tjd|| | z } (tj d| } tj d|| S)NrJrKrc tj}|  j|t j| vr|tjdz } |}t|dkryt|dtjrY|d }|  j |t j n||z }|tjdz }|tjdz }||z }|S)N)r1z (rrrR)rn)r rrUrIr'rrprTpoprrrVrzre) rJrKrs fieldtypetypenamer-r1r2r3r+rNs r handle_itemz*TypedField.make_field..handle_itemsO/##C JJtt}fh'/'>C'II J J J5 'uz$'''"IIh// y>>Q&%:ilEJ+O+O%(|2244HJJtt/@&(/7/Hc7> / S STTTT9$Cuz#& 5:f%% %C 7NCJrr5rr) rcr rrSr%rrhrorqrWrX) r+rNr-rlr1r2r3rrYrJrKbodynoderZs ``` ``` rr[zTypedField.make_fields #             ,$R44 u::? Pt0 P %a Hg([7;;HH~~''H%* P P!'EOB Hg0N0NOOO$R22 {2y)444r)r"r"NNNFr\)r]r^r_r`rbrcrrdr,rrr rr r rXr[rurvs@rrxrxs$H\^NR&+))S)sCx)%PSUXPX/)).1)HK)#)04)))))):>=A"5"5S$t*_ 5"5s"5"5&6"5#"56:"5FKk"5"5"5"5"5"5"5"5rrxczeZdZUdZeeeeeffe d<d dZ de j ddfd Z dejddfd ZdS) DocFieldTransformerz Transforms field lists in "doc field" syntax into better-looking equivalents, using the field type definitions given on a domain. typemap directiverrNcF||_||_dSr*)rget_field_type_mapr)r+rs rr,zDocFieldTransformer.__init__s " 3355 rrcn|D]1}t|tjr||2dS)z,Transform all field list children of a node.N)rr field_list transform)r+rchilds r transform_allz!DocFieldTransformer.transform_allsE & &E%!122 &u%%% & &rc  |j}g}i}i}tttj|D]l}t |dksJttj|d}ttj|d} | dd\} } n&#t$r|d} } YnwxYw| | d\} } t|r(ttj |d} | j}n|j}| | jt!| kr| dd| ddz}| r|d| zz }tj||d<||| r4| r1|r.t |dkrt)|dtjrtt*| }|d}||j|jj||d|jjjjj}t|rJttj |d} | | |n*||tj ddg|Rz }| j }| r)d |D}|r||!|i| <| j"rY | #dd\}}tj|g|!|i|<|} n#t$rYnwxYwtj$|j%d }|j&j|_|j&j'|_'|j&j(|_(||z }| j)r||vr:ttTtVttXf|||}n,t |||<| g|f}||| -| |g}|d|=| -| |g}|| ||fntj.}|D]}t)|tjr||z }"|\}}}| |j i}|jjjjj}|jjj/} ||0||jj||| | z }|1|dS) z%Transform a single field list *node*.rrNr5)NNrQ)r0r1c^g|]*}t|tjtjf(|+Sr")rr InlinerT).0ns r z1DocFieldTransformer.transform..:s0[[[A ej?Y1Z1Z[1[[[rT) translatablerR)2rr rr rXrrSrWrVsplit ValueErrorgetrrchildrenr&rdupperrTappendrrxrIrzrr-statedocumentsettingsr1clearrUr# setdefaultrbrsplitrA rawsourceparentsourcelinerarr!r rMrr2r[ replace_self)!r+rrentries groupindicesrNrXrSrWfieldtype_namerJtypedesc is_typefieldrrK new_fieldname typed_fieldr.xrefsrargtypeargnametranslatable_contentgroup new_entrynew_listentryrrlr3 fieldtypesr1r2s! rrzDocFieldTransformer.transforms,EG') !#$u{+T22] =] =Eu::? " " "e.a99Je.a99J C+5+<+<+>+>+D+DT1+M+M( C C C+5+<+<+>+> C&-[[%N%N "Hl$J// . *Q-@@ #,$- 8#3tH~~#E !/qs 3 9 9 ; ;nQRR>P P 4!S8^3M % = 9 9 1 u%%%FF'FG )F.8UZ.P.PF"&z8"<" % G + " =|+* udD'8!97rs LKKKKKKKKKKKKKKKKKKK////////////++++++4333333  8 $ $ u/ D    P5P5P5P5P5P5P5P5f)5)5)5)5)55)5)5)5X>5>5>5>5>5>5>5>5BI$I$I$I$I$I$I$I$I$I$r