Ri0 dZddlmZddlZddlmZddlmZmZddl m Z erLddl m Z m Z mZddlmZmZdd lmZdd lmZmZdd lmZdd lmZdd lmZddlmZddlmZddl m!Z!ddl"m#Z#m$Z$dZ%GddZ&GddZ'y)zSupport for domains. Domains are groupings of description directives and roles describing e.g. constructs of one programming language. ) annotationsN) TYPE_CHECKING)Index IndexEntry)_)IterableSequenceSet)AnyClassVar)nodes)ElementNode) Directive)Inliner) pending_xref)Builder)BuildEnvironment)XRefRole) RoleFunction TitleGetter)DomainrrObjTypec eZdZdZddiZddZy)ra.An ObjType is the description for a type of object that a domain can document. In the object_types attribute of Domain subclasses, object type names are mapped to instances of this class. Constructor arguments: - *lname*: localized name of the type (do not include domain name) - *roles*: all the roles that can refer to an object of this type - *attrs*: object attributes -- currently only "searchprio" is known, which defines the object's priority in the full-text search index, see :meth:`Domain.get_objects()`. searchpriocH||_||_|j|z|_yN)lnameroles known_attrsattrs)selfrr r"s O/home/agent/.friday_env/lib/python3.12/site-packages/sphinx/domains/__init__.py__init__zObjType.__init__8s" &+ %)%5%5%= N)rstrr r r"r returnNone)__name__ __module__ __qualname____doc__r!r%r&r$rr&s  aK>r&rcveZdZUdZdZded<dZded<iZded<iZded <iZ d ed <gZ d ed <iZ ded<iZ ded<iZ ded<ded<dZded<d*dZd+dZd,dZd-dZd.dZd/dZd0dZ d1d Zd+d!Zd2d"Z d3d#Z d4d$Zd5d%Zd6d7d&Zd8d'Zd9d(Zy)):raA Domain is meant to be a group of "object" description directives for objects of a similar nature, and corresponding roles to create references to them. Examples would be Python modules, classes, functions etc., elements of a templating language, Sphinx roles and directives, etc. Each domain has a separate storage for information about existing objects and how to reference them in `self.data`, which must be a dictionary. It also must implement several functions that expose the object information in a uniform way to parts of Sphinx that allow the user to reference or search for objects in a domain-agnostic way. About `self.data`: since all object and cross-referencing information is stored on a BuildEnvironment instance, the `domain.data` object is also stored in the `env.domaindata` dict under the key `domain.name`. Before the build process starts, every active domain is instantiated and given the environment object; the `domaindata` dict must then either be nonexistent or a dictionary whose 'version' key is equal to the domain class' :attr:`data_version` attribute. Otherwise, `OSError` is raised and the pickled environment is discarded. z ClassVar[str]namelabelzClassVar[dict[str, ObjType]] object_typesz$ClassVar[dict[str, type[Directive]]] directivesz,ClassVar[dict[str, RoleFunction | XRefRole]]r zClassVar[list[type[Index]]]indiceszClassVar[dict[str, str]]dangling_warningsz:ClassVar[dict[type[Node], tuple[str, TitleGetter | None]]]enumerable_nodeszClassVar[dict[str, Any]] initial_datadict[str, Any]datarz ClassVar[int] data_versionc|j}||_i|_i|_i|_i|_t |j|_t |j|_t |j|_ t|j|_ |j|vrat|jt sJtj |j}|j"|d<|x|_||j<nH||j|_|j$d|j"k7rt'd|j(z|jj+D]k\}}|jD]-}|jj-|gj/|/|jr|jdnd|j |<m|jj0|_|j j0|_y)Nversionzdata of %r domain out of daterr0) domaindataenv _role_cache_directive_cache _role2type _type2roledictr3r4r listr5r1 isinstancer8copydeepcopyr;r:OSErrorr2items setdefaultappendgetobjtypes_for_rolerole_for_objtype)r#r? domain_datanew_datar1objrolenames r$r%zDomain.__init__ks14 %(46<>02*,!!2!23t/$**% DLL) 99K 'd//6 66}}T%6%67H"&"3"3HY 19 9DI DII.#DII.DIyy#t'8'88= JKK**002 FID#II F**8R8??E F47IICIIaL2DOOD ! F"&!4!4 $ 3 3r&c |jjj}|jD]U}|js|j s|jd|j}|j ||d|j Wy)zSet up domain object.-r0N)r?domainsstandard_domainr5r1 localnamenote_hyperlink_target)r#stdindexdocnames r$setupz Domain.setupskhh..\\ QEzzeoo!YYKq 5))'7BP Qr&c ||j|<|jr|jd|j|<nd|j|<|jD]-}|jj |gj |/y)zAdd an object type.rr0N)r3r rCrBrKrL)r#r1objtyperoles r$add_object_typezDomain.add_object_typesp")$ ==$+MM!$4DOOD !$&DOOD !MM >D OO & &tR 0 7 7 = >r&cjvrjSjvryjd d dfd }|j<|S)zReturn a role adapter function that always gives the registered role its full name ('domain:name') as the first argument. N:c B j|||||xsi|Sr)r ) typrawtexttextlinenoinlineroptionscontentfullnamer1r#s r$ role_adapterz!Domain.role..role_adapters0$4::d#'4'-R r&)Nr.)rer'rfr'rgr'rhintrirrjzdict[str, Any] | Nonerkz Sequence[str]r(z-tuple[list[Node], list[nodes.system_message]])r@r r1)r#r1rmrls`` @r$r`z Domain.roles 4## ###D) ) tzz !ii[$(.2%'        + # ; ".r&c||jvr|j|S||jvry|jd||j|}Gfdd|}||j|<|S)zReturn a directive adapter class that always gives the registered directive its full name ('domain:name') as ``self.name``. Nrcc$eZdZdfd ZxZS)*Domain.directive..DirectiveAdapterc.|_t| Sr)r1superrun)r# __class__rls r$rtz.Domain.directive..DirectiveAdapter.runs$ w{}$r&)r(z list[Node])r*r+r,rt __classcell__)rurls@r$DirectiveAdapterrqs  % %r&rw)rAr4r1)r#r1 BaseDirectiverwrls @r$ directivezDomain.directivesy 4(( (((. . t &ii[$(-  %} % '7d#r&cy)z?Remove traces of a document in the domain-specific inventories.Nr.)r#r\s r$ clear_doczDomain.clear_doc r&c8d|jd}t|)zMerge in data regarding *docnames* from a different domaindata inventory (coming from a subprocess in parallel builds). z(merge_domaindata must be implemented in z" to be able to do parallel builds!)ruNotImplementedError)r#docnames otherdatamsgs r$merge_domaindatazDomain.merge_domaindatas- 7t~~6FG0 0 "#&&r&cy)z7Process a document after it is read by the environment.Nr.)r#r?r\documents r$ process_doczDomain.process_doc r&cy)z)Do consistency checks (**experimental**).Nr.r#s r$check_consistencyzDomain.check_consistencyr|r&cy)zxProcess a pending xref created in a doc field. For example, attach information about the current scope. Nr.)r#pnodes r$process_field_xrefzDomain.process_field_xrefrr&cy)aLResolve the pending_xref *node* with the given *typ* and *target*. This method should return a new node, to replace the xref node, containing the *contnode* which is the markup content of the cross-reference. If no resolution can be found, None can be returned; the xref node will then given to the :event:`missing-reference` event, and if that yields no resolution, replaced by *contnode*. The method can also raise :exc:`sphinx.environment.NoUri` to suppress the :event:`missing-reference` event being emitted. Nr.)r#r? fromdocnamebuilderretargetnodecontnodes r$ resolve_xrefzDomain.resolve_xrefs. r&ct)a9Resolve the pending_xref *node* with the given *target*. The reference comes from an "any" or similar role, which means that we don't know the type. Otherwise, the arguments are the same as for :meth:`resolve_xref`. The method must return a list (potentially empty) of tuples ``('domain:role', newnode)``, where ``'domain:role'`` is the name of a role that could have created the same reference, e.g. ``'py:func'``. ``newnode`` is what :meth:`resolve_xref` would return. .. versionadded:: 1.3 )r~)r#r?rrrrrs r$resolve_any_xrefzDomain.resolve_any_xrefs ,"!r&cgS)auReturn an iterable of "object descriptions". Object descriptions are tuples with six items: ``name`` Fully qualified name. ``dispname`` Name to display when searching/linking. ``type`` Object type, a key in ``self.object_types``. ``docname`` The document where it is to be found. ``anchor`` The anchor name for the object. ``priority`` How "important" the object is (determines placement in search results). One of: ``1`` Default priority (placed before full-text matches). ``0`` Object is important (placed before default-priority objects). ``2`` Object is unimportant (placed after full-text matches). ``-1`` Object should not show up in search at all. r.rs r$ get_objectszDomain.get_objectss B r&cf|r |jStd|j|jfzS)z#Return full name for given ObjType.z%s %s)rrr2)r#typeprimarys r$ get_type_namezDomain.get_type_name>s+ :: zTZZ444r&cX|jj|jd\}}|S)z,Get type of enumerable nodes (experimental).)NN)r7rMru)r#renum_node_typers r$get_enumerable_node_typezDomain.get_enumerable_node_typeDs) 1155dnnlSr&cy)z*Return full qualified name for given node.Nr.)r#rs r$get_full_qualified_namezDomain.get_full_qualified_nameIr|r&N)r?rr(r))r(r))r1r'r_rr(r))r1r'r(zRoleFunction | None)r1r'r(ztype[Directive] | None)r\r'r(r))rzSet[str]rr9r(r))r?rr\r'rznodes.documentr(r))rrr(r))r?rrr'rrrer'rr'rrrrr(znodes.reference | None)r?rrr'rrrr'rrrrr(z!list[tuple[str, nodes.reference]])r(z-Iterable[tuple[str, str, str, str, str, int]])F)rrrboolr(r')rrr( str | None)rrr(r)r*r+r,r-r1__annotations__r2r3r4r r5r6r7r8r;r%r]rar`ryr{rrrrrrrrrrr.r&r$rr>s,D-E=13L.379J49:4 * ' # .1 =K                 2" "" "  "  "" +"0!F5   r&r)(r- __future__rrGtypingrsphinx.domains._indexrr sphinx.localercollections.abcrr r r r docutilsr docutils.nodesrrdocutils.parsers.rstrdocutils.parsers.rst.statesrsphinx.addnodesrsphinx.buildersrsphinx.environmentr sphinx.rolesrsphinx.util.typingrr__all__rrr.r&r$rs_ # 377$,.3,'3%< >>0M M r&