ยปCore Development>Code coverage>Lib/doctest.py

Python code coverage for Lib/doctest.py

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