Python code coverage for Doc/tools/rstlint.py

#	count	content
1	n/a	#!/usr/bin/env python3
2	n/a	# -- coding: utf-8 --
3	n/a
4	n/a	# Check for stylistic and formal issues in .rst and .py
5	n/a	# files included in the documentation.
6	n/a	#
7	n/a	# 01/2009, Georg Brandl
8	n/a
9	n/a	# TODO: - wrong versions in versionadded/changed
10	n/a	# - wrong markup after versionchanged directive
11	n/a
12	n/a	import os
13	n/a	import re
14	n/a	import sys
15	n/a	import getopt
16	n/a	from os.path import join, splitext, abspath, exists
17	n/a	from collections import defaultdict
18	n/a
19	n/a	directives = [
20	n/a	# standard docutils ones
21	n/a	'admonition', 'attention', 'caution', 'class', 'compound', 'container',
22	n/a	'contents', 'csv-table', 'danger', 'date', 'default-role', 'epigraph',
23	n/a	'error', 'figure', 'footer', 'header', 'highlights', 'hint', 'image',
24	n/a	'important', 'include', 'line-block', 'list-table', 'meta', 'note',
25	n/a	'parsed-literal', 'pull-quote', 'raw', 'replace',
26	n/a	'restructuredtext-test-directive', 'role', 'rubric', 'sectnum', 'sidebar',
27	n/a	'table', 'target-notes', 'tip', 'title', 'topic', 'unicode', 'warning',
28	n/a	# Sphinx and Python docs custom ones
29	n/a	'acks', 'attribute', 'autoattribute', 'autoclass', 'autodata',
30	n/a	'autoexception', 'autofunction', 'automethod', 'automodule', 'centered',
31	n/a	'cfunction', 'class', 'classmethod', 'cmacro', 'cmdoption', 'cmember',
32	n/a	'code-block', 'confval', 'cssclass', 'ctype', 'currentmodule', 'cvar',
33	n/a	'data', 'decorator', 'decoratormethod', 'deprecated-removed',
34	n/a	'deprecated(?!-removed)', 'describe', 'directive', 'doctest', 'envvar',
35	n/a	'event', 'exception', 'function', 'glossary', 'highlight', 'highlightlang',
36	n/a	'impl-detail', 'index', 'literalinclude', 'method', 'miscnews', 'module',
37	n/a	'moduleauthor', 'opcode', 'pdbcommand', 'productionlist',
38	n/a	'program', 'role', 'sectionauthor', 'seealso', 'sourcecode', 'staticmethod',
39	n/a	'tabularcolumns', 'testcode', 'testoutput', 'testsetup', 'toctree', 'todo',
40	n/a	'todolist', 'versionadded', 'versionchanged'
41	n/a	]
42	n/a
43	n/a	all_directives = '(' + '\|'.join(directives) + ')'
44	n/a	seems_directive_re = re.compile(r'(?<!\.)\.\. %s([^a-z:]\|:(?!:))' % all_directives)
45	n/a	default_role_re = re.compile(r'(^\| )`\w([^`]*?\w)?`($\| )')
46	n/a	leaked_markup_re = re.compile(r'[a-z]::\s\|`\|\.\.\s*\w+:')
47	n/a
48	n/a
49	n/a	checkers = {}
50	n/a
51	n/a	checker_props = {'severity': 1, 'falsepositives': False}
52	n/a
53	n/a
54	n/a	def checker(suffixes, *kwds):
55	n/a	"""Decorator to register a function as a checker."""
56	n/a	def deco(func):
57	n/a	for suffix in suffixes:
58	n/a	checkers.setdefault(suffix, []).append(func)
59	n/a	for prop in checker_props:
60	n/a	setattr(func, prop, kwds.get(prop, checker_props[prop]))
61	n/a	return func
62	n/a	return deco
63	n/a
64	n/a
65	n/a	@checker('.py', severity=4)
66	n/a	def check_syntax(fn, lines):
67	n/a	"""Check Python examples for valid syntax."""
68	n/a	code = ''.join(lines)
69	n/a	if '\r' in code:
70	n/a	if os.name != 'nt':
71	n/a	yield 0, '\\r in code file'
72	n/a	code = code.replace('\r', '')
73	n/a	try:
74	n/a	compile(code, fn, 'exec')
75	n/a	except SyntaxError as err:
76	n/a	yield err.lineno, 'not compilable: %s' % err
77	n/a
78	n/a
79	n/a	@checker('.rst', severity=2)
80	n/a	def check_suspicious_constructs(fn, lines):
81	n/a	"""Check for suspicious reST constructs."""
82	n/a	inprod = False
83	n/a	for lno, line in enumerate(lines):
84	n/a	if seems_directive_re.search(line):
85	n/a	yield lno+1, 'comment seems to be intended as a directive'
86	n/a	if '.. productionlist::' in line:
87	n/a	inprod = True
88	n/a	elif not inprod and default_role_re.search(line):
89	n/a	yield lno+1, 'default role used'
90	n/a	elif inprod and not line.strip():
91	n/a	inprod = False
92	n/a
93	n/a
94	n/a	@checker('.py', '.rst')
95	n/a	def check_whitespace(fn, lines):
96	n/a	"""Check for whitespace and line length issues."""
97	n/a	for lno, line in enumerate(lines):
98	n/a	if '\r' in line:
99	n/a	yield lno+1, '\\r in line'
100	n/a	if '\t' in line:
101	n/a	yield lno+1, 'OMG TABS!!!1'
102	n/a	if line[:-1].rstrip(' \t') != line[:-1]:
103	n/a	yield lno+1, 'trailing whitespace'
104	n/a
105	n/a
106	n/a	@checker('.rst', severity=0)
107	n/a	def check_line_length(fn, lines):
108	n/a	"""Check for line length; this checker is not run by default."""
109	n/a	for lno, line in enumerate(lines):
110	n/a	if len(line) > 81:
111	n/a	# don't complain about tables, links and function signatures
112	n/a	if line.lstrip()[0] not in '+\|' and \
113	n/a	'http://' not in line and \
114	n/a	not line.lstrip().startswith(('.. function',
115	n/a	'.. method',
116	n/a	'.. cfunction')):
117	n/a	yield lno+1, "line too long"
118	n/a
119	n/a
120	n/a	@checker('.html', severity=2, falsepositives=True)
121	n/a	def check_leaked_markup(fn, lines):
122	n/a	"""Check HTML files for leaked reST markup; this only works if
123	n/a	the HTML files have been built.
124	n/a	"""
125	n/a	for lno, line in enumerate(lines):
126	n/a	if leaked_markup_re.search(line):
127	n/a	yield lno+1, 'possibly leaked markup: %r' % line
128	n/a
129	n/a
130	n/a	def main(argv):
131	n/a	usage = '''\
132	n/a	Usage: %s [-v] [-f] [-s sev] [-i path]* [path]
133	n/a
134	n/a	Options: -v verbose (print all checked file names)
135	n/a	-f enable checkers that yield many false positives
136	n/a	-s sev only show problems with severity >= sev
137	n/a	-i path ignore subdir or file path
138	n/a	''' % argv[0]
139	n/a	try:
140	n/a	gopts, args = getopt.getopt(argv[1:], 'vfs:i:')
141	n/a	except getopt.GetoptError:
142	n/a	print(usage)
143	n/a	return 2
144	n/a
145	n/a	verbose = False
146	n/a	severity = 1
147	n/a	ignore = []
148	n/a	falsepos = False
149	n/a	for opt, val in gopts:
150	n/a	if opt == '-v':
151	n/a	verbose = True
152	n/a	elif opt == '-f':
153	n/a	falsepos = True
154	n/a	elif opt == '-s':
155	n/a	severity = int(val)
156	n/a	elif opt == '-i':
157	n/a	ignore.append(abspath(val))
158	n/a
159	n/a	if len(args) == 0:
160	n/a	path = '.'
161	n/a	elif len(args) == 1:
162	n/a	path = args[0]
163	n/a	else:
164	n/a	print(usage)
165	n/a	return 2
166	n/a
167	n/a	if not exists(path):
168	n/a	print('Error: path %s does not exist' % path)
169	n/a	return 2
170	n/a
171	n/a	count = defaultdict(int)
172	n/a
173	n/a	for root, dirs, files in os.walk(path):
174	n/a	# ignore subdirs in ignore list
175	n/a	if abspath(root) in ignore:
176	n/a	del dirs[:]
177	n/a	continue
178	n/a
179	n/a	for fn in files:
180	n/a	fn = join(root, fn)
181	n/a	if fn[:2] == './':
182	n/a	fn = fn[2:]
183	n/a
184	n/a	# ignore files in ignore list
185	n/a	if abspath(fn) in ignore:
186	n/a	continue
187	n/a
188	n/a	ext = splitext(fn)[1]
189	n/a	checkerlist = checkers.get(ext, None)
190	n/a	if not checkerlist:
191	n/a	continue
192	n/a
193	n/a	if verbose:
194	n/a	print('Checking %s...' % fn)
195	n/a
196	n/a	try:
197	n/a	with open(fn, 'r', encoding='utf-8') as f:
198	n/a	lines = list(f)
199	n/a	except (IOError, OSError) as err:
200	n/a	print('%s: cannot open: %s' % (fn, err))
201	n/a	count[4] += 1
202	n/a	continue
203	n/a
204	n/a	for checker in checkerlist:
205	n/a	if checker.falsepositives and not falsepos:
206	n/a	continue
207	n/a	csev = checker.severity
208	n/a	if csev >= severity:
209	n/a	for lno, msg in checker(fn, lines):
210	n/a	print('[%d] %s:%d: %s' % (csev, fn, lno, msg))
211	n/a	count[csev] += 1
212	n/a	if verbose:
213	n/a	print()
214	n/a	if not count:
215	n/a	if severity > 1:
216	n/a	print('No problems with severity >= %d found.' % severity)
217	n/a	else:
218	n/a	print('No problems found.')
219	n/a	else:
220	n/a	for severity in sorted(count):
221	n/a	number = count[severity]
222	n/a	print('%d problem%s with severity %d found.' %
223	n/a	(number, number > 1 and 's' or '', severity))
224	n/a	return int(bool(count))
225	n/a
226	n/a
227	n/a	if __name__ == '__main__':
228	n/a	sys.exit(main(sys.argv))