blob: 270e3087e752a5a613887f5898c021311855bebb [file] [log] [blame]
Eric S. Raymond630e69c2001-02-09 08:33:43 +00001# Module doctest version 0.9.7
Tim Peters8a7d2d52001-01-16 07:10:57 +00002# Released to the public domain 16-Jan-2001,
3# by Tim Peters (tim.one@home.com).
4
5# Provided as-is; use at your own risk; no warranty; no promises; enjoy!
6
7"""Module doctest -- a framework for running examples in docstrings.
8
9NORMAL USAGE
10
11In normal use, end each module M with:
12
13def _test():
14 import doctest, M # replace M with your module's name
15 return doctest.testmod(M) # ditto
16
17if __name__ == "__main__":
18 _test()
19
20Then running the module as a script will cause the examples in the
21docstrings to get executed and verified:
22
23python M.py
24
25This won't display anything unless an example fails, in which case the
26failing example(s) and the cause(s) of the failure(s) are printed to stdout
27(why not stderr? because stderr is a lame hack <0.2 wink>), and the final
28line of output is "Test failed.".
29
30Run it with the -v switch instead:
31
32python M.py -v
33
34and a detailed report of all examples tried is printed to stdout, along
35with assorted summaries at the end.
36
37You can force verbose mode by passing "verbose=1" to testmod, or prohibit
38it by passing "verbose=0". In either of those cases, sys.argv is not
39examined by testmod.
40
41In any case, testmod returns a 2-tuple of ints (f, t), where f is the
42number of docstring examples that failed and t is the total number of
43docstring examples attempted.
44
45
46WHICH DOCSTRINGS ARE EXAMINED?
47
48+ M.__doc__.
49
50+ f.__doc__ for all functions f in M.__dict__.values(), except those
51 with private names.
52
53+ C.__doc__ for all classes C in M.__dict__.values(), except those with
54 private names.
55
56+ If M.__test__ exists and "is true", it must be a dict, and
57 each entry maps a (string) name to a function object, class object, or
58 string. Function and class object docstrings found from M.__test__
59 are searched even if the name is private, and strings are searched
60 directly as if they were docstrings. In output, a key K in M.__test__
61 appears with name
62 <name of M>.__test__.K
63
64Any classes found are recursively searched similarly, to test docstrings in
65their contained methods and nested classes. Private names reached from M's
66globals are skipped, but all names reached from M.__test__ are searched.
67
68By default, a name is considered to be private if it begins with an
69underscore (like "_my_func") but doesn't both begin and end with (at least)
70two underscores (like "__init__"). You can change the default by passing
71your own "isprivate" function to testmod.
72
73If you want to test docstrings in objects with private names too, stuff
74them into an M.__test__ dict, or see ADVANCED USAGE below (e.g., pass your
75own isprivate function to Tester's constructor, or call the rundoc method
76of a Tester instance).
77
78Warning: imports can cause trouble; e.g., if you do
79
80from XYZ import XYZclass
81
82then XYZclass is a name in M.__dict__ too, and doctest has no way to know
83that XYZclass wasn't *defined* in M. So it may try to execute the examples
84in XYZclass's docstring, and those in turn may require a different set of
85globals to work correctly. I prefer to do "import *"- friendly imports,
86a la
87
88import XYY
89_XYZclass = XYZ.XYZclass
90del XYZ
91
92or (Python 2.0)
93
94from XYZ import XYZclass as _XYZclass
95
96and then the leading underscore stops testmod from going nuts. You may
97prefer the method in the next section.
98
99
100WHAT'S THE EXECUTION CONTEXT?
101
102By default, each time testmod finds a docstring to test, it uses a *copy*
103of M's globals (so that running tests on a module doesn't change the
104module's real globals, and so that one test in M can't leave behind crumbs
105that accidentally allow another test to work). This means examples can
106freely use any names defined at top-level in M. It also means that sloppy
107imports (see above) can cause examples in external docstrings to use
108globals inappropriate for them.
109
110You can force use of your own dict as the execution context by passing
111"globs=your_dict" to testmod instead. Presumably this would be a copy of
112M.__dict__ merged with the globals from other imported modules.
113
114
115WHAT IF I WANT TO TEST A WHOLE PACKAGE?
116
117Piece o' cake, provided the modules do their testing from docstrings.
118Here's the test.py I use for the world's most elaborate Rational/
119floating-base-conversion pkg (which I'll distribute some day):
120
121from Rational import Cvt
122from Rational import Format
123from Rational import machprec
124from Rational import Rat
125from Rational import Round
126from Rational import utils
127
128modules = (Cvt,
129 Format,
130 machprec,
131 Rat,
132 Round,
133 utils)
134
135def _test():
136 import doctest
137 import sys
138 verbose = "-v" in sys.argv
139 for mod in modules:
140 doctest.testmod(mod, verbose=verbose, report=0)
141 doctest.master.summarize()
142
143if __name__ == "__main__":
144 _test()
145
146IOW, it just runs testmod on all the pkg modules. testmod remembers the
147names and outcomes (# of failures, # of tries) for each item it's seen, and
148passing "report=0" prevents it from printing a summary in verbose mode.
149Instead, the summary is delayed until all modules have been tested, and
150then "doctest.master.summarize()" forces the summary at the end.
151
152So this is very nice in practice: each module can be tested individually
153with almost no work beyond writing up docstring examples, and collections
154of modules can be tested too as a unit with no more work than the above.
155
156
157WHAT ABOUT EXCEPTIONS?
158
159No problem, as long as the only output generated by the example is the
160traceback itself. For example:
161
Tim Peters60e23f42001-02-14 00:43:21 +0000162 >>> [1, 2, 3].remove(42)
Tim Petersea4f9312001-02-13 20:54:42 +0000163 Traceback (most recent call last):
Tim Peters8a7d2d52001-01-16 07:10:57 +0000164 File "<stdin>", line 1, in ?
Tim Peters60e23f42001-02-14 00:43:21 +0000165 ValueError: list.remove(x): x not in list
Tim Peters8a7d2d52001-01-16 07:10:57 +0000166 >>>
167
168Note that only the exception type and value are compared (specifically,
169only the last line in the traceback).
170
171
172ADVANCED USAGE
173
174doctest.testmod() captures the testing policy I find most useful most
175often. You may want other policies.
176
177testmod() actually creates a local instance of class doctest.Tester, runs
178appropriate methods of that class, and merges the results into global
179Tester instance doctest.master.
180
181You can create your own instances of doctest.Tester, and so build your own
182policies, or even run methods of doctest.master directly. See
183doctest.Tester.__doc__ for details.
184
185
186SO WHAT DOES A DOCSTRING EXAMPLE LOOK LIKE ALREADY!?
187
188Oh ya. It's easy! In most cases a copy-and-paste of an interactive
189console session works fine -- just make sure the leading whitespace is
190rigidly consistent (you can mix tabs and spaces if you're too lazy to do it
191right, but doctest is not in the business of guessing what you think a tab
192means).
193
194 >>> # comments are ignored
195 >>> x = 12
196 >>> x
197 12
198 >>> if x == 13:
199 ... print "yes"
200 ... else:
201 ... print "no"
202 ... print "NO"
203 ... print "NO!!!"
204 ...
205 no
206 NO
207 NO!!!
208 >>>
209
210Any expected output must immediately follow the final ">>>" or "..." line
211containing the code, and the expected output (if any) extends to the next
212">>>" or all-whitespace line. That's it.
213
214Bummers:
215
216+ Expected output cannot contain an all-whitespace line, since such a line
217 is taken to signal the end of expected output.
218
219+ Output to stdout is captured, but not output to stderr (exception
220 tracebacks are captured via a different means).
221
222+ If you continue a line via backslashing in an interactive session, or for
223 any other reason use a backslash, you need to double the backslash in the
224 docstring version. This is simply because you're in a string, and so the
225 backslash must be escaped for it to survive intact. Like:
226
227>>> if "yes" == \\
228... "y" + \\
229... "es": # in the source code you'll see the doubled backslashes
230... print 'yes'
231yes
232
233The starting column doesn't matter:
234
235>>> assert "Easy!"
236 >>> import math
237 >>> math.floor(1.9)
238 1.0
239
240and as many leading whitespace characters are stripped from the expected
241output as appeared in the initial ">>>" line that triggered it.
242
243If you execute this very file, the examples above will be found and
244executed, leading to this output in verbose mode:
245
246Running doctest.__doc__
Tim Peters60e23f42001-02-14 00:43:21 +0000247Trying: [1, 2, 3].remove(42)
Tim Peters8a7d2d52001-01-16 07:10:57 +0000248Expecting:
Tim Petersea4f9312001-02-13 20:54:42 +0000249Traceback (most recent call last):
Tim Peters8a7d2d52001-01-16 07:10:57 +0000250 File "<stdin>", line 1, in ?
Tim Peters60e23f42001-02-14 00:43:21 +0000251ValueError: list.remove(x): x not in list
Tim Peters8a7d2d52001-01-16 07:10:57 +0000252ok
253Trying: x = 12
254Expecting: nothing
255ok
256Trying: x
257Expecting: 12
258ok
259Trying:
260if x == 13:
261 print "yes"
262else:
263 print "no"
264 print "NO"
265 print "NO!!!"
266Expecting:
267no
268NO
269NO!!!
270ok
271... and a bunch more like that, with this summary at the end:
272
2735 items had no tests:
274 doctest.Tester.__init__
275 doctest.Tester.run__test__
276 doctest.Tester.summarize
277 doctest.run_docstring_examples
278 doctest.testmod
27912 items passed all tests:
280 8 tests in doctest
281 6 tests in doctest.Tester
282 10 tests in doctest.Tester.merge
283 7 tests in doctest.Tester.rundict
284 3 tests in doctest.Tester.rundoc
285 3 tests in doctest.Tester.runstring
286 2 tests in doctest.__test__._TestClass
287 2 tests in doctest.__test__._TestClass.__init__
288 2 tests in doctest.__test__._TestClass.get
289 1 tests in doctest.__test__._TestClass.square
290 2 tests in doctest.__test__.string
291 7 tests in doctest.is_private
29253 tests in 17 items.
29353 passed and 0 failed.
294Test passed.
295"""
296
297# 0,0,1 06-Mar-1999
298# initial version posted
299# 0,0,2 06-Mar-1999
300# loosened parsing:
301# cater to stinkin' tabs
302# don't insist on a blank after PS2 prefix
303# so trailing "... " line from a compound stmt no longer
304# breaks if the file gets whitespace-trimmed
305# better error msgs for inconsistent leading whitespace
306# 0,9,1 08-Mar-1999
307# exposed the Tester class and added client methods
308# plus docstring examples of their use (eww - head-twisting!)
309# fixed logic error in reporting total # of tests & failures
310# added __test__ support to testmod (a pale reflection of Christian
311# Tismer's vision ...)
312# removed the "deep" argument; fiddle __test__ instead
313# simplified endcase logic for extracting tests, and running them.
314# before, if no output was expected but some was produced
315# anyway via an eval'ed result, the discrepancy wasn't caught
316# made TestClass private and used __test__ to get at it
317# many doc updates
318# speed _SpoofOut for long expected outputs
319# 0,9,2 09-Mar-1999
320# throw out comments from examples, enabling use of the much simpler
321# exec compile(... "single") ...
322# for simulating the runtime; that barfs on comment-only lines
323# used the traceback module to do a much better job of reporting
324# exceptions
325# run __doc__ values thru str(), "just in case"
326# privateness of names now determined by an overridable "isprivate"
327# function
328# by default a name now considered to be private iff it begins with
329# an underscore but doesn't both begin & end with two of 'em; so
330# e.g. Class.__init__ etc are searched now -- as they always
331# should have been
332# 0,9,3 18-Mar-1999
333# added .flush stub to _SpoofOut (JPython buglet diagnosed by
334# Hugh Emberson)
335# repaired ridiculous docs about backslashes in examples
336# minor internal changes
337# changed source to Unix line-end conventions
338# moved __test__ logic into new Tester.run__test__ method
339# 0,9,4 27-Mar-1999
340# report item name and line # in failing examples
341# 0,9,5 29-Jun-1999
342# allow straightforward exceptions in examples - thanks to Mark Hammond!
343# 0,9,6 16-Jan-2001
344# fiddling for changes in Python 2.0: some of the embedded docstring
345# examples no longer worked *exactly* as advertised, due to minor
346# language changes, and running doctest on itself pointed that out.
347# Hard to think of a better example of why this is useful <wink>.
Eric S. Raymond630e69c2001-02-09 08:33:43 +0000348# 0,9,7 9-Feb-2001
349# string method conversion
Tim Peters8a7d2d52001-01-16 07:10:57 +0000350
Tim Petersecb6fb92001-02-10 01:24:50 +0000351__version__ = 0, 9, 7
Tim Peters8a7d2d52001-01-16 07:10:57 +0000352
353import types
354_FunctionType = types.FunctionType
355_ClassType = types.ClassType
356_ModuleType = types.ModuleType
357_StringType = types.StringType
358del types
359
Tim Peters8a7d2d52001-01-16 07:10:57 +0000360import re
361PS1 = ">>>"
362PS2 = "..."
363_isPS1 = re.compile(r"(\s*)" + re.escape(PS1)).match
364_isPS2 = re.compile(r"(\s*)" + re.escape(PS2)).match
365_isEmpty = re.compile(r"\s*$").match
366_isComment = re.compile(r"\s*#").match
367del re
368
Skip Montanaroeccd02a2001-01-20 23:34:12 +0000369__all__ = []
370
Tim Peters8a7d2d52001-01-16 07:10:57 +0000371# Extract interactive examples from a string. Return a list of triples,
372# (source, outcome, lineno). "source" is the source code, and ends
373# with a newline iff the source spans more than one line. "outcome" is
374# the expected output if any, else an empty string. When not empty,
375# outcome always ends with a newline. "lineno" is the line number,
376# 0-based wrt the start of the string, of the first source line.
377
378def _extract_examples(s):
379 isPS1, isPS2 = _isPS1, _isPS2
380 isEmpty, isComment = _isEmpty, _isComment
381 examples = []
Eric S. Raymond630e69c2001-02-09 08:33:43 +0000382 lines = s.split("\n")
Tim Peters8a7d2d52001-01-16 07:10:57 +0000383 i, n = 0, len(lines)
384 while i < n:
385 line = lines[i]
386 i = i + 1
387 m = isPS1(line)
388 if m is None:
389 continue
390 j = m.end(0) # beyond the prompt
391 if isEmpty(line, j) or isComment(line, j):
392 # a bare prompt or comment -- not interesting
393 continue
394 lineno = i - 1
395 if line[j] != " ":
396 raise ValueError("line " + `lineno` + " of docstring lacks "
397 "blank after " + PS1 + ": " + line)
398 j = j + 1
399 blanks = m.group(1)
400 nblanks = len(blanks)
401 # suck up this and following PS2 lines
402 source = []
403 while 1:
404 source.append(line[j:])
405 line = lines[i]
406 m = isPS2(line)
407 if m:
408 if m.group(1) != blanks:
409 raise ValueError("inconsistent leading whitespace "
410 "in line " + `i` + " of docstring: " + line)
411 i = i + 1
412 else:
413 break
414 if len(source) == 1:
415 source = source[0]
416 else:
417 # get rid of useless null line from trailing empty "..."
418 if source[-1] == "":
419 del source[-1]
Eric S. Raymond630e69c2001-02-09 08:33:43 +0000420 source = "\n".join(source) + "\n"
Tim Peters8a7d2d52001-01-16 07:10:57 +0000421 # suck up response
422 if isPS1(line) or isEmpty(line):
423 expect = ""
424 else:
425 expect = []
426 while 1:
427 if line[:nblanks] != blanks:
428 raise ValueError("inconsistent leading whitespace "
429 "in line " + `i` + " of docstring: " + line)
430 expect.append(line[nblanks:])
431 i = i + 1
432 line = lines[i]
433 if isPS1(line) or isEmpty(line):
434 break
Eric S. Raymond630e69c2001-02-09 08:33:43 +0000435 expect = "\n".join(expect) + "\n"
Tim Peters8a7d2d52001-01-16 07:10:57 +0000436 examples.append( (source, expect, lineno) )
437 return examples
438
439# Capture stdout when running examples.
440
441class _SpoofOut:
442 def __init__(self):
443 self.clear()
444 def write(self, s):
445 self.buf.append(s)
446 def get(self):
Tim Petersf9bb4962001-02-14 06:35:35 +0000447 guts = "".join(self.buf)
448 # If anything at all was written, make sure there's a trailing
449 # newline. There's no way for the expected output to indicate
450 # that a trailing newline is missing.
451 if guts and not guts.endswith("\n"):
452 guts = guts + "\n"
453 return guts
Tim Peters8a7d2d52001-01-16 07:10:57 +0000454 def clear(self):
455 self.buf = []
456 def flush(self):
457 # JPython calls flush
458 pass
459
460# Display some tag-and-msg pairs nicely, keeping the tag and its msg
461# on the same line when that makes sense.
462
463def _tag_out(printer, *tag_msg_pairs):
464 for tag, msg in tag_msg_pairs:
465 printer(tag + ":")
466 msg_has_nl = msg[-1:] == "\n"
467 msg_has_two_nl = msg_has_nl and \
Eric S. Raymond630e69c2001-02-09 08:33:43 +0000468 msg.find("\n") < len(msg) - 1
Tim Peters8a7d2d52001-01-16 07:10:57 +0000469 if len(tag) + len(msg) < 76 and not msg_has_two_nl:
470 printer(" ")
471 else:
472 printer("\n")
473 printer(msg)
474 if not msg_has_nl:
475 printer("\n")
476
477# Run list of examples, in context globs. "out" can be used to display
478# stuff to "the real" stdout, and fakeout is an instance of _SpoofOut
479# that captures the examples' std output. Return (#failures, #tries).
480
481def _run_examples_inner(out, fakeout, examples, globs, verbose, name):
482 import sys, traceback
483 OK, BOOM, FAIL = range(3)
484 NADA = "nothing"
485 stderr = _SpoofOut()
486 failures = 0
487 for source, want, lineno in examples:
488 if verbose:
489 _tag_out(out, ("Trying", source),
490 ("Expecting", want or NADA))
491 fakeout.clear()
492 try:
493 exec compile(source, "<string>", "single") in globs
494 got = fakeout.get()
495 state = OK
496 except:
497 # See whether the exception was expected.
Tim Petersea4f9312001-02-13 20:54:42 +0000498 if want.find("Traceback (innermost last):\n") == 0 or \
499 want.find("Traceback (most recent call last):\n") == 0:
Tim Peters8a7d2d52001-01-16 07:10:57 +0000500 # Only compare exception type and value - the rest of
501 # the traceback isn't necessary.
Eric S. Raymond630e69c2001-02-09 08:33:43 +0000502 want = want.split('\n')[-2] + '\n'
Tim Peters8a7d2d52001-01-16 07:10:57 +0000503 exc_type, exc_val, exc_tb = sys.exc_info()
504 got = traceback.format_exception_only(exc_type, exc_val)[0]
505 state = OK
506 else:
507 # unexpected exception
508 stderr.clear()
509 traceback.print_exc(file=stderr)
510 state = BOOM
511
512 if state == OK:
513 if got == want:
514 if verbose:
515 out("ok\n")
516 continue
517 state = FAIL
518
519 assert state in (FAIL, BOOM)
520 failures = failures + 1
521 out("*" * 65 + "\n")
522 _tag_out(out, ("Failure in example", source))
523 out("from line #" + `lineno` + " of " + name + "\n")
524 if state == FAIL:
525 _tag_out(out, ("Expected", want or NADA), ("Got", got))
526 else:
527 assert state == BOOM
528 _tag_out(out, ("Exception raised", stderr.get()))
529
530 return failures, len(examples)
531
532# Run list of examples, in context globs. Return (#failures, #tries).
533
534def _run_examples(examples, globs, verbose, name):
535 import sys
536 saveout = sys.stdout
537 try:
538 sys.stdout = fakeout = _SpoofOut()
539 x = _run_examples_inner(saveout.write, fakeout, examples,
540 globs, verbose, name)
541 finally:
542 sys.stdout = saveout
543 return x
544
545def run_docstring_examples(f, globs, verbose=0, name="NoName"):
546 """f, globs, verbose=0, name="NoName" -> run examples from f.__doc__.
547
548 Use dict globs as the globals for execution.
549 Return (#failures, #tries).
550
551 If optional arg verbose is true, print stuff even if there are no
552 failures.
553 Use string name in failure msgs.
554 """
555
556 try:
557 doc = f.__doc__
558 if not doc:
559 # docstring empty or None
560 return 0, 0
561 # just in case CT invents a doc object that has to be forced
562 # to look like a string <0.9 wink>
563 doc = str(doc)
564 except:
565 return 0, 0
566
567 e = _extract_examples(doc)
568 if not e:
569 return 0, 0
570 return _run_examples(e, globs, verbose, name)
571
572def is_private(prefix, base):
573 """prefix, base -> true iff name prefix + "." + base is "private".
574
575 Prefix may be an empty string, and base does not contain a period.
576 Prefix is ignored (although functions you write conforming to this
577 protocol may make use of it).
578 Return true iff base begins with an (at least one) underscore, but
579 does not both begin and end with (at least) two underscores.
580
581 >>> is_private("a.b", "my_func")
582 0
583 >>> is_private("____", "_my_func")
584 1
585 >>> is_private("someclass", "__init__")
586 0
587 >>> is_private("sometypo", "__init_")
588 1
589 >>> is_private("x.y.z", "_")
590 1
591 >>> is_private("_x.y.z", "__")
592 0
593 >>> is_private("", "") # senseless but consistent
594 0
595 """
596
597 return base[:1] == "_" and not base[:2] == "__" == base[-2:]
598
599class Tester:
600 """Class Tester -- runs docstring examples and accumulates stats.
601
602In normal use, function doctest.testmod() hides all this from you,
603so use that if you can. Create your own instances of Tester to do
604fancier things.
605
606Methods:
607 runstring(s, name)
608 Search string s for examples to run; use name for logging.
609 Return (#failures, #tries).
610
611 rundoc(object, name=None)
612 Search object.__doc__ for examples to run; use name (or
613 object.__name__) for logging. Return (#failures, #tries).
614
615 rundict(d, name)
616 Search for examples in docstrings in all of d.values(); use name
617 for logging. Return (#failures, #tries).
618
619 run__test__(d, name)
620 Treat dict d like module.__test__. Return (#failures, #tries).
621
622 summarize(verbose=None)
623 Display summary of testing results, to stdout. Return
624 (#failures, #tries).
625
626 merge(other)
627 Merge in the test results from Tester instance "other".
628
629>>> from doctest import Tester
630>>> t = Tester(globs={'x': 42}, verbose=0)
631>>> t.runstring(r'''
632... >>> x = x * 2
633... >>> print x
634... 42
635... ''', 'XYZ')
636*****************************************************************
637Failure in example: print x
638from line #2 of XYZ
639Expected: 42
640Got: 84
641(1, 2)
642>>> t.runstring(">>> x = x * 2\\n>>> print x\\n84\\n", 'example2')
643(0, 2)
644>>> t.summarize()
Guido van Rossum261d91a2001-03-18 17:05:58 +0000645*****************************************************************
Tim Peters8a7d2d52001-01-16 07:10:57 +00006461 items had failures:
647 1 of 2 in XYZ
648***Test Failed*** 1 failures.
649(1, 4)
650>>> t.summarize(verbose=1)
6511 items passed all tests:
652 2 tests in example2
Guido van Rossum261d91a2001-03-18 17:05:58 +0000653*****************************************************************
Tim Peters8a7d2d52001-01-16 07:10:57 +00006541 items had failures:
655 1 of 2 in XYZ
6564 tests in 2 items.
6573 passed and 1 failed.
658***Test Failed*** 1 failures.
659(1, 4)
660>>>
661"""
662
663 def __init__(self, mod=None, globs=None, verbose=None,
664 isprivate=None):
665 """mod=None, globs=None, verbose=None, isprivate=None
666
667See doctest.__doc__ for an overview.
668
669Optional keyword arg "mod" is a module, whose globals are used for
670executing examples. If not specified, globs must be specified.
671
672Optional keyword arg "globs" gives a dict to be used as the globals
673when executing examples; if not specified, use the globals from
674module mod.
675
676In either case, a copy of the dict is used for each docstring
677examined.
678
679Optional keyword arg "verbose" prints lots of stuff if true, only
680failures if false; by default, it's true iff "-v" is in sys.argv.
681
682Optional keyword arg "isprivate" specifies a function used to determine
683whether a name is private. The default function is doctest.is_private;
684see its docs for details.
685"""
686
687 if mod is None and globs is None:
688 raise TypeError("Tester.__init__: must specify mod or globs")
689 if mod is not None and type(mod) is not _ModuleType:
690 raise TypeError("Tester.__init__: mod must be a module; " +
691 `mod`)
692 if globs is None:
693 globs = mod.__dict__
694 self.globs = globs
695
696 if verbose is None:
697 import sys
698 verbose = "-v" in sys.argv
699 self.verbose = verbose
700
701 if isprivate is None:
702 isprivate = is_private
703 self.isprivate = isprivate
704
705 self.name2ft = {} # map name to (#failures, #trials) pair
706
707 def runstring(self, s, name):
708 """
709 s, name -> search string s for examples to run, logging as name.
710
711 Use string name as the key for logging the outcome.
712 Return (#failures, #examples).
713
714 >>> t = Tester(globs={}, verbose=1)
715 >>> test = r'''
716 ... # just an example
717 ... >>> x = 1 + 2
718 ... >>> x
719 ... 3
720 ... '''
721 >>> t.runstring(test, "Example")
722 Running string Example
723 Trying: x = 1 + 2
724 Expecting: nothing
725 ok
726 Trying: x
727 Expecting: 3
728 ok
729 0 of 2 examples failed in string Example
730 (0, 2)
731 """
732
733 if self.verbose:
734 print "Running string", name
735 f = t = 0
736 e = _extract_examples(s)
737 if e:
738 f, t = _run_examples(e, self.globs.copy(), self.verbose, name)
739 if self.verbose:
740 print f, "of", t, "examples failed in string", name
741 self.__record_outcome(name, f, t)
742 return f, t
743
744 def rundoc(self, object, name=None):
745 """
746 object, name=None -> search object.__doc__ for examples to run.
747
748 Use optional string name as the key for logging the outcome;
749 by default use object.__name__.
750 Return (#failures, #examples).
751 If object is a class object, search recursively for method
752 docstrings too.
753 object.__doc__ is examined regardless of name, but if object is
754 a class, whether private names reached from object are searched
755 depends on the constructor's "isprivate" argument.
756
757 >>> t = Tester(globs={}, verbose=0)
758 >>> def _f():
759 ... '''Trivial docstring example.
760 ... >>> assert 2 == 2
761 ... '''
762 ... return 32
763 ...
764 >>> t.rundoc(_f) # expect 0 failures in 1 example
765 (0, 1)
766 """
767
768 if name is None:
769 try:
770 name = object.__name__
771 except AttributeError:
772 raise ValueError("Tester.rundoc: name must be given "
773 "when object.__name__ doesn't exist; " + `object`)
774 if self.verbose:
775 print "Running", name + ".__doc__"
776 f, t = run_docstring_examples(object, self.globs.copy(),
777 self.verbose, name)
778 if self.verbose:
779 print f, "of", t, "examples failed in", name + ".__doc__"
780 self.__record_outcome(name, f, t)
781 if type(object) is _ClassType:
782 f2, t2 = self.rundict(object.__dict__, name)
783 f = f + f2
784 t = t + t2
785 return f, t
786
787 def rundict(self, d, name):
788 """
789 d. name -> search for docstring examples in all of d.values().
790
791 For k, v in d.items() such that v is a function or class,
792 do self.rundoc(v, name + "." + k). Whether this includes
793 objects with private names depends on the constructor's
794 "isprivate" argument.
795 Return aggregate (#failures, #examples).
796
797 >>> def _f():
798 ... '''>>> assert 1 == 1
799 ... '''
800 >>> def g():
801 ... '''>>> assert 2 != 1
802 ... '''
803 >>> d = {"_f": _f, "g": g}
804 >>> t = Tester(globs={}, verbose=0)
805 >>> t.rundict(d, "rundict_test") # _f is skipped
806 (0, 1)
807 >>> t = Tester(globs={}, verbose=0, isprivate=lambda x,y: 0)
808 >>> t.rundict(d, "rundict_test_pvt") # both are searched
809 (0, 2)
810 """
811
812 if not hasattr(d, "items"):
813 raise TypeError("Tester.rundict: d must support .items(); " +
814 `d`)
815 f = t = 0
Tim Peters24a41912001-03-21 23:07:59 +0000816 # Run the tests by alpha order of names, for consistency in
817 # verbose-mode output.
818 names = d.keys()
819 names.sort()
820 for thisname in names:
821 value = d[thisname]
Tim Peters8a7d2d52001-01-16 07:10:57 +0000822 if type(value) in (_FunctionType, _ClassType):
823 f2, t2 = self.__runone(value, name + "." + thisname)
824 f = f + f2
825 t = t + t2
826 return f, t
827
828 def run__test__(self, d, name):
829 """d, name -> Treat dict d like module.__test__.
830
831 Return (#failures, #tries).
832 See testmod.__doc__ for details.
833 """
834
835 failures = tries = 0
836 prefix = name + "."
837 savepvt = self.isprivate
838 try:
839 self.isprivate = lambda *args: 0
Tim Peters24a41912001-03-21 23:07:59 +0000840 # Run the tests by alpha order of names, for consistency in
841 # verbose-mode output.
842 keys = d.keys()
843 keys.sort()
844 for k in keys:
845 v = d[k]
Tim Peters8a7d2d52001-01-16 07:10:57 +0000846 thisname = prefix + k
847 if type(v) is _StringType:
848 f, t = self.runstring(v, thisname)
849 elif type(v) in (_FunctionType, _ClassType):
850 f, t = self.rundoc(v, thisname)
851 else:
852 raise TypeError("Tester.run__test__: values in "
853 "dict must be strings, functions "
854 "or classes; " + `v`)
855 failures = failures + f
856 tries = tries + t
857 finally:
858 self.isprivate = savepvt
859 return failures, tries
860
861 def summarize(self, verbose=None):
862 """
863 verbose=None -> summarize results, return (#failures, #tests).
864
865 Print summary of test results to stdout.
866 Optional arg 'verbose' controls how wordy this is. By
867 default, use the verbose setting established by the
868 constructor.
869 """
870
871 if verbose is None:
872 verbose = self.verbose
873 notests = []
874 passed = []
875 failed = []
876 totalt = totalf = 0
877 for x in self.name2ft.items():
878 name, (f, t) = x
879 assert f <= t
880 totalt = totalt + t
881 totalf = totalf + f
882 if t == 0:
883 notests.append(name)
884 elif f == 0:
885 passed.append( (name, t) )
886 else:
887 failed.append(x)
888 if verbose:
889 if notests:
890 print len(notests), "items had no tests:"
891 notests.sort()
892 for thing in notests:
893 print " ", thing
894 if passed:
895 print len(passed), "items passed all tests:"
896 passed.sort()
897 for thing, count in passed:
898 print " %3d tests in %s" % (count, thing)
899 if failed:
Guido van Rossumaf00a462001-03-18 16:58:44 +0000900 print "*" * 65
Tim Peters8a7d2d52001-01-16 07:10:57 +0000901 print len(failed), "items had failures:"
902 failed.sort()
903 for thing, (f, t) in failed:
904 print " %3d of %3d in %s" % (f, t, thing)
905 if verbose:
906 print totalt, "tests in", len(self.name2ft), "items."
907 print totalt - totalf, "passed and", totalf, "failed."
908 if totalf:
909 print "***Test Failed***", totalf, "failures."
910 elif verbose:
911 print "Test passed."
912 return totalf, totalt
913
914 def merge(self, other):
915 """
916 other -> merge in test results from the other Tester instance.
917
918 If self and other both have a test result for something
919 with the same name, the (#failures, #tests) results are
920 summed, and a warning is printed to stdout.
921
922 >>> from doctest import Tester
923 >>> t1 = Tester(globs={}, verbose=0)
924 >>> t1.runstring('''
925 ... >>> x = 12
926 ... >>> print x
927 ... 12
928 ... ''', "t1example")
929 (0, 2)
930 >>>
931 >>> t2 = Tester(globs={}, verbose=0)
932 >>> t2.runstring('''
933 ... >>> x = 13
934 ... >>> print x
935 ... 13
936 ... ''', "t2example")
937 (0, 2)
938 >>> common = ">>> assert 1 + 2 == 3\\n"
939 >>> t1.runstring(common, "common")
940 (0, 1)
941 >>> t2.runstring(common, "common")
942 (0, 1)
943 >>> t1.merge(t2)
944 *** Tester.merge: 'common' in both testers; summing outcomes.
945 >>> t1.summarize(1)
946 3 items passed all tests:
947 2 tests in common
948 2 tests in t1example
949 2 tests in t2example
950 6 tests in 3 items.
951 6 passed and 0 failed.
952 Test passed.
953 (0, 6)
954 >>>
955 """
956
957 d = self.name2ft
958 for name, (f, t) in other.name2ft.items():
959 if d.has_key(name):
960 print "*** Tester.merge: '" + name + "' in both" \
961 " testers; summing outcomes."
962 f2, t2 = d[name]
963 f = f + f2
964 t = t + t2
965 d[name] = f, t
966
967 def __record_outcome(self, name, f, t):
968 if self.name2ft.has_key(name):
969 print "*** Warning: '" + name + "' was tested before;", \
970 "summing outcomes."
971 f2, t2 = self.name2ft[name]
972 f = f + f2
973 t = t + t2
974 self.name2ft[name] = f, t
975
976 def __runone(self, target, name):
977 if "." in name:
Eric S. Raymond630e69c2001-02-09 08:33:43 +0000978 i = name.rindex(".")
Tim Peters8a7d2d52001-01-16 07:10:57 +0000979 prefix, base = name[:i], name[i+1:]
980 else:
981 prefix, base = "", base
982 if self.isprivate(prefix, base):
983 return 0, 0
984 return self.rundoc(target, name)
985
986master = None
987
988def testmod(m, name=None, globs=None, verbose=None, isprivate=None,
989 report=1):
990 """m, name=None, globs=None, verbose=None, isprivate=None, report=1
991
992 Test examples in docstrings in functions and classes reachable from
993 module m, starting with m.__doc__. Private names are skipped.
994
995 Also test examples reachable from dict m.__test__ if it exists and is
996 not None. m.__dict__ maps names to functions, classes and strings;
997 function and class docstrings are tested even if the name is private;
998 strings are tested directly, as if they were docstrings.
999
1000 Return (#failures, #tests).
1001
1002 See doctest.__doc__ for an overview.
1003
1004 Optional keyword arg "name" gives the name of the module; by default
1005 use m.__name__.
1006
1007 Optional keyword arg "globs" gives a dict to be used as the globals
1008 when executing examples; by default, use m.__dict__. A copy of this
1009 dict is actually used for each docstring, so that each docstring's
1010 examples start with a clean slate.
1011
1012 Optional keyword arg "verbose" prints lots of stuff if true, prints
1013 only failures if false; by default, it's true iff "-v" is in sys.argv.
1014
1015 Optional keyword arg "isprivate" specifies a function used to
1016 determine whether a name is private. The default function is
1017 doctest.is_private; see its docs for details.
1018
1019 Optional keyword arg "report" prints a summary at the end when true,
1020 else prints nothing at the end. In verbose mode, the summary is
1021 detailed, else very brief (in fact, empty if all tests passed).
1022
1023 Advanced tomfoolery: testmod runs methods of a local instance of
1024 class doctest.Tester, then merges the results into (or creates)
1025 global Tester instance doctest.master. Methods of doctest.master
1026 can be called directly too, if you want to do something unusual.
1027 Passing report=0 to testmod is especially useful then, to delay
1028 displaying a summary. Invoke doctest.master.summarize(verbose)
1029 when you're done fiddling.
1030 """
1031
1032 global master
1033
1034 if type(m) is not _ModuleType:
1035 raise TypeError("testmod: module required; " + `m`)
1036 if name is None:
1037 name = m.__name__
1038 tester = Tester(m, globs=globs, verbose=verbose, isprivate=isprivate)
1039 failures, tries = tester.rundoc(m, name)
1040 f, t = tester.rundict(m.__dict__, name)
1041 failures = failures + f
1042 tries = tries + t
1043 if hasattr(m, "__test__"):
1044 testdict = m.__test__
1045 if testdict:
1046 if not hasattr(testdict, "items"):
1047 raise TypeError("testmod: module.__test__ must support "
1048 ".items(); " + `testdict`)
1049 f, t = tester.run__test__(testdict, name + ".__test__")
1050 failures = failures + f
1051 tries = tries + t
1052 if report:
1053 tester.summarize()
1054 if master is None:
1055 master = tester
1056 else:
1057 master.merge(tester)
1058 return failures, tries
1059
1060class _TestClass:
1061 """
1062 A pointless class, for sanity-checking of docstring testing.
1063
1064 Methods:
1065 square()
1066 get()
1067
1068 >>> _TestClass(13).get() + _TestClass(-12).get()
1069 1
1070 >>> hex(_TestClass(13).square().get())
1071 '0xa9'
1072 """
1073
1074 def __init__(self, val):
1075 """val -> _TestClass object with associated value val.
1076
1077 >>> t = _TestClass(123)
1078 >>> print t.get()
1079 123
1080 """
1081
1082 self.val = val
1083
1084 def square(self):
1085 """square() -> square TestClass's associated value
1086
1087 >>> _TestClass(13).square().get()
1088 169
1089 """
1090
1091 self.val = self.val ** 2
1092 return self
1093
1094 def get(self):
1095 """get() -> return TestClass's associated value.
1096
1097 >>> x = _TestClass(-42)
1098 >>> print x.get()
1099 -42
1100 """
1101
1102 return self.val
1103
1104__test__ = {"_TestClass": _TestClass,
1105 "string": r"""
1106 Example of a string object, searched as-is.
1107 >>> x = 1; y = 2
1108 >>> x + y, x * y
1109 (3, 2)
1110 """
1111 }
1112
1113def _test():
1114 import doctest
1115 return doctest.testmod(doctest)
1116
1117if __name__ == "__main__":
1118 _test()