Mailing List Archive

https://github.com/python/cpython/commit/3284b84c437e3b0b0a052471e8a6aabc528fc651
commit: 3284b84c437e3b0b0a052471e8a6aabc528fc651
branch: main
author: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
committer: hugovk <1324225+hugovk@users.noreply.github.com>
date: 2024-04-16T15:56:15Z
summary:

Docs: Add classes to C API return value annotations (#117926)

Co-authored-by: Nikita Sobolev <mail@sobolevn.me>

files:
M Doc/tools/extensions/c_annotations.py

diff --git a/Doc/tools/extensions/c_annotations.py b/Doc/tools/extensions/c_annotations.py
index a8b6d8995e3f40..abd0a8c817f154 100644
--- a/Doc/tools/extensions/c_annotations.py
+++ b/Doc/tools/extensions/c_annotations.py
@@ -1,4 +1,3 @@
-# -*- coding: utf-8 -*-
"""
c_annotations.py
~~~~~~~~~~~~~~~~
@@ -34,11 +33,10 @@

REST_ROLE_MAP = {
'function': 'func',
- 'var': 'data',
- 'type': 'type',
'macro': 'macro',
- 'type': 'type',
'member': 'member',
+ 'type': 'type',
+ 'var': 'data',
}


@@ -63,7 +61,7 @@ def __init__(self, name):
class Annotations:
def __init__(self, refcount_filename, stable_abi_file):
self.refcount_data = {}
- with open(refcount_filename, 'r') as fp:
+ with open(refcount_filename, encoding='utf8') as fp:
for line in fp:
line = line.strip()
if line[:1] in ("", "#"):
@@ -71,7 +69,7 @@ def __init__(self, refcount_filename, stable_abi_file):
continue
parts = line.split(":", 4)
if len(parts) != 5:
- raise ValueError("Wrong field count in %r" % line)
+ raise ValueError(f"Wrong field count in {line!r}")
function, type, arg, refcount, comment = parts
# Get the entry, creating it if needed:
try:
@@ -91,9 +89,8 @@ def __init__(self, refcount_filename, stable_abi_file):
entry.result_refs = refcount

self.stable_abi_data = {}
- with open(stable_abi_file, 'r') as fp:
+ with open(stable_abi_file, encoding='utf8') as fp:
for record in csv.DictReader(fp):
- role = record['role']
name = record['name']
self.stable_abi_data[name] = record

@@ -180,13 +177,17 @@ def add_annotations(self, app, doctree):
continue
elif not entry.result_type.endswith("Object*"):
continue
+ classes = ['refcount']
if entry.result_refs is None:
rc = sphinx_gettext('Return value: Always NULL.')
+ classes.append('return_null')
elif entry.result_refs:
rc = sphinx_gettext('Return value: New reference.')
+ classes.append('return_new_ref')
else:
rc = sphinx_gettext('Return value: Borrowed reference.')
- node.insert(0, nodes.emphasis(rc, rc, classes=['refcount']))
+ classes.append('return_borrowed_ref')
+ node.insert(0, nodes.emphasis(rc, rc, classes=classes))


def init_annotations(app):
@@ -228,6 +229,7 @@ def setup(app):
'stableabi': directives.flag,
}
old_handle_signature = CObject.handle_signature
+
def new_handle_signature(self, sig, signode):
signode.parent['stableabi'] = 'stableabi' in self.options
return old_handle_signature(self, sig, signode)

_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-leave@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: list-python-checkins@lists.gossamer-threads.com