From 111795c73f9eddda08a6b3e64073d2286619a282 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 16 Apr 2024 12:33:08 +0300 Subject: [PATCH 1/5] Add classes to C API return value annotations --- Doc/tools/extensions/c_annotations.py | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/Doc/tools/extensions/c_annotations.py b/Doc/tools/extensions/c_annotations.py index a8b6d8995e3f40..c7e2edc83aeb1e 100644 --- a/Doc/tools/extensions/c_annotations.py +++ b/Doc/tools/extensions/c_annotations.py @@ -180,13 +180,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): From 48884bbcdbf73cc1f8b9beec69f04d0a2aea976a Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 16 Apr 2024 12:34:15 +0300 Subject: [PATCH 2/5] Cleanup: remove duplicate key and sort; remove unused variable; whitespace --- Doc/tools/extensions/c_annotations.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/tools/extensions/c_annotations.py b/Doc/tools/extensions/c_annotations.py index c7e2edc83aeb1e..3d753e4c5ad449 100644 --- a/Doc/tools/extensions/c_annotations.py +++ b/Doc/tools/extensions/c_annotations.py @@ -34,11 +34,10 @@ REST_ROLE_MAP = { 'function': 'func', - 'var': 'data', - 'type': 'type', 'macro': 'macro', - 'type': 'type', 'member': 'member', + 'type': 'type', + 'var': 'data', } @@ -93,7 +92,6 @@ def __init__(self, refcount_filename, stable_abi_file): self.stable_abi_data = {} with open(stable_abi_file, 'r') as fp: for record in csv.DictReader(fp): - role = record['role'] name = record['name'] self.stable_abi_data[name] = record @@ -232,6 +230,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) From 1aa606c131fbcdebbc8dad26a07eedc4d49f51bc Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 16 Apr 2024 12:35:27 +0300 Subject: [PATCH 3/5] Cleanup: remove redundant encoding and default open mode --- Doc/tools/extensions/c_annotations.py | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/Doc/tools/extensions/c_annotations.py b/Doc/tools/extensions/c_annotations.py index 3d753e4c5ad449..809f7086b5cf5e 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 ~~~~~~~~~~~~~~~~ @@ -62,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) as fp: for line in fp: line = line.strip() if line[:1] in ("", "#"): @@ -90,7 +89,7 @@ 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) as fp: for record in csv.DictReader(fp): name = record['name'] self.stable_abi_data[name] = record From 7d0ac69a4923a86292998b0e959e2510f7714dac Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 16 Apr 2024 12:37:09 +0300 Subject: [PATCH 4/5] Use f-string --- Doc/tools/extensions/c_annotations.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tools/extensions/c_annotations.py b/Doc/tools/extensions/c_annotations.py index 809f7086b5cf5e..0afbd27b9764bf 100644 --- a/Doc/tools/extensions/c_annotations.py +++ b/Doc/tools/extensions/c_annotations.py @@ -69,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: From f923cc3f1c1daf25d410fb543b2a8938584d88c7 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Date: Tue, 16 Apr 2024 18:38:19 +0300 Subject: [PATCH 5/5] Explicitly specify encoding='utf8' Co-authored-by: Nikita Sobolev --- Doc/tools/extensions/c_annotations.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/tools/extensions/c_annotations.py b/Doc/tools/extensions/c_annotations.py index 0afbd27b9764bf..abd0a8c817f154 100644 --- a/Doc/tools/extensions/c_annotations.py +++ b/Doc/tools/extensions/c_annotations.py @@ -61,7 +61,7 @@ def __init__(self, name): class Annotations: def __init__(self, refcount_filename, stable_abi_file): self.refcount_data = {} - with open(refcount_filename) as fp: + with open(refcount_filename, encoding='utf8') as fp: for line in fp: line = line.strip() if line[:1] in ("", "#"): @@ -89,7 +89,7 @@ def __init__(self, refcount_filename, stable_abi_file): entry.result_refs = refcount self.stable_abi_data = {} - with open(stable_abi_file) as fp: + with open(stable_abi_file, encoding='utf8') as fp: for record in csv.DictReader(fp): name = record['name'] self.stable_abi_data[name] = record