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

#	count	content
1	n/a	# -- coding: utf-8 --
2	n/a	"""
3	n/a	pyspecific.py
4	n/a	~~~~~~~~~~~~~
5	n/a
6	n/a	Sphinx extension with Python doc-specific markup.
7	n/a
8	n/a	:copyright: 2008-2014 by Georg Brandl.
9	n/a	:license: Python license.
10	n/a	"""
11	n/a
12	n/a	import re
13	n/a	import codecs
14	n/a	from os import path
15	n/a	from time import asctime
16	n/a	from pprint import pformat
17	n/a	from docutils.io import StringOutput
18	n/a	from docutils.utils import new_document
19	n/a
20	n/a	from docutils import nodes, utils
21	n/a
22	n/a	from sphinx import addnodes
23	n/a	from sphinx.builders import Builder
24	n/a	from sphinx.util.nodes import split_explicit_title
25	n/a	from sphinx.util.compat import Directive
26	n/a	from sphinx.writers.html import HTMLTranslator
27	n/a	from sphinx.writers.text import TextWriter
28	n/a	from sphinx.writers.latex import LaTeXTranslator
29	n/a	from sphinx.domains.python import PyModulelevel, PyClassmember
30	n/a
31	n/a	# Support for checking for suspicious markup
32	n/a
33	n/a	import suspicious
34	n/a
35	n/a
36	n/a	ISSUE_URI = 'https://bugs.python.org/issue%s'
37	n/a	SOURCE_URI = 'https://hg.python.org/cpython/file/3.6/%s'
38	n/a
39	n/a	# monkey-patch reST parser to disable alphabetic and roman enumerated lists
40	n/a	from docutils.parsers.rst.states import Body
41	n/a	Body.enum.converters['loweralpha'] = \
42	n/a	Body.enum.converters['upperalpha'] = \
43	n/a	Body.enum.converters['lowerroman'] = \
44	n/a	Body.enum.converters['upperroman'] = lambda x: None
45	n/a
46	n/a	# monkey-patch HTML and LaTeX translators to keep doctest blocks in the
47	n/a	# doctest docs themselves
48	n/a	orig_visit_literal_block = HTMLTranslator.visit_literal_block
49	n/a	orig_depart_literal_block = LaTeXTranslator.depart_literal_block
50	n/a
51	n/a
52	n/a	def new_visit_literal_block(self, node):
53	n/a	meta = self.builder.env.metadata[self.builder.current_docname]
54	n/a	old_trim_doctest_flags = self.highlighter.trim_doctest_flags
55	n/a	if 'keepdoctest' in meta:
56	n/a	self.highlighter.trim_doctest_flags = False
57	n/a	try:
58	n/a	orig_visit_literal_block(self, node)
59	n/a	finally:
60	n/a	self.highlighter.trim_doctest_flags = old_trim_doctest_flags
61	n/a
62	n/a
63	n/a	def new_depart_literal_block(self, node):
64	n/a	meta = self.builder.env.metadata[self.curfilestack[-1]]
65	n/a	old_trim_doctest_flags = self.highlighter.trim_doctest_flags
66	n/a	if 'keepdoctest' in meta:
67	n/a	self.highlighter.trim_doctest_flags = False
68	n/a	try:
69	n/a	orig_depart_literal_block(self, node)
70	n/a	finally:
71	n/a	self.highlighter.trim_doctest_flags = old_trim_doctest_flags
72	n/a
73	n/a
74	n/a	HTMLTranslator.visit_literal_block = new_visit_literal_block
75	n/a	LaTeXTranslator.depart_literal_block = new_depart_literal_block
76	n/a
77	n/a
78	n/a	# Support for marking up and linking to bugs.python.org issues
79	n/a
80	n/a	def issue_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
81	n/a	issue = utils.unescape(text)
82	n/a	text = 'issue ' + issue
83	n/a	refnode = nodes.reference(text, text, refuri=ISSUE_URI % issue)
84	n/a	return [refnode], []
85	n/a
86	n/a
87	n/a	# Support for linking to Python source files easily
88	n/a
89	n/a	def source_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
90	n/a	has_t, title, target = split_explicit_title(text)
91	n/a	title = utils.unescape(title)
92	n/a	target = utils.unescape(target)
93	n/a	refnode = nodes.reference(title, title, refuri=SOURCE_URI % target)
94	n/a	return [refnode], []
95	n/a
96	n/a
97	n/a	# Support for marking up implementation details
98	n/a
99	n/a	class ImplementationDetail(Directive):
100	n/a
101	n/a	has_content = True
102	n/a	required_arguments = 0
103	n/a	optional_arguments = 1
104	n/a	final_argument_whitespace = True
105	n/a
106	n/a	def run(self):
107	n/a	pnode = nodes.compound(classes=['impl-detail'])
108	n/a	content = self.content
109	n/a	add_text = nodes.strong('CPython implementation detail:',
110	n/a	'CPython implementation detail:')
111	n/a	if self.arguments:
112	n/a	n, m = self.state.inline_text(self.arguments[0], self.lineno)
113	n/a	pnode.append(nodes.paragraph('', '', *(n + m)))
114	n/a	self.state.nested_parse(content, self.content_offset, pnode)
115	n/a	if pnode.children and isinstance(pnode[0], nodes.paragraph):
116	n/a	pnode[0].insert(0, add_text)
117	n/a	pnode[0].insert(1, nodes.Text(' '))
118	n/a	else:
119	n/a	pnode.insert(0, nodes.paragraph('', '', add_text))
120	n/a	return [pnode]
121	n/a
122	n/a
123	n/a	# Support for documenting decorators
124	n/a
125	n/a	class PyDecoratorMixin(object):
126	n/a	def handle_signature(self, sig, signode):
127	n/a	ret = super(PyDecoratorMixin, self).handle_signature(sig, signode)
128	n/a	signode.insert(0, addnodes.desc_addname('@', '@'))
129	n/a	return ret
130	n/a
131	n/a	def needs_arglist(self):
132	n/a	return False
133	n/a
134	n/a
135	n/a	class PyDecoratorFunction(PyDecoratorMixin, PyModulelevel):
136	n/a	def run(self):
137	n/a	# a decorator function is a function after all
138	n/a	self.name = 'py:function'
139	n/a	return PyModulelevel.run(self)
140	n/a
141	n/a
142	n/a	class PyDecoratorMethod(PyDecoratorMixin, PyClassmember):
143	n/a	def run(self):
144	n/a	self.name = 'py:method'
145	n/a	return PyClassmember.run(self)
146	n/a
147	n/a
148	n/a	class PyCoroutineMixin(object):
149	n/a	def handle_signature(self, sig, signode):
150	n/a	ret = super(PyCoroutineMixin, self).handle_signature(sig, signode)
151	n/a	signode.insert(0, addnodes.desc_annotation('coroutine ', 'coroutine '))
152	n/a	return ret
153	n/a
154	n/a
155	n/a	class PyCoroutineFunction(PyCoroutineMixin, PyModulelevel):
156	n/a	def run(self):
157	n/a	self.name = 'py:function'
158	n/a	return PyModulelevel.run(self)
159	n/a
160	n/a
161	n/a	class PyCoroutineMethod(PyCoroutineMixin, PyClassmember):
162	n/a	def run(self):
163	n/a	self.name = 'py:method'
164	n/a	return PyClassmember.run(self)
165	n/a
166	n/a
167	n/a	class PyAbstractMethod(PyClassmember):
168	n/a
169	n/a	def handle_signature(self, sig, signode):
170	n/a	ret = super(PyAbstractMethod, self).handle_signature(sig, signode)
171	n/a	signode.insert(0, addnodes.desc_annotation('abstractmethod ',
172	n/a	'abstractmethod '))
173	n/a	return ret
174	n/a
175	n/a	def run(self):
176	n/a	self.name = 'py:method'
177	n/a	return PyClassmember.run(self)
178	n/a
179	n/a
180	n/a	# Support for documenting version of removal in deprecations
181	n/a
182	n/a	class DeprecatedRemoved(Directive):
183	n/a	has_content = True
184	n/a	required_arguments = 2
185	n/a	optional_arguments = 1
186	n/a	final_argument_whitespace = True
187	n/a	option_spec = {}
188	n/a
189	n/a	_label = 'Deprecated since version %s, will be removed in version %s'
190	n/a
191	n/a	def run(self):
192	n/a	node = addnodes.versionmodified()
193	n/a	node.document = self.state.document
194	n/a	node['type'] = 'deprecated-removed'
195	n/a	version = (self.arguments[0], self.arguments[1])
196	n/a	node['version'] = version
197	n/a	text = self._label % version
198	n/a	if len(self.arguments) == 3:
199	n/a	inodes, messages = self.state.inline_text(self.arguments[2],
200	n/a	self.lineno+1)
201	n/a	para = nodes.paragraph(self.arguments[2], '', *inodes)
202	n/a	node.append(para)
203	n/a	else:
204	n/a	messages = []
205	n/a	if self.content:
206	n/a	self.state.nested_parse(self.content, self.content_offset, node)
207	n/a	if len(node):
208	n/a	if isinstance(node[0], nodes.paragraph) and node[0].rawsource:
209	n/a	content = nodes.inline(node[0].rawsource, translatable=True)
210	n/a	content.source = node[0].source
211	n/a	content.line = node[0].line
212	n/a	content += node[0].children
213	n/a	node[0].replace_self(nodes.paragraph('', '', content))
214	n/a	node[0].insert(0, nodes.inline('', '%s: ' % text,
215	n/a	classes=['versionmodified']))
216	n/a	else:
217	n/a	para = nodes.paragraph('', '',
218	n/a	nodes.inline('', '%s.' % text,
219	n/a	classes=['versionmodified']))
220	n/a	node.append(para)
221	n/a	env = self.state.document.settings.env
222	n/a	env.note_versionchange('deprecated', version[0], node, self.lineno)
223	n/a	return [node] + messages
224	n/a
225	n/a
226	n/a	# Support for including Misc/NEWS
227	n/a
228	n/a	issue_re = re.compile('([Ii])ssue #([0-9]+)')
229	n/a	whatsnew_re = re.compile(r"(?im)^what's new in (.*?)\??$")
230	n/a
231	n/a
232	n/a	class MiscNews(Directive):
233	n/a	has_content = False
234	n/a	required_arguments = 1
235	n/a	optional_arguments = 0
236	n/a	final_argument_whitespace = False
237	n/a	option_spec = {}
238	n/a
239	n/a	def run(self):
240	n/a	fname = self.arguments[0]
241	n/a	source = self.state_machine.input_lines.source(
242	n/a	self.lineno - self.state_machine.input_offset - 1)
243	n/a	source_dir = path.dirname(path.abspath(source))
244	n/a	fpath = path.join(source_dir, fname)
245	n/a	self.state.document.settings.record_dependencies.add(fpath)
246	n/a	try:
247	n/a	fp = codecs.open(fpath, encoding='utf-8')
248	n/a	try:
249	n/a	content = fp.read()
250	n/a	finally:
251	n/a	fp.close()
252	n/a	except Exception:
253	n/a	text = 'The NEWS file is not available.'
254	n/a	node = nodes.strong(text, text)
255	n/a	return [node]
256	n/a	content = issue_re.sub(r'`\1ssue #\2 <https://bugs.python.org/\2>`__',
257	n/a	content)
258	n/a	content = whatsnew_re.sub(r'\1', content)
259	n/a	# remove first 3 lines as they are the main heading
260	n/a	lines = ['.. default-role:: obj', ''] + content.splitlines()[3:]
261	n/a	self.state_machine.insert_input(lines, fname)
262	n/a	return []
263	n/a
264	n/a
265	n/a	# Support for building "topic help" for pydoc
266	n/a
267	n/a	pydoc_topic_labels = [
268	n/a	'assert', 'assignment', 'atom-identifiers', 'atom-literals',
269	n/a	'attribute-access', 'attribute-references', 'augassign', 'binary',
270	n/a	'bitwise', 'bltin-code-objects', 'bltin-ellipsis-object',
271	n/a	'bltin-null-object', 'bltin-type-objects', 'booleans',
272	n/a	'break', 'callable-types', 'calls', 'class', 'comparisons', 'compound',
273	n/a	'context-managers', 'continue', 'conversions', 'customization', 'debugger',
274	n/a	'del', 'dict', 'dynamic-features', 'else', 'exceptions', 'execmodel',
275	n/a	'exprlists', 'floating', 'for', 'formatstrings', 'function', 'global',
276	n/a	'id-classes', 'identifiers', 'if', 'imaginary', 'import', 'in', 'integers',
277	n/a	'lambda', 'lists', 'naming', 'nonlocal', 'numbers', 'numeric-types',
278	n/a	'objects', 'operator-summary', 'pass', 'power', 'raise', 'return',
279	n/a	'sequence-types', 'shifting', 'slicings', 'specialattrs', 'specialnames',
280	n/a	'string-methods', 'strings', 'subscriptions', 'truth', 'try', 'types',
281	n/a	'typesfunctions', 'typesmapping', 'typesmethods', 'typesmodules',
282	n/a	'typesseq', 'typesseq-mutable', 'unary', 'while', 'with', 'yield'
283	n/a	]
284	n/a
285	n/a
286	n/a	class PydocTopicsBuilder(Builder):
287	n/a	name = 'pydoc-topics'
288	n/a
289	n/a	def init(self):
290	n/a	self.topics = {}
291	n/a
292	n/a	def get_outdated_docs(self):
293	n/a	return 'all pydoc topics'
294	n/a
295	n/a	def get_target_uri(self, docname, typ=None):
296	n/a	return '' # no URIs
297	n/a
298	n/a	def write(self, *ignored):
299	n/a	writer = TextWriter(self)
300	n/a	for label in self.status_iterator(pydoc_topic_labels,
301	n/a	'building topics... ',
302	n/a	length=len(pydoc_topic_labels)):
303	n/a	if label not in self.env.domaindata['std']['labels']:
304	n/a	self.warn('label %r not in documentation' % label)
305	n/a	continue
306	n/a	docname, labelid, sectname = self.env.domaindata['std']['labels'][label]
307	n/a	doctree = self.env.get_and_resolve_doctree(docname, self)
308	n/a	document = new_document('<section node>')
309	n/a	document.append(doctree.ids[labelid])
310	n/a	destination = StringOutput(encoding='utf-8')
311	n/a	writer.write(document, destination)
312	n/a	self.topics[label] = writer.output
313	n/a
314	n/a	def finish(self):
315	n/a	f = open(path.join(self.outdir, 'topics.py'), 'wb')
316	n/a	try:
317	n/a	f.write('# -- coding: utf-8 --\n'.encode('utf-8'))
318	n/a	f.write(('# Autogenerated by Sphinx on %s\n' % asctime()).encode('utf-8'))
319	n/a	f.write(('topics = ' + pformat(self.topics) + '\n').encode('utf-8'))
320	n/a	finally:
321	n/a	f.close()
322	n/a
323	n/a
324	n/a	# Support for documenting Opcodes
325	n/a
326	n/a	opcode_sig_re = re.compile(r'(\w+(?:\+\d)?)(?:\s$(.)$)?')
327	n/a
328	n/a
329	n/a	def parse_opcode_signature(env, sig, signode):
330	n/a	"""Transform an opcode signature into RST nodes."""
331	n/a	m = opcode_sig_re.match(sig)
332	n/a	if m is None:
333	n/a	raise ValueError
334	n/a	opname, arglist = m.groups()
335	n/a	signode += addnodes.desc_name(opname, opname)
336	n/a	if arglist is not None:
337	n/a	paramlist = addnodes.desc_parameterlist()
338	n/a	signode += paramlist
339	n/a	paramlist += addnodes.desc_parameter(arglist, arglist)
340	n/a	return opname.strip()
341	n/a
342	n/a
343	n/a	# Support for documenting pdb commands
344	n/a
345	n/a	pdbcmd_sig_re = re.compile(r'([a-z()!]+)\s(.)')
346	n/a
347	n/a	# later...
348	n/a	# pdbargs_tokens_re = re.compile(r'''[a-zA-Z]+ \| # identifiers
349	n/a	# [.,:]+ \| # punctuation
350	n/a	# [\[\]()] \| # parens
351	n/a	# \s+ # whitespace
352	n/a	# ''', re.X)
353	n/a
354	n/a
355	n/a	def parse_pdb_command(env, sig, signode):
356	n/a	"""Transform a pdb command signature into RST nodes."""
357	n/a	m = pdbcmd_sig_re.match(sig)
358	n/a	if m is None:
359	n/a	raise ValueError
360	n/a	name, args = m.groups()
361	n/a	fullname = name.replace('(', '').replace(')', '')
362	n/a	signode += addnodes.desc_name(name, name)
363	n/a	if args:
364	n/a	signode += addnodes.desc_addname(' '+args, ' '+args)
365	n/a	return fullname
366	n/a
367	n/a
368	n/a	def setup(app):
369	n/a	app.add_role('issue', issue_role)
370	n/a	app.add_role('source', source_role)
371	n/a	app.add_directive('impl-detail', ImplementationDetail)
372	n/a	app.add_directive('deprecated-removed', DeprecatedRemoved)
373	n/a	app.add_builder(PydocTopicsBuilder)
374	n/a	app.add_builder(suspicious.CheckSuspiciousMarkupBuilder)
375	n/a	app.add_description_unit('opcode', 'opcode', '%s (opcode)',
376	n/a	parse_opcode_signature)
377	n/a	app.add_description_unit('pdbcommand', 'pdbcmd', '%s (pdb command)',
378	n/a	parse_pdb_command)
379	n/a	app.add_description_unit('2to3fixer', '2to3fixer', '%s (2to3 fixer)')
380	n/a	app.add_directive_to_domain('py', 'decorator', PyDecoratorFunction)
381	n/a	app.add_directive_to_domain('py', 'decoratormethod', PyDecoratorMethod)
382	n/a	app.add_directive_to_domain('py', 'coroutinefunction', PyCoroutineFunction)
383	n/a	app.add_directive_to_domain('py', 'coroutinemethod', PyCoroutineMethod)
384	n/a	app.add_directive_to_domain('py', 'abstractmethod', PyAbstractMethod)
385	n/a	app.add_directive('miscnews', MiscNews)
386	n/a	return {'version': '1.0', 'parallel_read_safe': True}