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