c_annotations.py

"""Support annotations for C API elements.

* Reference count annotations for C API functions.
* Stable ABI annotations
* Limited API annotations

Configuration:
* Set ``refcount_file`` to the path to the reference count data file.
* Set ``stable_abi_file`` to the path to stable ABI list.
"""

from __future__ importannotations

importcsv
importdataclasses
frompathlibimportPath
fromtypingimportTYPE_CHECKING

fromdocutilsimportnodes
fromdocutils.statemachineimportStringList
fromsphinximportaddnodes
fromsphinx.localeimport_assphinx_gettext
fromsphinx.util.docutilsimportSphinxDirective

ifTYPE_CHECKING:
fromsphinx.applicationimportSphinx
fromsphinx.util.typingimportExtensionMetadata

ROLE_TO_OBJECT_TYPE= {
"func": "function",
"macro": "macro",
"member": "member",
"type": "type",
"data": "var",
}


@dataclasses.dataclass(slots=True)
classRefCountEntry:
# Name of the function.
name: str
# List of (argument name, type, refcount effect) tuples.
# (Currently not used. If it was, a dataclass might work better.)
args: list=dataclasses.field(default_factory=list)
# Return type of the function.
result_type: str=""
# Reference count effect for the return value.
result_refs: int|None=None


@dataclasses.dataclass(frozen=True, slots=True)
classStableABIEntry:
# Role of the object.
# Source: Each [item_kind] in stable_abi.toml is mapped to a C Domain role.
role: str
# Name of the object.
# Source: [<item_kind>.*] in stable_abi.toml.
name: str
# Version when the object was added to the stable ABI.
# (Source: [<item_kind>.*.added] in stable_abi.toml.
added: str
# An explananatory blurb for the ifdef.
# Source: ``feature_macro.*.doc`` in stable_abi.toml.
ifdef_note: str
# Defines how much of the struct is exposed. Only relevant for structs.
# Source: [<item_kind>.*.struct_abi_kind] in stable_abi.toml.
struct_abi_kind: str


defread_refcount_data(refcount_filename: Path) ->dict[str, RefCountEntry]:
refcount_data= {}
refcounts=refcount_filename.read_text(encoding="utf8")
forlineinrefcounts.splitlines():
line=line.strip()
ifnotlineorline.startswith("#"):
# blank lines and comments
continue

# Each line is of the form
# function ':' type ':' [param name] ':' [refcount effect] ':' [comment]
parts=line.split(":", 4)
iflen(parts) !=5:
raiseValueError(f"Wrong field count in {line!r}")
function, type, arg, refcount, _comment=parts

# Get the entry, creating it if needed:
try:
entry=refcount_data[function]
exceptKeyError:
entry=refcount_data[function] =RefCountEntry(function)
ifnotrefcountorrefcount=="null":
refcount=None
else:
refcount=int(refcount)
# Update the entry with the new parameter
# or the result information.
ifarg:
entry.args.append((arg, type, refcount))
else:
entry.result_type=type
entry.result_refs=refcount

returnrefcount_data


defread_stable_abi_data(stable_abi_file: Path) ->dict[str, StableABIEntry]:
stable_abi_data= {}
withopen(stable_abi_file, encoding="utf8") asfp:
forrecordincsv.DictReader(fp):
name=record["name"]
stable_abi_data[name] =StableABIEntry(**record)

returnstable_abi_data


defadd_annotations(app: Sphinx, doctree: nodes.document) ->None:
state=app.env.domaindata["c_annotations"]
refcount_data=state["refcount_data"]
stable_abi_data=state["stable_abi_data"]
fornodeindoctree.findall(addnodes.desc_content):
par=node.parent
ifpar["domain"] !="c":
continue
ifnotpar[0].get("ids", None):
continue
name=par[0]["ids"][0].removeprefix("c.")
objtype=par["objtype"]

# Stable ABI annotation.
ifrecord:=stable_abi_data.get(name):
ifROLE_TO_OBJECT_TYPE[record.role] !=objtype:
msg= (
f"Object type mismatch in limited API annotation for {name}: "
f"{ROLE_TO_OBJECT_TYPE[record.role]!r} != {objtype!r}"
 )
raiseValueError(msg)
annotation=_stable_abi_annotation(record)
node.insert(0, annotation)

# Unstable API annotation.
ifname.startswith("PyUnstable"):
annotation=_unstable_api_annotation()
node.insert(0, annotation)

# Return value annotation
ifobjtype!="function":
continue
ifnamenotinrefcount_data:
continue
entry=refcount_data[name]
ifnotentry.result_type.endswith("Object*"):
continue
annotation=_return_value_annotation(entry.result_refs)
node.insert(0, annotation)


def_stable_abi_annotation(record: StableABIEntry) ->nodes.emphasis:
"""Create the Stable ABI annotation.

 These have two forms:
 Part of the `Stable ABI <link>`_.
 Part of the `Stable ABI <link>`_ since version X.Y.
 For structs, there's some more info in the message:
 Part of the `Limited API <link>`_ (as an opaque struct).
 Part of the `Stable ABI <link>`_ (including all members).
 Part of the `Limited API <link>`_ (Only some members are part
 of the stable ABI.).
 ... all of which can have "since version X.Y" appended.
 """
stable_added=record.added
message=sphinx_gettext("Part of the")
message=message.center(len(message) +2)
emph_node=nodes.emphasis(message, message, classes=["stableabi"])
ref_node=addnodes.pending_xref(
"Stable ABI",
refdomain="std",
reftarget="stable",
reftype="ref",
refexplicit="False",
 )
struct_abi_kind=record.struct_abi_kind
ifstruct_abi_kindin {"opaque", "members"}:
ref_node+=nodes.Text(sphinx_gettext("Limited API"))
else:
ref_node+=nodes.Text(sphinx_gettext("Stable ABI"))
emph_node+=ref_node
ifstruct_abi_kind=="opaque":
emph_node+=nodes.Text(" "+sphinx_gettext("(as an opaque struct)"))
elifstruct_abi_kind=="full-abi":
emph_node+=nodes.Text(
" "+sphinx_gettext("(including all members)")
 )
ifrecord.ifdef_note:
emph_node+=nodes.Text(f" {record.ifdef_note}")
ifstable_added=="3.2":
# Stable ABI was introduced in 3.2.
pass
else:
emph_node+=nodes.Text(
" "+sphinx_gettext("since version %s") %stable_added
 )
emph_node+=nodes.Text(".")
ifstruct_abi_kind=="members":
msg=" "+sphinx_gettext(
"(Only some members are part of the stable ABI.)"
 )
emph_node+=nodes.Text(msg)
returnemph_node


def_unstable_api_annotation() ->nodes.admonition:
ref_node=addnodes.pending_xref(
"Unstable API",
nodes.Text(sphinx_gettext("Unstable API")),
refdomain="std",
reftarget="unstable-c-api",
reftype="ref",
refexplicit="False",
 )
emph_node=nodes.emphasis(
"This is ",
sphinx_gettext("This is") +" ",
ref_node,
nodes.Text(
sphinx_gettext(
". It may change without warning in minor releases."
 )
 ),
 )
returnnodes.admonition(
"",
emph_node,
classes=["unstable-c-api", "warning"],
 )


def_return_value_annotation(result_refs: int|None) ->nodes.emphasis:
classes= ["refcount"]
ifresult_refsisNone:
rc=sphinx_gettext("Return value: Always NULL.")
classes.append("return_null")
elifresult_refs:
rc=sphinx_gettext("Return value: New reference.")
classes.append("return_new_ref")
else:
rc=sphinx_gettext("Return value: Borrowed reference.")
classes.append("return_borrowed_ref")
returnnodes.emphasis(rc, rc, classes=classes)


classLimitedAPIList(SphinxDirective):
has_content=False
required_arguments=0
optional_arguments=0
final_argument_whitespace=True

defrun(self) ->list[nodes.Node]:
state=self.env.domaindata["c_annotations"]
content= [
f"* :c:{record.role}:`{record.name}`"
forrecordinstate["stable_abi_data"].values()
 ]
node=nodes.paragraph()
self.state.nested_parse(StringList(content), 0, node)
return [node]


definit_annotations(app: Sphinx) ->None:
# Using domaindata is a bit hack-ish,
# but allows storing state without a global variable or closure.
app.env.domaindata["c_annotations"] =state= {}
state["refcount_data"] =read_refcount_data(
Path(app.srcdir, app.config.refcount_file)
 )
state["stable_abi_data"] =read_stable_abi_data(
Path(app.srcdir, app.config.stable_abi_file)
 )


defsetup(app: Sphinx) ->ExtensionMetadata:
app.add_config_value("refcount_file", "", "env", types={str})
app.add_config_value("stable_abi_file", "", "env", types={str})
app.add_directive("limited-api-list", LimitedAPIList)
app.connect("builder-inited", init_annotations)
app.connect("doctree-read", add_annotations)

return {
"version": "1.0",
"parallel_read_safe": True,
"parallel_write_safe": True,
 }