Python code coverage for Doc/tools/extensions/c_annotations.py

#	count	content
1	n/a	# -- coding: utf-8 --
2	n/a	"""
3	n/a	c_annotations.py
4	n/a	~~~~~~~~~~~~~~~~
5	n/a
6	n/a	Supports annotations for C API elements:
7	n/a
8	n/a	* reference count annotations for C API functions. Based on
9	n/a	refcount.py and anno-api.py in the old Python documentation tools.
10	n/a
11	n/a	* stable API annotations
12	n/a
13	n/a	Usage: Set the `refcount_file` config value to the path to the reference
14	n/a	count data file.
15	n/a
16	n/a	:copyright: Copyright 2007-2014 by Georg Brandl.
17	n/a	:license: Python license.
18	n/a	"""
19	n/a
20	n/a	from os import path
21	n/a	from docutils import nodes
22	n/a	from docutils.parsers.rst import directives
23	n/a
24	n/a	from sphinx import addnodes
25	n/a	from sphinx.domains.c import CObject
26	n/a
27	n/a
28	n/a	class RCEntry:
29	n/a	def __init__(self, name):
30	n/a	self.name = name
31	n/a	self.args = []
32	n/a	self.result_type = ''
33	n/a	self.result_refs = None
34	n/a
35	n/a
36	n/a	class Annotations(dict):
37	n/a	@classmethod
38	n/a	def fromfile(cls, filename):
39	n/a	d = cls()
40	n/a	fp = open(filename, 'r')
41	n/a	try:
42	n/a	for line in fp:
43	n/a	line = line.strip()
44	n/a	if line[:1] in ("", "#"):
45	n/a	# blank lines and comments
46	n/a	continue
47	n/a	parts = line.split(":", 4)
48	n/a	if len(parts) != 5:
49	n/a	raise ValueError("Wrong field count in %r" % line)
50	n/a	function, type, arg, refcount, comment = parts
51	n/a	# Get the entry, creating it if needed:
52	n/a	try:
53	n/a	entry = d[function]
54	n/a	except KeyError:
55	n/a	entry = d[function] = RCEntry(function)
56	n/a	if not refcount or refcount == "null":
57	n/a	refcount = None
58	n/a	else:
59	n/a	refcount = int(refcount)
60	n/a	# Update the entry with the new parameter or the result
61	n/a	# information.
62	n/a	if arg:
63	n/a	entry.args.append((arg, type, refcount))
64	n/a	else:
65	n/a	entry.result_type = type
66	n/a	entry.result_refs = refcount
67	n/a	finally:
68	n/a	fp.close()
69	n/a	return d
70	n/a
71	n/a	def add_annotations(self, app, doctree):
72	n/a	for node in doctree.traverse(addnodes.desc_content):
73	n/a	par = node.parent
74	n/a	if par['domain'] != 'c':
75	n/a	continue
76	n/a	if par['stableabi']:
77	n/a	node.insert(0, nodes.emphasis(' Part of the stable ABI.',
78	n/a	' Part of the stable ABI.',
79	n/a	classes=['stableabi']))
80	n/a	if par['objtype'] != 'function':
81	n/a	continue
82	n/a	if not par[0].has_key('names') or not par[0]['names']:
83	n/a	continue
84	n/a	name = par[0]['names'][0]
85	n/a	if name.startswith("c."):
86	n/a	name = name[2:]
87	n/a	entry = self.get(name)
88	n/a	if not entry:
89	n/a	continue
90	n/a	elif entry.result_type not in ("PyObject", "PyVarObject"):
91	n/a	continue
92	n/a	if entry.result_refs is None:
93	n/a	rc = 'Return value: Always NULL.'
94	n/a	elif entry.result_refs:
95	n/a	rc = 'Return value: New reference.'
96	n/a	else:
97	n/a	rc = 'Return value: Borrowed reference.'
98	n/a	node.insert(0, nodes.emphasis(rc, rc, classes=['refcount']))
99	n/a
100	n/a
101	n/a	def init_annotations(app):
102	n/a	refcounts = Annotations.fromfile(
103	n/a	path.join(app.srcdir, app.config.refcount_file))
104	n/a	app.connect('doctree-read', refcounts.add_annotations)
105	n/a
106	n/a
107	n/a	def setup(app):
108	n/a	app.add_config_value('refcount_file', '', True)
109	n/a	app.connect('builder-inited', init_annotations)
110	n/a
111	n/a	# monkey-patch C object...
112	n/a	CObject.option_spec = {
113	n/a	'noindex': directives.flag,
114	n/a	'stableabi': directives.flag,
115	n/a	}
116	n/a	old_handle_signature = CObject.handle_signature
117	n/a	def new_handle_signature(self, sig, signode):
118	n/a	signode.parent['stableabi'] = 'stableabi' in self.options
119	n/a	return old_handle_signature(self, sig, signode)
120	n/a	CObject.handle_signature = new_handle_signature
121	n/a	return {'version': '1.0', 'parallel_read_safe': True}