Python code coverage for Lib/test/test_doctest.py

#	count	content
1	n/a	"""
2	n/a	Test script for doctest.
3	n/a	"""
4	n/a
5	n/a	from test import support
6	n/a	import doctest
7	n/a	import functools
8	n/a	import os
9	n/a	import sys
10	n/a
11	n/a
12	n/a	# NOTE: There are some additional tests relating to interaction with
13	n/a	# zipimport in the test_zipimport_support test module.
14	n/a
15	n/a	######################################################################
16	n/a	## Sample Objects (used by test cases)
17	n/a	######################################################################
18	n/a
19	n/a	def sample_func(v):
20	n/a	"""
21	n/a	Blah blah
22	n/a
23	n/a	>>> print(sample_func(22))
24	n/a	44
25	n/a
26	n/a	Yee ha!
27	n/a	"""
28	n/a	return v+v
29	n/a
30	n/a	class SampleClass:
31	n/a	"""
32	n/a	>>> print(1)
33	n/a	1
34	n/a
35	n/a	>>> # comments get ignored. so are empty PS1 and PS2 prompts:
36	n/a	>>>
37	n/a	...
38	n/a
39	n/a	Multiline example:
40	n/a	>>> sc = SampleClass(3)
41	n/a	>>> for i in range(10):
42	n/a	... sc = sc.double()
43	n/a	... print(' ', sc.get(), sep='', end='')
44	n/a	6 12 24 48 96 192 384 768 1536 3072
45	n/a	"""
46	n/a	def __init__(self, val):
47	n/a	"""
48	n/a	>>> print(SampleClass(12).get())
49	n/a	12
50	n/a	"""
51	n/a	self.val = val
52	n/a
53	n/a	def double(self):
54	n/a	"""
55	n/a	>>> print(SampleClass(12).double().get())
56	n/a	24
57	n/a	"""
58	n/a	return SampleClass(self.val + self.val)
59	n/a
60	n/a	def get(self):
61	n/a	"""
62	n/a	>>> print(SampleClass(-5).get())
63	n/a	-5
64	n/a	"""
65	n/a	return self.val
66	n/a
67	n/a	def a_staticmethod(v):
68	n/a	"""
69	n/a	>>> print(SampleClass.a_staticmethod(10))
70	n/a	11
71	n/a	"""
72	n/a	return v+1
73	n/a	a_staticmethod = staticmethod(a_staticmethod)
74	n/a
75	n/a	def a_classmethod(cls, v):
76	n/a	"""
77	n/a	>>> print(SampleClass.a_classmethod(10))
78	n/a	12
79	n/a	>>> print(SampleClass(0).a_classmethod(10))
80	n/a	12
81	n/a	"""
82	n/a	return v+2
83	n/a	a_classmethod = classmethod(a_classmethod)
84	n/a
85	n/a	a_property = property(get, doc="""
86	n/a	>>> print(SampleClass(22).a_property)
87	n/a	22
88	n/a	""")
89	n/a
90	n/a	class NestedClass:
91	n/a	"""
92	n/a	>>> x = SampleClass.NestedClass(5)
93	n/a	>>> y = x.square()
94	n/a	>>> print(y.get())
95	n/a	25
96	n/a	"""
97	n/a	def __init__(self, val=0):
98	n/a	"""
99	n/a	>>> print(SampleClass.NestedClass().get())
100	n/a	0
101	n/a	"""
102	n/a	self.val = val
103	n/a	def square(self):
104	n/a	return SampleClass.NestedClass(self.val*self.val)
105	n/a	def get(self):
106	n/a	return self.val
107	n/a
108	n/a	class SampleNewStyleClass(object):
109	n/a	r"""
110	n/a	>>> print('1\n2\n3')
111	n/a	1
112	n/a	2
113	n/a	3
114	n/a	"""
115	n/a	def __init__(self, val):
116	n/a	"""
117	n/a	>>> print(SampleNewStyleClass(12).get())
118	n/a	12
119	n/a	"""
120	n/a	self.val = val
121	n/a
122	n/a	def double(self):
123	n/a	"""
124	n/a	>>> print(SampleNewStyleClass(12).double().get())
125	n/a	24
126	n/a	"""
127	n/a	return SampleNewStyleClass(self.val + self.val)
128	n/a
129	n/a	def get(self):
130	n/a	"""
131	n/a	>>> print(SampleNewStyleClass(-5).get())
132	n/a	-5
133	n/a	"""
134	n/a	return self.val
135	n/a
136	n/a	######################################################################
137	n/a	## Fake stdin (for testing interactive debugging)
138	n/a	######################################################################
139	n/a
140	n/a	class _FakeInput:
141	n/a	"""
142	n/a	A fake input stream for pdb's interactive debugger. Whenever a
143	n/a	line is read, print it (to simulate the user typing it), and then
144	n/a	return it. The set of lines to return is specified in the
145	n/a	constructor; they should not have trailing newlines.
146	n/a	"""
147	n/a	def __init__(self, lines):
148	n/a	self.lines = lines
149	n/a
150	n/a	def readline(self):
151	n/a	line = self.lines.pop(0)
152	n/a	print(line)
153	n/a	return line+'\n'
154	n/a
155	n/a	######################################################################
156	n/a	## Test Cases
157	n/a	######################################################################
158	n/a
159	n/a	def test_Example(): r"""
160	n/a	Unit tests for the `Example` class.
161	n/a
162	n/a	Example is a simple container class that holds:
163	n/a	- `source`: A source string.
164	n/a	- `want`: An expected output string.
165	n/a	- `exc_msg`: An expected exception message string (or None if no
166	n/a	exception is expected).
167	n/a	- `lineno`: A line number (within the docstring).
168	n/a	- `indent`: The example's indentation in the input string.
169	n/a	- `options`: An option dictionary, mapping option flags to True or
170	n/a	False.
171	n/a
172	n/a	These attributes are set by the constructor. `source` and `want` are
173	n/a	required; the other attributes all have default values:
174	n/a
175	n/a	>>> example = doctest.Example('print(1)', '1\n')
176	n/a	>>> (example.source, example.want, example.exc_msg,
177	n/a	... example.lineno, example.indent, example.options)
178	n/a	('print(1)\n', '1\n', None, 0, 0, {})
179	n/a
180	n/a	The first three attributes (`source`, `want`, and `exc_msg`) may be
181	n/a	specified positionally; the remaining arguments should be specified as
182	n/a	keyword arguments:
183	n/a
184	n/a	>>> exc_msg = 'IndexError: pop from an empty list'
185	n/a	>>> example = doctest.Example('[].pop()', '', exc_msg,
186	n/a	... lineno=5, indent=4,
187	n/a	... options={doctest.ELLIPSIS: True})
188	n/a	>>> (example.source, example.want, example.exc_msg,
189	n/a	... example.lineno, example.indent, example.options)
190	n/a	('[].pop()\n', '', 'IndexError: pop from an empty list\n', 5, 4, {8: True})
191	n/a
192	n/a	The constructor normalizes the `source` string to end in a newline:
193	n/a
194	n/a	Source spans a single line: no terminating newline.
195	n/a	>>> e = doctest.Example('print(1)', '1\n')
196	n/a	>>> e.source, e.want
197	n/a	('print(1)\n', '1\n')
198	n/a
199	n/a	>>> e = doctest.Example('print(1)\n', '1\n')
200	n/a	>>> e.source, e.want
201	n/a	('print(1)\n', '1\n')
202	n/a
203	n/a	Source spans multiple lines: require terminating newline.
204	n/a	>>> e = doctest.Example('print(1);\nprint(2)\n', '1\n2\n')
205	n/a	>>> e.source, e.want
206	n/a	('print(1);\nprint(2)\n', '1\n2\n')
207	n/a
208	n/a	>>> e = doctest.Example('print(1);\nprint(2)', '1\n2\n')
209	n/a	>>> e.source, e.want
210	n/a	('print(1);\nprint(2)\n', '1\n2\n')
211	n/a
212	n/a	Empty source string (which should never appear in real examples)
213	n/a	>>> e = doctest.Example('', '')
214	n/a	>>> e.source, e.want
215	n/a	('\n', '')
216	n/a
217	n/a	The constructor normalizes the `want` string to end in a newline,
218	n/a	unless it's the empty string:
219	n/a
220	n/a	>>> e = doctest.Example('print(1)', '1\n')
221	n/a	>>> e.source, e.want
222	n/a	('print(1)\n', '1\n')
223	n/a
224	n/a	>>> e = doctest.Example('print(1)', '1')
225	n/a	>>> e.source, e.want
226	n/a	('print(1)\n', '1\n')
227	n/a
228	n/a	>>> e = doctest.Example('print', '')
229	n/a	>>> e.source, e.want
230	n/a	('print\n', '')
231	n/a
232	n/a	The constructor normalizes the `exc_msg` string to end in a newline,
233	n/a	unless it's `None`:
234	n/a
235	n/a	Message spans one line
236	n/a	>>> exc_msg = 'IndexError: pop from an empty list'
237	n/a	>>> e = doctest.Example('[].pop()', '', exc_msg)
238	n/a	>>> e.exc_msg
239	n/a	'IndexError: pop from an empty list\n'
240	n/a
241	n/a	>>> exc_msg = 'IndexError: pop from an empty list\n'
242	n/a	>>> e = doctest.Example('[].pop()', '', exc_msg)
243	n/a	>>> e.exc_msg
244	n/a	'IndexError: pop from an empty list\n'
245	n/a
246	n/a	Message spans multiple lines
247	n/a	>>> exc_msg = 'ValueError: 1\n 2'
248	n/a	>>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
249	n/a	>>> e.exc_msg
250	n/a	'ValueError: 1\n 2\n'
251	n/a
252	n/a	>>> exc_msg = 'ValueError: 1\n 2\n'
253	n/a	>>> e = doctest.Example('raise ValueError("1\n 2")', '', exc_msg)
254	n/a	>>> e.exc_msg
255	n/a	'ValueError: 1\n 2\n'
256	n/a
257	n/a	Empty (but non-None) exception message (which should never appear
258	n/a	in real examples)
259	n/a	>>> exc_msg = ''
260	n/a	>>> e = doctest.Example('raise X()', '', exc_msg)
261	n/a	>>> e.exc_msg
262	n/a	'\n'
263	n/a
264	n/a	Compare `Example`:
265	n/a	>>> example = doctest.Example('print 1', '1\n')
266	n/a	>>> same_example = doctest.Example('print 1', '1\n')
267	n/a	>>> other_example = doctest.Example('print 42', '42\n')
268	n/a	>>> example == same_example
269	n/a	True
270	n/a	>>> example != same_example
271	n/a	False
272	n/a	>>> hash(example) == hash(same_example)
273	n/a	True
274	n/a	>>> example == other_example
275	n/a	False
276	n/a	>>> example != other_example
277	n/a	True
278	n/a	"""
279	n/a
280	n/a	def test_DocTest(): r"""
281	n/a	Unit tests for the `DocTest` class.
282	n/a
283	n/a	DocTest is a collection of examples, extracted from a docstring, along
284	n/a	with information about where the docstring comes from (a name,
285	n/a	filename, and line number). The docstring is parsed by the `DocTest`
286	n/a	constructor:
287	n/a
288	n/a	>>> docstring = '''
289	n/a	... >>> print(12)
290	n/a	... 12
291	n/a	...
292	n/a	... Non-example text.
293	n/a	...
294	n/a	... >>> print('another\\example')
295	n/a	... another
296	n/a	... example
297	n/a	... '''
298	n/a	>>> globs = {} # globals to run the test in.
299	n/a	>>> parser = doctest.DocTestParser()
300	n/a	>>> test = parser.get_doctest(docstring, globs, 'some_test',
301	n/a	... 'some_file', 20)
302	n/a	>>> print(test)
303	n/a	<DocTest some_test from some_file:20 (2 examples)>
304	n/a	>>> len(test.examples)
305	n/a	2
306	n/a	>>> e1, e2 = test.examples
307	n/a	>>> (e1.source, e1.want, e1.lineno)
308	n/a	('print(12)\n', '12\n', 1)
309	n/a	>>> (e2.source, e2.want, e2.lineno)
310	n/a	("print('another\\example')\n", 'another\nexample\n', 6)
311	n/a
312	n/a	Source information (name, filename, and line number) is available as
313	n/a	attributes on the doctest object:
314	n/a
315	n/a	>>> (test.name, test.filename, test.lineno)
316	n/a	('some_test', 'some_file', 20)
317	n/a
318	n/a	The line number of an example within its containing file is found by
319	n/a	adding the line number of the example and the line number of its
320	n/a	containing test:
321	n/a
322	n/a	>>> test.lineno + e1.lineno
323	n/a	21
324	n/a	>>> test.lineno + e2.lineno
325	n/a	26
326	n/a
327	n/a	If the docstring contains inconsistent leading whitespace in the
328	n/a	expected output of an example, then `DocTest` will raise a ValueError:
329	n/a
330	n/a	>>> docstring = r'''
331	n/a	... >>> print('bad\nindentation')
332	n/a	... bad
333	n/a	... indentation
334	n/a	... '''
335	n/a	>>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
336	n/a	Traceback (most recent call last):
337	n/a	ValueError: line 4 of the docstring for some_test has inconsistent leading whitespace: 'indentation'
338	n/a
339	n/a	If the docstring contains inconsistent leading whitespace on
340	n/a	continuation lines, then `DocTest` will raise a ValueError:
341	n/a
342	n/a	>>> docstring = r'''
343	n/a	... >>> print(('bad indentation',
344	n/a	... ... 2))
345	n/a	... ('bad', 'indentation')
346	n/a	... '''
347	n/a	>>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
348	n/a	Traceback (most recent call last):
349	n/a	ValueError: line 2 of the docstring for some_test has inconsistent leading whitespace: '... 2))'
350	n/a
351	n/a	If there's no blank space after a PS1 prompt ('>>>'), then `DocTest`
352	n/a	will raise a ValueError:
353	n/a
354	n/a	>>> docstring = '>>>print(1)\n1'
355	n/a	>>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
356	n/a	Traceback (most recent call last):
357	n/a	ValueError: line 1 of the docstring for some_test lacks blank after >>>: '>>>print(1)'
358	n/a
359	n/a	If there's no blank space after a PS2 prompt ('...'), then `DocTest`
360	n/a	will raise a ValueError:
361	n/a
362	n/a	>>> docstring = '>>> if 1:\n...print(1)\n1'
363	n/a	>>> parser.get_doctest(docstring, globs, 'some_test', 'filename', 0)
364	n/a	Traceback (most recent call last):
365	n/a	ValueError: line 2 of the docstring for some_test lacks blank after ...: '...print(1)'
366	n/a
367	n/a	Compare `DocTest`:
368	n/a
369	n/a	>>> docstring = '''
370	n/a	... >>> print 12
371	n/a	... 12
372	n/a	... '''
373	n/a	>>> test = parser.get_doctest(docstring, globs, 'some_test',
374	n/a	... 'some_test', 20)
375	n/a	>>> same_test = parser.get_doctest(docstring, globs, 'some_test',
376	n/a	... 'some_test', 20)
377	n/a	>>> test == same_test
378	n/a	True
379	n/a	>>> test != same_test
380	n/a	False
381	n/a	>>> hash(test) == hash(same_test)
382	n/a	True
383	n/a	>>> docstring = '''
384	n/a	... >>> print 42
385	n/a	... 42
386	n/a	... '''
387	n/a	>>> other_test = parser.get_doctest(docstring, globs, 'other_test',
388	n/a	... 'other_file', 10)
389	n/a	>>> test == other_test
390	n/a	False
391	n/a	>>> test != other_test
392	n/a	True
393	n/a
394	n/a	Compare `DocTestCase`:
395	n/a
396	n/a	>>> DocTestCase = doctest.DocTestCase
397	n/a	>>> test_case = DocTestCase(test)
398	n/a	>>> same_test_case = DocTestCase(same_test)
399	n/a	>>> other_test_case = DocTestCase(other_test)
400	n/a	>>> test_case == same_test_case
401	n/a	True
402	n/a	>>> test_case != same_test_case
403	n/a	False
404	n/a	>>> hash(test_case) == hash(same_test_case)
405	n/a	True
406	n/a	>>> test == other_test_case
407	n/a	False
408	n/a	>>> test != other_test_case
409	n/a	True
410	n/a
411	n/a	"""
412	n/a
413	n/a	class test_DocTestFinder:
414	n/a	def basics(): r"""
415	n/a	Unit tests for the `DocTestFinder` class.
416	n/a
417	n/a	DocTestFinder is used to extract DocTests from an object's docstring
418	n/a	and the docstrings of its contained objects. It can be used with
419	n/a	modules, functions, classes, methods, staticmethods, classmethods, and
420	n/a	properties.
421	n/a
422	n/a	Finding Tests in Functions
423	n/a	~~~~~~~~~~~~~~~~~~~~~~~~~~
424	n/a	For a function whose docstring contains examples, DocTestFinder.find()
425	n/a	will return a single test (for that function's docstring):
426	n/a
427	n/a	>>> finder = doctest.DocTestFinder()
428	n/a
429	n/a	We'll simulate a __file__ attr that ends in pyc:
430	n/a
431	n/a	>>> import test.test_doctest
432	n/a	>>> old = test.test_doctest.__file__
433	n/a	>>> test.test_doctest.__file__ = 'test_doctest.pyc'
434	n/a
435	n/a	>>> tests = finder.find(sample_func)
436	n/a
437	n/a	>>> print(tests) # doctest: +ELLIPSIS
438	n/a	[<DocTest sample_func from ...:19 (1 example)>]
439	n/a
440	n/a	The exact name depends on how test_doctest was invoked, so allow for
441	n/a	leading path components.
442	n/a
443	n/a	>>> tests[0].filename # doctest: +ELLIPSIS
444	n/a	'...test_doctest.py'
445	n/a
446	n/a	>>> test.test_doctest.__file__ = old
447	n/a
448	n/a
449	n/a	>>> e = tests[0].examples[0]
450	n/a	>>> (e.source, e.want, e.lineno)
451	n/a	('print(sample_func(22))\n', '44\n', 3)
452	n/a
453	n/a	By default, tests are created for objects with no docstring:
454	n/a
455	n/a	>>> def no_docstring(v):
456	n/a	... pass
457	n/a	>>> finder.find(no_docstring)
458	n/a	[]
459	n/a
460	n/a	However, the optional argument `exclude_empty` to the DocTestFinder
461	n/a	constructor can be used to exclude tests for objects with empty
462	n/a	docstrings:
463	n/a
464	n/a	>>> def no_docstring(v):
465	n/a	... pass
466	n/a	>>> excl_empty_finder = doctest.DocTestFinder(exclude_empty=True)
467	n/a	>>> excl_empty_finder.find(no_docstring)
468	n/a	[]
469	n/a
470	n/a	If the function has a docstring with no examples, then a test with no
471	n/a	examples is returned. (This lets `DocTestRunner` collect statistics
472	n/a	about which functions have no tests -- but is that useful? And should
473	n/a	an empty test also be created when there's no docstring?)
474	n/a
475	n/a	>>> def no_examples(v):
476	n/a	... ''' no doctest examples '''
477	n/a	>>> finder.find(no_examples) # doctest: +ELLIPSIS
478	n/a	[<DocTest no_examples from ...:1 (no examples)>]
479	n/a
480	n/a	Finding Tests in Classes
481	n/a	~~~~~~~~~~~~~~~~~~~~~~~~
482	n/a	For a class, DocTestFinder will create a test for the class's
483	n/a	docstring, and will recursively explore its contents, including
484	n/a	methods, classmethods, staticmethods, properties, and nested classes.
485	n/a
486	n/a	>>> finder = doctest.DocTestFinder()
487	n/a	>>> tests = finder.find(SampleClass)
488	n/a	>>> for t in tests:
489	n/a	... print('%2s %s' % (len(t.examples), t.name))
490	n/a	3 SampleClass
491	n/a	3 SampleClass.NestedClass
492	n/a	1 SampleClass.NestedClass.__init__
493	n/a	1 SampleClass.__init__
494	n/a	2 SampleClass.a_classmethod
495	n/a	1 SampleClass.a_property
496	n/a	1 SampleClass.a_staticmethod
497	n/a	1 SampleClass.double
498	n/a	1 SampleClass.get
499	n/a
500	n/a	New-style classes are also supported:
501	n/a
502	n/a	>>> tests = finder.find(SampleNewStyleClass)
503	n/a	>>> for t in tests:
504	n/a	... print('%2s %s' % (len(t.examples), t.name))
505	n/a	1 SampleNewStyleClass
506	n/a	1 SampleNewStyleClass.__init__
507	n/a	1 SampleNewStyleClass.double
508	n/a	1 SampleNewStyleClass.get
509	n/a
510	n/a	Finding Tests in Modules
511	n/a	~~~~~~~~~~~~~~~~~~~~~~~~
512	n/a	For a module, DocTestFinder will create a test for the class's
513	n/a	docstring, and will recursively explore its contents, including
514	n/a	functions, classes, and the `__test__` dictionary, if it exists:
515	n/a
516	n/a	>>> # A module
517	n/a	>>> import types
518	n/a	>>> m = types.ModuleType('some_module')
519	n/a	>>> def triple(val):
520	n/a	... '''
521	n/a	... >>> print(triple(11))
522	n/a	... 33
523	n/a	... '''
524	n/a	... return val*3
525	n/a	>>> m.__dict__.update({
526	n/a	... 'sample_func': sample_func,
527	n/a	... 'SampleClass': SampleClass,
528	n/a	... '__doc__': '''
529	n/a	... Module docstring.
530	n/a	... >>> print('module')
531	n/a	... module
532	n/a	... ''',
533	n/a	... '__test__': {
534	n/a	... 'd': '>>> print(6)\n6\n>>> print(7)\n7\n',
535	n/a	... 'c': triple}})
536	n/a
537	n/a	>>> finder = doctest.DocTestFinder()
538	n/a	>>> # Use module=test.test_doctest, to prevent doctest from
539	n/a	>>> # ignoring the objects since they weren't defined in m.
540	n/a	>>> import test.test_doctest
541	n/a	>>> tests = finder.find(m, module=test.test_doctest)
542	n/a	>>> for t in tests:
543	n/a	... print('%2s %s' % (len(t.examples), t.name))
544	n/a	1 some_module
545	n/a	3 some_module.SampleClass
546	n/a	3 some_module.SampleClass.NestedClass
547	n/a	1 some_module.SampleClass.NestedClass.__init__
548	n/a	1 some_module.SampleClass.__init__
549	n/a	2 some_module.SampleClass.a_classmethod
550	n/a	1 some_module.SampleClass.a_property
551	n/a	1 some_module.SampleClass.a_staticmethod
552	n/a	1 some_module.SampleClass.double
553	n/a	1 some_module.SampleClass.get
554	n/a	1 some_module.__test__.c
555	n/a	2 some_module.__test__.d
556	n/a	1 some_module.sample_func
557	n/a
558	n/a	Duplicate Removal
559	n/a	~~~~~~~~~~~~~~~~~
560	n/a	If a single object is listed twice (under different names), then tests
561	n/a	will only be generated for it once:
562	n/a
563	n/a	>>> from test import doctest_aliases
564	n/a	>>> assert doctest_aliases.TwoNames.f
565	n/a	>>> assert doctest_aliases.TwoNames.g
566	n/a	>>> tests = excl_empty_finder.find(doctest_aliases)
567	n/a	>>> print(len(tests))
568	n/a	2
569	n/a	>>> print(tests[0].name)
570	n/a	test.doctest_aliases.TwoNames
571	n/a
572	n/a	TwoNames.f and TwoNames.g are bound to the same object.
573	n/a	We can't guess which will be found in doctest's traversal of
574	n/a	TwoNames.__dict__ first, so we have to allow for either.
575	n/a
576	n/a	>>> tests[1].name.split('.')[-1] in ['f', 'g']
577	n/a	True
578	n/a
579	n/a	Empty Tests
580	n/a	~~~~~~~~~~~
581	n/a	By default, an object with no doctests doesn't create any tests:
582	n/a
583	n/a	>>> tests = doctest.DocTestFinder().find(SampleClass)
584	n/a	>>> for t in tests:
585	n/a	... print('%2s %s' % (len(t.examples), t.name))
586	n/a	3 SampleClass
587	n/a	3 SampleClass.NestedClass
588	n/a	1 SampleClass.NestedClass.__init__
589	n/a	1 SampleClass.__init__
590	n/a	2 SampleClass.a_classmethod
591	n/a	1 SampleClass.a_property
592	n/a	1 SampleClass.a_staticmethod
593	n/a	1 SampleClass.double
594	n/a	1 SampleClass.get
595	n/a
596	n/a	By default, that excluded objects with no doctests. exclude_empty=False
597	n/a	tells it to include (empty) tests for objects with no doctests. This feature
598	n/a	is really to support backward compatibility in what doctest.master.summarize()
599	n/a	displays.
600	n/a
601	n/a	>>> tests = doctest.DocTestFinder(exclude_empty=False).find(SampleClass)
602	n/a	>>> for t in tests:
603	n/a	... print('%2s %s' % (len(t.examples), t.name))
604	n/a	3 SampleClass
605	n/a	3 SampleClass.NestedClass
606	n/a	1 SampleClass.NestedClass.__init__
607	n/a	0 SampleClass.NestedClass.get
608	n/a	0 SampleClass.NestedClass.square
609	n/a	1 SampleClass.__init__
610	n/a	2 SampleClass.a_classmethod
611	n/a	1 SampleClass.a_property
612	n/a	1 SampleClass.a_staticmethod
613	n/a	1 SampleClass.double
614	n/a	1 SampleClass.get
615	n/a
616	n/a	Turning off Recursion
617	n/a	~~~~~~~~~~~~~~~~~~~~~
618	n/a	DocTestFinder can be told not to look for tests in contained objects
619	n/a	using the `recurse` flag:
620	n/a
621	n/a	>>> tests = doctest.DocTestFinder(recurse=False).find(SampleClass)
622	n/a	>>> for t in tests:
623	n/a	... print('%2s %s' % (len(t.examples), t.name))
624	n/a	3 SampleClass
625	n/a
626	n/a	Line numbers
627	n/a	~~~~~~~~~~~~
628	n/a	DocTestFinder finds the line number of each example:
629	n/a
630	n/a	>>> def f(x):
631	n/a	... '''
632	n/a	... >>> x = 12
633	n/a	...
634	n/a	... some text
635	n/a	...
636	n/a	... >>> # examples are not created for comments & bare prompts.
637	n/a	... >>>
638	n/a	... ...
639	n/a	...
640	n/a	... >>> for x in range(10):
641	n/a	... ... print(x, end=' ')
642	n/a	... 0 1 2 3 4 5 6 7 8 9
643	n/a	... >>> x//2
644	n/a	... 6
645	n/a	... '''
646	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
647	n/a	>>> [e.lineno for e in test.examples]
648	n/a	[1, 9, 12]
649	n/a	"""
650	n/a
651	n/a	if int.__doc__: # simple check for --without-doc-strings, skip if lacking
652	n/a	def non_Python_modules(): r"""
653	n/a
654	n/a	Finding Doctests in Modules Not Written in Python
655	n/a	~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
656	n/a	DocTestFinder can also find doctests in most modules not written in Python.
657	n/a	We'll use builtins as an example, since it almost certainly isn't written in
658	n/a	plain ol' Python and is guaranteed to be available.
659	n/a
660	n/a	>>> import builtins
661	n/a	>>> tests = doctest.DocTestFinder().find(builtins)
662	n/a	>>> 790 < len(tests) < 810 # approximate number of objects with docstrings
663	n/a	True
664	n/a	>>> real_tests = [t for t in tests if len(t.examples) > 0]
665	n/a	>>> len(real_tests) # objects that actually have doctests
666	n/a	8
667	n/a	>>> for t in real_tests:
668	n/a	... print('{} {}'.format(len(t.examples), t.name))
669	n/a	...
670	n/a	1 builtins.bin
671	n/a	3 builtins.float.as_integer_ratio
672	n/a	2 builtins.float.fromhex
673	n/a	2 builtins.float.hex
674	n/a	1 builtins.hex
675	n/a	1 builtins.int
676	n/a	2 builtins.int.bit_length
677	n/a	1 builtins.oct
678	n/a
679	n/a	Note here that 'bin', 'oct', and 'hex' are functions; 'float.as_integer_ratio',
680	n/a	'float.hex', and 'int.bit_length' are methods; 'float.fromhex' is a classmethod,
681	n/a	and 'int' is a type.
682	n/a	"""
683	n/a
684	n/a	def test_DocTestParser(): r"""
685	n/a	Unit tests for the `DocTestParser` class.
686	n/a
687	n/a	DocTestParser is used to parse docstrings containing doctest examples.
688	n/a
689	n/a	The `parse` method divides a docstring into examples and intervening
690	n/a	text:
691	n/a
692	n/a	>>> s = '''
693	n/a	... >>> x, y = 2, 3 # no output expected
694	n/a	... >>> if 1:
695	n/a	... ... print(x)
696	n/a	... ... print(y)
697	n/a	... 2
698	n/a	... 3
699	n/a	...
700	n/a	... Some text.
701	n/a	... >>> x+y
702	n/a	... 5
703	n/a	... '''
704	n/a	>>> parser = doctest.DocTestParser()
705	n/a	>>> for piece in parser.parse(s):
706	n/a	... if isinstance(piece, doctest.Example):
707	n/a	... print('Example:', (piece.source, piece.want, piece.lineno))
708	n/a	... else:
709	n/a	... print(' Text:', repr(piece))
710	n/a	Text: '\n'
711	n/a	Example: ('x, y = 2, 3 # no output expected\n', '', 1)
712	n/a	Text: ''
713	n/a	Example: ('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
714	n/a	Text: '\nSome text.\n'
715	n/a	Example: ('x+y\n', '5\n', 9)
716	n/a	Text: ''
717	n/a
718	n/a	The `get_examples` method returns just the examples:
719	n/a
720	n/a	>>> for piece in parser.get_examples(s):
721	n/a	... print((piece.source, piece.want, piece.lineno))
722	n/a	('x, y = 2, 3 # no output expected\n', '', 1)
723	n/a	('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
724	n/a	('x+y\n', '5\n', 9)
725	n/a
726	n/a	The `get_doctest` method creates a Test from the examples, along with the
727	n/a	given arguments:
728	n/a
729	n/a	>>> test = parser.get_doctest(s, {}, 'name', 'filename', lineno=5)
730	n/a	>>> (test.name, test.filename, test.lineno)
731	n/a	('name', 'filename', 5)
732	n/a	>>> for piece in test.examples:
733	n/a	... print((piece.source, piece.want, piece.lineno))
734	n/a	('x, y = 2, 3 # no output expected\n', '', 1)
735	n/a	('if 1:\n print(x)\n print(y)\n', '2\n3\n', 2)
736	n/a	('x+y\n', '5\n', 9)
737	n/a	"""
738	n/a
739	n/a	class test_DocTestRunner:
740	n/a	def basics(): r"""
741	n/a	Unit tests for the `DocTestRunner` class.
742	n/a
743	n/a	DocTestRunner is used to run DocTest test cases, and to accumulate
744	n/a	statistics. Here's a simple DocTest case we can use:
745	n/a
746	n/a	>>> def f(x):
747	n/a	... '''
748	n/a	... >>> x = 12
749	n/a	... >>> print(x)
750	n/a	... 12
751	n/a	... >>> x//2
752	n/a	... 6
753	n/a	... '''
754	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
755	n/a
756	n/a	The main DocTestRunner interface is the `run` method, which runs a
757	n/a	given DocTest case in a given namespace (globs). It returns a tuple
758	n/a	`(f,t)`, where `f` is the number of failed tests and `t` is the number
759	n/a	of tried tests.
760	n/a
761	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
762	n/a	TestResults(failed=0, attempted=3)
763	n/a
764	n/a	If any example produces incorrect output, then the test runner reports
765	n/a	the failure and proceeds to the next example:
766	n/a
767	n/a	>>> def f(x):
768	n/a	... '''
769	n/a	... >>> x = 12
770	n/a	... >>> print(x)
771	n/a	... 14
772	n/a	... >>> x//2
773	n/a	... 6
774	n/a	... '''
775	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
776	n/a	>>> doctest.DocTestRunner(verbose=True).run(test)
777	n/a	... # doctest: +ELLIPSIS
778	n/a	Trying:
779	n/a	x = 12
780	n/a	Expecting nothing
781	n/a	ok
782	n/a	Trying:
783	n/a	print(x)
784	n/a	Expecting:
785	n/a	14
786	n/a	**********************************************************************
787	n/a	File ..., line 4, in f
788	n/a	Failed example:
789	n/a	print(x)
790	n/a	Expected:
791	n/a	14
792	n/a	Got:
793	n/a	12
794	n/a	Trying:
795	n/a	x//2
796	n/a	Expecting:
797	n/a	6
798	n/a	ok
799	n/a	TestResults(failed=1, attempted=3)
800	n/a	"""
801	n/a	def verbose_flag(): r"""
802	n/a	The `verbose` flag makes the test runner generate more detailed
803	n/a	output:
804	n/a
805	n/a	>>> def f(x):
806	n/a	... '''
807	n/a	... >>> x = 12
808	n/a	... >>> print(x)
809	n/a	... 12
810	n/a	... >>> x//2
811	n/a	... 6
812	n/a	... '''
813	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
814	n/a
815	n/a	>>> doctest.DocTestRunner(verbose=True).run(test)
816	n/a	Trying:
817	n/a	x = 12
818	n/a	Expecting nothing
819	n/a	ok
820	n/a	Trying:
821	n/a	print(x)
822	n/a	Expecting:
823	n/a	12
824	n/a	ok
825	n/a	Trying:
826	n/a	x//2
827	n/a	Expecting:
828	n/a	6
829	n/a	ok
830	n/a	TestResults(failed=0, attempted=3)
831	n/a
832	n/a	If the `verbose` flag is unspecified, then the output will be verbose
833	n/a	iff `-v` appears in sys.argv:
834	n/a
835	n/a	>>> # Save the real sys.argv list.
836	n/a	>>> old_argv = sys.argv
837	n/a
838	n/a	>>> # If -v does not appear in sys.argv, then output isn't verbose.
839	n/a	>>> sys.argv = ['test']
840	n/a	>>> doctest.DocTestRunner().run(test)
841	n/a	TestResults(failed=0, attempted=3)
842	n/a
843	n/a	>>> # If -v does appear in sys.argv, then output is verbose.
844	n/a	>>> sys.argv = ['test', '-v']
845	n/a	>>> doctest.DocTestRunner().run(test)
846	n/a	Trying:
847	n/a	x = 12
848	n/a	Expecting nothing
849	n/a	ok
850	n/a	Trying:
851	n/a	print(x)
852	n/a	Expecting:
853	n/a	12
854	n/a	ok
855	n/a	Trying:
856	n/a	x//2
857	n/a	Expecting:
858	n/a	6
859	n/a	ok
860	n/a	TestResults(failed=0, attempted=3)
861	n/a
862	n/a	>>> # Restore sys.argv
863	n/a	>>> sys.argv = old_argv
864	n/a
865	n/a	In the remaining examples, the test runner's verbosity will be
866	n/a	explicitly set, to ensure that the test behavior is consistent.
867	n/a	"""
868	n/a	def exceptions(): r"""
869	n/a	Tests of `DocTestRunner`'s exception handling.
870	n/a
871	n/a	An expected exception is specified with a traceback message. The
872	n/a	lines between the first line and the type/value may be omitted or
873	n/a	replaced with any other string:
874	n/a
875	n/a	>>> def f(x):
876	n/a	... '''
877	n/a	... >>> x = 12
878	n/a	... >>> print(x//0)
879	n/a	... Traceback (most recent call last):
880	n/a	... ZeroDivisionError: integer division or modulo by zero
881	n/a	... '''
882	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
883	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
884	n/a	TestResults(failed=0, attempted=2)
885	n/a
886	n/a	An example may not generate output before it raises an exception; if
887	n/a	it does, then the traceback message will not be recognized as
888	n/a	signaling an expected exception, so the example will be reported as an
889	n/a	unexpected exception:
890	n/a
891	n/a	>>> def f(x):
892	n/a	... '''
893	n/a	... >>> x = 12
894	n/a	... >>> print('pre-exception output', x//0)
895	n/a	... pre-exception output
896	n/a	... Traceback (most recent call last):
897	n/a	... ZeroDivisionError: integer division or modulo by zero
898	n/a	... '''
899	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
900	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
901	n/a	... # doctest: +ELLIPSIS
902	n/a	**********************************************************************
903	n/a	File ..., line 4, in f
904	n/a	Failed example:
905	n/a	print('pre-exception output', x//0)
906	n/a	Exception raised:
907	n/a	...
908	n/a	ZeroDivisionError: integer division or modulo by zero
909	n/a	TestResults(failed=1, attempted=2)
910	n/a
911	n/a	Exception messages may contain newlines:
912	n/a
913	n/a	>>> def f(x):
914	n/a	... r'''
915	n/a	... >>> raise ValueError('multi\nline\nmessage')
916	n/a	... Traceback (most recent call last):
917	n/a	... ValueError: multi
918	n/a	... line
919	n/a	... message
920	n/a	... '''
921	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
922	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
923	n/a	TestResults(failed=0, attempted=1)
924	n/a
925	n/a	If an exception is expected, but an exception with the wrong type or
926	n/a	message is raised, then it is reported as a failure:
927	n/a
928	n/a	>>> def f(x):
929	n/a	... r'''
930	n/a	... >>> raise ValueError('message')
931	n/a	... Traceback (most recent call last):
932	n/a	... ValueError: wrong message
933	n/a	... '''
934	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
935	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
936	n/a	... # doctest: +ELLIPSIS
937	n/a	**********************************************************************
938	n/a	File ..., line 3, in f
939	n/a	Failed example:
940	n/a	raise ValueError('message')
941	n/a	Expected:
942	n/a	Traceback (most recent call last):
943	n/a	ValueError: wrong message
944	n/a	Got:
945	n/a	Traceback (most recent call last):
946	n/a	...
947	n/a	ValueError: message
948	n/a	TestResults(failed=1, attempted=1)
949	n/a
950	n/a	However, IGNORE_EXCEPTION_DETAIL can be used to allow a mismatch in the
951	n/a	detail:
952	n/a
953	n/a	>>> def f(x):
954	n/a	... r'''
955	n/a	... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
956	n/a	... Traceback (most recent call last):
957	n/a	... ValueError: wrong message
958	n/a	... '''
959	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
960	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
961	n/a	TestResults(failed=0, attempted=1)
962	n/a
963	n/a	IGNORE_EXCEPTION_DETAIL also ignores difference in exception formatting
964	n/a	between Python versions. For example, in Python 2.x, the module path of
965	n/a	the exception is not in the output, but this will fail under Python 3:
966	n/a
967	n/a	>>> def f(x):
968	n/a	... r'''
969	n/a	... >>> from http.client import HTTPException
970	n/a	... >>> raise HTTPException('message')
971	n/a	... Traceback (most recent call last):
972	n/a	... HTTPException: message
973	n/a	... '''
974	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
975	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
976	n/a	... # doctest: +ELLIPSIS
977	n/a	**********************************************************************
978	n/a	File ..., line 4, in f
979	n/a	Failed example:
980	n/a	raise HTTPException('message')
981	n/a	Expected:
982	n/a	Traceback (most recent call last):
983	n/a	HTTPException: message
984	n/a	Got:
985	n/a	Traceback (most recent call last):
986	n/a	...
987	n/a	http.client.HTTPException: message
988	n/a	TestResults(failed=1, attempted=2)
989	n/a
990	n/a	But in Python 3 the module path is included, and therefore a test must look
991	n/a	like the following test to succeed in Python 3. But that test will fail under
992	n/a	Python 2.
993	n/a
994	n/a	>>> def f(x):
995	n/a	... r'''
996	n/a	... >>> from http.client import HTTPException
997	n/a	... >>> raise HTTPException('message')
998	n/a	... Traceback (most recent call last):
999	n/a	... http.client.HTTPException: message
1000	n/a	... '''
1001	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1002	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1003	n/a	TestResults(failed=0, attempted=2)
1004	n/a
1005	n/a	However, with IGNORE_EXCEPTION_DETAIL, the module name of the exception
1006	n/a	(or its unexpected absence) will be ignored:
1007	n/a
1008	n/a	>>> def f(x):
1009	n/a	... r'''
1010	n/a	... >>> from http.client import HTTPException
1011	n/a	... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1012	n/a	... Traceback (most recent call last):
1013	n/a	... HTTPException: message
1014	n/a	... '''
1015	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1016	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1017	n/a	TestResults(failed=0, attempted=2)
1018	n/a
1019	n/a	The module path will be completely ignored, so two different module paths will
1020	n/a	still pass if IGNORE_EXCEPTION_DETAIL is given. This is intentional, so it can
1021	n/a	be used when exceptions have changed module.
1022	n/a
1023	n/a	>>> def f(x):
1024	n/a	... r'''
1025	n/a	... >>> from http.client import HTTPException
1026	n/a	... >>> raise HTTPException('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1027	n/a	... Traceback (most recent call last):
1028	n/a	... foo.bar.HTTPException: message
1029	n/a	... '''
1030	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1031	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1032	n/a	TestResults(failed=0, attempted=2)
1033	n/a
1034	n/a	But IGNORE_EXCEPTION_DETAIL does not allow a mismatch in the exception type:
1035	n/a
1036	n/a	>>> def f(x):
1037	n/a	... r'''
1038	n/a	... >>> raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1039	n/a	... Traceback (most recent call last):
1040	n/a	... TypeError: wrong type
1041	n/a	... '''
1042	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1043	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1044	n/a	... # doctest: +ELLIPSIS
1045	n/a	**********************************************************************
1046	n/a	File ..., line 3, in f
1047	n/a	Failed example:
1048	n/a	raise ValueError('message') #doctest: +IGNORE_EXCEPTION_DETAIL
1049	n/a	Expected:
1050	n/a	Traceback (most recent call last):
1051	n/a	TypeError: wrong type
1052	n/a	Got:
1053	n/a	Traceback (most recent call last):
1054	n/a	...
1055	n/a	ValueError: message
1056	n/a	TestResults(failed=1, attempted=1)
1057	n/a
1058	n/a	If the exception does not have a message, you can still use
1059	n/a	IGNORE_EXCEPTION_DETAIL to normalize the modules between Python 2 and 3:
1060	n/a
1061	n/a	>>> def f(x):
1062	n/a	... r'''
1063	n/a	... >>> from http.client import HTTPException
1064	n/a	... >>> raise HTTPException() #doctest: +IGNORE_EXCEPTION_DETAIL
1065	n/a	... Traceback (most recent call last):
1066	n/a	... foo.bar.HTTPException
1067	n/a	... '''
1068	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1069	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1070	n/a	TestResults(failed=0, attempted=2)
1071	n/a
1072	n/a	Note that a trailing colon doesn't matter either:
1073	n/a
1074	n/a	>>> def f(x):
1075	n/a	... r'''
1076	n/a	... >>> from http.client import HTTPException
1077	n/a	... >>> raise HTTPException() #doctest: +IGNORE_EXCEPTION_DETAIL
1078	n/a	... Traceback (most recent call last):
1079	n/a	... foo.bar.HTTPException:
1080	n/a	... '''
1081	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1082	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1083	n/a	TestResults(failed=0, attempted=2)
1084	n/a
1085	n/a	If an exception is raised but not expected, then it is reported as an
1086	n/a	unexpected exception:
1087	n/a
1088	n/a	>>> def f(x):
1089	n/a	... r'''
1090	n/a	... >>> 1//0
1091	n/a	... 0
1092	n/a	... '''
1093	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1094	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1095	n/a	... # doctest: +ELLIPSIS
1096	n/a	**********************************************************************
1097	n/a	File ..., line 3, in f
1098	n/a	Failed example:
1099	n/a	1//0
1100	n/a	Exception raised:
1101	n/a	Traceback (most recent call last):
1102	n/a	...
1103	n/a	ZeroDivisionError: integer division or modulo by zero
1104	n/a	TestResults(failed=1, attempted=1)
1105	n/a	"""
1106	n/a	def displayhook(): r"""
1107	n/a	Test that changing sys.displayhook doesn't matter for doctest.
1108	n/a
1109	n/a	>>> import sys
1110	n/a	>>> orig_displayhook = sys.displayhook
1111	n/a	>>> def my_displayhook(x):
1112	n/a	... print('hi!')
1113	n/a	>>> sys.displayhook = my_displayhook
1114	n/a	>>> def f():
1115	n/a	... '''
1116	n/a	... >>> 3
1117	n/a	... 3
1118	n/a	... '''
1119	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1120	n/a	>>> r = doctest.DocTestRunner(verbose=False).run(test)
1121	n/a	>>> post_displayhook = sys.displayhook
1122	n/a
1123	n/a	We need to restore sys.displayhook now, so that we'll be able to test
1124	n/a	results.
1125	n/a
1126	n/a	>>> sys.displayhook = orig_displayhook
1127	n/a
1128	n/a	Ok, now we can check that everything is ok.
1129	n/a
1130	n/a	>>> r
1131	n/a	TestResults(failed=0, attempted=1)
1132	n/a	>>> post_displayhook is my_displayhook
1133	n/a	True
1134	n/a	"""
1135	n/a	def optionflags(): r"""
1136	n/a	Tests of `DocTestRunner`'s option flag handling.
1137	n/a
1138	n/a	Several option flags can be used to customize the behavior of the test
1139	n/a	runner. These are defined as module constants in doctest, and passed
1140	n/a	to the DocTestRunner constructor (multiple constants should be ORed
1141	n/a	together).
1142	n/a
1143	n/a	The DONT_ACCEPT_TRUE_FOR_1 flag disables matches between True/False
1144	n/a	and 1/0:
1145	n/a
1146	n/a	>>> def f(x):
1147	n/a	... '>>> True\n1\n'
1148	n/a
1149	n/a	>>> # Without the flag:
1150	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1151	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1152	n/a	TestResults(failed=0, attempted=1)
1153	n/a
1154	n/a	>>> # With the flag:
1155	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1156	n/a	>>> flags = doctest.DONT_ACCEPT_TRUE_FOR_1
1157	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1158	n/a	... # doctest: +ELLIPSIS
1159	n/a	**********************************************************************
1160	n/a	File ..., line 2, in f
1161	n/a	Failed example:
1162	n/a	True
1163	n/a	Expected:
1164	n/a	1
1165	n/a	Got:
1166	n/a	True
1167	n/a	TestResults(failed=1, attempted=1)
1168	n/a
1169	n/a	The DONT_ACCEPT_BLANKLINE flag disables the match between blank lines
1170	n/a	and the '<BLANKLINE>' marker:
1171	n/a
1172	n/a	>>> def f(x):
1173	n/a	... '>>> print("a\\n\\nb")\na\n<BLANKLINE>\nb\n'
1174	n/a
1175	n/a	>>> # Without the flag:
1176	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1177	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1178	n/a	TestResults(failed=0, attempted=1)
1179	n/a
1180	n/a	>>> # With the flag:
1181	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1182	n/a	>>> flags = doctest.DONT_ACCEPT_BLANKLINE
1183	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1184	n/a	... # doctest: +ELLIPSIS
1185	n/a	**********************************************************************
1186	n/a	File ..., line 2, in f
1187	n/a	Failed example:
1188	n/a	print("a\n\nb")
1189	n/a	Expected:
1190	n/a	a
1191	n/a	<BLANKLINE>
1192	n/a	b
1193	n/a	Got:
1194	n/a	a
1195	n/a	<BLANKLINE>
1196	n/a	b
1197	n/a	TestResults(failed=1, attempted=1)
1198	n/a
1199	n/a	The NORMALIZE_WHITESPACE flag causes all sequences of whitespace to be
1200	n/a	treated as equal:
1201	n/a
1202	n/a	>>> def f(x):
1203	n/a	... '>>> print(1, 2, 3)\n 1 2\n 3'
1204	n/a
1205	n/a	>>> # Without the flag:
1206	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1207	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1208	n/a	... # doctest: +ELLIPSIS
1209	n/a	**********************************************************************
1210	n/a	File ..., line 2, in f
1211	n/a	Failed example:
1212	n/a	print(1, 2, 3)
1213	n/a	Expected:
1214	n/a	1 2
1215	n/a	3
1216	n/a	Got:
1217	n/a	1 2 3
1218	n/a	TestResults(failed=1, attempted=1)
1219	n/a
1220	n/a	>>> # With the flag:
1221	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1222	n/a	>>> flags = doctest.NORMALIZE_WHITESPACE
1223	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1224	n/a	TestResults(failed=0, attempted=1)
1225	n/a
1226	n/a	An example from the docs:
1227	n/a	>>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE
1228	n/a	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,
1229	n/a	10, 11, 12, 13, 14, 15, 16, 17, 18, 19]
1230	n/a
1231	n/a	The ELLIPSIS flag causes ellipsis marker ("...") in the expected
1232	n/a	output to match any substring in the actual output:
1233	n/a
1234	n/a	>>> def f(x):
1235	n/a	... '>>> print(list(range(15)))\n[0, 1, 2, ..., 14]\n'
1236	n/a
1237	n/a	>>> # Without the flag:
1238	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1239	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1240	n/a	... # doctest: +ELLIPSIS
1241	n/a	**********************************************************************
1242	n/a	File ..., line 2, in f
1243	n/a	Failed example:
1244	n/a	print(list(range(15)))
1245	n/a	Expected:
1246	n/a	[0, 1, 2, ..., 14]
1247	n/a	Got:
1248	n/a	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14]
1249	n/a	TestResults(failed=1, attempted=1)
1250	n/a
1251	n/a	>>> # With the flag:
1252	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1253	n/a	>>> flags = doctest.ELLIPSIS
1254	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1255	n/a	TestResults(failed=0, attempted=1)
1256	n/a
1257	n/a	... also matches nothing:
1258	n/a
1259	n/a	>>> if 1:
1260	n/a	... for i in range(100):
1261	n/a	... print(i**2, end=' ') #doctest: +ELLIPSIS
1262	n/a	... print('!')
1263	n/a	0 1...4...9 16 ... 36 49 64 ... 9801 !
1264	n/a
1265	n/a	... can be surprising; e.g., this test passes:
1266	n/a
1267	n/a	>>> if 1: #doctest: +ELLIPSIS
1268	n/a	... for i in range(20):
1269	n/a	... print(i, end=' ')
1270	n/a	... print(20)
1271	n/a	0 1 2 ...1...2...0
1272	n/a
1273	n/a	Examples from the docs:
1274	n/a
1275	n/a	>>> print(list(range(20))) # doctest:+ELLIPSIS
1276	n/a	[0, 1, ..., 18, 19]
1277	n/a
1278	n/a	>>> print(list(range(20))) # doctest: +ELLIPSIS
1279	n/a	... # doctest: +NORMALIZE_WHITESPACE
1280	n/a	[0, 1, ..., 18, 19]
1281	n/a
1282	n/a	The SKIP flag causes an example to be skipped entirely. I.e., the
1283	n/a	example is not run. It can be useful in contexts where doctest
1284	n/a	examples serve as both documentation and test cases, and an example
1285	n/a	should be included for documentation purposes, but should not be
1286	n/a	checked (e.g., because its output is random, or depends on resources
1287	n/a	which would be unavailable.) The SKIP flag can also be used for
1288	n/a	'commenting out' broken examples.
1289	n/a
1290	n/a	>>> import unavailable_resource # doctest: +SKIP
1291	n/a	>>> unavailable_resource.do_something() # doctest: +SKIP
1292	n/a	>>> unavailable_resource.blow_up() # doctest: +SKIP
1293	n/a	Traceback (most recent call last):
1294	n/a	...
1295	n/a	UncheckedBlowUpError: Nobody checks me.
1296	n/a
1297	n/a	>>> import random
1298	n/a	>>> print(random.random()) # doctest: +SKIP
1299	n/a	0.721216923889
1300	n/a
1301	n/a	The REPORT_UDIFF flag causes failures that involve multi-line expected
1302	n/a	and actual outputs to be displayed using a unified diff:
1303	n/a
1304	n/a	>>> def f(x):
1305	n/a	... r'''
1306	n/a	... >>> print('\n'.join('abcdefg'))
1307	n/a	... a
1308	n/a	... B
1309	n/a	... c
1310	n/a	... d
1311	n/a	... f
1312	n/a	... g
1313	n/a	... h
1314	n/a	... '''
1315	n/a
1316	n/a	>>> # Without the flag:
1317	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1318	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1319	n/a	... # doctest: +ELLIPSIS
1320	n/a	**********************************************************************
1321	n/a	File ..., line 3, in f
1322	n/a	Failed example:
1323	n/a	print('\n'.join('abcdefg'))
1324	n/a	Expected:
1325	n/a	a
1326	n/a	B
1327	n/a	c
1328	n/a	d
1329	n/a	f
1330	n/a	g
1331	n/a	h
1332	n/a	Got:
1333	n/a	a
1334	n/a	b
1335	n/a	c
1336	n/a	d
1337	n/a	e
1338	n/a	f
1339	n/a	g
1340	n/a	TestResults(failed=1, attempted=1)
1341	n/a
1342	n/a	>>> # With the flag:
1343	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1344	n/a	>>> flags = doctest.REPORT_UDIFF
1345	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1346	n/a	... # doctest: +ELLIPSIS
1347	n/a	**********************************************************************
1348	n/a	File ..., line 3, in f
1349	n/a	Failed example:
1350	n/a	print('\n'.join('abcdefg'))
1351	n/a	Differences (unified diff with -expected +actual):
1352	n/a	@@ -1,7 +1,7 @@
1353	n/a	a
1354	n/a	-B
1355	n/a	+b
1356	n/a	c
1357	n/a	d
1358	n/a	+e
1359	n/a	f
1360	n/a	g
1361	n/a	-h
1362	n/a	TestResults(failed=1, attempted=1)
1363	n/a
1364	n/a	The REPORT_CDIFF flag causes failures that involve multi-line expected
1365	n/a	and actual outputs to be displayed using a context diff:
1366	n/a
1367	n/a	>>> # Reuse f() from the REPORT_UDIFF example, above.
1368	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1369	n/a	>>> flags = doctest.REPORT_CDIFF
1370	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1371	n/a	... # doctest: +ELLIPSIS
1372	n/a	**********************************************************************
1373	n/a	File ..., line 3, in f
1374	n/a	Failed example:
1375	n/a	print('\n'.join('abcdefg'))
1376	n/a	Differences (context diff with expected followed by actual):
1377	n/a	***************
1378	n/a	* 1,7 **
1379	n/a	a
1380	n/a	! B
1381	n/a	c
1382	n/a	d
1383	n/a	f
1384	n/a	g
1385	n/a	- h
1386	n/a	--- 1,7 ----
1387	n/a	a
1388	n/a	! b
1389	n/a	c
1390	n/a	d
1391	n/a	+ e
1392	n/a	f
1393	n/a	g
1394	n/a	TestResults(failed=1, attempted=1)
1395	n/a
1396	n/a
1397	n/a	The REPORT_NDIFF flag causes failures to use the difflib.Differ algorithm
1398	n/a	used by the popular ndiff.py utility. This does intraline difference
1399	n/a	marking, as well as interline differences.
1400	n/a
1401	n/a	>>> def f(x):
1402	n/a	... r'''
1403	n/a	... >>> print("a b c d e f g h i j k l m")
1404	n/a	... a b c d e f g h i j k 1 m
1405	n/a	... '''
1406	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1407	n/a	>>> flags = doctest.REPORT_NDIFF
1408	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1409	n/a	... # doctest: +ELLIPSIS
1410	n/a	**********************************************************************
1411	n/a	File ..., line 3, in f
1412	n/a	Failed example:
1413	n/a	print("a b c d e f g h i j k l m")
1414	n/a	Differences (ndiff with -expected +actual):
1415	n/a	- a b c d e f g h i j k 1 m
1416	n/a	? ^
1417	n/a	+ a b c d e f g h i j k l m
1418	n/a	? + ++ ^
1419	n/a	TestResults(failed=1, attempted=1)
1420	n/a
1421	n/a	The REPORT_ONLY_FIRST_FAILURE suppresses result output after the first
1422	n/a	failing example:
1423	n/a
1424	n/a	>>> def f(x):
1425	n/a	... r'''
1426	n/a	... >>> print(1) # first success
1427	n/a	... 1
1428	n/a	... >>> print(2) # first failure
1429	n/a	... 200
1430	n/a	... >>> print(3) # second failure
1431	n/a	... 300
1432	n/a	... >>> print(4) # second success
1433	n/a	... 4
1434	n/a	... >>> print(5) # third failure
1435	n/a	... 500
1436	n/a	... '''
1437	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1438	n/a	>>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1439	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1440	n/a	... # doctest: +ELLIPSIS
1441	n/a	**********************************************************************
1442	n/a	File ..., line 5, in f
1443	n/a	Failed example:
1444	n/a	print(2) # first failure
1445	n/a	Expected:
1446	n/a	200
1447	n/a	Got:
1448	n/a	2
1449	n/a	TestResults(failed=3, attempted=5)
1450	n/a
1451	n/a	However, output from `report_start` is not suppressed:
1452	n/a
1453	n/a	>>> doctest.DocTestRunner(verbose=True, optionflags=flags).run(test)
1454	n/a	... # doctest: +ELLIPSIS
1455	n/a	Trying:
1456	n/a	print(1) # first success
1457	n/a	Expecting:
1458	n/a	1
1459	n/a	ok
1460	n/a	Trying:
1461	n/a	print(2) # first failure
1462	n/a	Expecting:
1463	n/a	200
1464	n/a	**********************************************************************
1465	n/a	File ..., line 5, in f
1466	n/a	Failed example:
1467	n/a	print(2) # first failure
1468	n/a	Expected:
1469	n/a	200
1470	n/a	Got:
1471	n/a	2
1472	n/a	TestResults(failed=3, attempted=5)
1473	n/a
1474	n/a	The FAIL_FAST flag causes the runner to exit after the first failing example,
1475	n/a	so subsequent examples are not even attempted:
1476	n/a
1477	n/a	>>> flags = doctest.FAIL_FAST
1478	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1479	n/a	... # doctest: +ELLIPSIS
1480	n/a	**********************************************************************
1481	n/a	File ..., line 5, in f
1482	n/a	Failed example:
1483	n/a	print(2) # first failure
1484	n/a	Expected:
1485	n/a	200
1486	n/a	Got:
1487	n/a	2
1488	n/a	TestResults(failed=1, attempted=2)
1489	n/a
1490	n/a	Specifying both FAIL_FAST and REPORT_ONLY_FIRST_FAILURE is equivalent to
1491	n/a	FAIL_FAST only:
1492	n/a
1493	n/a	>>> flags = doctest.FAIL_FAST \| doctest.REPORT_ONLY_FIRST_FAILURE
1494	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1495	n/a	... # doctest: +ELLIPSIS
1496	n/a	**********************************************************************
1497	n/a	File ..., line 5, in f
1498	n/a	Failed example:
1499	n/a	print(2) # first failure
1500	n/a	Expected:
1501	n/a	200
1502	n/a	Got:
1503	n/a	2
1504	n/a	TestResults(failed=1, attempted=2)
1505	n/a
1506	n/a	For the purposes of both REPORT_ONLY_FIRST_FAILURE and FAIL_FAST, unexpected
1507	n/a	exceptions count as failures:
1508	n/a
1509	n/a	>>> def f(x):
1510	n/a	... r'''
1511	n/a	... >>> print(1) # first success
1512	n/a	... 1
1513	n/a	... >>> raise ValueError(2) # first failure
1514	n/a	... 200
1515	n/a	... >>> print(3) # second failure
1516	n/a	... 300
1517	n/a	... >>> print(4) # second success
1518	n/a	... 4
1519	n/a	... >>> print(5) # third failure
1520	n/a	... 500
1521	n/a	... '''
1522	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1523	n/a	>>> flags = doctest.REPORT_ONLY_FIRST_FAILURE
1524	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1525	n/a	... # doctest: +ELLIPSIS
1526	n/a	**********************************************************************
1527	n/a	File ..., line 5, in f
1528	n/a	Failed example:
1529	n/a	raise ValueError(2) # first failure
1530	n/a	Exception raised:
1531	n/a	...
1532	n/a	ValueError: 2
1533	n/a	TestResults(failed=3, attempted=5)
1534	n/a	>>> flags = doctest.FAIL_FAST
1535	n/a	>>> doctest.DocTestRunner(verbose=False, optionflags=flags).run(test)
1536	n/a	... # doctest: +ELLIPSIS
1537	n/a	**********************************************************************
1538	n/a	File ..., line 5, in f
1539	n/a	Failed example:
1540	n/a	raise ValueError(2) # first failure
1541	n/a	Exception raised:
1542	n/a	...
1543	n/a	ValueError: 2
1544	n/a	TestResults(failed=1, attempted=2)
1545	n/a
1546	n/a	New option flags can also be registered, via register_optionflag(). Here
1547	n/a	we reach into doctest's internals a bit.
1548	n/a
1549	n/a	>>> unlikely = "UNLIKELY_OPTION_NAME"
1550	n/a	>>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1551	n/a	False
1552	n/a	>>> new_flag_value = doctest.register_optionflag(unlikely)
1553	n/a	>>> unlikely in doctest.OPTIONFLAGS_BY_NAME
1554	n/a	True
1555	n/a
1556	n/a	Before 2.4.4/2.5, registering a name more than once erroneously created
1557	n/a	more than one flag value. Here we verify that's fixed:
1558	n/a
1559	n/a	>>> redundant_flag_value = doctest.register_optionflag(unlikely)
1560	n/a	>>> redundant_flag_value == new_flag_value
1561	n/a	True
1562	n/a
1563	n/a	Clean up.
1564	n/a	>>> del doctest.OPTIONFLAGS_BY_NAME[unlikely]
1565	n/a
1566	n/a	"""
1567	n/a
1568	n/a	def option_directives(): r"""
1569	n/a	Tests of `DocTestRunner`'s option directive mechanism.
1570	n/a
1571	n/a	Option directives can be used to turn option flags on or off for a
1572	n/a	single example. To turn an option on for an example, follow that
1573	n/a	example with a comment of the form ``# doctest: +OPTION``:
1574	n/a
1575	n/a	>>> def f(x): r'''
1576	n/a	... >>> print(list(range(10))) # should fail: no ellipsis
1577	n/a	... [0, 1, ..., 9]
1578	n/a	...
1579	n/a	... >>> print(list(range(10))) # doctest: +ELLIPSIS
1580	n/a	... [0, 1, ..., 9]
1581	n/a	... '''
1582	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1583	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1584	n/a	... # doctest: +ELLIPSIS
1585	n/a	**********************************************************************
1586	n/a	File ..., line 2, in f
1587	n/a	Failed example:
1588	n/a	print(list(range(10))) # should fail: no ellipsis
1589	n/a	Expected:
1590	n/a	[0, 1, ..., 9]
1591	n/a	Got:
1592	n/a	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1593	n/a	TestResults(failed=1, attempted=2)
1594	n/a
1595	n/a	To turn an option off for an example, follow that example with a
1596	n/a	comment of the form ``# doctest: -OPTION``:
1597	n/a
1598	n/a	>>> def f(x): r'''
1599	n/a	... >>> print(list(range(10)))
1600	n/a	... [0, 1, ..., 9]
1601	n/a	...
1602	n/a	... >>> # should fail: no ellipsis
1603	n/a	... >>> print(list(range(10))) # doctest: -ELLIPSIS
1604	n/a	... [0, 1, ..., 9]
1605	n/a	... '''
1606	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1607	n/a	>>> doctest.DocTestRunner(verbose=False,
1608	n/a	... optionflags=doctest.ELLIPSIS).run(test)
1609	n/a	... # doctest: +ELLIPSIS
1610	n/a	**********************************************************************
1611	n/a	File ..., line 6, in f
1612	n/a	Failed example:
1613	n/a	print(list(range(10))) # doctest: -ELLIPSIS
1614	n/a	Expected:
1615	n/a	[0, 1, ..., 9]
1616	n/a	Got:
1617	n/a	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1618	n/a	TestResults(failed=1, attempted=2)
1619	n/a
1620	n/a	Option directives affect only the example that they appear with; they
1621	n/a	do not change the options for surrounding examples:
1622	n/a
1623	n/a	>>> def f(x): r'''
1624	n/a	... >>> print(list(range(10))) # Should fail: no ellipsis
1625	n/a	... [0, 1, ..., 9]
1626	n/a	...
1627	n/a	... >>> print(list(range(10))) # doctest: +ELLIPSIS
1628	n/a	... [0, 1, ..., 9]
1629	n/a	...
1630	n/a	... >>> print(list(range(10))) # Should fail: no ellipsis
1631	n/a	... [0, 1, ..., 9]
1632	n/a	... '''
1633	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1634	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1635	n/a	... # doctest: +ELLIPSIS
1636	n/a	**********************************************************************
1637	n/a	File ..., line 2, in f
1638	n/a	Failed example:
1639	n/a	print(list(range(10))) # Should fail: no ellipsis
1640	n/a	Expected:
1641	n/a	[0, 1, ..., 9]
1642	n/a	Got:
1643	n/a	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1644	n/a	**********************************************************************
1645	n/a	File ..., line 8, in f
1646	n/a	Failed example:
1647	n/a	print(list(range(10))) # Should fail: no ellipsis
1648	n/a	Expected:
1649	n/a	[0, 1, ..., 9]
1650	n/a	Got:
1651	n/a	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1652	n/a	TestResults(failed=2, attempted=3)
1653	n/a
1654	n/a	Multiple options may be modified by a single option directive. They
1655	n/a	may be separated by whitespace, commas, or both:
1656	n/a
1657	n/a	>>> def f(x): r'''
1658	n/a	... >>> print(list(range(10))) # Should fail
1659	n/a	... [0, 1, ..., 9]
1660	n/a	... >>> print(list(range(10))) # Should succeed
1661	n/a	... ... # doctest: +ELLIPSIS +NORMALIZE_WHITESPACE
1662	n/a	... [0, 1, ..., 9]
1663	n/a	... '''
1664	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1665	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1666	n/a	... # doctest: +ELLIPSIS
1667	n/a	**********************************************************************
1668	n/a	File ..., line 2, in f
1669	n/a	Failed example:
1670	n/a	print(list(range(10))) # Should fail
1671	n/a	Expected:
1672	n/a	[0, 1, ..., 9]
1673	n/a	Got:
1674	n/a	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1675	n/a	TestResults(failed=1, attempted=2)
1676	n/a
1677	n/a	>>> def f(x): r'''
1678	n/a	... >>> print(list(range(10))) # Should fail
1679	n/a	... [0, 1, ..., 9]
1680	n/a	... >>> print(list(range(10))) # Should succeed
1681	n/a	... ... # doctest: +ELLIPSIS,+NORMALIZE_WHITESPACE
1682	n/a	... [0, 1, ..., 9]
1683	n/a	... '''
1684	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1685	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1686	n/a	... # doctest: +ELLIPSIS
1687	n/a	**********************************************************************
1688	n/a	File ..., line 2, in f
1689	n/a	Failed example:
1690	n/a	print(list(range(10))) # Should fail
1691	n/a	Expected:
1692	n/a	[0, 1, ..., 9]
1693	n/a	Got:
1694	n/a	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1695	n/a	TestResults(failed=1, attempted=2)
1696	n/a
1697	n/a	>>> def f(x): r'''
1698	n/a	... >>> print(list(range(10))) # Should fail
1699	n/a	... [0, 1, ..., 9]
1700	n/a	... >>> print(list(range(10))) # Should succeed
1701	n/a	... ... # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE
1702	n/a	... [0, 1, ..., 9]
1703	n/a	... '''
1704	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1705	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1706	n/a	... # doctest: +ELLIPSIS
1707	n/a	**********************************************************************
1708	n/a	File ..., line 2, in f
1709	n/a	Failed example:
1710	n/a	print(list(range(10))) # Should fail
1711	n/a	Expected:
1712	n/a	[0, 1, ..., 9]
1713	n/a	Got:
1714	n/a	[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
1715	n/a	TestResults(failed=1, attempted=2)
1716	n/a
1717	n/a	The option directive may be put on the line following the source, as
1718	n/a	long as a continuation prompt is used:
1719	n/a
1720	n/a	>>> def f(x): r'''
1721	n/a	... >>> print(list(range(10)))
1722	n/a	... ... # doctest: +ELLIPSIS
1723	n/a	... [0, 1, ..., 9]
1724	n/a	... '''
1725	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1726	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1727	n/a	TestResults(failed=0, attempted=1)
1728	n/a
1729	n/a	For examples with multi-line source, the option directive may appear
1730	n/a	at the end of any line:
1731	n/a
1732	n/a	>>> def f(x): r'''
1733	n/a	... >>> for x in range(10): # doctest: +ELLIPSIS
1734	n/a	... ... print(' ', x, end='', sep='')
1735	n/a	... 0 1 2 ... 9
1736	n/a	...
1737	n/a	... >>> for x in range(10):
1738	n/a	... ... print(' ', x, end='', sep='') # doctest: +ELLIPSIS
1739	n/a	... 0 1 2 ... 9
1740	n/a	... '''
1741	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1742	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1743	n/a	TestResults(failed=0, attempted=2)
1744	n/a
1745	n/a	If more than one line of an example with multi-line source has an
1746	n/a	option directive, then they are combined:
1747	n/a
1748	n/a	>>> def f(x): r'''
1749	n/a	... Should fail (option directive not on the last line):
1750	n/a	... >>> for x in range(10): # doctest: +ELLIPSIS
1751	n/a	... ... print(x, end=' ') # doctest: +NORMALIZE_WHITESPACE
1752	n/a	... 0 1 2...9
1753	n/a	... '''
1754	n/a	>>> test = doctest.DocTestFinder().find(f)[0]
1755	n/a	>>> doctest.DocTestRunner(verbose=False).run(test)
1756	n/a	TestResults(failed=0, attempted=1)
1757	n/a
1758	n/a	It is an error to have a comment of the form ``# doctest:`` that is
1759	n/a	not followed by words of the form ``+OPTION`` or ``-OPTION``, where
1760	n/a	``OPTION`` is an option that has been registered with
1761	n/a	`register_option`:
1762	n/a
1763	n/a	>>> # Error: Option not registered
1764	n/a	>>> s = '>>> print(12) #doctest: +BADOPTION'
1765	n/a	>>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1766	n/a	Traceback (most recent call last):
1767	n/a	ValueError: line 1 of the doctest for s has an invalid option: '+BADOPTION'
1768	n/a
1769	n/a	>>> # Error: No + or - prefix
1770	n/a	>>> s = '>>> print(12) #doctest: ELLIPSIS'
1771	n/a	>>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1772	n/a	Traceback (most recent call last):
1773	n/a	ValueError: line 1 of the doctest for s has an invalid option: 'ELLIPSIS'
1774	n/a
1775	n/a	It is an error to use an option directive on a line that contains no
1776	n/a	source:
1777	n/a
1778	n/a	>>> s = '>>> # doctest: +ELLIPSIS'
1779	n/a	>>> test = doctest.DocTestParser().get_doctest(s, {}, 's', 's.py', 0)
1780	n/a	Traceback (most recent call last):
1781	n/a	ValueError: line 0 of the doctest for s has an option directive on a line with no example: '# doctest: +ELLIPSIS'
1782	n/a	"""
1783	n/a
1784	n/a	def test_testsource(): r"""
1785	n/a	Unit tests for `testsource()`.
1786	n/a
1787	n/a	The testsource() function takes a module and a name, finds the (first)
1788	n/a	test with that name in that module, and converts it to a script. The
1789	n/a	example code is converted to regular Python code. The surrounding
1790	n/a	words and expected output are converted to comments:
1791	n/a
1792	n/a	>>> import test.test_doctest
1793	n/a	>>> name = 'test.test_doctest.sample_func'
1794	n/a	>>> print(doctest.testsource(test.test_doctest, name))
1795	n/a	# Blah blah
1796	n/a	#
1797	n/a	print(sample_func(22))
1798	n/a	# Expected:
1799	n/a	## 44
1800	n/a	#
1801	n/a	# Yee ha!
1802	n/a	<BLANKLINE>
1803	n/a
1804	n/a	>>> name = 'test.test_doctest.SampleNewStyleClass'
1805	n/a	>>> print(doctest.testsource(test.test_doctest, name))
1806	n/a	print('1\n2\n3')
1807	n/a	# Expected:
1808	n/a	## 1
1809	n/a	## 2
1810	n/a	## 3
1811	n/a	<BLANKLINE>
1812	n/a
1813	n/a	>>> name = 'test.test_doctest.SampleClass.a_classmethod'
1814	n/a	>>> print(doctest.testsource(test.test_doctest, name))
1815	n/a	print(SampleClass.a_classmethod(10))
1816	n/a	# Expected:
1817	n/a	## 12
1818	n/a	print(SampleClass(0).a_classmethod(10))
1819	n/a	# Expected:
1820	n/a	## 12
1821	n/a	<BLANKLINE>
1822	n/a	"""
1823	n/a
1824	n/a	def test_debug(): r"""
1825	n/a
1826	n/a	Create a docstring that we want to debug:
1827	n/a
1828	n/a	>>> s = '''
1829	n/a	... >>> x = 12
1830	n/a	... >>> print(x)
1831	n/a	... 12
1832	n/a	... '''
1833	n/a
1834	n/a	Create some fake stdin input, to feed to the debugger:
1835	n/a
1836	n/a	>>> real_stdin = sys.stdin
1837	n/a	>>> sys.stdin = _FakeInput(['next', 'print(x)', 'continue'])
1838	n/a
1839	n/a	Run the debugger on the docstring, and then restore sys.stdin.
1840	n/a
1841	n/a	>>> try: doctest.debug_src(s)
1842	n/a	... finally: sys.stdin = real_stdin
1843	n/a	> <string>(1)<module>()
1844	n/a	(Pdb) next
1845	n/a	12
1846	n/a	--Return--
1847	n/a	> <string>(1)<module>()->None
1848	n/a	(Pdb) print(x)
1849	n/a	12
1850	n/a	(Pdb) continue
1851	n/a
1852	n/a	"""
1853	n/a
1854	n/a	if not hasattr(sys, 'gettrace') or not sys.gettrace():
1855	n/a	def test_pdb_set_trace():
1856	n/a	"""Using pdb.set_trace from a doctest.
1857	n/a
1858	n/a	You can use pdb.set_trace from a doctest. To do so, you must
1859	n/a	retrieve the set_trace function from the pdb module at the time
1860	n/a	you use it. The doctest module changes sys.stdout so that it can
1861	n/a	capture program output. It also temporarily replaces pdb.set_trace
1862	n/a	with a version that restores stdout. This is necessary for you to
1863	n/a	see debugger output.
1864	n/a
1865	n/a	>>> doc = '''
1866	n/a	... >>> x = 42
1867	n/a	... >>> raise Exception('clÃ©')
1868	n/a	... Traceback (most recent call last):
1869	n/a	... Exception: clÃ©
1870	n/a	... >>> import pdb; pdb.set_trace()
1871	n/a	... '''
1872	n/a	>>> parser = doctest.DocTestParser()
1873	n/a	>>> test = parser.get_doctest(doc, {}, "foo-bar@baz", "foo-bar@baz.py", 0)
1874	n/a	>>> runner = doctest.DocTestRunner(verbose=False)
1875	n/a
1876	n/a	To demonstrate this, we'll create a fake standard input that
1877	n/a	captures our debugger input:
1878	n/a
1879	n/a	>>> real_stdin = sys.stdin
1880	n/a	>>> sys.stdin = _FakeInput([
1881	n/a	... 'print(x)', # print data defined by the example
1882	n/a	... 'continue', # stop debugging
1883	n/a	... ''])
1884	n/a
1885	n/a	>>> try: runner.run(test)
1886	n/a	... finally: sys.stdin = real_stdin
1887	n/a	--Return--
1888	n/a	> <doctest foo-bar@baz[2]>(1)<module>()->None
1889	n/a	-> import pdb; pdb.set_trace()
1890	n/a	(Pdb) print(x)
1891	n/a	42
1892	n/a	(Pdb) continue
1893	n/a	TestResults(failed=0, attempted=3)
1894	n/a
1895	n/a	You can also put pdb.set_trace in a function called from a test:
1896	n/a
1897	n/a	>>> def calls_set_trace():
1898	n/a	... y=2
1899	n/a	... import pdb; pdb.set_trace()
1900	n/a
1901	n/a	>>> doc = '''
1902	n/a	... >>> x=1
1903	n/a	... >>> calls_set_trace()
1904	n/a	... '''
1905	n/a	>>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
1906	n/a	>>> real_stdin = sys.stdin
1907	n/a	>>> sys.stdin = _FakeInput([
1908	n/a	... 'print(y)', # print data defined in the function
1909	n/a	... 'up', # out of function
1910	n/a	... 'print(x)', # print data defined by the example
1911	n/a	... 'continue', # stop debugging
1912	n/a	... ''])
1913	n/a
1914	n/a	>>> try:
1915	n/a	... runner.run(test)
1916	n/a	... finally:
1917	n/a	... sys.stdin = real_stdin
1918	n/a	--Return--
1919	n/a	> <doctest test.test_doctest.test_pdb_set_trace[7]>(3)calls_set_trace()->None
1920	n/a	-> import pdb; pdb.set_trace()
1921	n/a	(Pdb) print(y)
1922	n/a	2
1923	n/a	(Pdb) up
1924	n/a	> <doctest foo-bar@baz[1]>(1)<module>()
1925	n/a	-> calls_set_trace()
1926	n/a	(Pdb) print(x)
1927	n/a	1
1928	n/a	(Pdb) continue
1929	n/a	TestResults(failed=0, attempted=2)
1930	n/a
1931	n/a	During interactive debugging, source code is shown, even for
1932	n/a	doctest examples:
1933	n/a
1934	n/a	>>> doc = '''
1935	n/a	... >>> def f(x):
1936	n/a	... ... g(x*2)
1937	n/a	... >>> def g(x):
1938	n/a	... ... print(x+3)
1939	n/a	... ... import pdb; pdb.set_trace()
1940	n/a	... >>> f(3)
1941	n/a	... '''
1942	n/a	>>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
1943	n/a	>>> real_stdin = sys.stdin
1944	n/a	>>> sys.stdin = _FakeInput([
1945	n/a	... 'list', # list source from example 2
1946	n/a	... 'next', # return from g()
1947	n/a	... 'list', # list source from example 1
1948	n/a	... 'next', # return from f()
1949	n/a	... 'list', # list source from example 3
1950	n/a	... 'continue', # stop debugging
1951	n/a	... ''])
1952	n/a	>>> try: runner.run(test)
1953	n/a	... finally: sys.stdin = real_stdin
1954	n/a	... # doctest: +NORMALIZE_WHITESPACE
1955	n/a	--Return--
1956	n/a	> <doctest foo-bar@baz[1]>(3)g()->None
1957	n/a	-> import pdb; pdb.set_trace()
1958	n/a	(Pdb) list
1959	n/a	1 def g(x):
1960	n/a	2 print(x+3)
1961	n/a	3 -> import pdb; pdb.set_trace()
1962	n/a	[EOF]
1963	n/a	(Pdb) next
1964	n/a	--Return--
1965	n/a	> <doctest foo-bar@baz[0]>(2)f()->None
1966	n/a	-> g(x*2)
1967	n/a	(Pdb) list
1968	n/a	1 def f(x):
1969	n/a	2 -> g(x*2)
1970	n/a	[EOF]
1971	n/a	(Pdb) next
1972	n/a	--Return--
1973	n/a	> <doctest foo-bar@baz[2]>(1)<module>()->None
1974	n/a	-> f(3)
1975	n/a	(Pdb) list
1976	n/a	1 -> f(3)
1977	n/a	[EOF]
1978	n/a	(Pdb) continue
1979	n/a	**********************************************************************
1980	n/a	File "foo-bar@baz.py", line 7, in foo-bar@baz
1981	n/a	Failed example:
1982	n/a	f(3)
1983	n/a	Expected nothing
1984	n/a	Got:
1985	n/a	9
1986	n/a	TestResults(failed=1, attempted=3)
1987	n/a	"""
1988	n/a
1989	n/a	def test_pdb_set_trace_nested():
1990	n/a	"""This illustrates more-demanding use of set_trace with nested functions.
1991	n/a
1992	n/a	>>> class C(object):
1993	n/a	... def calls_set_trace(self):
1994	n/a	... y = 1
1995	n/a	... import pdb; pdb.set_trace()
1996	n/a	... self.f1()
1997	n/a	... y = 2
1998	n/a	... def f1(self):
1999	n/a	... x = 1
2000	n/a	... self.f2()
2001	n/a	... x = 2
2002	n/a	... def f2(self):
2003	n/a	... z = 1
2004	n/a	... z = 2
2005	n/a
2006	n/a	>>> calls_set_trace = C().calls_set_trace
2007	n/a
2008	n/a	>>> doc = '''
2009	n/a	... >>> a = 1
2010	n/a	... >>> calls_set_trace()
2011	n/a	... '''
2012	n/a	>>> parser = doctest.DocTestParser()
2013	n/a	>>> runner = doctest.DocTestRunner(verbose=False)
2014	n/a	>>> test = parser.get_doctest(doc, globals(), "foo-bar@baz", "foo-bar@baz.py", 0)
2015	n/a	>>> real_stdin = sys.stdin
2016	n/a	>>> sys.stdin = _FakeInput([
2017	n/a	... 'print(y)', # print data defined in the function
2018	n/a	... 'step', 'step', 'step', 'step', 'step', 'step', 'print(z)',
2019	n/a	... 'up', 'print(x)',
2020	n/a	... 'up', 'print(y)',
2021	n/a	... 'up', 'print(foo)',
2022	n/a	... 'continue', # stop debugging
2023	n/a	... ''])
2024	n/a
2025	n/a	>>> try:
2026	n/a	... runner.run(test)
2027	n/a	... finally:
2028	n/a	... sys.stdin = real_stdin
2029	n/a	... # doctest: +REPORT_NDIFF
2030	n/a	> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
2031	n/a	-> self.f1()
2032	n/a	(Pdb) print(y)
2033	n/a	1
2034	n/a	(Pdb) step
2035	n/a	--Call--
2036	n/a	> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(7)f1()
2037	n/a	-> def f1(self):
2038	n/a	(Pdb) step
2039	n/a	> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(8)f1()
2040	n/a	-> x = 1
2041	n/a	(Pdb) step
2042	n/a	> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
2043	n/a	-> self.f2()
2044	n/a	(Pdb) step
2045	n/a	--Call--
2046	n/a	> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(11)f2()
2047	n/a	-> def f2(self):
2048	n/a	(Pdb) step
2049	n/a	> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(12)f2()
2050	n/a	-> z = 1
2051	n/a	(Pdb) step
2052	n/a	> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(13)f2()
2053	n/a	-> z = 2
2054	n/a	(Pdb) print(z)
2055	n/a	1
2056	n/a	(Pdb) up
2057	n/a	> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(9)f1()
2058	n/a	-> self.f2()
2059	n/a	(Pdb) print(x)
2060	n/a	1
2061	n/a	(Pdb) up
2062	n/a	> <doctest test.test_doctest.test_pdb_set_trace_nested[0]>(5)calls_set_trace()
2063	n/a	-> self.f1()
2064	n/a	(Pdb) print(y)
2065	n/a	1
2066	n/a	(Pdb) up
2067	n/a	> <doctest foo-bar@baz[1]>(1)<module>()
2068	n/a	-> calls_set_trace()
2069	n/a	(Pdb) print(foo)
2070	n/a	*** NameError: name 'foo' is not defined
2071	n/a	(Pdb) continue
2072	n/a	TestResults(failed=0, attempted=2)
2073	n/a	"""
2074	n/a
2075	n/a	def test_DocTestSuite():
2076	n/a	"""DocTestSuite creates a unittest test suite from a doctest.
2077	n/a
2078	n/a	We create a Suite by providing a module. A module can be provided
2079	n/a	by passing a module object:
2080	n/a
2081	n/a	>>> import unittest
2082	n/a	>>> import test.sample_doctest
2083	n/a	>>> suite = doctest.DocTestSuite(test.sample_doctest)
2084	n/a	>>> suite.run(unittest.TestResult())
2085	n/a	<unittest.result.TestResult run=9 errors=0 failures=4>
2086	n/a
2087	n/a	We can also supply the module by name:
2088	n/a
2089	n/a	>>> suite = doctest.DocTestSuite('test.sample_doctest')
2090	n/a	>>> suite.run(unittest.TestResult())
2091	n/a	<unittest.result.TestResult run=9 errors=0 failures=4>
2092	n/a
2093	n/a	The module need not contain any doctest examples:
2094	n/a
2095	n/a	>>> suite = doctest.DocTestSuite('test.sample_doctest_no_doctests')
2096	n/a	>>> suite.run(unittest.TestResult())
2097	n/a	<unittest.result.TestResult run=0 errors=0 failures=0>
2098	n/a
2099	n/a	The module need not contain any docstrings either:
2100	n/a
2101	n/a	>>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings')
2102	n/a	>>> suite.run(unittest.TestResult())
2103	n/a	<unittest.result.TestResult run=0 errors=0 failures=0>
2104	n/a
2105	n/a	We can use the current module:
2106	n/a
2107	n/a	>>> suite = test.sample_doctest.test_suite()
2108	n/a	>>> suite.run(unittest.TestResult())
2109	n/a	<unittest.result.TestResult run=9 errors=0 failures=4>
2110	n/a
2111	n/a	We can also provide a DocTestFinder:
2112	n/a
2113	n/a	>>> finder = doctest.DocTestFinder()
2114	n/a	>>> suite = doctest.DocTestSuite('test.sample_doctest',
2115	n/a	... test_finder=finder)
2116	n/a	>>> suite.run(unittest.TestResult())
2117	n/a	<unittest.result.TestResult run=9 errors=0 failures=4>
2118	n/a
2119	n/a	The DocTestFinder need not return any tests:
2120	n/a
2121	n/a	>>> finder = doctest.DocTestFinder()
2122	n/a	>>> suite = doctest.DocTestSuite('test.sample_doctest_no_docstrings',
2123	n/a	... test_finder=finder)
2124	n/a	>>> suite.run(unittest.TestResult())
2125	n/a	<unittest.result.TestResult run=0 errors=0 failures=0>
2126	n/a
2127	n/a	We can supply global variables. If we pass globs, they will be
2128	n/a	used instead of the module globals. Here we'll pass an empty
2129	n/a	globals, triggering an extra error:
2130	n/a
2131	n/a	>>> suite = doctest.DocTestSuite('test.sample_doctest', globs={})
2132	n/a	>>> suite.run(unittest.TestResult())
2133	n/a	<unittest.result.TestResult run=9 errors=0 failures=5>
2134	n/a
2135	n/a	Alternatively, we can provide extra globals. Here we'll make an
2136	n/a	error go away by providing an extra global variable:
2137	n/a
2138	n/a	>>> suite = doctest.DocTestSuite('test.sample_doctest',
2139	n/a	... extraglobs={'y': 1})
2140	n/a	>>> suite.run(unittest.TestResult())
2141	n/a	<unittest.result.TestResult run=9 errors=0 failures=3>
2142	n/a
2143	n/a	You can pass option flags. Here we'll cause an extra error
2144	n/a	by disabling the blank-line feature:
2145	n/a
2146	n/a	>>> suite = doctest.DocTestSuite('test.sample_doctest',
2147	n/a	... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2148	n/a	>>> suite.run(unittest.TestResult())
2149	n/a	<unittest.result.TestResult run=9 errors=0 failures=5>
2150	n/a
2151	n/a	You can supply setUp and tearDown functions:
2152	n/a
2153	n/a	>>> def setUp(t):
2154	n/a	... import test.test_doctest
2155	n/a	... test.test_doctest.sillySetup = True
2156	n/a
2157	n/a	>>> def tearDown(t):
2158	n/a	... import test.test_doctest
2159	n/a	... del test.test_doctest.sillySetup
2160	n/a
2161	n/a	Here, we installed a silly variable that the test expects:
2162	n/a
2163	n/a	>>> suite = doctest.DocTestSuite('test.sample_doctest',
2164	n/a	... setUp=setUp, tearDown=tearDown)
2165	n/a	>>> suite.run(unittest.TestResult())
2166	n/a	<unittest.result.TestResult run=9 errors=0 failures=3>
2167	n/a
2168	n/a	But the tearDown restores sanity:
2169	n/a
2170	n/a	>>> import test.test_doctest
2171	n/a	>>> test.test_doctest.sillySetup
2172	n/a	Traceback (most recent call last):
2173	n/a	...
2174	n/a	AttributeError: module 'test.test_doctest' has no attribute 'sillySetup'
2175	n/a
2176	n/a	The setUp and tearDown functions are passed test objects. Here
2177	n/a	we'll use the setUp function to supply the missing variable y:
2178	n/a
2179	n/a	>>> def setUp(test):
2180	n/a	... test.globs['y'] = 1
2181	n/a
2182	n/a	>>> suite = doctest.DocTestSuite('test.sample_doctest', setUp=setUp)
2183	n/a	>>> suite.run(unittest.TestResult())
2184	n/a	<unittest.result.TestResult run=9 errors=0 failures=3>
2185	n/a
2186	n/a	Here, we didn't need to use a tearDown function because we
2187	n/a	modified the test globals, which are a copy of the
2188	n/a	sample_doctest module dictionary. The test globals are
2189	n/a	automatically cleared for us after a test.
2190	n/a	"""
2191	n/a
2192	n/a	def test_DocFileSuite():
2193	n/a	"""We can test tests found in text files using a DocFileSuite.
2194	n/a
2195	n/a	We create a suite by providing the names of one or more text
2196	n/a	files that include examples:
2197	n/a
2198	n/a	>>> import unittest
2199	n/a	>>> suite = doctest.DocFileSuite('test_doctest.txt',
2200	n/a	... 'test_doctest2.txt',
2201	n/a	... 'test_doctest4.txt')
2202	n/a	>>> suite.run(unittest.TestResult())
2203	n/a	<unittest.result.TestResult run=3 errors=0 failures=2>
2204	n/a
2205	n/a	The test files are looked for in the directory containing the
2206	n/a	calling module. A package keyword argument can be provided to
2207	n/a	specify a different relative location.
2208	n/a
2209	n/a	>>> import unittest
2210	n/a	>>> suite = doctest.DocFileSuite('test_doctest.txt',
2211	n/a	... 'test_doctest2.txt',
2212	n/a	... 'test_doctest4.txt',
2213	n/a	... package='test')
2214	n/a	>>> suite.run(unittest.TestResult())
2215	n/a	<unittest.result.TestResult run=3 errors=0 failures=2>
2216	n/a
2217	n/a	Support for using a package's __loader__.get_data() is also
2218	n/a	provided.
2219	n/a
2220	n/a	>>> import unittest, pkgutil, test
2221	n/a	>>> added_loader = False
2222	n/a	>>> if not hasattr(test, '__loader__'):
2223	n/a	... test.__loader__ = pkgutil.get_loader(test)
2224	n/a	... added_loader = True
2225	n/a	>>> try:
2226	n/a	... suite = doctest.DocFileSuite('test_doctest.txt',
2227	n/a	... 'test_doctest2.txt',
2228	n/a	... 'test_doctest4.txt',
2229	n/a	... package='test')
2230	n/a	... suite.run(unittest.TestResult())
2231	n/a	... finally:
2232	n/a	... if added_loader:
2233	n/a	... del test.__loader__
2234	n/a	<unittest.result.TestResult run=3 errors=0 failures=2>
2235	n/a
2236	n/a	'/' should be used as a path separator. It will be converted
2237	n/a	to a native separator at run time:
2238	n/a
2239	n/a	>>> suite = doctest.DocFileSuite('../test/test_doctest.txt')
2240	n/a	>>> suite.run(unittest.TestResult())
2241	n/a	<unittest.result.TestResult run=1 errors=0 failures=1>
2242	n/a
2243	n/a	If DocFileSuite is used from an interactive session, then files
2244	n/a	are resolved relative to the directory of sys.argv[0]:
2245	n/a
2246	n/a	>>> import types, os.path, test.test_doctest
2247	n/a	>>> save_argv = sys.argv
2248	n/a	>>> sys.argv = [test.test_doctest.__file__]
2249	n/a	>>> suite = doctest.DocFileSuite('test_doctest.txt',
2250	n/a	... package=types.ModuleType('__main__'))
2251	n/a	>>> sys.argv = save_argv
2252	n/a
2253	n/a	By setting `module_relative=False`, os-specific paths may be
2254	n/a	used (including absolute paths and paths relative to the
2255	n/a	working directory):
2256	n/a
2257	n/a	>>> # Get the absolute path of the test package.
2258	n/a	>>> test_doctest_path = os.path.abspath(test.test_doctest.__file__)
2259	n/a	>>> test_pkg_path = os.path.split(test_doctest_path)[0]
2260	n/a
2261	n/a	>>> # Use it to find the absolute path of test_doctest.txt.
2262	n/a	>>> test_file = os.path.join(test_pkg_path, 'test_doctest.txt')
2263	n/a
2264	n/a	>>> suite = doctest.DocFileSuite(test_file, module_relative=False)
2265	n/a	>>> suite.run(unittest.TestResult())
2266	n/a	<unittest.result.TestResult run=1 errors=0 failures=1>
2267	n/a
2268	n/a	It is an error to specify `package` when `module_relative=False`:
2269	n/a
2270	n/a	>>> suite = doctest.DocFileSuite(test_file, module_relative=False,
2271	n/a	... package='test')
2272	n/a	Traceback (most recent call last):
2273	n/a	ValueError: Package may only be specified for module-relative paths.
2274	n/a
2275	n/a	You can specify initial global variables:
2276	n/a
2277	n/a	>>> suite = doctest.DocFileSuite('test_doctest.txt',
2278	n/a	... 'test_doctest2.txt',
2279	n/a	... 'test_doctest4.txt',
2280	n/a	... globs={'favorite_color': 'blue'})
2281	n/a	>>> suite.run(unittest.TestResult())
2282	n/a	<unittest.result.TestResult run=3 errors=0 failures=1>
2283	n/a
2284	n/a	In this case, we supplied a missing favorite color. You can
2285	n/a	provide doctest options:
2286	n/a
2287	n/a	>>> suite = doctest.DocFileSuite('test_doctest.txt',
2288	n/a	... 'test_doctest2.txt',
2289	n/a	... 'test_doctest4.txt',
2290	n/a	... optionflags=doctest.DONT_ACCEPT_BLANKLINE,
2291	n/a	... globs={'favorite_color': 'blue'})
2292	n/a	>>> suite.run(unittest.TestResult())
2293	n/a	<unittest.result.TestResult run=3 errors=0 failures=2>
2294	n/a
2295	n/a	And, you can provide setUp and tearDown functions:
2296	n/a
2297	n/a	>>> def setUp(t):
2298	n/a	... import test.test_doctest
2299	n/a	... test.test_doctest.sillySetup = True
2300	n/a
2301	n/a	>>> def tearDown(t):
2302	n/a	... import test.test_doctest
2303	n/a	... del test.test_doctest.sillySetup
2304	n/a
2305	n/a	Here, we installed a silly variable that the test expects:
2306	n/a
2307	n/a	>>> suite = doctest.DocFileSuite('test_doctest.txt',
2308	n/a	... 'test_doctest2.txt',
2309	n/a	... 'test_doctest4.txt',
2310	n/a	... setUp=setUp, tearDown=tearDown)
2311	n/a	>>> suite.run(unittest.TestResult())
2312	n/a	<unittest.result.TestResult run=3 errors=0 failures=1>
2313	n/a
2314	n/a	But the tearDown restores sanity:
2315	n/a
2316	n/a	>>> import test.test_doctest
2317	n/a	>>> test.test_doctest.sillySetup
2318	n/a	Traceback (most recent call last):
2319	n/a	...
2320	n/a	AttributeError: module 'test.test_doctest' has no attribute 'sillySetup'
2321	n/a
2322	n/a	The setUp and tearDown functions are passed test objects.
2323	n/a	Here, we'll use a setUp function to set the favorite color in
2324	n/a	test_doctest.txt:
2325	n/a
2326	n/a	>>> def setUp(test):
2327	n/a	... test.globs['favorite_color'] = 'blue'
2328	n/a
2329	n/a	>>> suite = doctest.DocFileSuite('test_doctest.txt', setUp=setUp)
2330	n/a	>>> suite.run(unittest.TestResult())
2331	n/a	<unittest.result.TestResult run=1 errors=0 failures=0>
2332	n/a
2333	n/a	Here, we didn't need to use a tearDown function because we
2334	n/a	modified the test globals. The test globals are
2335	n/a	automatically cleared for us after a test.
2336	n/a
2337	n/a	Tests in a file run using `DocFileSuite` can also access the
2338	n/a	`__file__` global, which is set to the name of the file
2339	n/a	containing the tests:
2340	n/a
2341	n/a	>>> suite = doctest.DocFileSuite('test_doctest3.txt')
2342	n/a	>>> suite.run(unittest.TestResult())
2343	n/a	<unittest.result.TestResult run=1 errors=0 failures=0>
2344	n/a
2345	n/a	If the tests contain non-ASCII characters, we have to specify which
2346	n/a	encoding the file is encoded with. We do so by using the `encoding`
2347	n/a	parameter:
2348	n/a
2349	n/a	>>> suite = doctest.DocFileSuite('test_doctest.txt',
2350	n/a	... 'test_doctest2.txt',
2351	n/a	... 'test_doctest4.txt',
2352	n/a	... encoding='utf-8')
2353	n/a	>>> suite.run(unittest.TestResult())
2354	n/a	<unittest.result.TestResult run=3 errors=0 failures=2>
2355	n/a
2356	n/a	"""
2357	n/a
2358	n/a	def test_trailing_space_in_test():
2359	n/a	"""
2360	n/a	Trailing spaces in expected output are significant:
2361	n/a
2362	n/a	>>> x, y = 'foo', ''
2363	n/a	>>> print(x, y)
2364	n/a	foo \n
2365	n/a	"""
2366	n/a
2367	n/a	class Wrapper:
2368	n/a	def __init__(self, func):
2369	n/a	self.func = func
2370	n/a	functools.update_wrapper(self, func)
2371	n/a
2372	n/a	def __call__(self, args, *kwargs):
2373	n/a	self.func(args, *kwargs)
2374	n/a
2375	n/a	@Wrapper
2376	n/a	def test_look_in_unwrapped():
2377	n/a	"""
2378	n/a	Docstrings in wrapped functions must be detected as well.
2379	n/a
2380	n/a	>>> 'one other test'
2381	n/a	'one other test'
2382	n/a	"""
2383	n/a
2384	n/a	def test_unittest_reportflags():
2385	n/a	"""Default unittest reporting flags can be set to control reporting
2386	n/a
2387	n/a	Here, we'll set the REPORT_ONLY_FIRST_FAILURE option so we see
2388	n/a	only the first failure of each test. First, we'll look at the
2389	n/a	output without the flag. The file test_doctest.txt file has two
2390	n/a	tests. They both fail if blank lines are disabled:
2391	n/a
2392	n/a	>>> suite = doctest.DocFileSuite('test_doctest.txt',
2393	n/a	... optionflags=doctest.DONT_ACCEPT_BLANKLINE)
2394	n/a	>>> import unittest
2395	n/a	>>> result = suite.run(unittest.TestResult())
2396	n/a	>>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2397	n/a	Traceback ...
2398	n/a	Failed example:
2399	n/a	favorite_color
2400	n/a	...
2401	n/a	Failed example:
2402	n/a	if 1:
2403	n/a	...
2404	n/a
2405	n/a	Note that we see both failures displayed.
2406	n/a
2407	n/a	>>> old = doctest.set_unittest_reportflags(
2408	n/a	... doctest.REPORT_ONLY_FIRST_FAILURE)
2409	n/a
2410	n/a	Now, when we run the test:
2411	n/a
2412	n/a	>>> result = suite.run(unittest.TestResult())
2413	n/a	>>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2414	n/a	Traceback ...
2415	n/a	Failed example:
2416	n/a	favorite_color
2417	n/a	Exception raised:
2418	n/a	...
2419	n/a	NameError: name 'favorite_color' is not defined
2420	n/a	<BLANKLINE>
2421	n/a	<BLANKLINE>
2422	n/a
2423	n/a	We get only the first failure.
2424	n/a
2425	n/a	If we give any reporting options when we set up the tests,
2426	n/a	however:
2427	n/a
2428	n/a	>>> suite = doctest.DocFileSuite('test_doctest.txt',
2429	n/a	... optionflags=doctest.DONT_ACCEPT_BLANKLINE \| doctest.REPORT_NDIFF)
2430	n/a
2431	n/a	Then the default eporting options are ignored:
2432	n/a
2433	n/a	>>> result = suite.run(unittest.TestResult())
2434	n/a	>>> print(result.failures[0][1]) # doctest: +ELLIPSIS
2435	n/a	Traceback ...
2436	n/a	Failed example:
2437	n/a	favorite_color
2438	n/a	...
2439	n/a	Failed example:
2440	n/a	if 1:
2441	n/a	print('a')
2442	n/a	print()
2443	n/a	print('b')
2444	n/a	Differences (ndiff with -expected +actual):
2445	n/a	a
2446	n/a	- <BLANKLINE>
2447	n/a	+
2448	n/a	b
2449	n/a	<BLANKLINE>
2450	n/a	<BLANKLINE>
2451	n/a
2452	n/a
2453	n/a	Test runners can restore the formatting flags after they run:
2454	n/a
2455	n/a	>>> ignored = doctest.set_unittest_reportflags(old)
2456	n/a
2457	n/a	"""
2458	n/a
2459	n/a	def test_testfile(): r"""
2460	n/a	Tests for the `testfile()` function. This function runs all the
2461	n/a	doctest examples in a given file. In its simple invokation, it is
2462	n/a	called with the name of a file, which is taken to be relative to the
2463	n/a	calling module. The return value is (#failures, #tests).
2464	n/a
2465	n/a	We don't want `-v` in sys.argv for these tests.
2466	n/a
2467	n/a	>>> save_argv = sys.argv
2468	n/a	>>> if '-v' in sys.argv:
2469	n/a	... sys.argv = [arg for arg in save_argv if arg != '-v']
2470	n/a
2471	n/a
2472	n/a	>>> doctest.testfile('test_doctest.txt') # doctest: +ELLIPSIS
2473	n/a	**********************************************************************
2474	n/a	File "...", line 6, in test_doctest.txt
2475	n/a	Failed example:
2476	n/a	favorite_color
2477	n/a	Exception raised:
2478	n/a	...
2479	n/a	NameError: name 'favorite_color' is not defined
2480	n/a	**********************************************************************
2481	n/a	1 items had failures:
2482	n/a	1 of 2 in test_doctest.txt
2483	n/a	*Test Failed* 1 failures.
2484	n/a	TestResults(failed=1, attempted=2)
2485	n/a	>>> doctest.master = None # Reset master.
2486	n/a
2487	n/a	(Note: we'll be clearing doctest.master after each call to
2488	n/a	`doctest.testfile`, to suppress warnings about multiple tests with the
2489	n/a	same name.)
2490	n/a
2491	n/a	Globals may be specified with the `globs` and `extraglobs` parameters:
2492	n/a
2493	n/a	>>> globs = {'favorite_color': 'blue'}
2494	n/a	>>> doctest.testfile('test_doctest.txt', globs=globs)
2495	n/a	TestResults(failed=0, attempted=2)
2496	n/a	>>> doctest.master = None # Reset master.
2497	n/a
2498	n/a	>>> extraglobs = {'favorite_color': 'red'}
2499	n/a	>>> doctest.testfile('test_doctest.txt', globs=globs,
2500	n/a	... extraglobs=extraglobs) # doctest: +ELLIPSIS
2501	n/a	**********************************************************************
2502	n/a	File "...", line 6, in test_doctest.txt
2503	n/a	Failed example:
2504	n/a	favorite_color
2505	n/a	Expected:
2506	n/a	'blue'
2507	n/a	Got:
2508	n/a	'red'
2509	n/a	**********************************************************************
2510	n/a	1 items had failures:
2511	n/a	1 of 2 in test_doctest.txt
2512	n/a	*Test Failed* 1 failures.
2513	n/a	TestResults(failed=1, attempted=2)
2514	n/a	>>> doctest.master = None # Reset master.
2515	n/a
2516	n/a	The file may be made relative to a given module or package, using the
2517	n/a	optional `module_relative` parameter:
2518	n/a
2519	n/a	>>> doctest.testfile('test_doctest.txt', globs=globs,
2520	n/a	... module_relative='test')
2521	n/a	TestResults(failed=0, attempted=2)
2522	n/a	>>> doctest.master = None # Reset master.
2523	n/a
2524	n/a	Verbosity can be increased with the optional `verbose` parameter:
2525	n/a
2526	n/a	>>> doctest.testfile('test_doctest.txt', globs=globs, verbose=True)
2527	n/a	Trying:
2528	n/a	favorite_color
2529	n/a	Expecting:
2530	n/a	'blue'
2531	n/a	ok
2532	n/a	Trying:
2533	n/a	if 1:
2534	n/a	print('a')
2535	n/a	print()
2536	n/a	print('b')
2537	n/a	Expecting:
2538	n/a	a
2539	n/a	<BLANKLINE>
2540	n/a	b
2541	n/a	ok
2542	n/a	1 items passed all tests:
2543	n/a	2 tests in test_doctest.txt
2544	n/a	2 tests in 1 items.
2545	n/a	2 passed and 0 failed.
2546	n/a	Test passed.
2547	n/a	TestResults(failed=0, attempted=2)
2548	n/a	>>> doctest.master = None # Reset master.
2549	n/a
2550	n/a	The name of the test may be specified with the optional `name`
2551	n/a	parameter:
2552	n/a
2553	n/a	>>> doctest.testfile('test_doctest.txt', name='newname')
2554	n/a	... # doctest: +ELLIPSIS
2555	n/a	**********************************************************************
2556	n/a	File "...", line 6, in newname
2557	n/a	...
2558	n/a	TestResults(failed=1, attempted=2)
2559	n/a	>>> doctest.master = None # Reset master.
2560	n/a
2561	n/a	The summary report may be suppressed with the optional `report`
2562	n/a	parameter:
2563	n/a
2564	n/a	>>> doctest.testfile('test_doctest.txt', report=False)
2565	n/a	... # doctest: +ELLIPSIS
2566	n/a	**********************************************************************
2567	n/a	File "...", line 6, in test_doctest.txt
2568	n/a	Failed example:
2569	n/a	favorite_color
2570	n/a	Exception raised:
2571	n/a	...
2572	n/a	NameError: name 'favorite_color' is not defined
2573	n/a	TestResults(failed=1, attempted=2)
2574	n/a	>>> doctest.master = None # Reset master.
2575	n/a
2576	n/a	The optional keyword argument `raise_on_error` can be used to raise an
2577	n/a	exception on the first error (which may be useful for postmortem
2578	n/a	debugging):
2579	n/a
2580	n/a	>>> doctest.testfile('test_doctest.txt', raise_on_error=True)
2581	n/a	... # doctest: +ELLIPSIS
2582	n/a	Traceback (most recent call last):
2583	n/a	doctest.UnexpectedException: ...
2584	n/a	>>> doctest.master = None # Reset master.
2585	n/a
2586	n/a	If the tests contain non-ASCII characters, the tests might fail, since
2587	n/a	it's unknown which encoding is used. The encoding can be specified
2588	n/a	using the optional keyword argument `encoding`:
2589	n/a
2590	n/a	>>> doctest.testfile('test_doctest4.txt', encoding='latin-1') # doctest: +ELLIPSIS
2591	n/a	**********************************************************************
2592	n/a	File "...", line 7, in test_doctest4.txt
2593	n/a	Failed example:
2594	n/a	'...'
2595	n/a	Expected:
2596	n/a	'f\xf6\xf6'
2597	n/a	Got:
2598	n/a	'f\xc3\xb6\xc3\xb6'
2599	n/a	**********************************************************************
2600	n/a	...
2601	n/a	**********************************************************************
2602	n/a	1 items had failures:
2603	n/a	2 of 2 in test_doctest4.txt
2604	n/a	*Test Failed* 2 failures.
2605	n/a	TestResults(failed=2, attempted=2)
2606	n/a	>>> doctest.master = None # Reset master.
2607	n/a
2608	n/a	>>> doctest.testfile('test_doctest4.txt', encoding='utf-8')
2609	n/a	TestResults(failed=0, attempted=2)
2610	n/a	>>> doctest.master = None # Reset master.
2611	n/a
2612	n/a	Test the verbose output:
2613	n/a
2614	n/a	>>> doctest.testfile('test_doctest4.txt', encoding='utf-8', verbose=True)
2615	n/a	Trying:
2616	n/a	'fÃ¶Ã¶'
2617	n/a	Expecting:
2618	n/a	'f\xf6\xf6'
2619	n/a	ok
2620	n/a	Trying:
2621	n/a	'bÄr'
2622	n/a	Expecting:
2623	n/a	'b\u0105r'
2624	n/a	ok
2625	n/a	1 items passed all tests:
2626	n/a	2 tests in test_doctest4.txt
2627	n/a	2 tests in 1 items.
2628	n/a	2 passed and 0 failed.
2629	n/a	Test passed.
2630	n/a	TestResults(failed=0, attempted=2)
2631	n/a	>>> doctest.master = None # Reset master.
2632	n/a	>>> sys.argv = save_argv
2633	n/a	"""
2634	n/a
2635	n/a	def test_lineendings(): r"""
2636	n/a	*nix systems use \n line endings, while Windows systems use \r\n. Python
2637	n/a	handles this using universal newline mode for reading files. Let's make
2638	n/a	sure doctest does so (issue 8473) by creating temporary test files using each
2639	n/a	of the two line disciplines. One of the two will be the "wrong" one for the
2640	n/a	platform the test is run on.
2641	n/a
2642	n/a	Windows line endings first:
2643	n/a
2644	n/a	>>> import tempfile, os
2645	n/a	>>> fn = tempfile.mktemp()
2646	n/a	>>> with open(fn, 'wb') as f:
2647	n/a	... f.write(b'Test:\r\n\r\n >>> x = 1 + 1\r\n\r\nDone.\r\n')
2648	n/a	35
2649	n/a	>>> doctest.testfile(fn, module_relative=False, verbose=False)
2650	n/a	TestResults(failed=0, attempted=1)
2651	n/a	>>> os.remove(fn)
2652	n/a
2653	n/a	And now *nix line endings:
2654	n/a
2655	n/a	>>> fn = tempfile.mktemp()
2656	n/a	>>> with open(fn, 'wb') as f:
2657	n/a	... f.write(b'Test:\n\n >>> x = 1 + 1\n\nDone.\n')
2658	n/a	30
2659	n/a	>>> doctest.testfile(fn, module_relative=False, verbose=False)
2660	n/a	TestResults(failed=0, attempted=1)
2661	n/a	>>> os.remove(fn)
2662	n/a
2663	n/a	"""
2664	n/a
2665	n/a	def test_testmod(): r"""
2666	n/a	Tests for the testmod function. More might be useful, but for now we're just
2667	n/a	testing the case raised by Issue 6195, where trying to doctest a C module would
2668	n/a	fail with a UnicodeDecodeError because doctest tried to read the "source" lines
2669	n/a	out of the binary module.
2670	n/a
2671	n/a	>>> import unicodedata
2672	n/a	>>> doctest.testmod(unicodedata, verbose=False)
2673	n/a	TestResults(failed=0, attempted=0)
2674	n/a	"""
2675	n/a
2676	n/a	try:
2677	n/a	os.fsencode("foo-bÃ¤r@baz.py")
2678	n/a	except UnicodeEncodeError:
2679	n/a	# Skip the test: the filesystem encoding is unable to encode the filename
2680	n/a	pass
2681	n/a	else:
2682	n/a	def test_unicode(): """
2683	n/a	Check doctest with a non-ascii filename:
2684	n/a
2685	n/a	>>> doc = '''
2686	n/a	... >>> raise Exception('clÃ©')
2687	n/a	... '''
2688	n/a	...
2689	n/a	>>> parser = doctest.DocTestParser()
2690	n/a	>>> test = parser.get_doctest(doc, {}, "foo-bÃ¤r@baz", "foo-bÃ¤r@baz.py", 0)
2691	n/a	>>> test
2692	n/a	<DocTest foo-bÃ¤r@baz from foo-bÃ¤r@baz.py:0 (1 example)>
2693	n/a	>>> runner = doctest.DocTestRunner(verbose=False)
2694	n/a	>>> runner.run(test) # doctest: +ELLIPSIS
2695	n/a	**********************************************************************
2696	n/a	File "foo-bÃ¤r@baz.py", line 2, in foo-bÃ¤r@baz
2697	n/a	Failed example:
2698	n/a	raise Exception('clÃ©')
2699	n/a	Exception raised:
2700	n/a	Traceback (most recent call last):
2701	n/a	File ...
2702	n/a	compileflags, 1), test.globs)
2703	n/a	File "<doctest foo-bÃ¤r@baz[0]>", line 1, in <module>
2704	n/a	raise Exception('clÃ©')
2705	n/a	Exception: clÃ©
2706	n/a	TestResults(failed=1, attempted=1)
2707	n/a	"""
2708	n/a
2709	n/a	def test_CLI(): r"""
2710	n/a	The doctest module can be used to run doctests against an arbitrary file.
2711	n/a	These tests test this CLI functionality.
2712	n/a
2713	n/a	We'll use the support module's script_helpers for this, and write a test files
2714	n/a	to a temp dir to run the command against. Due to a current limitation in
2715	n/a	script_helpers, though, we need a little utility function to turn the returned
2716	n/a	output into something we can doctest against:
2717	n/a
2718	n/a	>>> def normalize(s):
2719	n/a	... return '\n'.join(s.decode().splitlines())
2720	n/a
2721	n/a	With those preliminaries out of the way, we'll start with a file with two
2722	n/a	simple tests and no errors. We'll run both the unadorned doctest command, and
2723	n/a	the verbose version, and then check the output:
2724	n/a
2725	n/a	>>> from test.support import script_helper, temp_dir
2726	n/a	>>> with temp_dir() as tmpdir:
2727	n/a	... fn = os.path.join(tmpdir, 'myfile.doc')
2728	n/a	... with open(fn, 'w') as f:
2729	n/a	... _ = f.write('This is a very simple test file.\n')
2730	n/a	... _ = f.write(' >>> 1 + 1\n')
2731	n/a	... _ = f.write(' 2\n')
2732	n/a	... _ = f.write(' >>> "a"\n')
2733	n/a	... _ = f.write(" 'a'\n")
2734	n/a	... _ = f.write('\n')
2735	n/a	... _ = f.write('And that is it.\n')
2736	n/a	... rc1, out1, err1 = script_helper.assert_python_ok(
2737	n/a	... '-m', 'doctest', fn)
2738	n/a	... rc2, out2, err2 = script_helper.assert_python_ok(
2739	n/a	... '-m', 'doctest', '-v', fn)
2740	n/a
2741	n/a	With no arguments and passing tests, we should get no output:
2742	n/a
2743	n/a	>>> rc1, out1, err1
2744	n/a	(0, b'', b'')
2745	n/a
2746	n/a	With the verbose flag, we should see the test output, but no error output:
2747	n/a
2748	n/a	>>> rc2, err2
2749	n/a	(0, b'')
2750	n/a	>>> print(normalize(out2))
2751	n/a	Trying:
2752	n/a	1 + 1
2753	n/a	Expecting:
2754	n/a	2
2755	n/a	ok
2756	n/a	Trying:
2757	n/a	"a"
2758	n/a	Expecting:
2759	n/a	'a'
2760	n/a	ok
2761	n/a	1 items passed all tests:
2762	n/a	2 tests in myfile.doc
2763	n/a	2 tests in 1 items.
2764	n/a	2 passed and 0 failed.
2765	n/a	Test passed.
2766	n/a
2767	n/a	Now we'll write a couple files, one with three tests, the other a python module
2768	n/a	with two tests, both of the files having "errors" in the tests that can be made
2769	n/a	non-errors by applying the appropriate doctest options to the run (ELLIPSIS in
2770	n/a	the first file, NORMALIZE_WHITESPACE in the second). This combination will
2771	n/a	allow thoroughly testing the -f and -o flags, as well as the doctest command's
2772	n/a	ability to process more than one file on the command line and, since the second
2773	n/a	file ends in '.py', its handling of python module files (as opposed to straight
2774	n/a	text files).
2775	n/a
2776	n/a	>>> from test.support import script_helper, temp_dir
2777	n/a	>>> with temp_dir() as tmpdir:
2778	n/a	... fn = os.path.join(tmpdir, 'myfile.doc')
2779	n/a	... with open(fn, 'w') as f:
2780	n/a	... _ = f.write('This is another simple test file.\n')
2781	n/a	... _ = f.write(' >>> 1 + 1\n')
2782	n/a	... _ = f.write(' 2\n')
2783	n/a	... _ = f.write(' >>> "abcdef"\n')
2784	n/a	... _ = f.write(" 'a...f'\n")
2785	n/a	... _ = f.write(' >>> "ajkml"\n')
2786	n/a	... _ = f.write(" 'a...l'\n")
2787	n/a	... _ = f.write('\n')
2788	n/a	... _ = f.write('And that is it.\n')
2789	n/a	... fn2 = os.path.join(tmpdir, 'myfile2.py')
2790	n/a	... with open(fn2, 'w') as f:
2791	n/a	... _ = f.write('def test_func():\n')
2792	n/a	... _ = f.write(' \"\"\"\n')
2793	n/a	... _ = f.write(' This is simple python test function.\n')
2794	n/a	... _ = f.write(' >>> 1 + 1\n')
2795	n/a	... _ = f.write(' 2\n')
2796	n/a	... _ = f.write(' >>> "abc def"\n')
2797	n/a	... _ = f.write(" 'abc def'\n")
2798	n/a	... _ = f.write("\n")
2799	n/a	... _ = f.write(' \"\"\"\n')
2800	n/a	... rc1, out1, err1 = script_helper.assert_python_failure(
2801	n/a	... '-m', 'doctest', fn, fn2)
2802	n/a	... rc2, out2, err2 = script_helper.assert_python_ok(
2803	n/a	... '-m', 'doctest', '-o', 'ELLIPSIS', fn)
2804	n/a	... rc3, out3, err3 = script_helper.assert_python_ok(
2805	n/a	... '-m', 'doctest', '-o', 'ELLIPSIS',
2806	n/a	... '-o', 'NORMALIZE_WHITESPACE', fn, fn2)
2807	n/a	... rc4, out4, err4 = script_helper.assert_python_failure(
2808	n/a	... '-m', 'doctest', '-f', fn, fn2)
2809	n/a	... rc5, out5, err5 = script_helper.assert_python_ok(
2810	n/a	... '-m', 'doctest', '-v', '-o', 'ELLIPSIS',
2811	n/a	... '-o', 'NORMALIZE_WHITESPACE', fn, fn2)
2812	n/a
2813	n/a	Our first test run will show the errors from the first file (doctest stops if a
2814	n/a	file has errors). Note that doctest test-run error output appears on stdout,
2815	n/a	not stderr:
2816	n/a
2817	n/a	>>> rc1, err1
2818	n/a	(1, b'')
2819	n/a	>>> print(normalize(out1)) # doctest: +ELLIPSIS
2820	n/a	**********************************************************************
2821	n/a	File "...myfile.doc", line 4, in myfile.doc
2822	n/a	Failed example:
2823	n/a	"abcdef"
2824	n/a	Expected:
2825	n/a	'a...f'
2826	n/a	Got:
2827	n/a	'abcdef'
2828	n/a	**********************************************************************
2829	n/a	File "...myfile.doc", line 6, in myfile.doc
2830	n/a	Failed example:
2831	n/a	"ajkml"
2832	n/a	Expected:
2833	n/a	'a...l'
2834	n/a	Got:
2835	n/a	'ajkml'
2836	n/a	**********************************************************************
2837	n/a	1 items had failures:
2838	n/a	2 of 3 in myfile.doc
2839	n/a	*Test Failed* 2 failures.
2840	n/a
2841	n/a	With -o ELLIPSIS specified, the second run, against just the first file, should
2842	n/a	produce no errors, and with -o NORMALIZE_WHITESPACE also specified, neither
2843	n/a	should the third, which ran against both files:
2844	n/a
2845	n/a	>>> rc2, out2, err2
2846	n/a	(0, b'', b'')
2847	n/a	>>> rc3, out3, err3
2848	n/a	(0, b'', b'')
2849	n/a
2850	n/a	The fourth run uses FAIL_FAST, so we should see only one error:
2851	n/a
2852	n/a	>>> rc4, err4
2853	n/a	(1, b'')
2854	n/a	>>> print(normalize(out4)) # doctest: +ELLIPSIS
2855	n/a	**********************************************************************
2856	n/a	File "...myfile.doc", line 4, in myfile.doc
2857	n/a	Failed example:
2858	n/a	"abcdef"
2859	n/a	Expected:
2860	n/a	'a...f'
2861	n/a	Got:
2862	n/a	'abcdef'
2863	n/a	**********************************************************************
2864	n/a	1 items had failures:
2865	n/a	1 of 2 in myfile.doc
2866	n/a	*Test Failed* 1 failures.
2867	n/a
2868	n/a	The fifth test uses verbose with the two options, so we should get verbose
2869	n/a	success output for the tests in both files:
2870	n/a
2871	n/a	>>> rc5, err5
2872	n/a	(0, b'')
2873	n/a	>>> print(normalize(out5))
2874	n/a	Trying:
2875	n/a	1 + 1
2876	n/a	Expecting:
2877	n/a	2
2878	n/a	ok
2879	n/a	Trying:
2880	n/a	"abcdef"
2881	n/a	Expecting:
2882	n/a	'a...f'
2883	n/a	ok
2884	n/a	Trying:
2885	n/a	"ajkml"
2886	n/a	Expecting:
2887	n/a	'a...l'
2888	n/a	ok
2889	n/a	1 items passed all tests:
2890	n/a	3 tests in myfile.doc
2891	n/a	3 tests in 1 items.
2892	n/a	3 passed and 0 failed.
2893	n/a	Test passed.
2894	n/a	Trying:
2895	n/a	1 + 1
2896	n/a	Expecting:
2897	n/a	2
2898	n/a	ok
2899	n/a	Trying:
2900	n/a	"abc def"
2901	n/a	Expecting:
2902	n/a	'abc def'
2903	n/a	ok
2904	n/a	1 items had no tests:
2905	n/a	myfile2
2906	n/a	1 items passed all tests:
2907	n/a	2 tests in myfile2.test_func
2908	n/a	2 tests in 2 items.
2909	n/a	2 passed and 0 failed.
2910	n/a	Test passed.
2911	n/a
2912	n/a	We should also check some typical error cases.
2913	n/a
2914	n/a	Invalid file name:
2915	n/a
2916	n/a	>>> rc, out, err = script_helper.assert_python_failure(
2917	n/a	... '-m', 'doctest', 'nosuchfile')
2918	n/a	>>> rc, out
2919	n/a	(1, b'')
2920	n/a	>>> print(normalize(err)) # doctest: +ELLIPSIS
2921	n/a	Traceback (most recent call last):
2922	n/a	...
2923	n/a	FileNotFoundError: [Errno ...] No such file or directory: 'nosuchfile'
2924	n/a
2925	n/a	Invalid doctest option:
2926	n/a
2927	n/a	>>> rc, out, err = script_helper.assert_python_failure(
2928	n/a	... '-m', 'doctest', '-o', 'nosuchoption')
2929	n/a	>>> rc, out
2930	n/a	(2, b'')
2931	n/a	>>> print(normalize(err)) # doctest: +ELLIPSIS
2932	n/a	usage...invalid...nosuchoption...
2933	n/a
2934	n/a	"""
2935	n/a
2936	n/a	######################################################################
2937	n/a	## Main
2938	n/a	######################################################################
2939	n/a
2940	n/a	def test_main():
2941	n/a	# Check the doctest cases in doctest itself:
2942	n/a	ret = support.run_doctest(doctest, verbosity=True)
2943	n/a
2944	n/a	# Check the doctest cases defined here:
2945	n/a	from test import test_doctest
2946	n/a	support.run_doctest(test_doctest, verbosity=True)
2947	n/a
2948	n/a	def test_coverage(coverdir):
2949	n/a	trace = support.import_module('trace')
2950	n/a	tracer = trace.Trace(ignoredirs=[sys.base_prefix, sys.base_exec_prefix,],
2951	n/a	trace=0, count=1)
2952	n/a	tracer.run('test_main()')
2953	n/a	r = tracer.results()
2954	n/a	print('Writing coverage results...')
2955	n/a	r.write_results(show_missing=True, summary=True,
2956	n/a	coverdir=coverdir)
2957	n/a
2958	n/a	if __name__ == '__main__':
2959	n/a	if '-c' in sys.argv:
2960	n/a	test_coverage('/tmp/doctest.cover')
2961	n/a	else:
2962	n/a	test_main()