FeA0dZddlmZddlZddlmZmZmZddlm Z ddl m Z m Z ddl mZddlmZdd lmZdd lmZerdd lmZdd lmZdd lmZddlmZej:eZddZ GddZ!Gdde!Z"Gdde"Z#GddZ$y)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_CHECKINGAnycast)nodes)ElementNode)addnodes)__)logging) get_node_line)Inliner)ObjectDescription)BuildEnvironment) TextlikeNodect|dk(ryt|dkDr&|ddD]}t|tjryt|dtjryy)zCTrue if the node only contains one paragraph (and system messages).rFNT)len isinstancersystem_message paragraph)nodesubnodes 7/usr/lib/python3/dist-packages/sphinx/util/docfields.py_is_single_paragraphrs] 4yA~ TQABx Ggu';';< $q'5??+ ceZdZdZdZdZ d d dZejddddf d dZ ejddddf d dZ d dZ d ddZ y)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 FcX||_||_||_||_||_||_yN)namenameslabelhas_argrolename bodyrolename)selfr!r"r#r$r%r&s r__init__zField.__init__:s/      (rNc X|J|du|duk(s J||f|s |xs |||S|j|j|} | |}| /|-td} tj t| |||t j d|d||} | |xs |||z } |j|j| | Sd} |-tjt5t|} ddd| |||| |ig\} }tj|dg| S#1swY1xYw)Nz]Problem in %s domain: field is supposed to use role '%s', but that role is not in the domain.)locationF) refdomain refexplicitreftype reftarget) get_domainroler loggerwarningr pending_xrefprocess_field_xref contextlibsuppress ValueErrorr rinline)r'r%domaintarget innernodecontnodeenvinlinerr*r2msgrefnodelinenonsmessagess r make_xrefzField.make_xrefJsQ 4X%56K(8KK68y8 8~~f%**84 <7?| 3QRr#w8L++B&e4<PG x<9VV#< N  $$Z0 1&x0 1Hfffgr2N H||FB,,, 1 1s $ D  D)c 4|j||||||||gSr )rF) r'r%r;r<r=r>r?r@r*s r make_xrefszField.make_xrefsgs+ xH"GX78 8rc ||fSr )r'fieldargcontents r make_entryzField.make_entryos '""rc |\}}tjd|j} |rW| tjdz } | j |j |j ||tj|||t|dk(rt|dtjsNt|dtjrgt|ddk(rVt|ddtjr6|j |j||dj|d|||}tjdtjddg|} tjd| | S)Nr+ r?r@r*rr)r>r?r@r*)r field_namer#TextextendrHr%rrr:r&astext field_bodyrfield) r'typesr;itemr?r@r*rKrL fieldname fieldbodys r make_fieldzField.make_fieldrs;!'$$R4  C (I   T__T]]F-5uzz14gPX-Z [ w<1 71:uzz2GAJ 5#gaj/Q:NGAJqM5::6ood&7&7&-aj&7&7&9GAJ*-w&SG$$RR)J')JK {{2y)44r)rJr+Tr+r+)r!strr"tuple[str, ...]r#r\r$boolr%r\r&r\returnNone)r%r\r;r\r<r\r=type[TextlikeNode]r> Node | Noner?BuildEnvironment | Noner@Inliner | Noner*Element | Noner_r )r%r\r;r\r<r\r=rar>rbr?rcr@rdr*rer_ list[Node])rKr\rLrfr_ztuple[str, list[Node]]NNN)rWdict[str, list[Node]]r;r\rXtupler?rcr@rdr*rer_ nodes.field) __name__ __module__ __qualname____doc__ is_groupedis_typedr(r literal_emphasisrFrHrMr[rJrrrr*sk JH "$))) )  )  )) )"3;2K2K*.t,0T-/-'-5L-*-=K-W[-<4<3L3L+/PT-1d808(86M8+8>L8# 8#(,"&#'5$55 5 % 5  5!5 5rrczeZdZdZdZej Z d dfd Z d ddZ xZ S) 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 Tc:t||||d|||_y)NT)superr( can_collapse)r'r!r"r#r%rv __class__s rr(zGroupedField.__init__s  ueT8<(rc tjd|j}|j}|D]\} } tj} | j |j |j|| tj|||| tjdz } | | z } |tjd| z }t|dk(rY|jrMttj|d} tjd| d} tj d|| Stjd|} tj d|| S)Nr+rP -- rr)rrQr# list_typerrSrHr%r literal_strongrR list_itemrrvrrUrV)r'rWr;itemsr?r@r*rYlistnoderKrLparr|rZs rr[zGroupedField.make_fields($$R4 >>#!& 1 Hg//#C JJtt}}fh'/'>'>+.('T U 5::f% %C 7NC C0 0H 1 u:?t00U__hqk:I((Yq\:I;;r9i8 8$$R2 {{2y)44r)rJr+r+F) r!r\r"r]r#r\r%r\rvr^r_r`rgrWrhr;r\r}rir?rcr@rdr*rer_rj) rkrlrmrnror bullet_listrzr(r[ __classcell__rws@rrsrss J!!ILN:?))37)DH)(,"&#'5$55 5 % 5  5!5 5rrsc~eZdZdZdZ d dfd Z d ddZxZS) 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 TcHt||||||||_||_yr )rur( typenames typerolename) r'r!r"rr#r%rrvrws rr(zTypedField.__init__s) ueX|D"(rc dfd }tjdj}t|dk(rjr|d\} } || | } n:j } |D]%\} } | tj d|| | z } 'tjd| } tjd|| S)Nc ttj}|j j j|t j | vr|tjdz } j|}t|dk(rpt|dtjrS|dj}|j j j|t jn||z }|tjdz }|tjdz }||z }|S)N)r?z (rrrP)ry)rrrSrHr%r r{rRpoprrrTrrq) rKrLr fieldtypetypenamer;r?r@r*r'rWs r handle_itemz*TypedField.make_field..handle_items//#C JJtt}}fh'/'>'>C'I J5 uzz$''"IIh/ y>Q&:ilEJJ+O(|224HJJtt/@/@&(/7/H/Hc7> / ST9$Cuzz#& 5::f% %C 7NCJrr+rr)rKr\rLr\r_znodes.paragraph) rrQr#rrvrzr|rUrV) r'rWr;r}r?r@r*rrYrKrLbodynoderZs ``` ``` rr[zTypedField.make_fields  ,$$R4 u:?t00 %a Hg(7;H~~'H%* P!'EOOB Hg0NOO P$$R2 {{2y)44r)rJrJr+r+r+F)r!r\r"r]rr]r#r\r%r\rr\rvr^r_r`rgr)rkrlrmrnrpr(r[rrs@rrrs$H "$%'" ) ) )# )  )  ) ) )  )&(,"&#'(5$(5(5 (5 % (5  (5!(5 (5rrc4eZdZUdZded<ddZd dZd dZy) DocFieldTransformerz Transforms field lists in "doc field" syntax into better-looking equivalents, using the field type definitions given on a domain. zdict[str, tuple[Field, bool]]typemapc<||_|j|_yr ) directiveget_field_type_mapr)r'rs rr(zDocFieldTransformer.__init__s" 335 rcj|D].}t|tjs|j|0y)z,Transform all field list children of a node.N)rr field_list transform)r'rchilds r transform_allz!DocFieldTransformer.transform_alls/ &E%!1!12u% &rc D |j}g}i}i}tttj|D]<}t |dk(sJttj |d}ttj|d} |jjdd\} } |j| d\} } t|r*ttj|d} | j}n |j}| | jt!| k7r| ddj#| ddz}| r|d| zz }tj$||d<|j'|| r7| r4|r1t |dk(r"t)|dtj$rtt*| }|dj}|j-|j.|j0j2xsd||d|j0j4j6j8j:}t|r?ttj|d} | j=| j?|n*|j=|tjddg|z }k| j@}| rS|Dcgc]/}t)|tjBtj$fs.|1}}|r||jE|i| <| jFrA | jIdd\}}tj$|g|jE|i|<|} tjJ|jLd }|jNj6|_|jNjP|_(|jNjR|_)||z }| jTrz||vr)ttVtXttZf|||}n$t |||<| g|f}|j'|| j]| |g}|dj'|| j]| |g}|j'| ||f?tj^}|D]}t)|tjr||z }#|\}}}|j|j@i}|j0j4j6j8j:} |j0j4j`}!|j0j2xsd}"||jc||"|| |!| z }|je|y#t$r|jd} } YwxYwcc}w#t$rYQwxYw) z%Transform a single field list *node*.rrNr+)NNrO)r>r?T) translatablerP)3rrlistrrVrrQrUrTsplitr9getrrchildrenr$r^upperrRappendrrrHrrr;statedocumentsettingsr?clearrSr!Inline setdefaultrprsplitr: rawsourceparentsourcelinerorirr rMrr@r[ replace_self)#r'rrentries groupindicesrWrVrQrUfieldtype_namerKtypedesc is_typefieldrrL new_fieldname typed_fieldr<xrefsrnargtypeargnametranslatable_contentgroup new_entrynew_listentryrr}r* fieldtypesr?r@r;s# rrzDocFieldTransformer.transform!s*,,BD') !#$u{{+T2] =Eu:? "?e..a9Je..a9J C+5+<+<+>+D+DT1+M(&-[[%N "Hl$J/ *Q-@ #,,$--8#3#3tH~#E!/q 3 9 9 ;nQR>P P !S8^3M % = 9 1 u%'G )jUZZ.P"&z8"(> % G + ""|+ udD'8!97 Cd\"s0#U+1/V !V  V+V  V  VVN)rrr_r`)rzaddnodes.desc_contentr_r`)rznodes.field_listr_r`)rkrlrmrn__annotations__r(rrrJrrrrs+*6 &w$rr)rznodes.field_bodyr_r^)%rn __future__rr7typingrrrdocutilsrdocutils.nodesrr sphinxr sphinx.localer sphinx.utilr sphinx.util.nodesr docutils.parsers.rst.statesrsphinx.directivesrsphinx.environmentrsphinx.util.typingr getLoggerrkr3rrrsrrrJrrrs #++(+333/   8 $ a5a5H/55/5dK5K5\J$J$r