Python code coverage for Lib/doctest.py

#	count	content
1	n/a	# Module doctest.
2	n/a	# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org).
3	n/a	# Major enhancements and refactoring by:
4	n/a	# Jim Fulton
5	n/a	# Edward Loper
6	n/a
7	n/a	# Provided as-is; use at your own risk; no warranty; no promises; enjoy!
8	n/a
9	n/a	r"""Module doctest -- a framework for running examples in docstrings.
10	n/a
11	n/a	In simplest use, end each module M to be tested with:
12	n/a
13	n/a	def _test():
14	n/a	import doctest
15	n/a	doctest.testmod()
16	n/a
17	n/a	if __name__ == "__main__":
18	n/a	_test()
19	n/a
20	n/a	Then running the module as a script will cause the examples in the
21	n/a	docstrings to get executed and verified:
22	n/a
23	n/a	python M.py
24	n/a
25	n/a	This won't display anything unless an example fails, in which case the
26	n/a	failing example(s) and the cause(s) of the failure(s) are printed to stdout
27	n/a	(why not stderr? because stderr is a lame hack <0.2 wink>), and the final
28	n/a	line of output is "Test failed.".
29	n/a
30	n/a	Run it with the -v switch instead:
31	n/a
32	n/a	python M.py -v
33	n/a
34	n/a	and a detailed report of all examples tried is printed to stdout, along
35	n/a	with assorted summaries at the end.
36	n/a
37	n/a	You can force verbose mode by passing "verbose=True" to testmod, or prohibit
38	n/a	it by passing "verbose=False". In either of those cases, sys.argv is not
39	n/a	examined by testmod.
40	n/a
41	n/a	There are a variety of other ways to run doctests, including integration
42	n/a	with the unittest framework, and support for running non-Python text
43	n/a	files containing doctests. There are also many ways to override parts
44	n/a	of doctest's default behaviors. See the Library Reference Manual for
45	n/a	details.
46	n/a	"""
47	n/a
48	n/a	__docformat__ = 'reStructuredText en'
49	n/a
50	n/a	__all__ = [
51	n/a	# 0, Option Flags
52	n/a	'register_optionflag',
53	n/a	'DONT_ACCEPT_TRUE_FOR_1',
54	n/a	'DONT_ACCEPT_BLANKLINE',
55	n/a	'NORMALIZE_WHITESPACE',
56	n/a	'ELLIPSIS',
57	n/a	'SKIP',
58	n/a	'IGNORE_EXCEPTION_DETAIL',
59	n/a	'COMPARISON_FLAGS',
60	n/a	'REPORT_UDIFF',
61	n/a	'REPORT_CDIFF',
62	n/a	'REPORT_NDIFF',
63	n/a	'REPORT_ONLY_FIRST_FAILURE',
64	n/a	'REPORTING_FLAGS',
65	n/a	'FAIL_FAST',
66	n/a	# 1. Utility Functions
67	n/a	# 2. Example & DocTest
68	n/a	'Example',
69	n/a	'DocTest',
70	n/a	# 3. Doctest Parser
71	n/a	'DocTestParser',
72	n/a	# 4. Doctest Finder
73	n/a	'DocTestFinder',
74	n/a	# 5. Doctest Runner
75	n/a	'DocTestRunner',
76	n/a	'OutputChecker',
77	n/a	'DocTestFailure',
78	n/a	'UnexpectedException',
79	n/a	'DebugRunner',
80	n/a	# 6. Test Functions
81	n/a	'testmod',
82	n/a	'testfile',
83	n/a	'run_docstring_examples',
84	n/a	# 7. Unittest Support
85	n/a	'DocTestSuite',
86	n/a	'DocFileSuite',
87	n/a	'set_unittest_reportflags',
88	n/a	# 8. Debugging Support
89	n/a	'script_from_examples',
90	n/a	'testsource',
91	n/a	'debug_src',
92	n/a	'debug',
93	n/a	]
94	n/a
95	n/a	import __future__
96	n/a	import argparse
97	n/a	import difflib
98	n/a	import inspect
99	n/a	import linecache
100	n/a	import os
101	n/a	import pdb
102	n/a	import re
103	n/a	import sys
104	n/a	import traceback
105	n/a	import unittest
106	n/a	from io import StringIO
107	n/a	from collections import namedtuple
108	n/a
109	n/a	TestResults = namedtuple('TestResults', 'failed attempted')
110	n/a
111	n/a	# There are 4 basic classes:
112	n/a	# - Example: a <source, want> pair, plus an intra-docstring line number.
113	n/a	# - DocTest: a collection of examples, parsed from a docstring, plus
114	n/a	# info about where the docstring came from (name, filename, lineno).
115	n/a	# - DocTestFinder: extracts DocTests from a given object's docstring and
116	n/a	# its contained objects' docstrings.
117	n/a	# - DocTestRunner: runs DocTest cases, and accumulates statistics.
118	n/a	#
119	n/a	# So the basic picture is:
120	n/a	#
121	n/a	# list of:
122	n/a	# +------+ +---------+ +-------+
123	n/a	# \|object\| --DocTestFinder-> \| DocTest \| --DocTestRunner-> \|results\|
124	n/a	# +------+ +---------+ +-------+
125	n/a	# \| Example \|
126	n/a	# \| ... \|
127	n/a	# \| Example \|
128	n/a	# +---------+
129	n/a
130	n/a	# Option constants.
131	n/a
132	n/a	OPTIONFLAGS_BY_NAME = {}
133	n/a	def register_optionflag(name):
134	n/a	# Create a new flag unless `name` is already known.
135	n/a	return OPTIONFLAGS_BY_NAME.setdefault(name, 1 << len(OPTIONFLAGS_BY_NAME))
136	n/a
137	n/a	DONT_ACCEPT_TRUE_FOR_1 = register_optionflag('DONT_ACCEPT_TRUE_FOR_1')
138	n/a	DONT_ACCEPT_BLANKLINE = register_optionflag('DONT_ACCEPT_BLANKLINE')
139	n/a	NORMALIZE_WHITESPACE = register_optionflag('NORMALIZE_WHITESPACE')
140	n/a	ELLIPSIS = register_optionflag('ELLIPSIS')
141	n/a	SKIP = register_optionflag('SKIP')
142	n/a	IGNORE_EXCEPTION_DETAIL = register_optionflag('IGNORE_EXCEPTION_DETAIL')
143	n/a
144	n/a	COMPARISON_FLAGS = (DONT_ACCEPT_TRUE_FOR_1 \|
145	n/a	DONT_ACCEPT_BLANKLINE \|
146	n/a	NORMALIZE_WHITESPACE \|
147	n/a	ELLIPSIS \|
148	n/a	SKIP \|
149	n/a	IGNORE_EXCEPTION_DETAIL)
150	n/a
151	n/a	REPORT_UDIFF = register_optionflag('REPORT_UDIFF')
152	n/a	REPORT_CDIFF = register_optionflag('REPORT_CDIFF')
153	n/a	REPORT_NDIFF = register_optionflag('REPORT_NDIFF')
154	n/a	REPORT_ONLY_FIRST_FAILURE = register_optionflag('REPORT_ONLY_FIRST_FAILURE')
155	n/a	FAIL_FAST = register_optionflag('FAIL_FAST')
156	n/a
157	n/a	REPORTING_FLAGS = (REPORT_UDIFF \|
158	n/a	REPORT_CDIFF \|
159	n/a	REPORT_NDIFF \|
160	n/a	REPORT_ONLY_FIRST_FAILURE \|
161	n/a	FAIL_FAST)
162	n/a
163	n/a	# Special string markers for use in `want` strings:
164	n/a	BLANKLINE_MARKER = '<BLANKLINE>'
165	n/a	ELLIPSIS_MARKER = '...'
166	n/a
167	n/a	######################################################################
168	n/a	## Table of Contents
169	n/a	######################################################################
170	n/a	# 1. Utility Functions
171	n/a	# 2. Example & DocTest -- store test cases
172	n/a	# 3. DocTest Parser -- extracts examples from strings
173	n/a	# 4. DocTest Finder -- extracts test cases from objects
174	n/a	# 5. DocTest Runner -- runs test cases
175	n/a	# 6. Test Functions -- convenient wrappers for testing
176	n/a	# 7. Unittest Support
177	n/a	# 8. Debugging Support
178	n/a	# 9. Example Usage
179	n/a
180	n/a	######################################################################
181	n/a	## 1. Utility Functions
182	n/a	######################################################################
183	n/a
184	n/a	def _extract_future_flags(globs):
185	n/a	"""
186	n/a	Return the compiler-flags associated with the future features that
187	n/a	have been imported into the given namespace (globs).
188	n/a	"""
189	n/a	flags = 0
190	n/a	for fname in __future__.all_feature_names:
191	n/a	feature = globs.get(fname, None)
192	n/a	if feature is getattr(__future__, fname):
193	n/a	flags \|= feature.compiler_flag
194	n/a	return flags
195	n/a
196	n/a	def _normalize_module(module, depth=2):
197	n/a	"""
198	n/a	Return the module specified by `module`. In particular:
199	n/a	- If `module` is a module, then return module.
200	n/a	- If `module` is a string, then import and return the
201	n/a	module with that name.
202	n/a	- If `module` is None, then return the calling module.
203	n/a	The calling module is assumed to be the module of
204	n/a	the stack frame at the given depth in the call stack.
205	n/a	"""
206	n/a	if inspect.ismodule(module):
207	n/a	return module
208	n/a	elif isinstance(module, str):
209	n/a	return __import__(module, globals(), locals(), ["*"])
210	n/a	elif module is None:
211	n/a	return sys.modules[sys._getframe(depth).f_globals['__name__']]
212	n/a	else:
213	n/a	raise TypeError("Expected a module, string, or None")
214	n/a
215	n/a	def _load_testfile(filename, package, module_relative, encoding):
216	n/a	if module_relative:
217	n/a	package = _normalize_module(package, 3)
218	n/a	filename = _module_relative_path(package, filename)
219	n/a	if getattr(package, '__loader__', None) is not None:
220	n/a	if hasattr(package.__loader__, 'get_data'):
221	n/a	file_contents = package.__loader__.get_data(filename)
222	n/a	file_contents = file_contents.decode(encoding)
223	n/a	# get_data() opens files as 'rb', so one must do the equivalent
224	n/a	# conversion as universal newlines would do.
225	n/a	return file_contents.replace(os.linesep, '\n'), filename
226	n/a	with open(filename, encoding=encoding) as f:
227	n/a	return f.read(), filename
228	n/a
229	n/a	def _indent(s, indent=4):
230	n/a	"""
231	n/a	Add the given number of space characters to the beginning of
232	n/a	every non-blank line in `s`, and return the result.
233	n/a	"""
234	n/a	# This regexp matches the start of non-blank lines:
235	n/a	return re.sub('(?m)^(?!$)', indent*' ', s)
236	n/a
237	n/a	def _exception_traceback(exc_info):
238	n/a	"""
239	n/a	Return a string containing a traceback message for the given
240	n/a	exc_info tuple (as returned by sys.exc_info()).
241	n/a	"""
242	n/a	# Get a traceback message.
243	n/a	excout = StringIO()
244	n/a	exc_type, exc_val, exc_tb = exc_info
245	n/a	traceback.print_exception(exc_type, exc_val, exc_tb, file=excout)
246	n/a	return excout.getvalue()
247	n/a
248	n/a	# Override some StringIO methods.
249	n/a	class _SpoofOut(StringIO):
250	n/a	def getvalue(self):
251	n/a	result = StringIO.getvalue(self)
252	n/a	# If anything at all was written, make sure there's a trailing
253	n/a	# newline. There's no way for the expected output to indicate
254	n/a	# that a trailing newline is missing.
255	n/a	if result and not result.endswith("\n"):
256	n/a	result += "\n"
257	n/a	return result
258	n/a
259	n/a	def truncate(self, size=None):
260	n/a	self.seek(size)
261	n/a	StringIO.truncate(self)
262	n/a
263	n/a	# Worst-case linear-time ellipsis matching.
264	n/a	def _ellipsis_match(want, got):
265	n/a	"""
266	n/a	Essentially the only subtle case:
267	n/a	>>> _ellipsis_match('aa...aa', 'aaa')
268	n/a	False
269	n/a	"""
270	n/a	if ELLIPSIS_MARKER not in want:
271	n/a	return want == got
272	n/a
273	n/a	# Find "the real" strings.
274	n/a	ws = want.split(ELLIPSIS_MARKER)
275	n/a	assert len(ws) >= 2
276	n/a
277	n/a	# Deal with exact matches possibly needed at one or both ends.
278	n/a	startpos, endpos = 0, len(got)
279	n/a	w = ws[0]
280	n/a	if w: # starts with exact match
281	n/a	if got.startswith(w):
282	n/a	startpos = len(w)
283	n/a	del ws[0]
284	n/a	else:
285	n/a	return False
286	n/a	w = ws[-1]
287	n/a	if w: # ends with exact match
288	n/a	if got.endswith(w):
289	n/a	endpos -= len(w)
290	n/a	del ws[-1]
291	n/a	else:
292	n/a	return False
293	n/a
294	n/a	if startpos > endpos:
295	n/a	# Exact end matches required more characters than we have, as in
296	n/a	# _ellipsis_match('aa...aa', 'aaa')
297	n/a	return False
298	n/a
299	n/a	# For the rest, we only need to find the leftmost non-overlapping
300	n/a	# match for each piece. If there's no overall match that way alone,
301	n/a	# there's no overall match period.
302	n/a	for w in ws:
303	n/a	# w may be '' at times, if there are consecutive ellipses, or
304	n/a	# due to an ellipsis at the start or end of `want`. That's OK.
305	n/a	# Search for an empty string succeeds, and doesn't change startpos.
306	n/a	startpos = got.find(w, startpos, endpos)
307	n/a	if startpos < 0:
308	n/a	return False
309	n/a	startpos += len(w)
310	n/a
311	n/a	return True
312	n/a
313	n/a	def _comment_line(line):
314	n/a	"Return a commented form of the given line"
315	n/a	line = line.rstrip()
316	n/a	if line:
317	n/a	return '# '+line
318	n/a	else:
319	n/a	return '#'
320	n/a
321	n/a	def _strip_exception_details(msg):
322	n/a	# Support for IGNORE_EXCEPTION_DETAIL.
323	n/a	# Get rid of everything except the exception name; in particular, drop
324	n/a	# the possibly dotted module path (if any) and the exception message (if
325	n/a	# any). We assume that a colon is never part of a dotted name, or of an
326	n/a	# exception name.
327	n/a	# E.g., given
328	n/a	# "foo.bar.MyError: la di da"
329	n/a	# return "MyError"
330	n/a	# Or for "abc.def" or "abc.def:\n" return "def".
331	n/a
332	n/a	start, end = 0, len(msg)
333	n/a	# The exception name must appear on the first line.
334	n/a	i = msg.find("\n")
335	n/a	if i >= 0:
336	n/a	end = i
337	n/a	# retain up to the first colon (if any)
338	n/a	i = msg.find(':', 0, end)
339	n/a	if i >= 0:
340	n/a	end = i
341	n/a	# retain just the exception name
342	n/a	i = msg.rfind('.', 0, end)
343	n/a	if i >= 0:
344	n/a	start = i+1
345	n/a	return msg[start: end]
346	n/a
347	n/a	class _OutputRedirectingPdb(pdb.Pdb):
348	n/a	"""
349	n/a	A specialized version of the python debugger that redirects stdout
350	n/a	to a given stream when interacting with the user. Stdout is not
351	n/a	redirected when traced code is executed.
352	n/a	"""
353	n/a	def __init__(self, out):
354	n/a	self.__out = out
355	n/a	self.__debugger_used = False
356	n/a	# do not play signal games in the pdb
357	n/a	pdb.Pdb.__init__(self, stdout=out, nosigint=True)
358	n/a	# still use input() to get user input
359	n/a	self.use_rawinput = 1
360	n/a
361	n/a	def set_trace(self, frame=None):
362	n/a	self.__debugger_used = True
363	n/a	if frame is None:
364	n/a	frame = sys._getframe().f_back
365	n/a	pdb.Pdb.set_trace(self, frame)
366	n/a
367	n/a	def set_continue(self):
368	n/a	# Calling set_continue unconditionally would break unit test
369	n/a	# coverage reporting, as Bdb.set_continue calls sys.settrace(None).
370	n/a	if self.__debugger_used:
371	n/a	pdb.Pdb.set_continue(self)
372	n/a
373	n/a	def trace_dispatch(self, *args):
374	n/a	# Redirect stdout to the given stream.
375	n/a	save_stdout = sys.stdout
376	n/a	sys.stdout = self.__out
377	n/a	# Call Pdb's trace dispatch method.
378	n/a	try:
379	n/a	return pdb.Pdb.trace_dispatch(self, *args)
380	n/a	finally:
381	n/a	sys.stdout = save_stdout
382	n/a
383	n/a	# [XX] Normalize with respect to os.path.pardir?
384	n/a	def _module_relative_path(module, test_path):
385	n/a	if not inspect.ismodule(module):
386	n/a	raise TypeError('Expected a module: %r' % module)
387	n/a	if test_path.startswith('/'):
388	n/a	raise ValueError('Module-relative files may not have absolute paths')
389	n/a
390	n/a	# Normalize the path. On Windows, replace "/" with "\".
391	n/a	test_path = os.path.join(*(test_path.split('/')))
392	n/a
393	n/a	# Find the base directory for the path.
394	n/a	if hasattr(module, '__file__'):
395	n/a	# A normal module/package
396	n/a	basedir = os.path.split(module.__file__)[0]
397	n/a	elif module.__name__ == '__main__':
398	n/a	# An interactive session.
399	n/a	if len(sys.argv)>0 and sys.argv[0] != '':
400	n/a	basedir = os.path.split(sys.argv[0])[0]
401	n/a	else:
402	n/a	basedir = os.curdir
403	n/a	else:
404	n/a	if hasattr(module, '__path__'):
405	n/a	for directory in module.__path__:
406	n/a	fullpath = os.path.join(directory, test_path)
407	n/a	if os.path.exists(fullpath):
408	n/a	return fullpath
409	n/a
410	n/a	# A module w/o __file__ (this includes builtins)
411	n/a	raise ValueError("Can't resolve paths relative to the module "
412	n/a	"%r (it has no __file__)"
413	n/a	% module.__name__)
414	n/a
415	n/a	# Combine the base directory and the test path.
416	n/a	return os.path.join(basedir, test_path)
417	n/a
418	n/a	######################################################################
419	n/a	## 2. Example & DocTest
420	n/a	######################################################################
421	n/a	## - An "example" is a <source, want> pair, where "source" is a
422	n/a	## fragment of source code, and "want" is the expected output for
423	n/a	## "source." The Example class also includes information about
424	n/a	## where the example was extracted from.
425	n/a	##
426	n/a	## - A "doctest" is a collection of examples, typically extracted from
427	n/a	## a string (such as an object's docstring). The DocTest class also
428	n/a	## includes information about where the string was extracted from.
429	n/a
430	n/a	class Example:
431	n/a	"""
432	n/a	A single doctest example, consisting of source code and expected
433	n/a	output. `Example` defines the following attributes:
434	n/a
435	n/a	- source: A single Python statement, always ending with a newline.
436	n/a	The constructor adds a newline if needed.
437	n/a
438	n/a	- want: The expected output from running the source code (either
439	n/a	from stdout, or a traceback in case of exception). `want` ends
440	n/a	with a newline unless it's empty, in which case it's an empty
441	n/a	string. The constructor adds a newline if needed.
442	n/a
443	n/a	- exc_msg: The exception message generated by the example, if
444	n/a	the example is expected to generate an exception; or `None` if
445	n/a	it is not expected to generate an exception. This exception
446	n/a	message is compared against the return value of
447	n/a	`traceback.format_exception_only()`. `exc_msg` ends with a
448	n/a	newline unless it's `None`. The constructor adds a newline
449	n/a	if needed.
450	n/a
451	n/a	- lineno: The line number within the DocTest string containing
452	n/a	this Example where the Example begins. This line number is
453	n/a	zero-based, with respect to the beginning of the DocTest.
454	n/a
455	n/a	- indent: The example's indentation in the DocTest string.
456	n/a	I.e., the number of space characters that precede the
457	n/a	example's first prompt.
458	n/a
459	n/a	- options: A dictionary mapping from option flags to True or
460	n/a	False, which is used to override default options for this
461	n/a	example. Any option flags not contained in this dictionary
462	n/a	are left at their default value (as specified by the
463	n/a	DocTestRunner's optionflags). By default, no options are set.
464	n/a	"""
465	n/a	def __init__(self, source, want, exc_msg=None, lineno=0, indent=0,
466	n/a	options=None):
467	n/a	# Normalize inputs.
468	n/a	if not source.endswith('\n'):
469	n/a	source += '\n'
470	n/a	if want and not want.endswith('\n'):
471	n/a	want += '\n'
472	n/a	if exc_msg is not None and not exc_msg.endswith('\n'):
473	n/a	exc_msg += '\n'
474	n/a	# Store properties.
475	n/a	self.source = source
476	n/a	self.want = want
477	n/a	self.lineno = lineno
478	n/a	self.indent = indent
479	n/a	if options is None: options = {}
480	n/a	self.options = options
481	n/a	self.exc_msg = exc_msg
482	n/a
483	n/a	def __eq__(self, other):
484	n/a	if type(self) is not type(other):
485	n/a	return NotImplemented
486	n/a
487	n/a	return self.source == other.source and \
488	n/a	self.want == other.want and \
489	n/a	self.lineno == other.lineno and \
490	n/a	self.indent == other.indent and \
491	n/a	self.options == other.options and \
492	n/a	self.exc_msg == other.exc_msg
493	n/a
494	n/a	def __hash__(self):
495	n/a	return hash((self.source, self.want, self.lineno, self.indent,
496	n/a	self.exc_msg))
497	n/a
498	n/a	class DocTest:
499	n/a	"""
500	n/a	A collection of doctest examples that should be run in a single
501	n/a	namespace. Each `DocTest` defines the following attributes:
502	n/a
503	n/a	- examples: the list of examples.
504	n/a
505	n/a	- globs: The namespace (aka globals) that the examples should
506	n/a	be run in.
507	n/a
508	n/a	- name: A name identifying the DocTest (typically, the name of
509	n/a	the object whose docstring this DocTest was extracted from).
510	n/a
511	n/a	- filename: The name of the file that this DocTest was extracted
512	n/a	from, or `None` if the filename is unknown.
513	n/a
514	n/a	- lineno: The line number within filename where this DocTest
515	n/a	begins, or `None` if the line number is unavailable. This
516	n/a	line number is zero-based, with respect to the beginning of
517	n/a	the file.
518	n/a
519	n/a	- docstring: The string that the examples were extracted from,
520	n/a	or `None` if the string is unavailable.
521	n/a	"""
522	n/a	def __init__(self, examples, globs, name, filename, lineno, docstring):
523	n/a	"""
524	n/a	Create a new DocTest containing the given examples. The
525	n/a	DocTest's globals are initialized with a copy of `globs`.
526	n/a	"""
527	n/a	assert not isinstance(examples, str), \
528	n/a	"DocTest no longer accepts str; use DocTestParser instead"
529	n/a	self.examples = examples
530	n/a	self.docstring = docstring
531	n/a	self.globs = globs.copy()
532	n/a	self.name = name
533	n/a	self.filename = filename
534	n/a	self.lineno = lineno
535	n/a
536	n/a	def __repr__(self):
537	n/a	if len(self.examples) == 0:
538	n/a	examples = 'no examples'
539	n/a	elif len(self.examples) == 1:
540	n/a	examples = '1 example'
541	n/a	else:
542	n/a	examples = '%d examples' % len(self.examples)
543	n/a	return ('<%s %s from %s:%s (%s)>' %
544	n/a	(self.__class__.__name__,
545	n/a	self.name, self.filename, self.lineno, examples))
546	n/a
547	n/a	def __eq__(self, other):
548	n/a	if type(self) is not type(other):
549	n/a	return NotImplemented
550	n/a
551	n/a	return self.examples == other.examples and \
552	n/a	self.docstring == other.docstring and \
553	n/a	self.globs == other.globs and \
554	n/a	self.name == other.name and \
555	n/a	self.filename == other.filename and \
556	n/a	self.lineno == other.lineno
557	n/a
558	n/a	def __hash__(self):
559	n/a	return hash((self.docstring, self.name, self.filename, self.lineno))
560	n/a
561	n/a	# This lets us sort tests by name:
562	n/a	def __lt__(self, other):
563	n/a	if not isinstance(other, DocTest):
564	n/a	return NotImplemented
565	n/a	return ((self.name, self.filename, self.lineno, id(self))
566	n/a	<
567	n/a	(other.name, other.filename, other.lineno, id(other)))
568	n/a
569	n/a	######################################################################
570	n/a	## 3. DocTestParser
571	n/a	######################################################################
572	n/a
573	n/a	class DocTestParser:
574	n/a	"""
575	n/a	A class used to parse strings containing doctest examples.
576	n/a	"""
577	n/a	# This regular expression is used to find doctest examples in a
578	n/a	# string. It defines three groups: `source` is the source code
579	n/a	# (including leading indentation and prompts); `indent` is the
580	n/a	# indentation of the first (PS1) line of the source code; and
581	n/a	# `want` is the expected output (including leading indentation).
582	n/a	_EXAMPLE_RE = re.compile(r'''
583	n/a	# Source consists of a PS1 line followed by zero or more PS2 lines.
584	n/a	(?P<source>
585	n/a	(?:^(?P<indent> [ ]) >>> .) # PS1 line
586	n/a	(?:\n [ ]* \.\.\. .)) # PS2 lines
587	n/a	\n?
588	n/a	# Want consists of any non-blank lines that do not start with PS1.
589	n/a	(?P<want> (?:(?![ ]*$) # Not a blank line
590	n/a	(?![ ]*>>>) # Not a line starting with PS1
591	n/a	.+$\n? # But any other line
592	n/a	)*)
593	n/a	''', re.MULTILINE \| re.VERBOSE)
594	n/a
595	n/a	# A regular expression for handling `want` strings that contain
596	n/a	# expected exceptions. It divides `want` into three pieces:
597	n/a	# - the traceback header line (`hdr`)
598	n/a	# - the traceback stack (`stack`)
599	n/a	# - the exception message (`msg`), as generated by
600	n/a	# traceback.format_exception_only()
601	n/a	# `msg` may have multiple lines. We assume/require that the
602	n/a	# exception message is the first non-indented line starting with a word
603	n/a	# character following the traceback header line.
604	n/a	_EXCEPTION_RE = re.compile(r"""
605	n/a	# Grab the traceback header. Different versions of Python have
606	n/a	# said different things on the first traceback line.
607	n/a	^(?P<hdr> Traceback\ \(
608	n/a	(?: most\ recent\ call\ last
609	n/a	\| innermost\ last
610	n/a	) \) :
611	n/a	)
612	n/a	\s* $ # toss trailing whitespace on the header.
613	n/a	(?P<stack> .*?) # don't blink: absorb stuff until...
614	n/a	^ (?P<msg> \w+ .) # a line starts* with alphanum.
615	n/a	""", re.VERBOSE \| re.MULTILINE \| re.DOTALL)
616	n/a
617	n/a	# A callable returning a true value iff its argument is a blank line
618	n/a	# or contains a single comment.
619	n/a	_IS_BLANK_OR_COMMENT = re.compile(r'^[ ](#.)?$').match
620	n/a
621	n/a	def parse(self, string, name='<string>'):
622	n/a	"""
623	n/a	Divide the given string into examples and intervening text,
624	n/a	and return them as a list of alternating Examples and strings.
625	n/a	Line numbers for the Examples are 0-based. The optional
626	n/a	argument `name` is a name identifying this string, and is only
627	n/a	used for error messages.
628	n/a	"""
629	n/a	string = string.expandtabs()
630	n/a	# If all lines begin with the same indentation, then strip it.
631	n/a	min_indent = self._min_indent(string)
632	n/a	if min_indent > 0:
633	n/a	string = '\n'.join([l[min_indent:] for l in string.split('\n')])
634	n/a
635	n/a	output = []
636	n/a	charno, lineno = 0, 0
637	n/a	# Find all doctest examples in the string:
638	n/a	for m in self._EXAMPLE_RE.finditer(string):
639	n/a	# Add the pre-example text to `output`.
640	n/a	output.append(string[charno:m.start()])
641	n/a	# Update lineno (lines before this example)
642	n/a	lineno += string.count('\n', charno, m.start())
643	n/a	# Extract info from the regexp match.
644	n/a	(source, options, want, exc_msg) = \
645	n/a	self._parse_example(m, name, lineno)
646	n/a	# Create an Example, and add it to the list.
647	n/a	if not self._IS_BLANK_OR_COMMENT(source):
648	n/a	output.append( Example(source, want, exc_msg,
649	n/a	lineno=lineno,
650	n/a	indent=min_indent+len(m.group('indent')),
651	n/a	options=options) )
652	n/a	# Update lineno (lines inside this example)
653	n/a	lineno += string.count('\n', m.start(), m.end())
654	n/a	# Update charno.
655	n/a	charno = m.end()
656	n/a	# Add any remaining post-example text to `output`.
657	n/a	output.append(string[charno:])
658	n/a	return output
659	n/a
660	n/a	def get_doctest(self, string, globs, name, filename, lineno):
661	n/a	"""
662	n/a	Extract all doctest examples from the given string, and
663	n/a	collect them into a `DocTest` object.
664	n/a
665	n/a	`globs`, `name`, `filename`, and `lineno` are attributes for
666	n/a	the new `DocTest` object. See the documentation for `DocTest`
667	n/a	for more information.
668	n/a	"""
669	n/a	return DocTest(self.get_examples(string, name), globs,
670	n/a	name, filename, lineno, string)
671	n/a
672	n/a	def get_examples(self, string, name='<string>'):
673	n/a	"""
674	n/a	Extract all doctest examples from the given string, and return
675	n/a	them as a list of `Example` objects. Line numbers are
676	n/a	0-based, because it's most common in doctests that nothing
677	n/a	interesting appears on the same line as opening triple-quote,
678	n/a	and so the first interesting line is called \"line 1\" then.
679	n/a
680	n/a	The optional argument `name` is a name identifying this
681	n/a	string, and is only used for error messages.
682	n/a	"""
683	n/a	return [x for x in self.parse(string, name)
684	n/a	if isinstance(x, Example)]
685	n/a
686	n/a	def _parse_example(self, m, name, lineno):
687	n/a	"""
688	n/a	Given a regular expression match from `_EXAMPLE_RE` (`m`),
689	n/a	return a pair `(source, want)`, where `source` is the matched
690	n/a	example's source code (with prompts and indentation stripped);
691	n/a	and `want` is the example's expected output (with indentation
692	n/a	stripped).
693	n/a
694	n/a	`name` is the string's name, and `lineno` is the line number
695	n/a	where the example starts; both are used for error messages.
696	n/a	"""
697	n/a	# Get the example's indentation level.
698	n/a	indent = len(m.group('indent'))
699	n/a
700	n/a	# Divide source into lines; check that they're properly
701	n/a	# indented; and then strip their indentation & prompts.
702	n/a	source_lines = m.group('source').split('\n')
703	n/a	self._check_prompt_blank(source_lines, indent, name, lineno)
704	n/a	self._check_prefix(source_lines[1:], ' '*indent + '.', name, lineno)
705	n/a	source = '\n'.join([sl[indent+4:] for sl in source_lines])
706	n/a
707	n/a	# Divide want into lines; check that it's properly indented; and
708	n/a	# then strip the indentation. Spaces before the last newline should
709	n/a	# be preserved, so plain rstrip() isn't good enough.
710	n/a	want = m.group('want')
711	n/a	want_lines = want.split('\n')
712	n/a	if len(want_lines) > 1 and re.match(r' *$', want_lines[-1]):
713	n/a	del want_lines[-1] # forget final newline & spaces after it
714	n/a	self._check_prefix(want_lines, ' '*indent, name,
715	n/a	lineno + len(source_lines))
716	n/a	want = '\n'.join([wl[indent:] for wl in want_lines])
717	n/a
718	n/a	# If `want` contains a traceback message, then extract it.
719	n/a	m = self._EXCEPTION_RE.match(want)
720	n/a	if m:
721	n/a	exc_msg = m.group('msg')
722	n/a	else:
723	n/a	exc_msg = None
724	n/a
725	n/a	# Extract options from the source.
726	n/a	options = self._find_options(source, name, lineno)
727	n/a
728	n/a	return source, options, want, exc_msg
729	n/a
730	n/a	# This regular expression looks for option directives in the
731	n/a	# source code of an example. Option directives are comments
732	n/a	# starting with "doctest:". Warning: this may give false
733	n/a	# positives for string-literals that contain the string
734	n/a	# "#doctest:". Eliminating these false positives would require
735	n/a	# actually parsing the string; but we limit them by ignoring any
736	n/a	# line containing "#doctest:" that is followed by a quote mark.
737	n/a	_OPTION_DIRECTIVE_RE = re.compile(r'#\sdoctest:\s([^\n\'"]*)$',
738	n/a	re.MULTILINE)
739	n/a
740	n/a	def _find_options(self, source, name, lineno):
741	n/a	"""
742	n/a	Return a dictionary containing option overrides extracted from
743	n/a	option directives in the given source string.
744	n/a
745	n/a	`name` is the string's name, and `lineno` is the line number
746	n/a	where the example starts; both are used for error messages.
747	n/a	"""
748	n/a	options = {}
749	n/a	# (note: with the current regexp, this will match at most once:)
750	n/a	for m in self._OPTION_DIRECTIVE_RE.finditer(source):
751	n/a	option_strings = m.group(1).replace(',', ' ').split()
752	n/a	for option in option_strings:
753	n/a	if (option[0] not in '+-' or
754	n/a	option[1:] not in OPTIONFLAGS_BY_NAME):
755	n/a	raise ValueError('line %r of the doctest for %s '
756	n/a	'has an invalid option: %r' %
757	n/a	(lineno+1, name, option))
758	n/a	flag = OPTIONFLAGS_BY_NAME[option[1:]]
759	n/a	options[flag] = (option[0] == '+')
760	n/a	if options and self._IS_BLANK_OR_COMMENT(source):
761	n/a	raise ValueError('line %r of the doctest for %s has an option '
762	n/a	'directive on a line with no example: %r' %
763	n/a	(lineno, name, source))
764	n/a	return options
765	n/a
766	n/a	# This regular expression finds the indentation of every non-blank
767	n/a	# line in a string.
768	n/a	_INDENT_RE = re.compile(r'^([ ]*)(?=\S)', re.MULTILINE)
769	n/a
770	n/a	def _min_indent(self, s):
771	n/a	"Return the minimum indentation of any non-blank line in `s`"
772	n/a	indents = [len(indent) for indent in self._INDENT_RE.findall(s)]
773	n/a	if len(indents) > 0:
774	n/a	return min(indents)
775	n/a	else:
776	n/a	return 0
777	n/a
778	n/a	def _check_prompt_blank(self, lines, indent, name, lineno):
779	n/a	"""
780	n/a	Given the lines of a source string (including prompts and
781	n/a	leading indentation), check to make sure that every prompt is
782	n/a	followed by a space character. If any line is not followed by
783	n/a	a space character, then raise ValueError.
784	n/a	"""
785	n/a	for i, line in enumerate(lines):
786	n/a	if len(line) >= indent+4 and line[indent+3] != ' ':
787	n/a	raise ValueError('line %r of the docstring for %s '
788	n/a	'lacks blank after %s: %r' %
789	n/a	(lineno+i+1, name,
790	n/a	line[indent:indent+3], line))
791	n/a
792	n/a	def _check_prefix(self, lines, prefix, name, lineno):
793	n/a	"""
794	n/a	Check that every line in the given list starts with the given
795	n/a	prefix; if any line does not, then raise a ValueError.
796	n/a	"""
797	n/a	for i, line in enumerate(lines):
798	n/a	if line and not line.startswith(prefix):
799	n/a	raise ValueError('line %r of the docstring for %s has '
800	n/a	'inconsistent leading whitespace: %r' %
801	n/a	(lineno+i+1, name, line))
802	n/a
803	n/a
804	n/a	######################################################################
805	n/a	## 4. DocTest Finder
806	n/a	######################################################################
807	n/a
808	n/a	class DocTestFinder:
809	n/a	"""
810	n/a	A class used to extract the DocTests that are relevant to a given
811	n/a	object, from its docstring and the docstrings of its contained
812	n/a	objects. Doctests can currently be extracted from the following
813	n/a	object types: modules, functions, classes, methods, staticmethods,
814	n/a	classmethods, and properties.
815	n/a	"""
816	n/a
817	n/a	def __init__(self, verbose=False, parser=DocTestParser(),
818	n/a	recurse=True, exclude_empty=True):
819	n/a	"""
820	n/a	Create a new doctest finder.
821	n/a
822	n/a	The optional argument `parser` specifies a class or
823	n/a	function that should be used to create new DocTest objects (or
824	n/a	objects that implement the same interface as DocTest). The
825	n/a	signature for this factory function should match the signature
826	n/a	of the DocTest constructor.
827	n/a
828	n/a	If the optional argument `recurse` is false, then `find` will
829	n/a	only examine the given object, and not any contained objects.
830	n/a
831	n/a	If the optional argument `exclude_empty` is false, then `find`
832	n/a	will include tests for objects with empty docstrings.
833	n/a	"""
834	n/a	self._parser = parser
835	n/a	self._verbose = verbose
836	n/a	self._recurse = recurse
837	n/a	self._exclude_empty = exclude_empty
838	n/a
839	n/a	def find(self, obj, name=None, module=None, globs=None, extraglobs=None):
840	n/a	"""
841	n/a	Return a list of the DocTests that are defined by the given
842	n/a	object's docstring, or by any of its contained objects'
843	n/a	docstrings.
844	n/a
845	n/a	The optional parameter `module` is the module that contains
846	n/a	the given object. If the module is not specified or is None, then
847	n/a	the test finder will attempt to automatically determine the
848	n/a	correct module. The object's module is used:
849	n/a
850	n/a	- As a default namespace, if `globs` is not specified.
851	n/a	- To prevent the DocTestFinder from extracting DocTests
852	n/a	from objects that are imported from other modules.
853	n/a	- To find the name of the file containing the object.
854	n/a	- To help find the line number of the object within its
855	n/a	file.
856	n/a
857	n/a	Contained objects whose module does not match `module` are ignored.
858	n/a
859	n/a	If `module` is False, no attempt to find the module will be made.
860	n/a	This is obscure, of use mostly in tests: if `module` is False, or
861	n/a	is None but cannot be found automatically, then all objects are
862	n/a	considered to belong to the (non-existent) module, so all contained
863	n/a	objects will (recursively) be searched for doctests.
864	n/a
865	n/a	The globals for each DocTest is formed by combining `globs`
866	n/a	and `extraglobs` (bindings in `extraglobs` override bindings
867	n/a	in `globs`). A new copy of the globals dictionary is created
868	n/a	for each DocTest. If `globs` is not specified, then it
869	n/a	defaults to the module's `__dict__`, if specified, or {}
870	n/a	otherwise. If `extraglobs` is not specified, then it defaults
871	n/a	to {}.
872	n/a
873	n/a	"""
874	n/a	# If name was not specified, then extract it from the object.
875	n/a	if name is None:
876	n/a	name = getattr(obj, '__name__', None)
877	n/a	if name is None:
878	n/a	raise ValueError("DocTestFinder.find: name must be given "
879	n/a	"when obj.__name__ doesn't exist: %r" %
880	n/a	(type(obj),))
881	n/a
882	n/a	# Find the module that contains the given object (if obj is
883	n/a	# a module, then module=obj.). Note: this may fail, in which
884	n/a	# case module will be None.
885	n/a	if module is False:
886	n/a	module = None
887	n/a	elif module is None:
888	n/a	module = inspect.getmodule(obj)
889	n/a
890	n/a	# Read the module's source code. This is used by
891	n/a	# DocTestFinder._find_lineno to find the line number for a
892	n/a	# given object's docstring.
893	n/a	try:
894	n/a	file = inspect.getsourcefile(obj)
895	n/a	except TypeError:
896	n/a	source_lines = None
897	n/a	else:
898	n/a	if not file:
899	n/a	# Check to see if it's one of our special internal "files"
900	n/a	# (see __patched_linecache_getlines).
901	n/a	file = inspect.getfile(obj)
902	n/a	if not file[0]+file[-2:] == '<]>': file = None
903	n/a	if file is None:
904	n/a	source_lines = None
905	n/a	else:
906	n/a	if module is not None:
907	n/a	# Supply the module globals in case the module was
908	n/a	# originally loaded via a PEP 302 loader and
909	n/a	# file is not a valid filesystem path
910	n/a	source_lines = linecache.getlines(file, module.__dict__)
911	n/a	else:
912	n/a	# No access to a loader, so assume it's a normal
913	n/a	# filesystem path
914	n/a	source_lines = linecache.getlines(file)
915	n/a	if not source_lines:
916	n/a	source_lines = None
917	n/a
918	n/a	# Initialize globals, and merge in extraglobs.
919	n/a	if globs is None:
920	n/a	if module is None:
921	n/a	globs = {}
922	n/a	else:
923	n/a	globs = module.__dict__.copy()
924	n/a	else:
925	n/a	globs = globs.copy()
926	n/a	if extraglobs is not None:
927	n/a	globs.update(extraglobs)
928	n/a	if '__name__' not in globs:
929	n/a	globs['__name__'] = '__main__' # provide a default module name
930	n/a
931	n/a	# Recursively explore `obj`, extracting DocTests.
932	n/a	tests = []
933	n/a	self._find(tests, obj, name, module, source_lines, globs, {})
934	n/a	# Sort the tests by alpha order of names, for consistency in
935	n/a	# verbose-mode output. This was a feature of doctest in Pythons
936	n/a	# <= 2.3 that got lost by accident in 2.4. It was repaired in
937	n/a	# 2.4.4 and 2.5.
938	n/a	tests.sort()
939	n/a	return tests
940	n/a
941	n/a	def _from_module(self, module, object):
942	n/a	"""
943	n/a	Return true if the given object is defined in the given
944	n/a	module.
945	n/a	"""
946	n/a	if module is None:
947	n/a	return True
948	n/a	elif inspect.getmodule(object) is not None:
949	n/a	return module is inspect.getmodule(object)
950	n/a	elif inspect.isfunction(object):
951	n/a	return module.__dict__ is object.__globals__
952	n/a	elif inspect.ismethoddescriptor(object):
953	n/a	if hasattr(object, '__objclass__'):
954	n/a	obj_mod = object.__objclass__.__module__
955	n/a	elif hasattr(object, '__module__'):
956	n/a	obj_mod = object.__module__
957	n/a	else:
958	n/a	return True # [XX] no easy way to tell otherwise
959	n/a	return module.__name__ == obj_mod
960	n/a	elif inspect.isclass(object):
961	n/a	return module.__name__ == object.__module__
962	n/a	elif hasattr(object, '__module__'):
963	n/a	return module.__name__ == object.__module__
964	n/a	elif isinstance(object, property):
965	n/a	return True # [XX] no way not be sure.
966	n/a	else:
967	n/a	raise ValueError("object must be a class or function")
968	n/a
969	n/a	def _find(self, tests, obj, name, module, source_lines, globs, seen):
970	n/a	"""
971	n/a	Find tests for the given object and any contained objects, and
972	n/a	add them to `tests`.
973	n/a	"""
974	n/a	if self._verbose:
975	n/a	print('Finding tests in %s' % name)
976	n/a
977	n/a	# If we've already processed this object, then ignore it.
978	n/a	if id(obj) in seen:
979	n/a	return
980	n/a	seen[id(obj)] = 1
981	n/a
982	n/a	# Find a test for this object, and add it to the list of tests.
983	n/a	test = self._get_test(obj, name, module, globs, source_lines)
984	n/a	if test is not None:
985	n/a	tests.append(test)
986	n/a
987	n/a	# Look for tests in a module's contained objects.
988	n/a	if inspect.ismodule(obj) and self._recurse:
989	n/a	for valname, val in obj.__dict__.items():
990	n/a	valname = '%s.%s' % (name, valname)
991	n/a	# Recurse to functions & classes.
992	n/a	if ((inspect.isroutine(inspect.unwrap(val))
993	n/a	or inspect.isclass(val)) and
994	n/a	self._from_module(module, val)):
995	n/a	self._find(tests, val, valname, module, source_lines,
996	n/a	globs, seen)
997	n/a
998	n/a	# Look for tests in a module's __test__ dictionary.
999	n/a	if inspect.ismodule(obj) and self._recurse:
1000	n/a	for valname, val in getattr(obj, '__test__', {}).items():
1001	n/a	if not isinstance(valname, str):
1002	n/a	raise ValueError("DocTestFinder.find: __test__ keys "
1003	n/a	"must be strings: %r" %
1004	n/a	(type(valname),))
1005	n/a	if not (inspect.isroutine(val) or inspect.isclass(val) or
1006	n/a	inspect.ismodule(val) or isinstance(val, str)):
1007	n/a	raise ValueError("DocTestFinder.find: __test__ values "
1008	n/a	"must be strings, functions, methods, "
1009	n/a	"classes, or modules: %r" %
1010	n/a	(type(val),))
1011	n/a	valname = '%s.__test__.%s' % (name, valname)
1012	n/a	self._find(tests, val, valname, module, source_lines,
1013	n/a	globs, seen)
1014	n/a
1015	n/a	# Look for tests in a class's contained objects.
1016	n/a	if inspect.isclass(obj) and self._recurse:
1017	n/a	for valname, val in obj.__dict__.items():
1018	n/a	# Special handling for staticmethod/classmethod.
1019	n/a	if isinstance(val, staticmethod):
1020	n/a	val = getattr(obj, valname)
1021	n/a	if isinstance(val, classmethod):
1022	n/a	val = getattr(obj, valname).__func__
1023	n/a
1024	n/a	# Recurse to methods, properties, and nested classes.
1025	n/a	if ((inspect.isroutine(val) or inspect.isclass(val) or
1026	n/a	isinstance(val, property)) and
1027	n/a	self._from_module(module, val)):
1028	n/a	valname = '%s.%s' % (name, valname)
1029	n/a	self._find(tests, val, valname, module, source_lines,
1030	n/a	globs, seen)
1031	n/a
1032	n/a	def _get_test(self, obj, name, module, globs, source_lines):
1033	n/a	"""
1034	n/a	Return a DocTest for the given object, if it defines a docstring;
1035	n/a	otherwise, return None.
1036	n/a	"""
1037	n/a	# Extract the object's docstring. If it doesn't have one,
1038	n/a	# then return None (no test for this object).
1039	n/a	if isinstance(obj, str):
1040	n/a	docstring = obj
1041	n/a	else:
1042	n/a	try:
1043	n/a	if obj.__doc__ is None:
1044	n/a	docstring = ''
1045	n/a	else:
1046	n/a	docstring = obj.__doc__
1047	n/a	if not isinstance(docstring, str):
1048	n/a	docstring = str(docstring)
1049	n/a	except (TypeError, AttributeError):
1050	n/a	docstring = ''
1051	n/a
1052	n/a	# Find the docstring's location in the file.
1053	n/a	lineno = self._find_lineno(obj, source_lines)
1054	n/a
1055	n/a	# Don't bother if the docstring is empty.
1056	n/a	if self._exclude_empty and not docstring:
1057	n/a	return None
1058	n/a
1059	n/a	# Return a DocTest for this object.
1060	n/a	if module is None:
1061	n/a	filename = None
1062	n/a	else:
1063	n/a	filename = getattr(module, '__file__', module.__name__)
1064	n/a	if filename[-4:] == ".pyc":
1065	n/a	filename = filename[:-1]
1066	n/a	return self._parser.get_doctest(docstring, globs, name,
1067	n/a	filename, lineno)
1068	n/a
1069	n/a	def _find_lineno(self, obj, source_lines):
1070	n/a	"""
1071	n/a	Return a line number of the given object's docstring. Note:
1072	n/a	this method assumes that the object has a docstring.
1073	n/a	"""
1074	n/a	lineno = None
1075	n/a
1076	n/a	# Find the line number for modules.
1077	n/a	if inspect.ismodule(obj):
1078	n/a	lineno = 0
1079	n/a
1080	n/a	# Find the line number for classes.
1081	n/a	# Note: this could be fooled if a class is defined multiple
1082	n/a	# times in a single file.
1083	n/a	if inspect.isclass(obj):
1084	n/a	if source_lines is None:
1085	n/a	return None
1086	n/a	pat = re.compile(r'^\sclass\s%s\b' %
1087	n/a	getattr(obj, '__name__', '-'))
1088	n/a	for i, line in enumerate(source_lines):
1089	n/a	if pat.match(line):
1090	n/a	lineno = i
1091	n/a	break
1092	n/a
1093	n/a	# Find the line number for functions & methods.
1094	n/a	if inspect.ismethod(obj): obj = obj.__func__
1095	n/a	if inspect.isfunction(obj): obj = obj.__code__
1096	n/a	if inspect.istraceback(obj): obj = obj.tb_frame
1097	n/a	if inspect.isframe(obj): obj = obj.f_code
1098	n/a	if inspect.iscode(obj):
1099	n/a	lineno = getattr(obj, 'co_firstlineno', None)-1
1100	n/a
1101	n/a	# Find the line number where the docstring starts. Assume
1102	n/a	# that it's the first line that begins with a quote mark.
1103	n/a	# Note: this could be fooled by a multiline function
1104	n/a	# signature, where a continuation line begins with a quote
1105	n/a	# mark.
1106	n/a	if lineno is not None:
1107	n/a	if source_lines is None:
1108	n/a	return lineno+1
1109	n/a	pat = re.compile(r'(^\|.:)\s\w*("\|\')')
1110	n/a	for lineno in range(lineno, len(source_lines)):
1111	n/a	if pat.match(source_lines[lineno]):
1112	n/a	return lineno
1113	n/a
1114	n/a	# We couldn't find the line number.
1115	n/a	return None
1116	n/a
1117	n/a	######################################################################
1118	n/a	## 5. DocTest Runner
1119	n/a	######################################################################
1120	n/a
1121	n/a	class DocTestRunner:
1122	n/a	"""
1123	n/a	A class used to run DocTest test cases, and accumulate statistics.
1124	n/a	The `run` method is used to process a single DocTest case. It
1125	n/a	returns a tuple `(f, t)`, where `t` is the number of test cases
1126	n/a	tried, and `f` is the number of test cases that failed.
1127	n/a
1128	n/a	>>> tests = DocTestFinder().find(_TestClass)
1129	n/a	>>> runner = DocTestRunner(verbose=False)
1130	n/a	>>> tests.sort(key = lambda test: test.name)
1131	n/a	>>> for test in tests:
1132	n/a	... print(test.name, '->', runner.run(test))
1133	n/a	_TestClass -> TestResults(failed=0, attempted=2)
1134	n/a	_TestClass.__init__ -> TestResults(failed=0, attempted=2)
1135	n/a	_TestClass.get -> TestResults(failed=0, attempted=2)
1136	n/a	_TestClass.square -> TestResults(failed=0, attempted=1)
1137	n/a
1138	n/a	The `summarize` method prints a summary of all the test cases that
1139	n/a	have been run by the runner, and returns an aggregated `(f, t)`
1140	n/a	tuple:
1141	n/a
1142	n/a	>>> runner.summarize(verbose=1)
1143	n/a	4 items passed all tests:
1144	n/a	2 tests in _TestClass
1145	n/a	2 tests in _TestClass.__init__
1146	n/a	2 tests in _TestClass.get
1147	n/a	1 tests in _TestClass.square
1148	n/a	7 tests in 4 items.
1149	n/a	7 passed and 0 failed.
1150	n/a	Test passed.
1151	n/a	TestResults(failed=0, attempted=7)
1152	n/a
1153	n/a	The aggregated number of tried examples and failed examples is
1154	n/a	also available via the `tries` and `failures` attributes:
1155	n/a
1156	n/a	>>> runner.tries
1157	n/a	7
1158	n/a	>>> runner.failures
1159	n/a	0
1160	n/a
1161	n/a	The comparison between expected outputs and actual outputs is done
1162	n/a	by an `OutputChecker`. This comparison may be customized with a
1163	n/a	number of option flags; see the documentation for `testmod` for
1164	n/a	more information. If the option flags are insufficient, then the
1165	n/a	comparison may also be customized by passing a subclass of
1166	n/a	`OutputChecker` to the constructor.
1167	n/a
1168	n/a	The test runner's display output can be controlled in two ways.
1169	n/a	First, an output function (`out) can be passed to
1170	n/a	`TestRunner.run`; this function will be called with strings that
1171	n/a	should be displayed. It defaults to `sys.stdout.write`. If
1172	n/a	capturing the output is not sufficient, then the display output
1173	n/a	can be also customized by subclassing DocTestRunner, and
1174	n/a	overriding the methods `report_start`, `report_success`,
1175	n/a	`report_unexpected_exception`, and `report_failure`.
1176	n/a	"""
1177	n/a	# This divider string is used to separate failure messages, and to
1178	n/a	# separate sections of the summary.
1179	n/a	DIVIDER = "" 70
1180	n/a
1181	n/a	def __init__(self, checker=None, verbose=None, optionflags=0):
1182	n/a	"""
1183	n/a	Create a new test runner.
1184	n/a
1185	n/a	Optional keyword arg `checker` is the `OutputChecker` that
1186	n/a	should be used to compare the expected outputs and actual
1187	n/a	outputs of doctest examples.
1188	n/a
1189	n/a	Optional keyword arg 'verbose' prints lots of stuff if true,
1190	n/a	only failures if false; by default, it's true iff '-v' is in
1191	n/a	sys.argv.
1192	n/a
1193	n/a	Optional argument `optionflags` can be used to control how the
1194	n/a	test runner compares expected output to actual output, and how
1195	n/a	it displays failures. See the documentation for `testmod` for
1196	n/a	more information.
1197	n/a	"""
1198	n/a	self._checker = checker or OutputChecker()
1199	n/a	if verbose is None:
1200	n/a	verbose = '-v' in sys.argv
1201	n/a	self._verbose = verbose
1202	n/a	self.optionflags = optionflags
1203	n/a	self.original_optionflags = optionflags
1204	n/a
1205	n/a	# Keep track of the examples we've run.
1206	n/a	self.tries = 0
1207	n/a	self.failures = 0
1208	n/a	self._name2ft = {}
1209	n/a
1210	n/a	# Create a fake output target for capturing doctest output.
1211	n/a	self._fakeout = _SpoofOut()
1212	n/a
1213	n/a	#/////////////////////////////////////////////////////////////////
1214	n/a	# Reporting methods
1215	n/a	#/////////////////////////////////////////////////////////////////
1216	n/a
1217	n/a	def report_start(self, out, test, example):
1218	n/a	"""
1219	n/a	Report that the test runner is about to process the given
1220	n/a	example. (Only displays a message if verbose=True)
1221	n/a	"""
1222	n/a	if self._verbose:
1223	n/a	if example.want:
1224	n/a	out('Trying:\n' + _indent(example.source) +
1225	n/a	'Expecting:\n' + _indent(example.want))
1226	n/a	else:
1227	n/a	out('Trying:\n' + _indent(example.source) +
1228	n/a	'Expecting nothing\n')
1229	n/a
1230	n/a	def report_success(self, out, test, example, got):
1231	n/a	"""
1232	n/a	Report that the given example ran successfully. (Only
1233	n/a	displays a message if verbose=True)
1234	n/a	"""
1235	n/a	if self._verbose:
1236	n/a	out("ok\n")
1237	n/a
1238	n/a	def report_failure(self, out, test, example, got):
1239	n/a	"""
1240	n/a	Report that the given example failed.
1241	n/a	"""
1242	n/a	out(self._failure_header(test, example) +
1243	n/a	self._checker.output_difference(example, got, self.optionflags))
1244	n/a
1245	n/a	def report_unexpected_exception(self, out, test, example, exc_info):
1246	n/a	"""
1247	n/a	Report that the given example raised an unexpected exception.
1248	n/a	"""
1249	n/a	out(self._failure_header(test, example) +
1250	n/a	'Exception raised:\n' + _indent(_exception_traceback(exc_info)))
1251	n/a
1252	n/a	def _failure_header(self, test, example):
1253	n/a	out = [self.DIVIDER]
1254	n/a	if test.filename:
1255	n/a	if test.lineno is not None and example.lineno is not None:
1256	n/a	lineno = test.lineno + example.lineno + 1
1257	n/a	else:
1258	n/a	lineno = '?'
1259	n/a	out.append('File "%s", line %s, in %s' %
1260	n/a	(test.filename, lineno, test.name))
1261	n/a	else:
1262	n/a	out.append('Line %s, in %s' % (example.lineno+1, test.name))
1263	n/a	out.append('Failed example:')
1264	n/a	source = example.source
1265	n/a	out.append(_indent(source))
1266	n/a	return '\n'.join(out)
1267	n/a
1268	n/a	#/////////////////////////////////////////////////////////////////
1269	n/a	# DocTest Running
1270	n/a	#/////////////////////////////////////////////////////////////////
1271	n/a
1272	n/a	def __run(self, test, compileflags, out):
1273	n/a	"""
1274	n/a	Run the examples in `test`. Write the outcome of each example
1275	n/a	with one of the `DocTestRunner.report_*` methods, using the
1276	n/a	writer function `out`. `compileflags` is the set of compiler
1277	n/a	flags that should be used to execute examples. Return a tuple
1278	n/a	`(f, t)`, where `t` is the number of examples tried, and `f`
1279	n/a	is the number of examples that failed. The examples are run
1280	n/a	in the namespace `test.globs`.
1281	n/a	"""
1282	n/a	# Keep track of the number of failures and tries.
1283	n/a	failures = tries = 0
1284	n/a
1285	n/a	# Save the option flags (since option directives can be used
1286	n/a	# to modify them).
1287	n/a	original_optionflags = self.optionflags
1288	n/a
1289	n/a	SUCCESS, FAILURE, BOOM = range(3) # `outcome` state
1290	n/a
1291	n/a	check = self._checker.check_output
1292	n/a
1293	n/a	# Process each example.
1294	n/a	for examplenum, example in enumerate(test.examples):
1295	n/a
1296	n/a	# If REPORT_ONLY_FIRST_FAILURE is set, then suppress
1297	n/a	# reporting after the first failure.
1298	n/a	quiet = (self.optionflags & REPORT_ONLY_FIRST_FAILURE and
1299	n/a	failures > 0)
1300	n/a
1301	n/a	# Merge in the example's options.
1302	n/a	self.optionflags = original_optionflags
1303	n/a	if example.options:
1304	n/a	for (optionflag, val) in example.options.items():
1305	n/a	if val:
1306	n/a	self.optionflags \|= optionflag
1307	n/a	else:
1308	n/a	self.optionflags &= ~optionflag
1309	n/a
1310	n/a	# If 'SKIP' is set, then skip this example.
1311	n/a	if self.optionflags & SKIP:
1312	n/a	continue
1313	n/a
1314	n/a	# Record that we started this example.
1315	n/a	tries += 1
1316	n/a	if not quiet:
1317	n/a	self.report_start(out, test, example)
1318	n/a
1319	n/a	# Use a special filename for compile(), so we can retrieve
1320	n/a	# the source code during interactive debugging (see
1321	n/a	# __patched_linecache_getlines).
1322	n/a	filename = '<doctest %s[%d]>' % (test.name, examplenum)
1323	n/a
1324	n/a	# Run the example in the given context (globs), and record
1325	n/a	# any exception that gets raised. (But don't intercept
1326	n/a	# keyboard interrupts.)
1327	n/a	try:
1328	n/a	# Don't blink! This is where the user's code gets run.
1329	n/a	exec(compile(example.source, filename, "single",
1330	n/a	compileflags, 1), test.globs)
1331	n/a	self.debugger.set_continue() # ==== Example Finished ====
1332	n/a	exception = None
1333	n/a	except KeyboardInterrupt:
1334	n/a	raise
1335	n/a	except:
1336	n/a	exception = sys.exc_info()
1337	n/a	self.debugger.set_continue() # ==== Example Finished ====
1338	n/a
1339	n/a	got = self._fakeout.getvalue() # the actual output
1340	n/a	self._fakeout.truncate(0)
1341	n/a	outcome = FAILURE # guilty until proved innocent or insane
1342	n/a
1343	n/a	# If the example executed without raising any exceptions,
1344	n/a	# verify its output.
1345	n/a	if exception is None:
1346	n/a	if check(example.want, got, self.optionflags):
1347	n/a	outcome = SUCCESS
1348	n/a
1349	n/a	# The example raised an exception: check if it was expected.
1350	n/a	else:
1351	n/a	exc_msg = traceback.format_exception_only(*exception[:2])[-1]
1352	n/a	if not quiet:
1353	n/a	got += _exception_traceback(exception)
1354	n/a
1355	n/a	# If `example.exc_msg` is None, then we weren't expecting
1356	n/a	# an exception.
1357	n/a	if example.exc_msg is None:
1358	n/a	outcome = BOOM
1359	n/a
1360	n/a	# We expected an exception: see whether it matches.
1361	n/a	elif check(example.exc_msg, exc_msg, self.optionflags):
1362	n/a	outcome = SUCCESS
1363	n/a
1364	n/a	# Another chance if they didn't care about the detail.
1365	n/a	elif self.optionflags & IGNORE_EXCEPTION_DETAIL:
1366	n/a	if check(_strip_exception_details(example.exc_msg),
1367	n/a	_strip_exception_details(exc_msg),
1368	n/a	self.optionflags):
1369	n/a	outcome = SUCCESS
1370	n/a
1371	n/a	# Report the outcome.
1372	n/a	if outcome is SUCCESS:
1373	n/a	if not quiet:
1374	n/a	self.report_success(out, test, example, got)
1375	n/a	elif outcome is FAILURE:
1376	n/a	if not quiet:
1377	n/a	self.report_failure(out, test, example, got)
1378	n/a	failures += 1
1379	n/a	elif outcome is BOOM:
1380	n/a	if not quiet:
1381	n/a	self.report_unexpected_exception(out, test, example,
1382	n/a	exception)
1383	n/a	failures += 1
1384	n/a	else:
1385	n/a	assert False, ("unknown outcome", outcome)
1386	n/a
1387	n/a	if failures and self.optionflags & FAIL_FAST:
1388	n/a	break
1389	n/a
1390	n/a	# Restore the option flags (in case they were modified)
1391	n/a	self.optionflags = original_optionflags
1392	n/a
1393	n/a	# Record and return the number of failures and tries.
1394	n/a	self.__record_outcome(test, failures, tries)
1395	n/a	return TestResults(failures, tries)
1396	n/a
1397	n/a	def __record_outcome(self, test, f, t):
1398	n/a	"""
1399	n/a	Record the fact that the given DocTest (`test`) generated `f`
1400	n/a	failures out of `t` tried examples.
1401	n/a	"""
1402	n/a	f2, t2 = self._name2ft.get(test.name, (0,0))
1403	n/a	self._name2ft[test.name] = (f+f2, t+t2)
1404	n/a	self.failures += f
1405	n/a	self.tries += t
1406	n/a
1407	n/a	__LINECACHE_FILENAME_RE = re.compile(r'<doctest '
1408	n/a	r'(?P<name>.+)'
1409	n/a	r'\[(?P<examplenum>\d+)\]>$')
1410	n/a	def __patched_linecache_getlines(self, filename, module_globals=None):
1411	n/a	m = self.__LINECACHE_FILENAME_RE.match(filename)
1412	n/a	if m and m.group('name') == self.test.name:
1413	n/a	example = self.test.examples[int(m.group('examplenum'))]
1414	n/a	return example.source.splitlines(keepends=True)
1415	n/a	else:
1416	n/a	return self.save_linecache_getlines(filename, module_globals)
1417	n/a
1418	n/a	def run(self, test, compileflags=None, out=None, clear_globs=True):
1419	n/a	"""
1420	n/a	Run the examples in `test`, and display the results using the
1421	n/a	writer function `out`.
1422	n/a
1423	n/a	The examples are run in the namespace `test.globs`. If
1424	n/a	`clear_globs` is true (the default), then this namespace will
1425	n/a	be cleared after the test runs, to help with garbage
1426	n/a	collection. If you would like to examine the namespace after
1427	n/a	the test completes, then use `clear_globs=False`.
1428	n/a
1429	n/a	`compileflags` gives the set of flags that should be used by
1430	n/a	the Python compiler when running the examples. If not
1431	n/a	specified, then it will default to the set of future-import
1432	n/a	flags that apply to `globs`.
1433	n/a
1434	n/a	The output of each example is checked using
1435	n/a	`DocTestRunner.check_output`, and the results are formatted by
1436	n/a	the `DocTestRunner.report_*` methods.
1437	n/a	"""
1438	n/a	self.test = test
1439	n/a
1440	n/a	if compileflags is None:
1441	n/a	compileflags = _extract_future_flags(test.globs)
1442	n/a
1443	n/a	save_stdout = sys.stdout
1444	n/a	if out is None:
1445	n/a	encoding = save_stdout.encoding
1446	n/a	if encoding is None or encoding.lower() == 'utf-8':
1447	n/a	out = save_stdout.write
1448	n/a	else:
1449	n/a	# Use backslashreplace error handling on write
1450	n/a	def out(s):
1451	n/a	s = str(s.encode(encoding, 'backslashreplace'), encoding)
1452	n/a	save_stdout.write(s)
1453	n/a	sys.stdout = self._fakeout
1454	n/a
1455	n/a	# Patch pdb.set_trace to restore sys.stdout during interactive
1456	n/a	# debugging (so it's not still redirected to self._fakeout).
1457	n/a	# Note that the interactive output will go to our
1458	n/a	# save_stdout, even if that's not the real sys.stdout; this
1459	n/a	# allows us to write test cases for the set_trace behavior.
1460	n/a	save_trace = sys.gettrace()
1461	n/a	save_set_trace = pdb.set_trace
1462	n/a	self.debugger = _OutputRedirectingPdb(save_stdout)
1463	n/a	self.debugger.reset()
1464	n/a	pdb.set_trace = self.debugger.set_trace
1465	n/a
1466	n/a	# Patch linecache.getlines, so we can see the example's source
1467	n/a	# when we're inside the debugger.
1468	n/a	self.save_linecache_getlines = linecache.getlines
1469	n/a	linecache.getlines = self.__patched_linecache_getlines
1470	n/a
1471	n/a	# Make sure sys.displayhook just prints the value to stdout
1472	n/a	save_displayhook = sys.displayhook
1473	n/a	sys.displayhook = sys.__displayhook__
1474	n/a
1475	n/a	try:
1476	n/a	return self.__run(test, compileflags, out)
1477	n/a	finally:
1478	n/a	sys.stdout = save_stdout
1479	n/a	pdb.set_trace = save_set_trace
1480	n/a	sys.settrace(save_trace)
1481	n/a	linecache.getlines = self.save_linecache_getlines
1482	n/a	sys.displayhook = save_displayhook
1483	n/a	if clear_globs:
1484	n/a	test.globs.clear()
1485	n/a	import builtins
1486	n/a	builtins._ = None
1487	n/a
1488	n/a	#/////////////////////////////////////////////////////////////////
1489	n/a	# Summarization
1490	n/a	#/////////////////////////////////////////////////////////////////
1491	n/a	def summarize(self, verbose=None):
1492	n/a	"""
1493	n/a	Print a summary of all the test cases that have been run by
1494	n/a	this DocTestRunner, and return a tuple `(f, t)`, where `f` is
1495	n/a	the total number of failed examples, and `t` is the total
1496	n/a	number of tried examples.
1497	n/a
1498	n/a	The optional `verbose` argument controls how detailed the
1499	n/a	summary is. If the verbosity is not specified, then the
1500	n/a	DocTestRunner's verbosity is used.
1501	n/a	"""
1502	n/a	if verbose is None:
1503	n/a	verbose = self._verbose
1504	n/a	notests = []
1505	n/a	passed = []
1506	n/a	failed = []
1507	n/a	totalt = totalf = 0
1508	n/a	for x in self._name2ft.items():
1509	n/a	name, (f, t) = x
1510	n/a	assert f <= t
1511	n/a	totalt += t
1512	n/a	totalf += f
1513	n/a	if t == 0:
1514	n/a	notests.append(name)
1515	n/a	elif f == 0:
1516	n/a	passed.append( (name, t) )
1517	n/a	else:
1518	n/a	failed.append(x)
1519	n/a	if verbose:
1520	n/a	if notests:
1521	n/a	print(len(notests), "items had no tests:")
1522	n/a	notests.sort()
1523	n/a	for thing in notests:
1524	n/a	print(" ", thing)
1525	n/a	if passed:
1526	n/a	print(len(passed), "items passed all tests:")
1527	n/a	passed.sort()
1528	n/a	for thing, count in passed:
1529	n/a	print(" %3d tests in %s" % (count, thing))
1530	n/a	if failed:
1531	n/a	print(self.DIVIDER)
1532	n/a	print(len(failed), "items had failures:")
1533	n/a	failed.sort()
1534	n/a	for thing, (f, t) in failed:
1535	n/a	print(" %3d of %3d in %s" % (f, t, thing))
1536	n/a	if verbose:
1537	n/a	print(totalt, "tests in", len(self._name2ft), "items.")
1538	n/a	print(totalt - totalf, "passed and", totalf, "failed.")
1539	n/a	if totalf:
1540	n/a	print("*Test Failed*", totalf, "failures.")
1541	n/a	elif verbose:
1542	n/a	print("Test passed.")
1543	n/a	return TestResults(totalf, totalt)
1544	n/a
1545	n/a	#/////////////////////////////////////////////////////////////////
1546	n/a	# Backward compatibility cruft to maintain doctest.master.
1547	n/a	#/////////////////////////////////////////////////////////////////
1548	n/a	def merge(self, other):
1549	n/a	d = self._name2ft
1550	n/a	for name, (f, t) in other._name2ft.items():
1551	n/a	if name in d:
1552	n/a	# Don't print here by default, since doing
1553	n/a	# so breaks some of the buildbots
1554	n/a	#print("*** DocTestRunner.merge: '" + name + "' in both" \
1555	n/a	# " testers; summing outcomes.")
1556	n/a	f2, t2 = d[name]
1557	n/a	f = f + f2
1558	n/a	t = t + t2
1559	n/a	d[name] = f, t
1560	n/a
1561	n/a	class OutputChecker:
1562	n/a	"""
1563	n/a	A class used to check the whether the actual output from a doctest
1564	n/a	example matches the expected output. `OutputChecker` defines two
1565	n/a	methods: `check_output`, which compares a given pair of outputs,
1566	n/a	and returns true if they match; and `output_difference`, which
1567	n/a	returns a string describing the differences between two outputs.
1568	n/a	"""
1569	n/a	def _toAscii(self, s):
1570	n/a	"""
1571	n/a	Convert string to hex-escaped ASCII string.
1572	n/a	"""
1573	n/a	return str(s.encode('ASCII', 'backslashreplace'), "ASCII")
1574	n/a
1575	n/a	def check_output(self, want, got, optionflags):
1576	n/a	"""
1577	n/a	Return True iff the actual output from an example (`got`)
1578	n/a	matches the expected output (`want`). These strings are
1579	n/a	always considered to match if they are identical; but
1580	n/a	depending on what option flags the test runner is using,
1581	n/a	several non-exact match types are also possible. See the
1582	n/a	documentation for `TestRunner` for more information about
1583	n/a	option flags.
1584	n/a	"""
1585	n/a
1586	n/a	# If `want` contains hex-escaped character such as "\u1234",
1587	n/a	# then `want` is a string of six characters(e.g. [\,u,1,2,3,4]).
1588	n/a	# On the other hand, `got` could be another sequence of
1589	n/a	# characters such as [\u1234], so `want` and `got` should
1590	n/a	# be folded to hex-escaped ASCII string to compare.
1591	n/a	got = self._toAscii(got)
1592	n/a	want = self._toAscii(want)
1593	n/a
1594	n/a	# Handle the common case first, for efficiency:
1595	n/a	# if they're string-identical, always return true.
1596	n/a	if got == want:
1597	n/a	return True
1598	n/a
1599	n/a	# The values True and False replaced 1 and 0 as the return
1600	n/a	# value for boolean comparisons in Python 2.3.
1601	n/a	if not (optionflags & DONT_ACCEPT_TRUE_FOR_1):
1602	n/a	if (got,want) == ("True\n", "1\n"):
1603	n/a	return True
1604	n/a	if (got,want) == ("False\n", "0\n"):
1605	n/a	return True
1606	n/a
1607	n/a	# <BLANKLINE> can be used as a special sequence to signify a
1608	n/a	# blank line, unless the DONT_ACCEPT_BLANKLINE flag is used.
1609	n/a	if not (optionflags & DONT_ACCEPT_BLANKLINE):
1610	n/a	# Replace <BLANKLINE> in want with a blank line.
1611	n/a	want = re.sub(r'(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER),
1612	n/a	'', want)
1613	n/a	# If a line in got contains only spaces, then remove the
1614	n/a	# spaces.
1615	n/a	got = re.sub(r'(?m)^\s*?$', '', got)
1616	n/a	if got == want:
1617	n/a	return True
1618	n/a
1619	n/a	# This flag causes doctest to ignore any differences in the
1620	n/a	# contents of whitespace strings. Note that this can be used
1621	n/a	# in conjunction with the ELLIPSIS flag.
1622	n/a	if optionflags & NORMALIZE_WHITESPACE:
1623	n/a	got = ' '.join(got.split())
1624	n/a	want = ' '.join(want.split())
1625	n/a	if got == want:
1626	n/a	return True
1627	n/a
1628	n/a	# The ELLIPSIS flag says to let the sequence "..." in `want`
1629	n/a	# match any substring in `got`.
1630	n/a	if optionflags & ELLIPSIS:
1631	n/a	if _ellipsis_match(want, got):
1632	n/a	return True
1633	n/a
1634	n/a	# We didn't find any match; return false.
1635	n/a	return False
1636	n/a
1637	n/a	# Should we do a fancy diff?
1638	n/a	def _do_a_fancy_diff(self, want, got, optionflags):
1639	n/a	# Not unless they asked for a fancy diff.
1640	n/a	if not optionflags & (REPORT_UDIFF \|
1641	n/a	REPORT_CDIFF \|
1642	n/a	REPORT_NDIFF):
1643	n/a	return False
1644	n/a
1645	n/a	# If expected output uses ellipsis, a meaningful fancy diff is
1646	n/a	# too hard ... or maybe not. In two real-life failures Tim saw,
1647	n/a	# a diff was a major help anyway, so this is commented out.
1648	n/a	# [todo] _ellipsis_match() knows which pieces do and don't match,
1649	n/a	# and could be the basis for a kick-ass diff in this case.
1650	n/a	##if optionflags & ELLIPSIS and ELLIPSIS_MARKER in want:
1651	n/a	## return False
1652	n/a
1653	n/a	# ndiff does intraline difference marking, so can be useful even
1654	n/a	# for 1-line differences.
1655	n/a	if optionflags & REPORT_NDIFF:
1656	n/a	return True
1657	n/a
1658	n/a	# The other diff types need at least a few lines to be helpful.
1659	n/a	return want.count('\n') > 2 and got.count('\n') > 2
1660	n/a
1661	n/a	def output_difference(self, example, got, optionflags):
1662	n/a	"""
1663	n/a	Return a string describing the differences between the
1664	n/a	expected output for a given example (`example`) and the actual
1665	n/a	output (`got`). `optionflags` is the set of option flags used
1666	n/a	to compare `want` and `got`.
1667	n/a	"""
1668	n/a	want = example.want
1669	n/a	# If <BLANKLINE>s are being used, then replace blank lines
1670	n/a	# with <BLANKLINE> in the actual output string.
1671	n/a	if not (optionflags & DONT_ACCEPT_BLANKLINE):
1672	n/a	got = re.sub('(?m)^[ ]*(?=\n)', BLANKLINE_MARKER, got)
1673	n/a
1674	n/a	# Check if we should use diff.
1675	n/a	if self._do_a_fancy_diff(want, got, optionflags):
1676	n/a	# Split want & got into lines.
1677	n/a	want_lines = want.splitlines(keepends=True)
1678	n/a	got_lines = got.splitlines(keepends=True)
1679	n/a	# Use difflib to find their differences.
1680	n/a	if optionflags & REPORT_UDIFF:
1681	n/a	diff = difflib.unified_diff(want_lines, got_lines, n=2)
1682	n/a	diff = list(diff)[2:] # strip the diff header
1683	n/a	kind = 'unified diff with -expected +actual'
1684	n/a	elif optionflags & REPORT_CDIFF:
1685	n/a	diff = difflib.context_diff(want_lines, got_lines, n=2)
1686	n/a	diff = list(diff)[2:] # strip the diff header
1687	n/a	kind = 'context diff with expected followed by actual'
1688	n/a	elif optionflags & REPORT_NDIFF:
1689	n/a	engine = difflib.Differ(charjunk=difflib.IS_CHARACTER_JUNK)
1690	n/a	diff = list(engine.compare(want_lines, got_lines))
1691	n/a	kind = 'ndiff with -expected +actual'
1692	n/a	else:
1693	n/a	assert 0, 'Bad diff option'
1694	n/a	# Remove trailing whitespace on diff output.
1695	n/a	diff = [line.rstrip() + '\n' for line in diff]
1696	n/a	return 'Differences (%s):\n' % kind + _indent(''.join(diff))
1697	n/a
1698	n/a	# If we're not using diff, then simply list the expected
1699	n/a	# output followed by the actual output.
1700	n/a	if want and got:
1701	n/a	return 'Expected:\n%sGot:\n%s' % (_indent(want), _indent(got))
1702	n/a	elif want:
1703	n/a	return 'Expected:\n%sGot nothing\n' % _indent(want)
1704	n/a	elif got:
1705	n/a	return 'Expected nothing\nGot:\n%s' % _indent(got)
1706	n/a	else:
1707	n/a	return 'Expected nothing\nGot nothing\n'
1708	n/a
1709	n/a	class DocTestFailure(Exception):
1710	n/a	"""A DocTest example has failed in debugging mode.
1711	n/a
1712	n/a	The exception instance has variables:
1713	n/a
1714	n/a	- test: the DocTest object being run
1715	n/a
1716	n/a	- example: the Example object that failed
1717	n/a
1718	n/a	- got: the actual output
1719	n/a	"""
1720	n/a	def __init__(self, test, example, got):
1721	n/a	self.test = test
1722	n/a	self.example = example
1723	n/a	self.got = got
1724	n/a
1725	n/a	def __str__(self):
1726	n/a	return str(self.test)
1727	n/a
1728	n/a	class UnexpectedException(Exception):
1729	n/a	"""A DocTest example has encountered an unexpected exception
1730	n/a
1731	n/a	The exception instance has variables:
1732	n/a
1733	n/a	- test: the DocTest object being run
1734	n/a
1735	n/a	- example: the Example object that failed
1736	n/a
1737	n/a	- exc_info: the exception info
1738	n/a	"""
1739	n/a	def __init__(self, test, example, exc_info):
1740	n/a	self.test = test
1741	n/a	self.example = example
1742	n/a	self.exc_info = exc_info
1743	n/a
1744	n/a	def __str__(self):
1745	n/a	return str(self.test)
1746	n/a
1747	n/a	class DebugRunner(DocTestRunner):
1748	n/a	r"""Run doc tests but raise an exception as soon as there is a failure.
1749	n/a
1750	n/a	If an unexpected exception occurs, an UnexpectedException is raised.
1751	n/a	It contains the test, the example, and the original exception:
1752	n/a
1753	n/a	>>> runner = DebugRunner(verbose=False)
1754	n/a	>>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
1755	n/a	... {}, 'foo', 'foo.py', 0)
1756	n/a	>>> try:
1757	n/a	... runner.run(test)
1758	n/a	... except UnexpectedException as f:
1759	n/a	... failure = f
1760	n/a
1761	n/a	>>> failure.test is test
1762	n/a	True
1763	n/a
1764	n/a	>>> failure.example.want
1765	n/a	'42\n'
1766	n/a
1767	n/a	>>> exc_info = failure.exc_info
1768	n/a	>>> raise exc_info[1] # Already has the traceback
1769	n/a	Traceback (most recent call last):
1770	n/a	...
1771	n/a	KeyError
1772	n/a
1773	n/a	We wrap the original exception to give the calling application
1774	n/a	access to the test and example information.
1775	n/a
1776	n/a	If the output doesn't match, then a DocTestFailure is raised:
1777	n/a
1778	n/a	>>> test = DocTestParser().get_doctest('''
1779	n/a	... >>> x = 1
1780	n/a	... >>> x
1781	n/a	... 2
1782	n/a	... ''', {}, 'foo', 'foo.py', 0)
1783	n/a
1784	n/a	>>> try:
1785	n/a	... runner.run(test)
1786	n/a	... except DocTestFailure as f:
1787	n/a	... failure = f
1788	n/a
1789	n/a	DocTestFailure objects provide access to the test:
1790	n/a
1791	n/a	>>> failure.test is test
1792	n/a	True
1793	n/a
1794	n/a	As well as to the example:
1795	n/a
1796	n/a	>>> failure.example.want
1797	n/a	'2\n'
1798	n/a
1799	n/a	and the actual output:
1800	n/a
1801	n/a	>>> failure.got
1802	n/a	'1\n'
1803	n/a
1804	n/a	If a failure or error occurs, the globals are left intact:
1805	n/a
1806	n/a	>>> del test.globs['__builtins__']
1807	n/a	>>> test.globs
1808	n/a	{'x': 1}
1809	n/a
1810	n/a	>>> test = DocTestParser().get_doctest('''
1811	n/a	... >>> x = 2
1812	n/a	... >>> raise KeyError
1813	n/a	... ''', {}, 'foo', 'foo.py', 0)
1814	n/a
1815	n/a	>>> runner.run(test)
1816	n/a	Traceback (most recent call last):
1817	n/a	...
1818	n/a	doctest.UnexpectedException: <DocTest foo from foo.py:0 (2 examples)>
1819	n/a
1820	n/a	>>> del test.globs['__builtins__']
1821	n/a	>>> test.globs
1822	n/a	{'x': 2}
1823	n/a
1824	n/a	But the globals are cleared if there is no error:
1825	n/a
1826	n/a	>>> test = DocTestParser().get_doctest('''
1827	n/a	... >>> x = 2
1828	n/a	... ''', {}, 'foo', 'foo.py', 0)
1829	n/a
1830	n/a	>>> runner.run(test)
1831	n/a	TestResults(failed=0, attempted=1)
1832	n/a
1833	n/a	>>> test.globs
1834	n/a	{}
1835	n/a
1836	n/a	"""
1837	n/a
1838	n/a	def run(self, test, compileflags=None, out=None, clear_globs=True):
1839	n/a	r = DocTestRunner.run(self, test, compileflags, out, False)
1840	n/a	if clear_globs:
1841	n/a	test.globs.clear()
1842	n/a	return r
1843	n/a
1844	n/a	def report_unexpected_exception(self, out, test, example, exc_info):
1845	n/a	raise UnexpectedException(test, example, exc_info)
1846	n/a
1847	n/a	def report_failure(self, out, test, example, got):
1848	n/a	raise DocTestFailure(test, example, got)
1849	n/a
1850	n/a	######################################################################
1851	n/a	## 6. Test Functions
1852	n/a	######################################################################
1853	n/a	# These should be backwards compatible.
1854	n/a
1855	n/a	# For backward compatibility, a global instance of a DocTestRunner
1856	n/a	# class, updated by testmod.
1857	n/a	master = None
1858	n/a
1859	n/a	def testmod(m=None, name=None, globs=None, verbose=None,
1860	n/a	report=True, optionflags=0, extraglobs=None,
1861	n/a	raise_on_error=False, exclude_empty=False):
1862	n/a	"""m=None, name=None, globs=None, verbose=None, report=True,
1863	n/a	optionflags=0, extraglobs=None, raise_on_error=False,
1864	n/a	exclude_empty=False
1865	n/a
1866	n/a	Test examples in docstrings in functions and classes reachable
1867	n/a	from module m (or the current module if m is not supplied), starting
1868	n/a	with m.__doc__.
1869	n/a
1870	n/a	Also test examples reachable from dict m.__test__ if it exists and is
1871	n/a	not None. m.__test__ maps names to functions, classes and strings;
1872	n/a	function and class docstrings are tested even if the name is private;
1873	n/a	strings are tested directly, as if they were docstrings.
1874	n/a
1875	n/a	Return (#failures, #tests).
1876	n/a
1877	n/a	See help(doctest) for an overview.
1878	n/a
1879	n/a	Optional keyword arg "name" gives the name of the module; by default
1880	n/a	use m.__name__.
1881	n/a
1882	n/a	Optional keyword arg "globs" gives a dict to be used as the globals
1883	n/a	when executing examples; by default, use m.__dict__. A copy of this
1884	n/a	dict is actually used for each docstring, so that each docstring's
1885	n/a	examples start with a clean slate.
1886	n/a
1887	n/a	Optional keyword arg "extraglobs" gives a dictionary that should be
1888	n/a	merged into the globals that are used to execute examples. By
1889	n/a	default, no extra globals are used. This is new in 2.4.
1890	n/a
1891	n/a	Optional keyword arg "verbose" prints lots of stuff if true, prints
1892	n/a	only failures if false; by default, it's true iff "-v" is in sys.argv.
1893	n/a
1894	n/a	Optional keyword arg "report" prints a summary at the end when true,
1895	n/a	else prints nothing at the end. In verbose mode, the summary is
1896	n/a	detailed, else very brief (in fact, empty if all tests passed).
1897	n/a
1898	n/a	Optional keyword arg "optionflags" or's together module constants,
1899	n/a	and defaults to 0. This is new in 2.3. Possible values (see the
1900	n/a	docs for details):
1901	n/a
1902	n/a	DONT_ACCEPT_TRUE_FOR_1
1903	n/a	DONT_ACCEPT_BLANKLINE
1904	n/a	NORMALIZE_WHITESPACE
1905	n/a	ELLIPSIS
1906	n/a	SKIP
1907	n/a	IGNORE_EXCEPTION_DETAIL
1908	n/a	REPORT_UDIFF
1909	n/a	REPORT_CDIFF
1910	n/a	REPORT_NDIFF
1911	n/a	REPORT_ONLY_FIRST_FAILURE
1912	n/a
1913	n/a	Optional keyword arg "raise_on_error" raises an exception on the
1914	n/a	first unexpected exception or failure. This allows failures to be
1915	n/a	post-mortem debugged.
1916	n/a
1917	n/a	Advanced tomfoolery: testmod runs methods of a local instance of
1918	n/a	class doctest.Tester, then merges the results into (or creates)
1919	n/a	global Tester instance doctest.master. Methods of doctest.master
1920	n/a	can be called directly too, if you want to do something unusual.
1921	n/a	Passing report=0 to testmod is especially useful then, to delay
1922	n/a	displaying a summary. Invoke doctest.master.summarize(verbose)
1923	n/a	when you're done fiddling.
1924	n/a	"""
1925	n/a	global master
1926	n/a
1927	n/a	# If no module was given, then use __main__.
1928	n/a	if m is None:
1929	n/a	# DWA - m will still be None if this wasn't invoked from the command
1930	n/a	# line, in which case the following TypeError is about as good an error
1931	n/a	# as we should expect
1932	n/a	m = sys.modules.get('__main__')
1933	n/a
1934	n/a	# Check that we were actually given a module.
1935	n/a	if not inspect.ismodule(m):
1936	n/a	raise TypeError("testmod: module required; %r" % (m,))
1937	n/a
1938	n/a	# If no name was given, then use the module's name.
1939	n/a	if name is None:
1940	n/a	name = m.__name__
1941	n/a
1942	n/a	# Find, parse, and run all tests in the given module.
1943	n/a	finder = DocTestFinder(exclude_empty=exclude_empty)
1944	n/a
1945	n/a	if raise_on_error:
1946	n/a	runner = DebugRunner(verbose=verbose, optionflags=optionflags)
1947	n/a	else:
1948	n/a	runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
1949	n/a
1950	n/a	for test in finder.find(m, name, globs=globs, extraglobs=extraglobs):
1951	n/a	runner.run(test)
1952	n/a
1953	n/a	if report:
1954	n/a	runner.summarize()
1955	n/a
1956	n/a	if master is None:
1957	n/a	master = runner
1958	n/a	else:
1959	n/a	master.merge(runner)
1960	n/a
1961	n/a	return TestResults(runner.failures, runner.tries)
1962	n/a
1963	n/a	def testfile(filename, module_relative=True, name=None, package=None,
1964	n/a	globs=None, verbose=None, report=True, optionflags=0,
1965	n/a	extraglobs=None, raise_on_error=False, parser=DocTestParser(),
1966	n/a	encoding=None):
1967	n/a	"""
1968	n/a	Test examples in the given file. Return (#failures, #tests).
1969	n/a
1970	n/a	Optional keyword arg "module_relative" specifies how filenames
1971	n/a	should be interpreted:
1972	n/a
1973	n/a	- If "module_relative" is True (the default), then "filename"
1974	n/a	specifies a module-relative path. By default, this path is
1975	n/a	relative to the calling module's directory; but if the
1976	n/a	"package" argument is specified, then it is relative to that
1977	n/a	package. To ensure os-independence, "filename" should use
1978	n/a	"/" characters to separate path segments, and should not
1979	n/a	be an absolute path (i.e., it may not begin with "/").
1980	n/a
1981	n/a	- If "module_relative" is False, then "filename" specifies an
1982	n/a	os-specific path. The path may be absolute or relative (to
1983	n/a	the current working directory).
1984	n/a
1985	n/a	Optional keyword arg "name" gives the name of the test; by default
1986	n/a	use the file's basename.
1987	n/a
1988	n/a	Optional keyword argument "package" is a Python package or the
1989	n/a	name of a Python package whose directory should be used as the
1990	n/a	base directory for a module relative filename. If no package is
1991	n/a	specified, then the calling module's directory is used as the base
1992	n/a	directory for module relative filenames. It is an error to
1993	n/a	specify "package" if "module_relative" is False.
1994	n/a
1995	n/a	Optional keyword arg "globs" gives a dict to be used as the globals
1996	n/a	when executing examples; by default, use {}. A copy of this dict
1997	n/a	is actually used for each docstring, so that each docstring's
1998	n/a	examples start with a clean slate.
1999	n/a
2000	n/a	Optional keyword arg "extraglobs" gives a dictionary that should be
2001	n/a	merged into the globals that are used to execute examples. By
2002	n/a	default, no extra globals are used.
2003	n/a
2004	n/a	Optional keyword arg "verbose" prints lots of stuff if true, prints
2005	n/a	only failures if false; by default, it's true iff "-v" is in sys.argv.
2006	n/a
2007	n/a	Optional keyword arg "report" prints a summary at the end when true,
2008	n/a	else prints nothing at the end. In verbose mode, the summary is
2009	n/a	detailed, else very brief (in fact, empty if all tests passed).
2010	n/a
2011	n/a	Optional keyword arg "optionflags" or's together module constants,
2012	n/a	and defaults to 0. Possible values (see the docs for details):
2013	n/a
2014	n/a	DONT_ACCEPT_TRUE_FOR_1
2015	n/a	DONT_ACCEPT_BLANKLINE
2016	n/a	NORMALIZE_WHITESPACE
2017	n/a	ELLIPSIS
2018	n/a	SKIP
2019	n/a	IGNORE_EXCEPTION_DETAIL
2020	n/a	REPORT_UDIFF
2021	n/a	REPORT_CDIFF
2022	n/a	REPORT_NDIFF
2023	n/a	REPORT_ONLY_FIRST_FAILURE
2024	n/a
2025	n/a	Optional keyword arg "raise_on_error" raises an exception on the
2026	n/a	first unexpected exception or failure. This allows failures to be
2027	n/a	post-mortem debugged.
2028	n/a
2029	n/a	Optional keyword arg "parser" specifies a DocTestParser (or
2030	n/a	subclass) that should be used to extract tests from the files.
2031	n/a
2032	n/a	Optional keyword arg "encoding" specifies an encoding that should
2033	n/a	be used to convert the file to unicode.
2034	n/a
2035	n/a	Advanced tomfoolery: testmod runs methods of a local instance of
2036	n/a	class doctest.Tester, then merges the results into (or creates)
2037	n/a	global Tester instance doctest.master. Methods of doctest.master
2038	n/a	can be called directly too, if you want to do something unusual.
2039	n/a	Passing report=0 to testmod is especially useful then, to delay
2040	n/a	displaying a summary. Invoke doctest.master.summarize(verbose)
2041	n/a	when you're done fiddling.
2042	n/a	"""
2043	n/a	global master
2044	n/a
2045	n/a	if package and not module_relative:
2046	n/a	raise ValueError("Package may only be specified for module-"
2047	n/a	"relative paths.")
2048	n/a
2049	n/a	# Relativize the path
2050	n/a	text, filename = _load_testfile(filename, package, module_relative,
2051	n/a	encoding or "utf-8")
2052	n/a
2053	n/a	# If no name was given, then use the file's name.
2054	n/a	if name is None:
2055	n/a	name = os.path.basename(filename)
2056	n/a
2057	n/a	# Assemble the globals.
2058	n/a	if globs is None:
2059	n/a	globs = {}
2060	n/a	else:
2061	n/a	globs = globs.copy()
2062	n/a	if extraglobs is not None:
2063	n/a	globs.update(extraglobs)
2064	n/a	if '__name__' not in globs:
2065	n/a	globs['__name__'] = '__main__'
2066	n/a
2067	n/a	if raise_on_error:
2068	n/a	runner = DebugRunner(verbose=verbose, optionflags=optionflags)
2069	n/a	else:
2070	n/a	runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2071	n/a
2072	n/a	# Read the file, convert it to a test, and run it.
2073	n/a	test = parser.get_doctest(text, globs, name, filename, 0)
2074	n/a	runner.run(test)
2075	n/a
2076	n/a	if report:
2077	n/a	runner.summarize()
2078	n/a
2079	n/a	if master is None:
2080	n/a	master = runner
2081	n/a	else:
2082	n/a	master.merge(runner)
2083	n/a
2084	n/a	return TestResults(runner.failures, runner.tries)
2085	n/a
2086	n/a	def run_docstring_examples(f, globs, verbose=False, name="NoName",
2087	n/a	compileflags=None, optionflags=0):
2088	n/a	"""
2089	n/a	Test examples in the given object's docstring (`f`), using `globs`
2090	n/a	as globals. Optional argument `name` is used in failure messages.
2091	n/a	If the optional argument `verbose` is true, then generate output
2092	n/a	even if there are no failures.
2093	n/a
2094	n/a	`compileflags` gives the set of flags that should be used by the
2095	n/a	Python compiler when running the examples. If not specified, then
2096	n/a	it will default to the set of future-import flags that apply to
2097	n/a	`globs`.
2098	n/a
2099	n/a	Optional keyword arg `optionflags` specifies options for the
2100	n/a	testing and output. See the documentation for `testmod` for more
2101	n/a	information.
2102	n/a	"""
2103	n/a	# Find, parse, and run all tests in the given module.
2104	n/a	finder = DocTestFinder(verbose=verbose, recurse=False)
2105	n/a	runner = DocTestRunner(verbose=verbose, optionflags=optionflags)
2106	n/a	for test in finder.find(f, name, globs=globs):
2107	n/a	runner.run(test, compileflags=compileflags)
2108	n/a
2109	n/a	######################################################################
2110	n/a	## 7. Unittest Support
2111	n/a	######################################################################
2112	n/a
2113	n/a	_unittest_reportflags = 0
2114	n/a
2115	n/a	def set_unittest_reportflags(flags):
2116	n/a	"""Sets the unittest option flags.
2117	n/a
2118	n/a	The old flag is returned so that a runner could restore the old
2119	n/a	value if it wished to:
2120	n/a
2121	n/a	>>> import doctest
2122	n/a	>>> old = doctest._unittest_reportflags
2123	n/a	>>> doctest.set_unittest_reportflags(REPORT_NDIFF \|
2124	n/a	... REPORT_ONLY_FIRST_FAILURE) == old
2125	n/a	True
2126	n/a
2127	n/a	>>> doctest._unittest_reportflags == (REPORT_NDIFF \|
2128	n/a	... REPORT_ONLY_FIRST_FAILURE)
2129	n/a	True
2130	n/a
2131	n/a	Only reporting flags can be set:
2132	n/a
2133	n/a	>>> doctest.set_unittest_reportflags(ELLIPSIS)
2134	n/a	Traceback (most recent call last):
2135	n/a	...
2136	n/a	ValueError: ('Only reporting flags allowed', 8)
2137	n/a
2138	n/a	>>> doctest.set_unittest_reportflags(old) == (REPORT_NDIFF \|
2139	n/a	... REPORT_ONLY_FIRST_FAILURE)
2140	n/a	True
2141	n/a	"""
2142	n/a	global _unittest_reportflags
2143	n/a
2144	n/a	if (flags & REPORTING_FLAGS) != flags:
2145	n/a	raise ValueError("Only reporting flags allowed", flags)
2146	n/a	old = _unittest_reportflags
2147	n/a	_unittest_reportflags = flags
2148	n/a	return old
2149	n/a
2150	n/a
2151	n/a	class DocTestCase(unittest.TestCase):
2152	n/a
2153	n/a	def __init__(self, test, optionflags=0, setUp=None, tearDown=None,
2154	n/a	checker=None):
2155	n/a
2156	n/a	unittest.TestCase.__init__(self)
2157	n/a	self._dt_optionflags = optionflags
2158	n/a	self._dt_checker = checker
2159	n/a	self._dt_test = test
2160	n/a	self._dt_setUp = setUp
2161	n/a	self._dt_tearDown = tearDown
2162	n/a
2163	n/a	def setUp(self):
2164	n/a	test = self._dt_test
2165	n/a
2166	n/a	if self._dt_setUp is not None:
2167	n/a	self._dt_setUp(test)
2168	n/a
2169	n/a	def tearDown(self):
2170	n/a	test = self._dt_test
2171	n/a
2172	n/a	if self._dt_tearDown is not None:
2173	n/a	self._dt_tearDown(test)
2174	n/a
2175	n/a	test.globs.clear()
2176	n/a
2177	n/a	def runTest(self):
2178	n/a	test = self._dt_test
2179	n/a	old = sys.stdout
2180	n/a	new = StringIO()
2181	n/a	optionflags = self._dt_optionflags
2182	n/a
2183	n/a	if not (optionflags & REPORTING_FLAGS):
2184	n/a	# The option flags don't include any reporting flags,
2185	n/a	# so add the default reporting flags
2186	n/a	optionflags \|= _unittest_reportflags
2187	n/a
2188	n/a	runner = DocTestRunner(optionflags=optionflags,
2189	n/a	checker=self._dt_checker, verbose=False)
2190	n/a
2191	n/a	try:
2192	n/a	runner.DIVIDER = "-"*70
2193	n/a	failures, tries = runner.run(
2194	n/a	test, out=new.write, clear_globs=False)
2195	n/a	finally:
2196	n/a	sys.stdout = old
2197	n/a
2198	n/a	if failures:
2199	n/a	raise self.failureException(self.format_failure(new.getvalue()))
2200	n/a
2201	n/a	def format_failure(self, err):
2202	n/a	test = self._dt_test
2203	n/a	if test.lineno is None:
2204	n/a	lineno = 'unknown line number'
2205	n/a	else:
2206	n/a	lineno = '%s' % test.lineno
2207	n/a	lname = '.'.join(test.name.split('.')[-1:])
2208	n/a	return ('Failed doctest test for %s\n'
2209	n/a	' File "%s", line %s, in %s\n\n%s'
2210	n/a	% (test.name, test.filename, lineno, lname, err)
2211	n/a	)
2212	n/a
2213	n/a	def debug(self):
2214	n/a	r"""Run the test case without results and without catching exceptions
2215	n/a
2216	n/a	The unit test framework includes a debug method on test cases
2217	n/a	and test suites to support post-mortem debugging. The test code
2218	n/a	is run in such a way that errors are not caught. This way a
2219	n/a	caller can catch the errors and initiate post-mortem debugging.
2220	n/a
2221	n/a	The DocTestCase provides a debug method that raises
2222	n/a	UnexpectedException errors if there is an unexpected
2223	n/a	exception:
2224	n/a
2225	n/a	>>> test = DocTestParser().get_doctest('>>> raise KeyError\n42',
2226	n/a	... {}, 'foo', 'foo.py', 0)
2227	n/a	>>> case = DocTestCase(test)
2228	n/a	>>> try:
2229	n/a	... case.debug()
2230	n/a	... except UnexpectedException as f:
2231	n/a	... failure = f
2232	n/a
2233	n/a	The UnexpectedException contains the test, the example, and
2234	n/a	the original exception:
2235	n/a
2236	n/a	>>> failure.test is test
2237	n/a	True
2238	n/a
2239	n/a	>>> failure.example.want
2240	n/a	'42\n'
2241	n/a
2242	n/a	>>> exc_info = failure.exc_info
2243	n/a	>>> raise exc_info[1] # Already has the traceback
2244	n/a	Traceback (most recent call last):
2245	n/a	...
2246	n/a	KeyError
2247	n/a
2248	n/a	If the output doesn't match, then a DocTestFailure is raised:
2249	n/a
2250	n/a	>>> test = DocTestParser().get_doctest('''
2251	n/a	... >>> x = 1
2252	n/a	... >>> x
2253	n/a	... 2
2254	n/a	... ''', {}, 'foo', 'foo.py', 0)
2255	n/a	>>> case = DocTestCase(test)
2256	n/a
2257	n/a	>>> try:
2258	n/a	... case.debug()
2259	n/a	... except DocTestFailure as f:
2260	n/a	... failure = f
2261	n/a
2262	n/a	DocTestFailure objects provide access to the test:
2263	n/a
2264	n/a	>>> failure.test is test
2265	n/a	True
2266	n/a
2267	n/a	As well as to the example:
2268	n/a
2269	n/a	>>> failure.example.want
2270	n/a	'2\n'
2271	n/a
2272	n/a	and the actual output:
2273	n/a
2274	n/a	>>> failure.got
2275	n/a	'1\n'
2276	n/a
2277	n/a	"""
2278	n/a
2279	n/a	self.setUp()
2280	n/a	runner = DebugRunner(optionflags=self._dt_optionflags,
2281	n/a	checker=self._dt_checker, verbose=False)
2282	n/a	runner.run(self._dt_test, clear_globs=False)
2283	n/a	self.tearDown()
2284	n/a
2285	n/a	def id(self):
2286	n/a	return self._dt_test.name
2287	n/a
2288	n/a	def __eq__(self, other):
2289	n/a	if type(self) is not type(other):
2290	n/a	return NotImplemented
2291	n/a
2292	n/a	return self._dt_test == other._dt_test and \
2293	n/a	self._dt_optionflags == other._dt_optionflags and \
2294	n/a	self._dt_setUp == other._dt_setUp and \
2295	n/a	self._dt_tearDown == other._dt_tearDown and \
2296	n/a	self._dt_checker == other._dt_checker
2297	n/a
2298	n/a	def __hash__(self):
2299	n/a	return hash((self._dt_optionflags, self._dt_setUp, self._dt_tearDown,
2300	n/a	self._dt_checker))
2301	n/a
2302	n/a	def __repr__(self):
2303	n/a	name = self._dt_test.name.split('.')
2304	n/a	return "%s (%s)" % (name[-1], '.'.join(name[:-1]))
2305	n/a
2306	n/a	__str__ = __repr__
2307	n/a
2308	n/a	def shortDescription(self):
2309	n/a	return "Doctest: " + self._dt_test.name
2310	n/a
2311	n/a	class SkipDocTestCase(DocTestCase):
2312	n/a	def __init__(self, module):
2313	n/a	self.module = module
2314	n/a	DocTestCase.__init__(self, None)
2315	n/a
2316	n/a	def setUp(self):
2317	n/a	self.skipTest("DocTestSuite will not work with -O2 and above")
2318	n/a
2319	n/a	def test_skip(self):
2320	n/a	pass
2321	n/a
2322	n/a	def shortDescription(self):
2323	n/a	return "Skipping tests from %s" % self.module.__name__
2324	n/a
2325	n/a	__str__ = shortDescription
2326	n/a
2327	n/a
2328	n/a	class _DocTestSuite(unittest.TestSuite):
2329	n/a
2330	n/a	def _removeTestAtIndex(self, index):
2331	n/a	pass
2332	n/a
2333	n/a
2334	n/a	def DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None,
2335	n/a	**options):
2336	n/a	"""
2337	n/a	Convert doctest tests for a module to a unittest test suite.
2338	n/a
2339	n/a	This converts each documentation string in a module that
2340	n/a	contains doctest tests to a unittest test case. If any of the
2341	n/a	tests in a doc string fail, then the test case fails. An exception
2342	n/a	is raised showing the name of the file containing the test and a
2343	n/a	(sometimes approximate) line number.
2344	n/a
2345	n/a	The `module` argument provides the module to be tested. The argument
2346	n/a	can be either a module or a module name.
2347	n/a
2348	n/a	If no argument is given, the calling module is used.
2349	n/a
2350	n/a	A number of options may be provided as keyword arguments:
2351	n/a
2352	n/a	setUp
2353	n/a	A set-up function. This is called before running the
2354	n/a	tests in each file. The setUp function will be passed a DocTest
2355	n/a	object. The setUp function can access the test globals as the
2356	n/a	globs attribute of the test passed.
2357	n/a
2358	n/a	tearDown
2359	n/a	A tear-down function. This is called after running the
2360	n/a	tests in each file. The tearDown function will be passed a DocTest
2361	n/a	object. The tearDown function can access the test globals as the
2362	n/a	globs attribute of the test passed.
2363	n/a
2364	n/a	globs
2365	n/a	A dictionary containing initial global variables for the tests.
2366	n/a
2367	n/a	optionflags
2368	n/a	A set of doctest option flags expressed as an integer.
2369	n/a	"""
2370	n/a
2371	n/a	if test_finder is None:
2372	n/a	test_finder = DocTestFinder()
2373	n/a
2374	n/a	module = _normalize_module(module)
2375	n/a	tests = test_finder.find(module, globs=globs, extraglobs=extraglobs)
2376	n/a
2377	n/a	if not tests and sys.flags.optimize >=2:
2378	n/a	# Skip doctests when running with -O2
2379	n/a	suite = _DocTestSuite()
2380	n/a	suite.addTest(SkipDocTestCase(module))
2381	n/a	return suite
2382	n/a
2383	n/a	tests.sort()
2384	n/a	suite = _DocTestSuite()
2385	n/a
2386	n/a	for test in tests:
2387	n/a	if len(test.examples) == 0:
2388	n/a	continue
2389	n/a	if not test.filename:
2390	n/a	filename = module.__file__
2391	n/a	if filename[-4:] == ".pyc":
2392	n/a	filename = filename[:-1]
2393	n/a	test.filename = filename
2394	n/a	suite.addTest(DocTestCase(test, **options))
2395	n/a
2396	n/a	return suite
2397	n/a
2398	n/a	class DocFileCase(DocTestCase):
2399	n/a
2400	n/a	def id(self):
2401	n/a	return '_'.join(self._dt_test.name.split('.'))
2402	n/a
2403	n/a	def __repr__(self):
2404	n/a	return self._dt_test.filename
2405	n/a	__str__ = __repr__
2406	n/a
2407	n/a	def format_failure(self, err):
2408	n/a	return ('Failed doctest test for %s\n File "%s", line 0\n\n%s'
2409	n/a	% (self._dt_test.name, self._dt_test.filename, err)
2410	n/a	)
2411	n/a
2412	n/a	def DocFileTest(path, module_relative=True, package=None,
2413	n/a	globs=None, parser=DocTestParser(),
2414	n/a	encoding=None, **options):
2415	n/a	if globs is None:
2416	n/a	globs = {}
2417	n/a	else:
2418	n/a	globs = globs.copy()
2419	n/a
2420	n/a	if package and not module_relative:
2421	n/a	raise ValueError("Package may only be specified for module-"
2422	n/a	"relative paths.")
2423	n/a
2424	n/a	# Relativize the path.
2425	n/a	doc, path = _load_testfile(path, package, module_relative,
2426	n/a	encoding or "utf-8")
2427	n/a
2428	n/a	if "__file__" not in globs:
2429	n/a	globs["__file__"] = path
2430	n/a
2431	n/a	# Find the file and read it.
2432	n/a	name = os.path.basename(path)
2433	n/a
2434	n/a	# Convert it to a test, and wrap it in a DocFileCase.
2435	n/a	test = parser.get_doctest(doc, globs, name, path, 0)
2436	n/a	return DocFileCase(test, **options)
2437	n/a
2438	n/a	def DocFileSuite(paths, *kw):
2439	n/a	"""A unittest suite for one or more doctest files.
2440	n/a
2441	n/a	The path to each doctest file is given as a string; the
2442	n/a	interpretation of that string depends on the keyword argument
2443	n/a	"module_relative".
2444	n/a
2445	n/a	A number of options may be provided as keyword arguments:
2446	n/a
2447	n/a	module_relative
2448	n/a	If "module_relative" is True, then the given file paths are
2449	n/a	interpreted as os-independent module-relative paths. By
2450	n/a	default, these paths are relative to the calling module's
2451	n/a	directory; but if the "package" argument is specified, then
2452	n/a	they are relative to that package. To ensure os-independence,
2453	n/a	"filename" should use "/" characters to separate path
2454	n/a	segments, and may not be an absolute path (i.e., it may not
2455	n/a	begin with "/").
2456	n/a
2457	n/a	If "module_relative" is False, then the given file paths are
2458	n/a	interpreted as os-specific paths. These paths may be absolute
2459	n/a	or relative (to the current working directory).
2460	n/a
2461	n/a	package
2462	n/a	A Python package or the name of a Python package whose directory
2463	n/a	should be used as the base directory for module relative paths.
2464	n/a	If "package" is not specified, then the calling module's
2465	n/a	directory is used as the base directory for module relative
2466	n/a	filenames. It is an error to specify "package" if
2467	n/a	"module_relative" is False.
2468	n/a
2469	n/a	setUp
2470	n/a	A set-up function. This is called before running the
2471	n/a	tests in each file. The setUp function will be passed a DocTest
2472	n/a	object. The setUp function can access the test globals as the
2473	n/a	globs attribute of the test passed.
2474	n/a
2475	n/a	tearDown
2476	n/a	A tear-down function. This is called after running the
2477	n/a	tests in each file. The tearDown function will be passed a DocTest
2478	n/a	object. The tearDown function can access the test globals as the
2479	n/a	globs attribute of the test passed.
2480	n/a
2481	n/a	globs
2482	n/a	A dictionary containing initial global variables for the tests.
2483	n/a
2484	n/a	optionflags
2485	n/a	A set of doctest option flags expressed as an integer.
2486	n/a
2487	n/a	parser
2488	n/a	A DocTestParser (or subclass) that should be used to extract
2489	n/a	tests from the files.
2490	n/a
2491	n/a	encoding
2492	n/a	An encoding that will be used to convert the files to unicode.
2493	n/a	"""
2494	n/a	suite = _DocTestSuite()
2495	n/a
2496	n/a	# We do this here so that _normalize_module is called at the right
2497	n/a	# level. If it were called in DocFileTest, then this function
2498	n/a	# would be the caller and we might guess the package incorrectly.
2499	n/a	if kw.get('module_relative', True):
2500	n/a	kw['package'] = _normalize_module(kw.get('package'))
2501	n/a
2502	n/a	for path in paths:
2503	n/a	suite.addTest(DocFileTest(path, **kw))
2504	n/a
2505	n/a	return suite
2506	n/a
2507	n/a	######################################################################
2508	n/a	## 8. Debugging Support
2509	n/a	######################################################################
2510	n/a
2511	n/a	def script_from_examples(s):
2512	n/a	r"""Extract script from text with examples.
2513	n/a
2514	n/a	Converts text with examples to a Python script. Example input is
2515	n/a	converted to regular code. Example output and all other words
2516	n/a	are converted to comments:
2517	n/a
2518	n/a	>>> text = '''
2519	n/a	... Here are examples of simple math.
2520	n/a	...
2521	n/a	... Python has super accurate integer addition
2522	n/a	...
2523	n/a	... >>> 2 + 2
2524	n/a	... 5
2525	n/a	...
2526	n/a	... And very friendly error messages:
2527	n/a	...
2528	n/a	... >>> 1/0
2529	n/a	... To Infinity
2530	n/a	... And
2531	n/a	... Beyond
2532	n/a	...
2533	n/a	... You can use logic if you want:
2534	n/a	...
2535	n/a	... >>> if 0:
2536	n/a	... ... blah
2537	n/a	... ... blah
2538	n/a	... ...
2539	n/a	...
2540	n/a	... Ho hum
2541	n/a	... '''
2542	n/a
2543	n/a	>>> print(script_from_examples(text))
2544	n/a	# Here are examples of simple math.
2545	n/a	#
2546	n/a	# Python has super accurate integer addition
2547	n/a	#
2548	n/a	2 + 2
2549	n/a	# Expected:
2550	n/a	## 5
2551	n/a	#
2552	n/a	# And very friendly error messages:
2553	n/a	#
2554	n/a	1/0
2555	n/a	# Expected:
2556	n/a	## To Infinity
2557	n/a	## And
2558	n/a	## Beyond
2559	n/a	#
2560	n/a	# You can use logic if you want:
2561	n/a	#
2562	n/a	if 0:
2563	n/a	blah
2564	n/a	blah
2565	n/a	#
2566	n/a	# Ho hum
2567	n/a	<BLANKLINE>
2568	n/a	"""
2569	n/a	output = []
2570	n/a	for piece in DocTestParser().parse(s):
2571	n/a	if isinstance(piece, Example):
2572	n/a	# Add the example's source code (strip trailing NL)
2573	n/a	output.append(piece.source[:-1])
2574	n/a	# Add the expected output:
2575	n/a	want = piece.want
2576	n/a	if want:
2577	n/a	output.append('# Expected:')
2578	n/a	output += ['## '+l for l in want.split('\n')[:-1]]
2579	n/a	else:
2580	n/a	# Add non-example text.
2581	n/a	output += [_comment_line(l)
2582	n/a	for l in piece.split('\n')[:-1]]
2583	n/a
2584	n/a	# Trim junk on both ends.
2585	n/a	while output and output[-1] == '#':
2586	n/a	output.pop()
2587	n/a	while output and output[0] == '#':
2588	n/a	output.pop(0)
2589	n/a	# Combine the output, and return it.
2590	n/a	# Add a courtesy newline to prevent exec from choking (see bug #1172785)
2591	n/a	return '\n'.join(output) + '\n'
2592	n/a
2593	n/a	def testsource(module, name):
2594	n/a	"""Extract the test sources from a doctest docstring as a script.
2595	n/a
2596	n/a	Provide the module (or dotted name of the module) containing the
2597	n/a	test to be debugged and the name (within the module) of the object
2598	n/a	with the doc string with tests to be debugged.
2599	n/a	"""
2600	n/a	module = _normalize_module(module)
2601	n/a	tests = DocTestFinder().find(module)
2602	n/a	test = [t for t in tests if t.name == name]
2603	n/a	if not test:
2604	n/a	raise ValueError(name, "not found in tests")
2605	n/a	test = test[0]
2606	n/a	testsrc = script_from_examples(test.docstring)
2607	n/a	return testsrc
2608	n/a
2609	n/a	def debug_src(src, pm=False, globs=None):
2610	n/a	"""Debug a single doctest docstring, in argument `src`'"""
2611	n/a	testsrc = script_from_examples(src)
2612	n/a	debug_script(testsrc, pm, globs)
2613	n/a
2614	n/a	def debug_script(src, pm=False, globs=None):
2615	n/a	"Debug a test script. `src` is the script, as a string."
2616	n/a	import pdb
2617	n/a
2618	n/a	if globs:
2619	n/a	globs = globs.copy()
2620	n/a	else:
2621	n/a	globs = {}
2622	n/a
2623	n/a	if pm:
2624	n/a	try:
2625	n/a	exec(src, globs, globs)
2626	n/a	except:
2627	n/a	print(sys.exc_info()[1])
2628	n/a	p = pdb.Pdb(nosigint=True)
2629	n/a	p.reset()
2630	n/a	p.interaction(None, sys.exc_info()[2])
2631	n/a	else:
2632	n/a	pdb.Pdb(nosigint=True).run("exec(%r)" % src, globs, globs)
2633	n/a
2634	n/a	def debug(module, name, pm=False):
2635	n/a	"""Debug a single doctest docstring.
2636	n/a
2637	n/a	Provide the module (or dotted name of the module) containing the
2638	n/a	test to be debugged and the name (within the module) of the object
2639	n/a	with the docstring with tests to be debugged.
2640	n/a	"""
2641	n/a	module = _normalize_module(module)
2642	n/a	testsrc = testsource(module, name)
2643	n/a	debug_script(testsrc, pm, module.__dict__)
2644	n/a
2645	n/a	######################################################################
2646	n/a	## 9. Example Usage
2647	n/a	######################################################################
2648	n/a	class _TestClass:
2649	n/a	"""
2650	n/a	A pointless class, for sanity-checking of docstring testing.
2651	n/a
2652	n/a	Methods:
2653	n/a	square()
2654	n/a	get()
2655	n/a
2656	n/a	>>> _TestClass(13).get() + _TestClass(-12).get()
2657	n/a	1
2658	n/a	>>> hex(_TestClass(13).square().get())
2659	n/a	'0xa9'
2660	n/a	"""
2661	n/a
2662	n/a	def __init__(self, val):
2663	n/a	"""val -> _TestClass object with associated value val.
2664	n/a
2665	n/a	>>> t = _TestClass(123)
2666	n/a	>>> print(t.get())
2667	n/a	123
2668	n/a	"""
2669	n/a
2670	n/a	self.val = val
2671	n/a
2672	n/a	def square(self):
2673	n/a	"""square() -> square TestClass's associated value
2674	n/a
2675	n/a	>>> _TestClass(13).square().get()
2676	n/a	169
2677	n/a	"""
2678	n/a
2679	n/a	self.val = self.val ** 2
2680	n/a	return self
2681	n/a
2682	n/a	def get(self):
2683	n/a	"""get() -> return TestClass's associated value.
2684	n/a
2685	n/a	>>> x = _TestClass(-42)
2686	n/a	>>> print(x.get())
2687	n/a	-42
2688	n/a	"""
2689	n/a
2690	n/a	return self.val
2691	n/a
2692	n/a	__test__ = {"_TestClass": _TestClass,
2693	n/a	"string": r"""
2694	n/a	Example of a string object, searched as-is.
2695	n/a	>>> x = 1; y = 2
2696	n/a	>>> x + y, x * y
2697	n/a	(3, 2)
2698	n/a	""",
2699	n/a
2700	n/a	"bool-int equivalence": r"""
2701	n/a	In 2.2, boolean expressions displayed
2702	n/a	0 or 1. By default, we still accept
2703	n/a	them. This can be disabled by passing
2704	n/a	DONT_ACCEPT_TRUE_FOR_1 to the new
2705	n/a	optionflags argument.
2706	n/a	>>> 4 == 4
2707	n/a	1
2708	n/a	>>> 4 == 4
2709	n/a	True
2710	n/a	>>> 4 > 4
2711	n/a	0
2712	n/a	>>> 4 > 4
2713	n/a	False
2714	n/a	""",
2715	n/a
2716	n/a	"blank lines": r"""
2717	n/a	Blank lines can be marked with <BLANKLINE>:
2718	n/a	>>> print('foo\n\nbar\n')
2719	n/a	foo
2720	n/a	<BLANKLINE>
2721	n/a	bar
2722	n/a	<BLANKLINE>
2723	n/a	""",
2724	n/a
2725	n/a	"ellipsis": r"""
2726	n/a	If the ellipsis flag is used, then '...' can be used to
2727	n/a	elide substrings in the desired output:
2728	n/a	>>> print(list(range(1000))) #doctest: +ELLIPSIS
2729	n/a	[0, 1, 2, ..., 999]
2730	n/a	""",
2731	n/a
2732	n/a	"whitespace normalization": r"""
2733	n/a	If the whitespace normalization flag is used, then
2734	n/a	differences in whitespace are ignored.
2735	n/a	>>> print(list(range(30))) #doctest: +NORMALIZE_WHITESPACE
2736	n/a	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14,
2737	n/a	15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26,
2738	n/a	27, 28, 29]
2739	n/a	""",
2740	n/a	}
2741	n/a
2742	n/a
2743	n/a	def _test():
2744	n/a	parser = argparse.ArgumentParser(description="doctest runner")
2745	n/a	parser.add_argument('-v', '--verbose', action='store_true', default=False,
2746	n/a	help='print very verbose output for all tests')
2747	n/a	parser.add_argument('-o', '--option', action='append',
2748	n/a	choices=OPTIONFLAGS_BY_NAME.keys(), default=[],
2749	n/a	help=('specify a doctest option flag to apply'
2750	n/a	' to the test run; may be specified more'
2751	n/a	' than once to apply multiple options'))
2752	n/a	parser.add_argument('-f', '--fail-fast', action='store_true',
2753	n/a	help=('stop running tests after first failure (this'
2754	n/a	' is a shorthand for -o FAIL_FAST, and is'
2755	n/a	' in addition to any other -o options)'))
2756	n/a	parser.add_argument('file', nargs='+',
2757	n/a	help='file containing the tests to run')
2758	n/a	args = parser.parse_args()
2759	n/a	testfiles = args.file
2760	n/a	# Verbose used to be handled by the "inspect argv" magic in DocTestRunner,
2761	n/a	# but since we are using argparse we are passing it manually now.
2762	n/a	verbose = args.verbose
2763	n/a	options = 0
2764	n/a	for option in args.option:
2765	n/a	options \|= OPTIONFLAGS_BY_NAME[option]
2766	n/a	if args.fail_fast:
2767	n/a	options \|= FAIL_FAST
2768	n/a	for filename in testfiles:
2769	n/a	if filename.endswith(".py"):
2770	n/a	# It is a module -- insert its dir into sys.path and try to
2771	n/a	# import it. If it is part of a package, that possibly
2772	n/a	# won't work because of package imports.
2773	n/a	dirname, filename = os.path.split(filename)
2774	n/a	sys.path.insert(0, dirname)
2775	n/a	m = __import__(filename[:-3])
2776	n/a	del sys.path[0]
2777	n/a	failures, _ = testmod(m, verbose=verbose, optionflags=options)
2778	n/a	else:
2779	n/a	failures, _ = testfile(filename, module_relative=False,
2780	n/a	verbose=verbose, optionflags=options)
2781	n/a	if failures:
2782	n/a	return 1
2783	n/a	return 0
2784	n/a
2785	n/a
2786	n/a	if __name__ == "__main__":
2787	n/a	sys.exit(_test())