Module py_domain 

The py domain: object and module registration with Sphinx’s duplicate semantics — PythonDomain.note_object / note_module / clear_doc / merge_domaindata (sphinx/domains/python/__init__.py:780-832 and :744-757) — and the resolution half: find_obj / resolve_xref (:855-994) plus the builtin_resolver missing-reference listener (:1077-1098).

Registrations replay from the parse layer’s records (crate::rst::RegistryExport::py_objects/py_modules) inside crate::env::std_domain::process_doc’s parse-time pass: in Sphinx every one of these calls fires while the directive runs, so a document’s py duplicate warnings interleave with its std description/term duplicates in document order — probe-verified against sphinx 9.1.0 (a doc with an envvar duplicate at line 8, a py duplicate at line 15 and a term duplicate at line 18 warns 8 → 15 → 18). PythonDomain defines no process_doc hook at all, so the py slot of _DomainsContainer._process_doc (dispatch order c, changeset, citation, cpp, index, js, math, py, rst, std) contributes nothing of its own.

Structs

ModindexEntry

One py-modindex row — Sphinx’s 7-field IndexEntry NamedTuple (sphinx/domains/_index.py:17-52). subtype: 0 = top-level module, 1 = group head (a parent with listed submodules — possibly a dummy with every other field empty), 2 = submodule.

ModindexGroup

One first-letter group of the module index.

PyDomainData

Python-domain (py) registries: domaindata['py']['objects'] and ['modules'].

PyModindex

PythonModuleIndex.generate()’s (sorted_content, collapse).

PyModuleEntry

Sphinx’s ModuleEntry (__init__.py:67-73), keyed by module name in PyDomainData::modules.

PyObjectEntry

Sphinx’s ObjectEntry (__init__.py:60-65), keyed by fullname in PyDomainData::objects.

PyXrefTarget

A resolved py cross-reference: what the resolver needs to build the reference node make_refnode / _make_module_refnode would.

Functions

builtin_resolver

builtin_resolver (__init__.py:1077-1098), the py domain’s missing-reference listener at priority 900 — AFTER intersphinx’s default-priority (500) handler, so a builtin name that a loaded inventory carries resolves externally instead of being silenced (probe: :py:class:int with `int` in a mapped inventory renders the external reference; `:py:class:`bool, absent from it, is silenced).

find_obj

PythonDomain.find_obj (__init__.py:855-928): find candidates for name, perhaps using the given module/class context. Returns (fullname, entry) pairs in match order.

generate_modindex

PythonModuleIndex.generate (__init__.py:628-717), verbatim: modindex_common_prefix sorted longest-first (stable, so equal lengths keep config order); modules sorted by lower() (stable over registration order); the FIRST matching prefix is stripped (and restored when it swallowed the whole name, clearing stripped); letter buckets key on the first character of the stripped name, lowercased; a submodule (package != modname on the stripped name) gets subtype 2, promoting the bucket’s previous entry to a group head when it IS the parent, or inserting an all-empty dummy parent when no prev_modname.startswith(package) entry preceded it; display names keep the stripped prefix (stripped + modname); collapse iff submodules outnumber top-levels; groups come out letter-sorted.

modindex_snapshot

The py_modindex slice of the environment snapshot, mirroring crate::env::genindex::snapshot’s serde shape.

resolve_any_xref

PythonDomain.resolve_any_xref (__init__.py:996-1037): always find_obj(..., type=None, searchmode=1); when there are several matches, aliased entries are skipped; a module match yields ('py:mod', module_refnode), everything else ('py:' + role_for_objtype(objtype), refnode) — in find_obj’s match order, which is what the generic any-resolver’s first-wins rule and its ambiguity candidate list run on.

resolve_xref

PythonDomain.resolve_xref minus the node plumbing (:930-994): the type-fallback retries, the ambiguity rule, and the module/object split. Returns the target (None = dangling, silent here — the warning is the resolver’s) and the ambiguity warning to log, type='ref', subtype='python' → [ref.python], which fires even on a successful resolution.