Debian Codegraph @

Doc/tools/extensions/c_annotations.py

raw
1 """Support annotations for C API elements.
2
3 * Reference count annotations for C API functions.
4 * Stable ABI annotations
5 * Limited API annotations
6
7 Configuration:
8 * Set ``refcount_file`` to the path to the reference count data file.
9 * Set ``stable_abi_file`` to the path to stable ABI list.
10 """
11
12 from __future__ import annotations
13
14 import csv
15 import dataclasses
16 from pathlib import Path
17 from typing import TYPE_CHECKING
18
19 from docutils import nodes
20 from docutils.statemachine import StringList
21 from sphinx import addnodes
22 from sphinx.locale import _ as sphinx_gettext
23 from sphinx.util.docutils import SphinxDirective
24
25 if TYPE_CHECKING:
26 from sphinx.application import Sphinx
27 from sphinx.util.typing import ExtensionMetadata
28
29 ROLE_TO_OBJECT_TYPE = {
30 "func": "function",
31 "macro": "macro",
32 "member": "member",
33 "type": "type",
34 "data": "var",
35 }
36
37
38 @dataclasses.dataclass(slots=True)
39 class RefCountEntry:
40 # Name of the function.
41 name: str
42 # List of (argument name, type, refcount effect) tuples.
43 # (Currently not used. If it was, a dataclass might work better.)
44 args: list = dataclasses.field(default_factory=list)
45 # Return type of the function.
46 result_type: str = ""
47 # Reference count effect for the return value.
48 result_refs: int | None = None
49
50
51 @dataclasses.dataclass(frozen=True, slots=True)
52 class StableABIEntry:
53 # Role of the object.
54 # Source: Each [item_kind] in stable_abi.toml is mapped to a C Domain role.
55 role: str
56 # Name of the object.
57 # Source: [<item_kind>.*] in stable_abi.toml.
58 name: str
59 # Version when the object was added to the stable ABI.
60 # (Source: [<item_kind>.*.added] in stable_abi.toml.
61 added: str
62 # An explananatory blurb for the ifdef.
63 # Source: ``feature_macro.*.doc`` in stable_abi.toml.
64 ifdef_note: str
65 # Defines how much of the struct is exposed. Only relevant for structs.
66 # Source: [<item_kind>.*.struct_abi_kind] in stable_abi.toml.
67 struct_abi_kind: str
68
69
70 def read_refcount_data(refcount_filename: Path) -> dict[str, RefCountEntry]:
71 refcount_data = {}
72 refcounts = refcount_filename.read_text(encoding="utf8")
73 for line in refcounts.splitlines():
74 line = line.strip()
75 if not line or line.startswith("#"):
76 # blank lines and comments
77 continue
78
79 # Each line is of the form
80 # function ':' type ':' [param name] ':' [refcount effect] ':' [comment]
81 parts = line.split(":", 4)
82 if len(parts) != 5:
83 raise ValueError(f"Wrong field count in {line!r}")
84 function, type, arg, refcount, _comment = parts
85
86 # Get the entry, creating it if needed:
87 try:
88 entry = refcount_data[function]
89 except KeyError:
90 entry = refcount_data[function] = RefCountEntry(function)
91 if not refcount or refcount == "null":
92 refcount = None
93 else:
94 refcount = int(refcount)
95 # Update the entry with the new parameter
96 # or the result information.
97 if arg:
98 entry.args.append((arg, type, refcount))
99 else:
100 entry.result_type = type
101 entry.result_refs = refcount
102
103 return refcount_data
104
105
106 def read_stable_abi_data(stable_abi_file: Path) -> dict[str, StableABIEntry]:
107 stable_abi_data = {}
108 with open(stable_abi_file, encoding="utf8") as fp:
109 for record in csv.DictReader(fp):
110 name = record["name"]
111 stable_abi_data[name] = StableABIEntry(**record)
112
113 return stable_abi_data
114
115
116 def add_annotations(app: Sphinx, doctree: nodes.document) -> None:
117 state = app.env.domaindata["c_annotations"]
118 refcount_data = state["refcount_data"]
119 stable_abi_data = state["stable_abi_data"]
120 for node in doctree.findall(addnodes.desc_content):
121 par = node.parent
122 if par["domain"] != "c":
123 continue
124 if not par[0].get("ids", None):
125 continue
126 name = par[0]["ids"][0].removeprefix("c.")
127 objtype = par["objtype"]
128
129 # Stable ABI annotation.
130 if record := stable_abi_data.get(name):
131 if ROLE_TO_OBJECT_TYPE[record.role] != objtype:
132 msg = (
133 f"Object type mismatch in limited API annotation for {name}: "
134 f"{ROLE_TO_OBJECT_TYPE[record.role]!r} != {objtype!r}"
135 )
136 raise ValueError(msg)
137 annotation = _stable_abi_annotation(record)
138 node.insert(0, annotation)
139
140 # Unstable API annotation.
141 if name.startswith("PyUnstable"):
142 annotation = _unstable_api_annotation()
143 node.insert(0, annotation)
144
145 # Return value annotation
146 if objtype != "function":
147 continue
148 if name not in refcount_data:
149 continue
150 entry = refcount_data[name]
151 if not entry.result_type.endswith("Object*"):
152 continue
153 annotation = _return_value_annotation(entry.result_refs)
154 node.insert(0, annotation)
155
156
157 def _stable_abi_annotation(
158 record: StableABIEntry,
159 is_corresponding_slot: bool = False,
160 ) -> nodes.emphasis:
161 """Create the Stable ABI annotation.
162
163 These have two forms:
164 Part of the `Stable ABI <link>`_.
165 Part of the `Stable ABI <link>`_ since version X.Y.
166 For structs, there's some more info in the message:
167 Part of the `Limited API <link>`_ (as an opaque struct).
168 Part of the `Stable ABI <link>`_ (including all members).
169 Part of the `Limited API <link>`_ (Only some members are part
170 of the stable ABI.).
171 ... all of which can have "since version X.Y" appended.
172 """
173 stable_added = record.added
174 emph_node = nodes.emphasis('', '', classes=["stableabi"])
175 if is_corresponding_slot:
176 # See "Type slot annotations" in add_annotations
177 ref_node = addnodes.pending_xref(
178 "slot ID",
179 refdomain="c",
180 reftarget="PyType_Slot",
181 reftype="type",
182 refexplicit="True",
183 )
184 ref_node += nodes.Text(sphinx_gettext("slot ID"))
185
186 message = sphinx_gettext("The corresponding")
187 emph_node += nodes.Text(" " + message + " ")
188 emph_node += ref_node
189 emph_node += nodes.Text(" ")
190 emph_node += nodes.literal(record.name, record.name)
191 message = sphinx_gettext("is part of the")
192 emph_node += nodes.Text(" " + message + " ")
193 else:
194 message = sphinx_gettext("Part of the")
195 emph_node += nodes.Text(" " + message + " ")
196 ref_node = addnodes.pending_xref(
197 "Stable ABI",
198 refdomain="std",
199 reftarget="stable",
200 reftype="ref",
201 refexplicit="False",
202 )
203 struct_abi_kind = record.struct_abi_kind
204 if struct_abi_kind in {"opaque", "members"}:
205 ref_node += nodes.Text(sphinx_gettext("Limited API"))
206 else:
207 ref_node += nodes.Text(sphinx_gettext("Stable ABI"))
208 emph_node += ref_node
209 if struct_abi_kind == "opaque":
210 emph_node += nodes.Text(" " + sphinx_gettext("(as an opaque struct)"))
211 elif struct_abi_kind == "full-abi":
212 emph_node += nodes.Text(
213 " " + sphinx_gettext("(including all members)")
214 )
215 if record.ifdef_note:
216 emph_node += nodes.Text(f" {record.ifdef_note}")
217 if stable_added == "3.2":
218 # Stable ABI was introduced in 3.2.
219 pass
220 else:
221 emph_node += nodes.Text(
222 " " + sphinx_gettext("since version %s") % stable_added
223 )
224 emph_node += nodes.Text(".")
225 if struct_abi_kind == "members":
226 msg = " " + sphinx_gettext(
227 "(Only some members are part of the stable ABI.)"
228 )
229 emph_node += nodes.Text(msg)
230 return emph_node
231
232
233 def _unstable_api_annotation() -> nodes.admonition:
234 ref_node = addnodes.pending_xref(
235 "Unstable API",
236 nodes.Text(sphinx_gettext("Unstable API")),
237 refdomain="std",
238 reftarget="unstable-c-api",
239 reftype="ref",
240 refexplicit="False",
241 )
242 emph_node = nodes.emphasis(
243 "This is ",
244 sphinx_gettext("This is") + " ",
245 ref_node,
246 nodes.Text(
247 sphinx_gettext(
248 ". It may change without warning in minor releases."
249 )
250 ),
251 )
252 return nodes.admonition(
253 "",
254 emph_node,
255 classes=["unstable-c-api", "warning"],
256 )
257
258
259 def _return_value_annotation(result_refs: int | None) -> nodes.emphasis:
260 classes = ["refcount"]
261 if result_refs is None:
262 rc = sphinx_gettext("Return value: Always NULL.")
263 classes.append("return_null")
264 elif result_refs:
265 rc = sphinx_gettext("Return value: New reference.")
266 classes.append("return_new_ref")
267 else:
268 rc = sphinx_gettext("Return value: Borrowed reference.")
269 classes.append("return_borrowed_ref")
270 return nodes.emphasis(rc, rc, classes=classes)
271
272
273 class LimitedAPIList(SphinxDirective):
274 has_content = False
275 required_arguments = 0
276 optional_arguments = 0
277 final_argument_whitespace = True
278
279 def run(self) -> list[nodes.Node]:
280 state = self.env.domaindata["c_annotations"]
281 content = [
282 f"* :c:{record.role}:`{record.name}`"
283 for record in state["stable_abi_data"].values()
284 ]
285 node = nodes.paragraph()
286 self.state.nested_parse(StringList(content), 0, node)
287 return [node]
288
289
290 class CorrespondingTypeSlot(SphinxDirective):
291 """Type slot annotations
292
293 Docs for these are with the corresponding field, for example,
294 "Py_tp_repr" is documented under "PyTypeObject.tp_repr", with
295 only a stable ABI note mentioning "Py_tp_repr" (and linking to
296 docs on how this works).
297
298 If there is no corresponding field, these should be documented as normal
299 macros.
300 """
301
302 has_content = False
303
304 required_arguments = 1
305 optional_arguments = 0
306
307 def run(self) -> list[nodes.Node]:
308 name = self.arguments[0]
309 state = self.env.domaindata["c_annotations"]
310 stable_abi_data = state["stable_abi_data"]
311
312 try:
313 record = stable_abi_data[name]
314 except LookupError as err:
315 raise LookupError(
316 f"{name} is not part of stable ABI. "
317 + "Document it as `c:macro::` rather than "
318 + "`corresponding-type-slot::`."
319 ) from err
320
321 annotation = _stable_abi_annotation(record, is_corresponding_slot=True)
322
323 node = nodes.paragraph()
324 content = [
325 ".. c:namespace:: NULL",
326 "",
327 ".. c:macro:: " + name,
328 " :no-typesetting:",
329 ]
330 self.state.nested_parse(StringList(content), 0, node)
331 node.insert(0, annotation)
332 return [node]
333
334
335 def init_annotations(app: Sphinx) -> None:
336 # Using domaindata is a bit hack-ish,
337 # but allows storing state without a global variable or closure.
338 app.env.domaindata["c_annotations"] = state = {}
339 state["refcount_data"] = read_refcount_data(
340 Path(app.srcdir, app.config.refcount_file)
341 )
342 state["stable_abi_data"] = read_stable_abi_data(
343 Path(app.srcdir, app.config.stable_abi_file)
344 )
345
346
347 def setup(app: Sphinx) -> ExtensionMetadata:
348 app.add_config_value("refcount_file", "", "env", types={str})
349 app.add_config_value("stable_abi_file", "", "env", types={str})
350 app.add_directive("limited-api-list", LimitedAPIList)
351 app.add_directive("corresponding-type-slot", CorrespondingTypeSlot)
352 app.connect("builder-inited", init_annotations)
353 app.connect("doctree-read", add_annotations)
354
355 return {
356 "version": "1.0",
357 "parallel_read_safe": True,
358 "parallel_write_safe": True,
359 }