mirrors/cpython
1
0
Fork 0
mirror of https://github.com/python/cpython.git synced 2025-08-30 21:48:47 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions 7

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

Browse source 
Co-authored-by: Nikita Sobolev <mail@sobolevn.me>
This commit is contained in:
Hugo van Kemenade 2024-04-16 18:56:15 +03:00 • committed by GitHub
parent df0f3a738f
commit 3284b84c43
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
1 changed files with 11 additions and 9 deletions
Download patch file Download diff file Expand all files Collapse all files

20
Doc/tools/extensions/c_annotations.py
View file

@ -1,4 +1,3 @@
# -*- coding: utf-8 -*-
""" """
c_annotations.py c_annotations.py
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
@ -34,11 +33,10 @@ from sphinx.domains.c import CObject
REST_ROLE_MAP = { REST_ROLE_MAP = {
'function': 'func', 'function': 'func',
'var': 'data',
'type': 'type',
'macro': 'macro', 'macro': 'macro',
'type': 'type',
'member': 'member', 'member': 'member',
'type': 'type',
'var': 'data',
} }
@ -63,7 +61,7 @@ class RCEntry:
class Annotations: class Annotations:
def __init__(self, refcount_filename, stable_abi_file): def __init__(self, refcount_filename, stable_abi_file):
self.refcount_data = {} self.refcount_data = {}
with open(refcount_filename, 'r') as fp: with open(refcount_filename, encoding='utf8') as fp:
for line in fp: for line in fp:
line = line.strip() line = line.strip()
if line[:1] in ("", "#"): if line[:1] in ("", "#"):
@ -71,7 +69,7 @@ class Annotations:
continue continue
parts = line.split(":", 4) parts = line.split(":", 4)
if len(parts) != 5: 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 function, type, arg, refcount, comment = parts
# Get the entry, creating it if needed: # Get the entry, creating it if needed:
try: try:
@ -91,9 +89,8 @@ class Annotations:
entry.result_refs = refcount entry.result_refs = refcount
self.stable_abi_data = {} 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): for record in csv.DictReader(fp):
role = record['role']
name = record['name'] name = record['name']
self.stable_abi_data[name] = record self.stable_abi_data[name] = record
@ -180,13 +177,17 @@ class Annotations:
continue continue
elif not entry.result_type.endswith("Object*"): elif not entry.result_type.endswith("Object*"):
continue continue
classes = ['refcount']
if entry.result_refs is None: if entry.result_refs is None:
rc = sphinx_gettext('Return value: Always NULL.') rc = sphinx_gettext('Return value: Always NULL.')
classes.append('return_null')
elif entry.result_refs: elif entry.result_refs:
rc = sphinx_gettext('Return value: New reference.') rc = sphinx_gettext('Return value: New reference.')
classes.append('return_new_ref')
else: else:
rc = sphinx_gettext('Return value: Borrowed reference.') 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): def init_annotations(app):
@ -228,6 +229,7 @@ def setup(app):
'stableabi': directives.flag, 'stableabi': directives.flag,
} }
old_handle_signature = CObject.handle_signature old_handle_signature = CObject.handle_signature
def new_handle_signature(self, sig, signode): def new_handle_signature(self, sig, signode):
signode.parent['stableabi'] = 'stableabi' in self.options signode.parent['stableabi'] = 'stableabi' in self.options
return old_handle_signature(self, sig, signode) return old_handle_signature(self, sig, signode)