doctest.py revision 6c542b731cfe3e17991643bfc41bb785331e7e5c
1e1f365035a952233463d85d659bd960ba78f012eJens Axboe# Module doctest. 2e1f365035a952233463d85d659bd960ba78f012eJens Axboe# Released to the public domain 16-Jan-2001, by Tim Peters (tim@python.org). 3e1f365035a952233463d85d659bd960ba78f012eJens Axboe# Major enhancements and refactoring by: 49f988e2ebb3bff7087cc9681a54bd7f0d0e42140Jens Axboe# Jim Fulton 59f988e2ebb3bff7087cc9681a54bd7f0d0e42140Jens Axboe# Edward Loper 6e1f365035a952233463d85d659bd960ba78f012eJens Axboe 7e1f365035a952233463d85d659bd960ba78f012eJens Axboe# Provided as-is; use at your own risk; no warranty; no promises; enjoy! 8e1f365035a952233463d85d659bd960ba78f012eJens Axboe 9e1f365035a952233463d85d659bd960ba78f012eJens Axboer"""Module doctest -- a framework for running examples in docstrings. 1007b3232de97ac32a873f0b5d17c8f49c18ed3ae7Jens Axboe 1107b3232de97ac32a873f0b5d17c8f49c18ed3ae7Jens AxboeNORMAL USAGE 125f6ddf1e568d5014925a98da316d92f9e6e03eb4Jens Axboe 13e1f365035a952233463d85d659bd960ba78f012eJens AxboeIn simplest use, end each module M to be tested with: 14e1f365035a952233463d85d659bd960ba78f012eJens Axboe 15e1f365035a952233463d85d659bd960ba78f012eJens Axboedef _test(): 16e1f365035a952233463d85d659bd960ba78f012eJens Axboe import doctest 17e1f365035a952233463d85d659bd960ba78f012eJens Axboe return doctest.testmod() 1813335ddb0e304efa0fc96593dd1fd995ec6f68d7Jens Axboe 19833491908a1afd67d27ce79257de3a4d80143d9fYu-ju Hongif __name__ == "__main__": 20e1f365035a952233463d85d659bd960ba78f012eJens Axboe _test() 2115ca150e8dbfd68aa5beb479fcb3f07447417a04Jens Axboe 22e1f365035a952233463d85d659bd960ba78f012eJens AxboeThen running the module as a script will cause the examples in the 23e1f365035a952233463d85d659bd960ba78f012eJens Axboedocstrings to get executed and verified: 24e1f365035a952233463d85d659bd960ba78f012eJens Axboe 25b1ec1da670aab645e32303ea5ffaa1e5ca336936Jens Axboepython M.py 26b1ec1da670aab645e32303ea5ffaa1e5ca336936Jens Axboe 27b1ec1da670aab645e32303ea5ffaa1e5ca336936Jens AxboeThis won't display anything unless an example fails, in which case the 28b1ec1da670aab645e32303ea5ffaa1e5ca336936Jens Axboefailing example(s) and the cause(s) of the failure(s) are printed to stdout 29b1ec1da670aab645e32303ea5ffaa1e5ca336936Jens Axboe(why not stderr? because stderr is a lame hack <0.2 wink>), and the final 307837213b66e20a8d91e7069f5823852f42c41440Jens Axboeline of output is "Test failed.". 315f6ddf1e568d5014925a98da316d92f9e6e03eb4Jens Axboe 32c44b1ff54402c589e8f07436ec56efb4f8b1ac23Jens AxboeRun it with the -v switch instead: 33b1ec1da670aab645e32303ea5ffaa1e5ca336936Jens Axboe 34b1ec1da670aab645e32303ea5ffaa1e5ca336936Jens Axboepython M.py -v 35c06c78c04c415bcb33350e8e56b924b75b4e93aaZhang, Yanmin 36b1ec1da670aab645e32303ea5ffaa1e5ca336936Jens Axboeand a detailed report of all examples tried is printed to stdout, along 37b1ec1da670aab645e32303ea5ffaa1e5ca336936Jens Axboewith assorted summaries at the end. 38b1ec1da670aab645e32303ea5ffaa1e5ca336936Jens Axboe 39e1f365035a952233463d85d659bd960ba78f012eJens AxboeYou can force verbose mode by passing "verbose=True" to testmod, or prohibit 40e1f365035a952233463d85d659bd960ba78f012eJens Axboeit by passing "verbose=False". In either of those cases, sys.argv is not 41e1f365035a952233463d85d659bd960ba78f012eJens Axboeexamined by testmod. 42ee738499877bb1ee913e839cb4a8d4edad2d52adJens Axboe 4303b74b3ec5268e731ed7fcaef31c8c0655acd530Jens AxboeIn any case, testmod returns a 2-tuple of ints (f, t), where f is the 44ee738499877bb1ee913e839cb4a8d4edad2d52adJens Axboenumber of docstring examples that failed and t is the total number of 45ee738499877bb1ee913e839cb4a8d4edad2d52adJens Axboedocstring examples attempted. 46e1f365035a952233463d85d659bd960ba78f012eJens Axboe 47f90eff5a414f6e8c16a51c3a7d9b5e077ab49aacJens AxboeThere are a variety of other ways to run doctests, including integration 48f90eff5a414f6e8c16a51c3a7d9b5e077ab49aacJens Axboewith the unittest framework, and support for running non-Python text 4902c6aad501477833c7e017eec0bb14f8e6957b68Jens Axboefiles containing doctests. There are also many ways to override parts 50ee738499877bb1ee913e839cb4a8d4edad2d52adJens Axboeof doctest's default behaviors. See the Library Reference Manual for 5163f29372bc1bd69b66816c96d88b9c0bd8f3d8b9Jens Axboedetails. 52833491908a1afd67d27ce79257de3a4d80143d9fYu-ju Hong 53833491908a1afd67d27ce79257de3a4d80143d9fYu-ju Hong 5420eb06bd2aef37fa8dd314a110bb81c733115e15Jens AxboeWHICH DOCSTRINGS ARE EXAMINED? 55833491908a1afd67d27ce79257de3a4d80143d9fYu-ju Hong 5676a43db448f9fd5e9f1397428a433466d98e0d5dJens Axboe+ M.__doc__. 573b8b7135602a4d3a7132fee10da9c1203ab643adJens Axboe 58ee738499877bb1ee913e839cb4a8d4edad2d52adJens Axboe+ f.__doc__ for all functions f in M.__dict__.values(), except those 59ee738499877bb1ee913e839cb4a8d4edad2d52adJens Axboe defined in other modules. 60ee738499877bb1ee913e839cb4a8d4edad2d52adJens Axboe 61f5b6bb85364fcb8b2ac8d922ca65afd9dfabc9bbJens Axboe+ C.__doc__ for all classes C in M.__dict__.values(), except those 62afdf935261b23cdf08214e708133318548ddf2c4Jens Axboe defined in other modules. 63d71c154c8b20a7ddca645d9854e640563f1b79c7Jens Axboe 6470a4c0c8417bba7c2e1e9a384b9acf226f5b9782Jens Axboe+ If M.__test__ exists and "is true", it must be a dict, and 6507b3232de97ac32a873f0b5d17c8f49c18ed3ae7Jens Axboe each entry maps a (string) name to a function object, class object, or 66c9c63318734feb94eae3013fa1b606d6da744655Jens Axboe string. Function and class object docstrings found from M.__test__ 67e1f365035a952233463d85d659bd960ba78f012eJens Axboe are searched, and strings are searched directly as if they were docstrings. 68e1f365035a952233463d85d659bd960ba78f012eJens Axboe In output, a key K in M.__test__ appears with name 69e1f365035a952233463d85d659bd960ba78f012eJens Axboe <name of M>.__test__.K 70e1f365035a952233463d85d659bd960ba78f012eJens Axboe 71de890a1e48d40238dac69f302708dde8719de240Steven LangAny classes found are recursively searched similarly, to test docstrings in 723b8b7135602a4d3a7132fee10da9c1203ab643adJens Axboetheir contained methods and nested classes. 7307b3232de97ac32a873f0b5d17c8f49c18ed3ae7Jens Axboe 7407b3232de97ac32a873f0b5d17c8f49c18ed3ae7Jens Axboe 75ee738499877bb1ee913e839cb4a8d4edad2d52adJens AxboeWHAT'S THE EXECUTION CONTEXT? 769f988e2ebb3bff7087cc9681a54bd7f0d0e42140Jens Axboe 7713335ddb0e304efa0fc96593dd1fd995ec6f68d7Jens AxboeBy default, each time testmod finds a docstring to test, it uses a *copy* 787e356b2dee2e86f3684424fc6e903f1ef9f00ef4Jens Axboeof M's globals (so that running tests on a module doesn't change the 79e1f365035a952233463d85d659bd960ba78f012eJens Axboemodule's real globals, and so that one test in M can't leave behind crumbs 80e1f365035a952233463d85d659bd960ba78f012eJens Axboethat accidentally allow another test to work). This means examples can 81e1f365035a952233463d85d659bd960ba78f012eJens Axboefreely use any names defined at top-level in M. It also means that sloppy 826925dd356191bc40e8a1ebc8fd92a40b476658c3Jens Axboeimports (see above) can cause examples in external docstrings to use 839af4a24408ea7d4cea084a4fe214b81145cc36acJens Axboeglobals inappropriate for them. 84e1f365035a952233463d85d659bd960ba78f012eJens Axboe 85e1f365035a952233463d85d659bd960ba78f012eJens AxboeYou can force use of your own dict as the execution context by passing 86e1f365035a952233463d85d659bd960ba78f012eJens Axboe"globs=your_dict" to testmod instead. Presumably this would be a copy of 87e1f365035a952233463d85d659bd960ba78f012eJens AxboeM.__dict__ merged with the globals from other imported modules. 88b46928282e0a890f49250e79b81af773a2b7108fJens Axboe 8963f29372bc1bd69b66816c96d88b9c0bd8f3d8b9Jens Axboe 9063f29372bc1bd69b66816c96d88b9c0bd8f3d8b9Jens AxboeWHAT ABOUT EXCEPTIONS? 91e1f365035a952233463d85d659bd960ba78f012eJens Axboe 92e1f365035a952233463d85d659bd960ba78f012eJens AxboeNo problem, as long as the only output generated by the example is the 93e1f365035a952233463d85d659bd960ba78f012eJens Axboetraceback itself. For example: 94e1f365035a952233463d85d659bd960ba78f012eJens Axboe 950e9f7fac2a501f2baeedd11446e9fe102720c27dJens Axboe >>> [1, 2, 3].remove(42) 960e9f7fac2a501f2baeedd11446e9fe102720c27dJens Axboe Traceback (most recent call last): 970e9f7fac2a501f2baeedd11446e9fe102720c27dJens Axboe File "<stdin>", line 1, in ? 980e9f7fac2a501f2baeedd11446e9fe102720c27dJens Axboe ValueError: list.remove(x): x not in list 990e9f7fac2a501f2baeedd11446e9fe102720c27dJens Axboe >>> 1000e9f7fac2a501f2baeedd11446e9fe102720c27dJens Axboe 1010e9f7fac2a501f2baeedd11446e9fe102720c27dJens AxboeNote that only the exception type and value are compared. 1027bb591020669b7266c57108f2a68b48a03ae72eeJens Axboe 1037bb591020669b7266c57108f2a68b48a03ae72eeJens Axboe 1047bb591020669b7266c57108f2a68b48a03ae72eeJens AxboeSO WHAT DOES A DOCTEST EXAMPLE LOOK LIKE ALREADY!? 1057bb591020669b7266c57108f2a68b48a03ae72eeJens Axboe 1067bb591020669b7266c57108f2a68b48a03ae72eeJens AxboeOh ya. It's easy! In most cases a copy-and-paste of an interactive 107e1f365035a952233463d85d659bd960ba78f012eJens Axboeconsole session works fine -- just make sure the leading whitespace is 108rigidly consistent (you can mix tabs and spaces if you're too lazy to do it 109right, but doctest is not in the business of guessing what you think a tab 110means). 111 112 >>> # comments are ignored 113 >>> x = 12 114 >>> x 115 12 116 >>> if x == 13: 117 ... print "yes" 118 ... else: 119 ... print "no" 120 ... print "NO" 121 ... print "NO!!!" 122 ... 123 no 124 NO 125 NO!!! 126 >>> 127 128Any expected output must immediately follow the final ">>>" or "..." line 129containing the code, and the expected output (if any) extends to the next 130">>>" or all-whitespace line. That's it. 131 132Bummers: 133 134+ Output to stdout is captured, but not output to stderr (exception 135 tracebacks are captured via a different means). 136 137+ If you continue a line via backslashing in an interactive session, 138 or for any other reason use a backslash, you should use a raw 139 docstring, which will preserve your backslahses exactly as you type 140 them: 141 142 >>> def f(x): 143 ... r'''Backslashes in a raw docstring: m\n''' 144 >>> print f.__doc__ 145 Backslashes in a raw docstring: m\n 146 147 Otherwise, the backslash will be interpreted as part of the string. 148 E.g., the "\n" above would be interpreted as a newline character. 149 Alternatively, you can double each backslash in the doctest version 150 (and not use a raw string): 151 152 >>> def f(x): 153 ... '''Backslashes in a raw docstring: m\\n''' 154 >>> print f.__doc__ 155 Backslashes in a raw docstring: m\n 156 157The starting column doesn't matter: 158 159>>> assert "Easy!" 160 >>> import math 161 >>> math.floor(1.9) 162 1.0 163 164and as many leading whitespace characters are stripped from the expected 165output as appeared in the initial ">>>" line that triggered it. 166 167If you execute this very file, the examples above will be found and 168executed. 169""" 170 171__all__ = [ 172 'is_private', 173 'Example', 174 'DocTest', 175 'DocTestFinder', 176 'DocTestRunner', 177 'testmod', 178 'run_docstring_examples', 179 'Tester', 180 'DocTestCase', 181 'DocTestSuite', 182 'testsource', 183 'debug', 184# 'master', 185] 186 187import __future__ 188 189import sys, traceback, inspect, linecache, os, re, types 190import unittest, difflib, pdb, tempfile 191import warnings 192from StringIO import StringIO 193 194real_pdb_set_trace = pdb.set_trace 195 196# Option constants. 197DONT_ACCEPT_TRUE_FOR_1 = 1 << 0 198DONT_ACCEPT_BLANKLINE = 1 << 1 199NORMALIZE_WHITESPACE = 1 << 2 200ELLIPSIS = 1 << 3 201UNIFIED_DIFF = 1 << 4 202CONTEXT_DIFF = 1 << 5 203 204OPTIONFLAGS_BY_NAME = { 205 'DONT_ACCEPT_TRUE_FOR_1': DONT_ACCEPT_TRUE_FOR_1, 206 'DONT_ACCEPT_BLANKLINE': DONT_ACCEPT_BLANKLINE, 207 'NORMALIZE_WHITESPACE': NORMALIZE_WHITESPACE, 208 'ELLIPSIS': ELLIPSIS, 209 'UNIFIED_DIFF': UNIFIED_DIFF, 210 'CONTEXT_DIFF': CONTEXT_DIFF, 211 } 212 213# Special string markers for use in `want` strings: 214BLANKLINE_MARKER = '<BLANKLINE>' 215ELLIPSIS_MARKER = '...' 216 217 218# There are 4 basic classes: 219# - Example: a <source, want> pair, plus an intra-docstring line number. 220# - DocTest: a collection of examples, parsed from a docstring, plus 221# info about where the docstring came from (name, filename, lineno). 222# - DocTestFinder: extracts DocTests from a given object's docstring and 223# its contained objects' docstrings. 224# - DocTestRunner: runs DocTest cases, and accumulates statistics. 225# 226# So the basic picture is: 227# 228# list of: 229# +------+ +---------+ +-------+ 230# |object| --DocTestFinder-> | DocTest | --DocTestRunner-> |results| 231# +------+ +---------+ +-------+ 232# | Example | 233# | ... | 234# | Example | 235# +---------+ 236 237###################################################################### 238## Table of Contents 239###################################################################### 240# 1. Utility Functions 241# 2. Example & DocTest -- store test cases 242# 3. DocTest Parser -- extracts examples from strings 243# 4. DocTest Finder -- extracts test cases from objects 244# 5. DocTest Runner -- runs test cases 245# 6. Test Functions -- convenient wrappers for testing 246# 7. Tester Class -- for backwards compatibility 247# 8. Unittest Support 248# 9. Debugging Support 249# 10. Example Usage 250 251###################################################################### 252## 1. Utility Functions 253###################################################################### 254 255def is_private(prefix, base): 256 """prefix, base -> true iff name prefix + "." + base is "private". 257 258 Prefix may be an empty string, and base does not contain a period. 259 Prefix is ignored (although functions you write conforming to this 260 protocol may make use of it). 261 Return true iff base begins with an (at least one) underscore, but 262 does not both begin and end with (at least) two underscores. 263 264 >>> warnings.filterwarnings("ignore", "is_private", DeprecationWarning, 265 ... "doctest", 0) 266 >>> is_private("a.b", "my_func") 267 False 268 >>> is_private("____", "_my_func") 269 True 270 >>> is_private("someclass", "__init__") 271 False 272 >>> is_private("sometypo", "__init_") 273 True 274 >>> is_private("x.y.z", "_") 275 True 276 >>> is_private("_x.y.z", "__") 277 False 278 >>> is_private("", "") # senseless but consistent 279 False 280 """ 281 warnings.warn("is_private is deprecated; it wasn't useful; " 282 "examine DocTestFinder.find() lists instead", 283 DeprecationWarning, stacklevel=2) 284 return base[:1] == "_" and not base[:2] == "__" == base[-2:] 285 286def _extract_future_flags(globs): 287 """ 288 Return the compiler-flags associated with the future features that 289 have been imported into the given namespace (globs). 290 """ 291 flags = 0 292 for fname in __future__.all_feature_names: 293 feature = globs.get(fname, None) 294 if feature is getattr(__future__, fname): 295 flags |= feature.compiler_flag 296 return flags 297 298def _normalize_module(module, depth=2): 299 """ 300 Return the module specified by `module`. In particular: 301 - If `module` is a module, then return module. 302 - If `module` is a string, then import and return the 303 module with that name. 304 - If `module` is None, then return the calling module. 305 The calling module is assumed to be the module of 306 the stack frame at the given depth in the call stack. 307 """ 308 if inspect.ismodule(module): 309 return module 310 elif isinstance(module, (str, unicode)): 311 return __import__(module, globals(), locals(), ["*"]) 312 elif module is None: 313 return sys.modules[sys._getframe(depth).f_globals['__name__']] 314 else: 315 raise TypeError("Expected a module, string, or None") 316 317def _tag_msg(tag, msg, indent=' '): 318 """ 319 Return a string that displays a tag-and-message pair nicely, 320 keeping the tag and its message on the same line when that 321 makes sense. If the message is displayed on separate lines, 322 then `indent` is added to the beginning of each line. 323 """ 324 # If the message doesn't end in a newline, then add one. 325 if msg[-1:] != '\n': 326 msg += '\n' 327 # If the message is short enough, and contains no internal 328 # newlines, then display it on the same line as the tag. 329 # Otherwise, display the tag on its own line. 330 if (len(tag) + len(msg) < 75 and 331 msg.find('\n', 0, len(msg)-1) == -1): 332 return '%s: %s' % (tag, msg) 333 else: 334 msg = '\n'.join([indent+l for l in msg[:-1].split('\n')]) 335 return '%s:\n%s\n' % (tag, msg) 336 337# Override some StringIO methods. 338class _SpoofOut(StringIO): 339 def getvalue(self): 340 result = StringIO.getvalue(self) 341 # If anything at all was written, make sure there's a trailing 342 # newline. There's no way for the expected output to indicate 343 # that a trailing newline is missing. 344 if result and not result.endswith("\n"): 345 result += "\n" 346 # Prevent softspace from screwing up the next test case, in 347 # case they used print with a trailing comma in an example. 348 if hasattr(self, "softspace"): 349 del self.softspace 350 return result 351 352 def truncate(self, size=None): 353 StringIO.truncate(self, size) 354 if hasattr(self, "softspace"): 355 del self.softspace 356 357###################################################################### 358## 2. Example & DocTest 359###################################################################### 360## - An "example" is a <source, want> pair, where "source" is a 361## fragment of source code, and "want" is the expected output for 362## "source." The Example class also includes information about 363## where the example was extracted from. 364## 365## - A "doctest" is a collection of examples, typically extracted from 366## a string (such as an object's docstring). The DocTest class also 367## includes information about where the string was extracted from. 368 369class Example: 370 """ 371 A single doctest example, consisting of source code and expected 372 output. `Example` defines the following attributes: 373 374 - source: A single Python statement, always ending with a newline. 375 The constructor adds a newline if needed. 376 377 - want: The expected output from running the source code (either 378 from stdout, or a traceback in case of exception). `want` ends 379 with a newline unless it's empty, in which case it's an empty 380 string. The constructor adds a newline if needed. 381 382 - lineno: The line number within the DocTest string containing 383 this Example where the Example begins. This line number is 384 zero-based, with respect to the beginning of the DocTest. 385 """ 386 def __init__(self, source, want, lineno): 387 # Normalize inputs. 388 if not source.endswith('\n'): 389 source += '\n' 390 if want and not want.endswith('\n'): 391 want += '\n' 392 # Store properties. 393 self.source = source 394 self.want = want 395 self.lineno = lineno 396 397class DocTest: 398 """ 399 A collection of doctest examples that should be run in a single 400 namespace. Each `DocTest` defines the following attributes: 401 402 - examples: the list of examples. 403 404 - globs: The namespace (aka globals) that the examples should 405 be run in. 406 407 - name: A name identifying the DocTest (typically, the name of 408 the object whose docstring this DocTest was extracted from). 409 410 - filename: The name of the file that this DocTest was extracted 411 from, or `None` if the filename is unknown. 412 413 - lineno: The line number within filename where this DocTest 414 begins, or `None` if the line number is unavailable. This 415 line number is zero-based, with respect to the beginning of 416 the file. 417 418 - docstring: The string that the examples were extracted from, 419 or `None` if the string is unavailable. 420 """ 421 def __init__(self, examples, globs, name, filename, lineno, docstring): 422 """ 423 Create a new DocTest containing the given examples. The 424 DocTest's globals are initialized with a copy of `globs`. 425 """ 426 assert not isinstance(examples, basestring), \ 427 "DocTest no longer accepts str; use DocTestParser instead" 428 self.examples = examples 429 self.docstring = docstring 430 self.globs = globs.copy() 431 self.name = name 432 self.filename = filename 433 self.lineno = lineno 434 435 def __repr__(self): 436 if len(self.examples) == 0: 437 examples = 'no examples' 438 elif len(self.examples) == 1: 439 examples = '1 example' 440 else: 441 examples = '%d examples' % len(self.examples) 442 return ('<DocTest %s from %s:%s (%s)>' % 443 (self.name, self.filename, self.lineno, examples)) 444 445 446 # This lets us sort tests by name: 447 def __cmp__(self, other): 448 if not isinstance(other, DocTest): 449 return -1 450 return cmp((self.name, self.filename, self.lineno, id(self)), 451 (other.name, other.filename, other.lineno, id(other))) 452 453###################################################################### 454## 2. DocTestParser 455###################################################################### 456 457class DocTestParser: 458 """ 459 A class used to parse strings containing doctest examples. 460 """ 461 _EXAMPLE_RE = re.compile(r''' 462 # Source consists of a PS1 line followed by zero or more PS2 lines. 463 (?P<source> 464 (?:^(?P<indent> [ ]*) >>> .*) # PS1 line 465 (?:\n [ ]* \.\.\. .*)*) # PS2 lines 466 \n? 467 # Want consists of any non-blank lines that do not start with PS1. 468 (?P<want> (?:(?![ ]*$) # Not a blank line 469 (?![ ]*>>>) # Not a line starting with PS1 470 .*$\n? # But any other line 471 )*) 472 ''', re.MULTILINE | re.VERBOSE) 473 _IS_BLANK_OR_COMMENT = re.compile('^[ ]*(#.*)?$').match 474 475 def get_doctest(self, string, globs, name, filename, lineno): 476 """ 477 Extract all doctest examples from the given string, and 478 collect them into a `DocTest` object. 479 480 `globs`, `name`, `filename`, and `lineno` are attributes for 481 the new `DocTest` object. See the documentation for `DocTest` 482 for more information. 483 """ 484 return DocTest(self.get_examples(string, name), globs, 485 name, filename, lineno, string) 486 487 def get_examples(self, string, name='<string>'): 488 """ 489 Extract all doctest examples from the given string, and return 490 them as a list of `Example` objects. Line numbers are 491 0-based, because it's most common in doctests that nothing 492 interesting appears on the same line as opening triple-quote, 493 and so the first interesting line is called \"line 1\" then. 494 495 The optional argument `name` is a name identifying this 496 string, and is only used for error messages. 497 498 >>> text = ''' 499 ... >>> x, y = 2, 3 # no output expected 500 ... >>> if 1: 501 ... ... print x 502 ... ... print y 503 ... 2 504 ... 3 505 ... 506 ... Some text. 507 ... >>> x+y 508 ... 5 509 ... ''' 510 >>> for x in DocTestParser().get_examples(text): 511 ... print (x.source, x.want, x.lineno) 512 ('x, y = 2, 3 # no output expected\\n', '', 1) 513 ('if 1:\\n print x\\n print y\\n', '2\\n3\\n', 2) 514 ('x+y\\n', '5\\n', 9) 515 """ 516 examples = [] 517 charno, lineno = 0, 0 518 # Find all doctest examples in the string: 519 for m in self._EXAMPLE_RE.finditer(string.expandtabs()): 520 # Update lineno (lines before this example) 521 lineno += string.count('\n', charno, m.start()) 522 523 # Extract source/want from the regexp match. 524 (source, want) = self._parse_example(m, name, lineno) 525 if self._IS_BLANK_OR_COMMENT(source): 526 continue 527 examples.append( Example(source, want, lineno) ) 528 529 # Update lineno (lines inside this example) 530 lineno += string.count('\n', m.start(), m.end()) 531 # Update charno. 532 charno = m.end() 533 return examples 534 535 def get_program(self, string, name="<string>"): 536 """ 537 Return an executable program from the given string, as a string. 538 539 The format of this isn't rigidly defined. In general, doctest 540 examples become the executable statements in the result, and 541 their expected outputs become comments, preceded by an \"#Expected:\" 542 comment. Everything else (text, comments, everything not part of 543 a doctest test) is also placed in comments. 544 545 The optional argument `name` is a name identifying this 546 string, and is only used for error messages. 547 548 >>> text = ''' 549 ... >>> x, y = 2, 3 # no output expected 550 ... >>> if 1: 551 ... ... print x 552 ... ... print y 553 ... 2 554 ... 3 555 ... 556 ... Some text. 557 ... >>> x+y 558 ... 5 559 ... ''' 560 >>> print DocTestParser().get_program(text) 561 x, y = 2, 3 # no output expected 562 if 1: 563 print x 564 print y 565 # Expected: 566 # 2 567 # 3 568 # 569 # Some text. 570 x+y 571 # Expected: 572 # 5 573 """ 574 output = [] 575 charnum, lineno = 0, 0 576 # Find all doctest examples in the string: 577 for m in self._EXAMPLE_RE.finditer(string.expandtabs()): 578 # Add any text before this example, as a comment. 579 if m.start() > charnum: 580 lines = string[charnum:m.start()-1].split('\n') 581 output.extend([self._comment_line(l) for l in lines]) 582 lineno += len(lines) 583 584 # Extract source/want from the regexp match. 585 (source, want) = self._parse_example(m, name, lineno, False) 586 # Display the source 587 output.append(source) 588 # Display the expected output, if any 589 if want: 590 output.append('# Expected:') 591 output.extend(['# '+l for l in want.split('\n')]) 592 593 # Update the line number & char number. 594 lineno += string.count('\n', m.start(), m.end()) 595 charnum = m.end() 596 # Add any remaining text, as comments. 597 output.extend([self._comment_line(l) 598 for l in string[charnum:].split('\n')]) 599 # Trim junk on both ends. 600 while output and output[-1] == '#': 601 output.pop() 602 while output and output[0] == '#': 603 output.pop(0) 604 # Combine the output, and return it. 605 return '\n'.join(output) 606 607 def _parse_example(self, m, name, lineno, add_newlines=True): 608 # Get the example's indentation level. 609 indent = len(m.group('indent')) 610 611 # Divide source into lines; check that they're properly 612 # indented; and then strip their indentation & prompts. 613 source_lines = m.group('source').split('\n') 614 self._check_prompt_blank(source_lines, indent, name, lineno) 615 self._check_prefix(source_lines[1:], ' '*indent+'.', name, lineno) 616 source = '\n'.join([sl[indent+4:] for sl in source_lines]) 617 if len(source_lines) > 1 and add_newlines: 618 source += '\n' 619 620 # Divide want into lines; check that it's properly 621 # indented; and then strip the indentation. 622 want_lines = m.group('want').rstrip().split('\n') 623 self._check_prefix(want_lines, ' '*indent, name, 624 lineno+len(source_lines)) 625 want = '\n'.join([wl[indent:] for wl in want_lines]) 626 if len(want) > 0 and add_newlines: 627 want += '\n' 628 629 return source, want 630 631 def _comment_line(self, line): 632 line = line.rstrip() 633 if line: 634 return '# '+line 635 else: 636 return '#' 637 638 def _check_prompt_blank(self, lines, indent, name, lineno): 639 for i, line in enumerate(lines): 640 if len(line) >= indent+4 and line[indent+3] != ' ': 641 raise ValueError('line %r of the docstring for %s ' 642 'lacks blank after %s: %r' % 643 (lineno+i+1, name, 644 line[indent:indent+3], line)) 645 646 def _check_prefix(self, lines, prefix, name, lineno): 647 for i, line in enumerate(lines): 648 if line and not line.startswith(prefix): 649 raise ValueError('line %r of the docstring for %s has ' 650 'inconsistent leading whitespace: %r' % 651 (lineno+i+1, name, line)) 652 653 654###################################################################### 655## 4. DocTest Finder 656###################################################################### 657 658class DocTestFinder: 659 """ 660 A class used to extract the DocTests that are relevant to a given 661 object, from its docstring and the docstrings of its contained 662 objects. Doctests can currently be extracted from the following 663 object types: modules, functions, classes, methods, staticmethods, 664 classmethods, and properties. 665 """ 666 667 def __init__(self, verbose=False, parser=DocTestParser(), 668 recurse=True, _namefilter=None): 669 """ 670 Create a new doctest finder. 671 672 The optional argument `parser` specifies a class or 673 function that should be used to create new DocTest objects (or 674 objects that implement the same interface as DocTest). The 675 signature for this factory function should match the signature 676 of the DocTest constructor. 677 678 If the optional argument `recurse` is false, then `find` will 679 only examine the given object, and not any contained objects. 680 """ 681 self._parser = parser 682 self._verbose = verbose 683 self._recurse = recurse 684 # _namefilter is undocumented, and exists only for temporary backward- 685 # compatibility support of testmod's deprecated isprivate mess. 686 self._namefilter = _namefilter 687 688 def find(self, obj, name=None, module=None, globs=None, 689 extraglobs=None): 690 """ 691 Return a list of the DocTests that are defined by the given 692 object's docstring, or by any of its contained objects' 693 docstrings. 694 695 The optional parameter `module` is the module that contains 696 the given object. If the module is not specified or is None, then 697 the test finder will attempt to automatically determine the 698 correct module. The object's module is used: 699 700 - As a default namespace, if `globs` is not specified. 701 - To prevent the DocTestFinder from extracting DocTests 702 from objects that are imported from other modules. 703 - To find the name of the file containing the object. 704 - To help find the line number of the object within its 705 file. 706 707 Contained objects whose module does not match `module` are ignored. 708 709 If `module` is False, no attempt to find the module will be made. 710 This is obscure, of use mostly in tests: if `module` is False, or 711 is None but cannot be found automatically, then all objects are 712 considered to belong to the (non-existent) module, so all contained 713 objects will (recursively) be searched for doctests. 714 715 The globals for each DocTest is formed by combining `globs` 716 and `extraglobs` (bindings in `extraglobs` override bindings 717 in `globs`). A new copy of the globals dictionary is created 718 for each DocTest. If `globs` is not specified, then it 719 defaults to the module's `__dict__`, if specified, or {} 720 otherwise. If `extraglobs` is not specified, then it defaults 721 to {}. 722 723 """ 724 # If name was not specified, then extract it from the object. 725 if name is None: 726 name = getattr(obj, '__name__', None) 727 if name is None: 728 raise ValueError("DocTestFinder.find: name must be given " 729 "when obj.__name__ doesn't exist: %r" % 730 (type(obj),)) 731 732 # Find the module that contains the given object (if obj is 733 # a module, then module=obj.). Note: this may fail, in which 734 # case module will be None. 735 if module is False: 736 module = None 737 elif module is None: 738 module = inspect.getmodule(obj) 739 740 # Read the module's source code. This is used by 741 # DocTestFinder._find_lineno to find the line number for a 742 # given object's docstring. 743 try: 744 file = inspect.getsourcefile(obj) or inspect.getfile(obj) 745 source_lines = linecache.getlines(file) 746 if not source_lines: 747 source_lines = None 748 except TypeError: 749 source_lines = None 750 751 # Initialize globals, and merge in extraglobs. 752 if globs is None: 753 if module is None: 754 globs = {} 755 else: 756 globs = module.__dict__.copy() 757 else: 758 globs = globs.copy() 759 if extraglobs is not None: 760 globs.update(extraglobs) 761 762 # Recursively expore `obj`, extracting DocTests. 763 tests = [] 764 self._find(tests, obj, name, module, source_lines, globs, {}) 765 return tests 766 767 def _filter(self, obj, prefix, base): 768 """ 769 Return true if the given object should not be examined. 770 """ 771 return (self._namefilter is not None and 772 self._namefilter(prefix, base)) 773 774 def _from_module(self, module, object): 775 """ 776 Return true if the given object is defined in the given 777 module. 778 """ 779 if module is None: 780 return True 781 elif inspect.isfunction(object): 782 return module.__dict__ is object.func_globals 783 elif inspect.isclass(object): 784 return module.__name__ == object.__module__ 785 elif inspect.getmodule(object) is not None: 786 return module is inspect.getmodule(object) 787 elif hasattr(object, '__module__'): 788 return module.__name__ == object.__module__ 789 elif isinstance(object, property): 790 return True # [XX] no way not be sure. 791 else: 792 raise ValueError("object must be a class or function") 793 794 def _find(self, tests, obj, name, module, source_lines, globs, seen): 795 """ 796 Find tests for the given object and any contained objects, and 797 add them to `tests`. 798 """ 799 if self._verbose: 800 print 'Finding tests in %s' % name 801 802 # If we've already processed this object, then ignore it. 803 if id(obj) in seen: 804 return 805 seen[id(obj)] = 1 806 807 # Find a test for this object, and add it to the list of tests. 808 test = self._get_test(obj, name, module, globs, source_lines) 809 if test is not None: 810 tests.append(test) 811 812 # Look for tests in a module's contained objects. 813 if inspect.ismodule(obj) and self._recurse: 814 for valname, val in obj.__dict__.items(): 815 # Check if this contained object should be ignored. 816 if self._filter(val, name, valname): 817 continue 818 valname = '%s.%s' % (name, valname) 819 # Recurse to functions & classes. 820 if ((inspect.isfunction(val) or inspect.isclass(val)) and 821 self._from_module(module, val)): 822 self._find(tests, val, valname, module, source_lines, 823 globs, seen) 824 825 # Look for tests in a module's __test__ dictionary. 826 if inspect.ismodule(obj) and self._recurse: 827 for valname, val in getattr(obj, '__test__', {}).items(): 828 if not isinstance(valname, basestring): 829 raise ValueError("DocTestFinder.find: __test__ keys " 830 "must be strings: %r" % 831 (type(valname),)) 832 if not (inspect.isfunction(val) or inspect.isclass(val) or 833 inspect.ismethod(val) or inspect.ismodule(val) or 834 isinstance(val, basestring)): 835 raise ValueError("DocTestFinder.find: __test__ values " 836 "must be strings, functions, methods, " 837 "classes, or modules: %r" % 838 (type(val),)) 839 valname = '%s.%s' % (name, valname) 840 self._find(tests, val, valname, module, source_lines, 841 globs, seen) 842 843 # Look for tests in a class's contained objects. 844 if inspect.isclass(obj) and self._recurse: 845 for valname, val in obj.__dict__.items(): 846 # Check if this contained object should be ignored. 847 if self._filter(val, name, valname): 848 continue 849 # Special handling for staticmethod/classmethod. 850 if isinstance(val, staticmethod): 851 val = getattr(obj, valname) 852 if isinstance(val, classmethod): 853 val = getattr(obj, valname).im_func 854 855 # Recurse to methods, properties, and nested classes. 856 if ((inspect.isfunction(val) or inspect.isclass(val) or 857 isinstance(val, property)) and 858 self._from_module(module, val)): 859 valname = '%s.%s' % (name, valname) 860 self._find(tests, val, valname, module, source_lines, 861 globs, seen) 862 863 def _get_test(self, obj, name, module, globs, source_lines): 864 """ 865 Return a DocTest for the given object, if it defines a docstring; 866 otherwise, return None. 867 """ 868 # Extract the object's docstring. If it doesn't have one, 869 # then return None (no test for this object). 870 if isinstance(obj, basestring): 871 docstring = obj 872 else: 873 try: 874 if obj.__doc__ is None: 875 return None 876 docstring = str(obj.__doc__) 877 except (TypeError, AttributeError): 878 return None 879 880 # Don't bother if the docstring is empty. 881 if not docstring: 882 return None 883 884 # Find the docstring's location in the file. 885 lineno = self._find_lineno(obj, source_lines) 886 887 # Return a DocTest for this object. 888 if module is None: 889 filename = None 890 else: 891 filename = getattr(module, '__file__', module.__name__) 892 return self._parser.get_doctest(docstring, globs, name, 893 filename, lineno) 894 895 def _find_lineno(self, obj, source_lines): 896 """ 897 Return a line number of the given object's docstring. Note: 898 this method assumes that the object has a docstring. 899 """ 900 lineno = None 901 902 # Find the line number for modules. 903 if inspect.ismodule(obj): 904 lineno = 0 905 906 # Find the line number for classes. 907 # Note: this could be fooled if a class is defined multiple 908 # times in a single file. 909 if inspect.isclass(obj): 910 if source_lines is None: 911 return None 912 pat = re.compile(r'^\s*class\s*%s\b' % 913 getattr(obj, '__name__', '-')) 914 for i, line in enumerate(source_lines): 915 if pat.match(line): 916 lineno = i 917 break 918 919 # Find the line number for functions & methods. 920 if inspect.ismethod(obj): obj = obj.im_func 921 if inspect.isfunction(obj): obj = obj.func_code 922 if inspect.istraceback(obj): obj = obj.tb_frame 923 if inspect.isframe(obj): obj = obj.f_code 924 if inspect.iscode(obj): 925 lineno = getattr(obj, 'co_firstlineno', None)-1 926 927 # Find the line number where the docstring starts. Assume 928 # that it's the first line that begins with a quote mark. 929 # Note: this could be fooled by a multiline function 930 # signature, where a continuation line begins with a quote 931 # mark. 932 if lineno is not None: 933 if source_lines is None: 934 return lineno+1 935 pat = re.compile('(^|.*:)\s*\w*("|\')') 936 for lineno in range(lineno, len(source_lines)): 937 if pat.match(source_lines[lineno]): 938 return lineno 939 940 # We couldn't find the line number. 941 return None 942 943###################################################################### 944## 5. DocTest Runner 945###################################################################### 946 947class DocTestRunner: 948 """ 949 A class used to run DocTest test cases, and accumulate statistics. 950 The `run` method is used to process a single DocTest case. It 951 returns a tuple `(f, t)`, where `t` is the number of test cases 952 tried, and `f` is the number of test cases that failed. 953 954 >>> tests = DocTestFinder().find(_TestClass) 955 >>> runner = DocTestRunner(verbose=False) 956 >>> for test in tests: 957 ... print runner.run(test) 958 (0, 2) 959 (0, 1) 960 (0, 2) 961 (0, 2) 962 963 The `summarize` method prints a summary of all the test cases that 964 have been run by the runner, and returns an aggregated `(f, t)` 965 tuple: 966 967 >>> runner.summarize(verbose=1) 968 4 items passed all tests: 969 2 tests in _TestClass 970 2 tests in _TestClass.__init__ 971 2 tests in _TestClass.get 972 1 tests in _TestClass.square 973 7 tests in 4 items. 974 7 passed and 0 failed. 975 Test passed. 976 (0, 7) 977 978 The aggregated number of tried examples and failed examples is 979 also available via the `tries` and `failures` attributes: 980 981 >>> runner.tries 982 7 983 >>> runner.failures 984 0 985 986 The comparison between expected outputs and actual outputs is done 987 by an `OutputChecker`. This comparison may be customized with a 988 number of option flags; see the documentation for `testmod` for 989 more information. If the option flags are insufficient, then the 990 comparison may also be customized by passing a subclass of 991 `OutputChecker` to the constructor. 992 993 The test runner's display output can be controlled in two ways. 994 First, an output function (`out) can be passed to 995 `TestRunner.run`; this function will be called with strings that 996 should be displayed. It defaults to `sys.stdout.write`. If 997 capturing the output is not sufficient, then the display output 998 can be also customized by subclassing DocTestRunner, and 999 overriding the methods `report_start`, `report_success`, 1000 `report_unexpected_exception`, and `report_failure`. 1001 """ 1002 # This divider string is used to separate failure messages, and to 1003 # separate sections of the summary. 1004 DIVIDER = "*" * 70 1005 1006 def __init__(self, checker=None, verbose=None, optionflags=0): 1007 """ 1008 Create a new test runner. 1009 1010 Optional keyword arg `checker` is the `OutputChecker` that 1011 should be used to compare the expected outputs and actual 1012 outputs of doctest examples. 1013 1014 Optional keyword arg 'verbose' prints lots of stuff if true, 1015 only failures if false; by default, it's true iff '-v' is in 1016 sys.argv. 1017 1018 Optional argument `optionflags` can be used to control how the 1019 test runner compares expected output to actual output, and how 1020 it displays failures. See the documentation for `testmod` for 1021 more information. 1022 """ 1023 self._checker = checker or OutputChecker() 1024 if verbose is None: 1025 verbose = '-v' in sys.argv 1026 self._verbose = verbose 1027 self.optionflags = optionflags 1028 1029 # Keep track of the examples we've run. 1030 self.tries = 0 1031 self.failures = 0 1032 self._name2ft = {} 1033 1034 # Create a fake output target for capturing doctest output. 1035 self._fakeout = _SpoofOut() 1036 1037 #///////////////////////////////////////////////////////////////// 1038 # Reporting methods 1039 #///////////////////////////////////////////////////////////////// 1040 1041 def report_start(self, out, test, example): 1042 """ 1043 Report that the test runner is about to process the given 1044 example. (Only displays a message if verbose=True) 1045 """ 1046 if self._verbose: 1047 out(_tag_msg("Trying", example.source) + 1048 _tag_msg("Expecting", example.want or "nothing")) 1049 1050 def report_success(self, out, test, example, got): 1051 """ 1052 Report that the given example ran successfully. (Only 1053 displays a message if verbose=True) 1054 """ 1055 if self._verbose: 1056 out("ok\n") 1057 1058 def report_failure(self, out, test, example, got): 1059 """ 1060 Report that the given example failed. 1061 """ 1062 # Print an error message. 1063 out(self.__failure_header(test, example) + 1064 self._checker.output_difference(example.want, got, 1065 self.optionflags)) 1066 1067 def report_unexpected_exception(self, out, test, example, exc_info): 1068 """ 1069 Report that the given example raised an unexpected exception. 1070 """ 1071 # Get a traceback message. 1072 excout = StringIO() 1073 exc_type, exc_val, exc_tb = exc_info 1074 traceback.print_exception(exc_type, exc_val, exc_tb, file=excout) 1075 exception_tb = excout.getvalue() 1076 # Print an error message. 1077 out(self.__failure_header(test, example) + 1078 _tag_msg("Exception raised", exception_tb)) 1079 1080 def __failure_header(self, test, example): 1081 s = (self.DIVIDER + "\n" + 1082 _tag_msg("Failure in example", example.source)) 1083 if test.filename is None: 1084 # [XX] I'm not putting +1 here, to give the same output 1085 # as the old version. But I think it *should* go here. 1086 return s + ("from line #%s of %s\n" % 1087 (example.lineno, test.name)) 1088 elif test.lineno is None: 1089 return s + ("from line #%s of %s in %s\n" % 1090 (example.lineno+1, test.name, test.filename)) 1091 else: 1092 lineno = test.lineno+example.lineno+1 1093 return s + ("from line #%s of %s (%s)\n" % 1094 (lineno, test.filename, test.name)) 1095 1096 #///////////////////////////////////////////////////////////////// 1097 # DocTest Running 1098 #///////////////////////////////////////////////////////////////// 1099 1100 # A regular expression for handling `want` strings that contain 1101 # expected exceptions. It divides `want` into two pieces: the 1102 # pre-exception output (`out`) and the exception message (`exc`), 1103 # as generated by traceback.format_exception_only(). (I assume 1104 # that the exception_only message is the first non-indented line 1105 # starting with word characters after the "Traceback ...".) 1106 _EXCEPTION_RE = re.compile(('^(?P<out>.*)' 1107 '^(?P<hdr>Traceback \((?:%s|%s)\):)\s*$.*?' 1108 '^(?P<exc>\w+.*)') % 1109 ('most recent call last', 'innermost last'), 1110 re.MULTILINE | re.DOTALL) 1111 1112 _OPTION_DIRECTIVE_RE = re.compile('\s*doctest:\s*(?P<flags>[^#\n]*)') 1113 1114 def __handle_directive(self, example): 1115 """ 1116 Check if the given example is actually a directive to doctest 1117 (to turn an optionflag on or off); and if it is, then handle 1118 the directive. 1119 1120 Return true iff the example is actually a directive (and so 1121 should not be executed). 1122 1123 """ 1124 m = self._OPTION_DIRECTIVE_RE.match(example.source) 1125 if m is None: 1126 return False 1127 1128 for flag in m.group('flags').upper().split(): 1129 if (flag[:1] not in '+-' or 1130 flag[1:] not in OPTIONFLAGS_BY_NAME): 1131 raise ValueError('Bad doctest option directive: '+flag) 1132 if flag[0] == '+': 1133 self.optionflags |= OPTIONFLAGS_BY_NAME[flag[1:]] 1134 else: 1135 self.optionflags &= ~OPTIONFLAGS_BY_NAME[flag[1:]] 1136 return True 1137 1138 def __run(self, test, compileflags, out): 1139 """ 1140 Run the examples in `test`. Write the outcome of each example 1141 with one of the `DocTestRunner.report_*` methods, using the 1142 writer function `out`. `compileflags` is the set of compiler 1143 flags that should be used to execute examples. Return a tuple 1144 `(f, t)`, where `t` is the number of examples tried, and `f` 1145 is the number of examples that failed. The examples are run 1146 in the namespace `test.globs`. 1147 """ 1148 # Keep track of the number of failures and tries. 1149 failures = tries = 0 1150 1151 # Save the option flags (since option directives can be used 1152 # to modify them). 1153 original_optionflags = self.optionflags 1154 1155 # Process each example. 1156 for example in test.examples: 1157 # Check if it's an option directive. If it is, then handle 1158 # it, and go on to the next example. 1159 if self.__handle_directive(example): 1160 continue 1161 1162 # Record that we started this example. 1163 tries += 1 1164 self.report_start(out, test, example) 1165 1166 # Run the example in the given context (globs), and record 1167 # any exception that gets raised. (But don't intercept 1168 # keyboard interrupts.) 1169 try: 1170 # Don't blink! This is where the user's code gets run. 1171 exec compile(example.source, "<string>", "single", 1172 compileflags, 1) in test.globs 1173 exception = None 1174 except KeyboardInterrupt: 1175 raise 1176 except: 1177 exception = sys.exc_info() 1178 1179 got = self._fakeout.getvalue() # the actual output 1180 self._fakeout.truncate(0) 1181 1182 # If the example executed without raising any exceptions, 1183 # then verify its output and report its outcome. 1184 if exception is None: 1185 if self._checker.check_output(example.want, got, 1186 self.optionflags): 1187 self.report_success(out, test, example, got) 1188 else: 1189 self.report_failure(out, test, example, got) 1190 failures += 1 1191 1192 # If the example raised an exception, then check if it was 1193 # expected. 1194 else: 1195 exc_info = sys.exc_info() 1196 exc_msg = traceback.format_exception_only(*exc_info[:2])[-1] 1197 1198 # Search the `want` string for an exception. If we don't 1199 # find one, then report an unexpected exception. 1200 m = self._EXCEPTION_RE.match(example.want) 1201 if m is None: 1202 self.report_unexpected_exception(out, test, example, 1203 exc_info) 1204 failures += 1 1205 else: 1206 exc_hdr = m.group('hdr')+'\n' # Exception header 1207 # The test passes iff the pre-exception output and 1208 # the exception description match the values given 1209 # in `want`. 1210 if (self._checker.check_output(m.group('out'), got, 1211 self.optionflags) and 1212 self._checker.check_output(m.group('exc'), exc_msg, 1213 self.optionflags)): 1214 # Is +exc_msg the right thing here?? 1215 self.report_success(out, test, example, 1216 got+exc_hdr+exc_msg) 1217 else: 1218 self.report_failure(out, test, example, 1219 got+exc_hdr+exc_msg) 1220 failures += 1 1221 1222 # Restore the option flags (in case they were modified) 1223 self.optionflags = original_optionflags 1224 1225 # Record and return the number of failures and tries. 1226 self.__record_outcome(test, failures, tries) 1227 return failures, tries 1228 1229 def __record_outcome(self, test, f, t): 1230 """ 1231 Record the fact that the given DocTest (`test`) generated `f` 1232 failures out of `t` tried examples. 1233 """ 1234 f2, t2 = self._name2ft.get(test.name, (0,0)) 1235 self._name2ft[test.name] = (f+f2, t+t2) 1236 self.failures += f 1237 self.tries += t 1238 1239 def run(self, test, compileflags=None, out=None, clear_globs=True): 1240 """ 1241 Run the examples in `test`, and display the results using the 1242 writer function `out`. 1243 1244 The examples are run in the namespace `test.globs`. If 1245 `clear_globs` is true (the default), then this namespace will 1246 be cleared after the test runs, to help with garbage 1247 collection. If you would like to examine the namespace after 1248 the test completes, then use `clear_globs=False`. 1249 1250 `compileflags` gives the set of flags that should be used by 1251 the Python compiler when running the examples. If not 1252 specified, then it will default to the set of future-import 1253 flags that apply to `globs`. 1254 1255 The output of each example is checked using 1256 `DocTestRunner.check_output`, and the results are formatted by 1257 the `DocTestRunner.report_*` methods. 1258 """ 1259 if compileflags is None: 1260 compileflags = _extract_future_flags(test.globs) 1261 1262 save_stdout = sys.stdout 1263 if out is None: 1264 out = save_stdout.write 1265 sys.stdout = self._fakeout 1266 1267 # Patch pdb.set_trace to restore sys.stdout, so that interactive 1268 # debugging output is visible (not still redirected to self._fakeout). 1269 # Note that we run "the real" pdb.set_trace (captured at doctest 1270 # import time) in our replacement. Because the current run() may 1271 # run another doctest (and so on), the current pdb.set_trace may be 1272 # our set_trace function, which changes sys.stdout. If we called 1273 # a chain of those, we wouldn't be left with the save_stdout 1274 # *this* run() invocation wants. 1275 def set_trace(): 1276 sys.stdout = save_stdout 1277 real_pdb_set_trace() 1278 1279 save_set_trace = pdb.set_trace 1280 pdb.set_trace = set_trace 1281 try: 1282 return self.__run(test, compileflags, out) 1283 finally: 1284 sys.stdout = save_stdout 1285 pdb.set_trace = save_set_trace 1286 if clear_globs: 1287 test.globs.clear() 1288 1289 #///////////////////////////////////////////////////////////////// 1290 # Summarization 1291 #///////////////////////////////////////////////////////////////// 1292 def summarize(self, verbose=None): 1293 """ 1294 Print a summary of all the test cases that have been run by 1295 this DocTestRunner, and return a tuple `(f, t)`, where `f` is 1296 the total number of failed examples, and `t` is the total 1297 number of tried examples. 1298 1299 The optional `verbose` argument controls how detailed the 1300 summary is. If the verbosity is not specified, then the 1301 DocTestRunner's verbosity is used. 1302 """ 1303 if verbose is None: 1304 verbose = self._verbose 1305 notests = [] 1306 passed = [] 1307 failed = [] 1308 totalt = totalf = 0 1309 for x in self._name2ft.items(): 1310 name, (f, t) = x 1311 assert f <= t 1312 totalt += t 1313 totalf += f 1314 if t == 0: 1315 notests.append(name) 1316 elif f == 0: 1317 passed.append( (name, t) ) 1318 else: 1319 failed.append(x) 1320 if verbose: 1321 if notests: 1322 print len(notests), "items had no tests:" 1323 notests.sort() 1324 for thing in notests: 1325 print " ", thing 1326 if passed: 1327 print len(passed), "items passed all tests:" 1328 passed.sort() 1329 for thing, count in passed: 1330 print " %3d tests in %s" % (count, thing) 1331 if failed: 1332 print self.DIVIDER 1333 print len(failed), "items had failures:" 1334 failed.sort() 1335 for thing, (f, t) in failed: 1336 print " %3d of %3d in %s" % (f, t, thing) 1337 if verbose: 1338 print totalt, "tests in", len(self._name2ft), "items." 1339 print totalt - totalf, "passed and", totalf, "failed." 1340 if totalf: 1341 print "***Test Failed***", totalf, "failures." 1342 elif verbose: 1343 print "Test passed." 1344 return totalf, totalt 1345 1346class OutputChecker: 1347 """ 1348 A class used to check the whether the actual output from a doctest 1349 example matches the expected output. `OutputChecker` defines two 1350 methods: `check_output`, which compares a given pair of outputs, 1351 and returns true if they match; and `output_difference`, which 1352 returns a string describing the differences between two outputs. 1353 """ 1354 def check_output(self, want, got, optionflags): 1355 """ 1356 Return True iff the actual output (`got`) matches the expected 1357 output (`want`). These strings are always considered to match 1358 if they are identical; but depending on what option flags the 1359 test runner is using, several non-exact match types are also 1360 possible. See the documentation for `TestRunner` for more 1361 information about option flags. 1362 """ 1363 # Handle the common case first, for efficiency: 1364 # if they're string-identical, always return true. 1365 if got == want: 1366 return True 1367 1368 # The values True and False replaced 1 and 0 as the return 1369 # value for boolean comparisons in Python 2.3. 1370 if not (optionflags & DONT_ACCEPT_TRUE_FOR_1): 1371 if (got,want) == ("True\n", "1\n"): 1372 return True 1373 if (got,want) == ("False\n", "0\n"): 1374 return True 1375 1376 # <BLANKLINE> can be used as a special sequence to signify a 1377 # blank line, unless the DONT_ACCEPT_BLANKLINE flag is used. 1378 if not (optionflags & DONT_ACCEPT_BLANKLINE): 1379 # Replace <BLANKLINE> in want with a blank line. 1380 want = re.sub('(?m)^%s\s*?$' % re.escape(BLANKLINE_MARKER), 1381 '', want) 1382 # If a line in got contains only spaces, then remove the 1383 # spaces. 1384 got = re.sub('(?m)^\s*?$', '', got) 1385 if got == want: 1386 return True 1387 1388 # This flag causes doctest to ignore any differences in the 1389 # contents of whitespace strings. Note that this can be used 1390 # in conjunction with the ELLISPIS flag. 1391 if (optionflags & NORMALIZE_WHITESPACE): 1392 got = ' '.join(got.split()) 1393 want = ' '.join(want.split()) 1394 if got == want: 1395 return True 1396 1397 # The ELLIPSIS flag says to let the sequence "..." in `want` 1398 # match any substring in `got`. We implement this by 1399 # transforming `want` into a regular expression. 1400 if (optionflags & ELLIPSIS): 1401 # Escape any special regexp characters 1402 want_re = re.escape(want) 1403 # Replace ellipsis markers ('...') with .* 1404 want_re = want_re.replace(re.escape(ELLIPSIS_MARKER), '.*') 1405 # Require that it matches the entire string; and set the 1406 # re.DOTALL flag (with '(?s)'). 1407 want_re = '(?s)^%s$' % want_re 1408 # Check if the `want_re` regexp matches got. 1409 if re.match(want_re, got): 1410 return True 1411 1412 # We didn't find any match; return false. 1413 return False 1414 1415 def output_difference(self, want, got, optionflags): 1416 """ 1417 Return a string describing the differences between the 1418 expected output (`want`) and the actual output (`got`). 1419 """ 1420 # If <BLANKLINE>s are being used, then replace <BLANKLINE> 1421 # with blank lines in the expected output string. 1422 if not (optionflags & DONT_ACCEPT_BLANKLINE): 1423 want = re.sub('(?m)^%s$' % re.escape(BLANKLINE_MARKER), '', want) 1424 1425 # Check if we should use diff. Don't use diff if the actual 1426 # or expected outputs are too short, or if the expected output 1427 # contains an ellipsis marker. 1428 if ((optionflags & (UNIFIED_DIFF | CONTEXT_DIFF)) and 1429 want.count('\n') > 2 and got.count('\n') > 2 and 1430 not (optionflags & ELLIPSIS and '...' in want)): 1431 # Split want & got into lines. 1432 want_lines = [l+'\n' for l in want.split('\n')] 1433 got_lines = [l+'\n' for l in got.split('\n')] 1434 # Use difflib to find their differences. 1435 if optionflags & UNIFIED_DIFF: 1436 diff = difflib.unified_diff(want_lines, got_lines, n=2, 1437 fromfile='Expected', tofile='Got') 1438 kind = 'unified' 1439 elif optionflags & CONTEXT_DIFF: 1440 diff = difflib.context_diff(want_lines, got_lines, n=2, 1441 fromfile='Expected', tofile='Got') 1442 kind = 'context' 1443 else: 1444 assert 0, 'Bad diff option' 1445 # Remove trailing whitespace on diff output. 1446 diff = [line.rstrip() + '\n' for line in diff] 1447 return _tag_msg("Differences (" + kind + " diff)", 1448 ''.join(diff)) 1449 1450 # If we're not using diff, then simply list the expected 1451 # output followed by the actual output. 1452 return (_tag_msg("Expected", want or "Nothing") + 1453 _tag_msg("Got", got)) 1454 1455class DocTestFailure(Exception): 1456 """A DocTest example has failed in debugging mode. 1457 1458 The exception instance has variables: 1459 1460 - test: the DocTest object being run 1461 1462 - excample: the Example object that failed 1463 1464 - got: the actual output 1465 """ 1466 def __init__(self, test, example, got): 1467 self.test = test 1468 self.example = example 1469 self.got = got 1470 1471 def __str__(self): 1472 return str(self.test) 1473 1474class UnexpectedException(Exception): 1475 """A DocTest example has encountered an unexpected exception 1476 1477 The exception instance has variables: 1478 1479 - test: the DocTest object being run 1480 1481 - excample: the Example object that failed 1482 1483 - exc_info: the exception info 1484 """ 1485 def __init__(self, test, example, exc_info): 1486 self.test = test 1487 self.example = example 1488 self.exc_info = exc_info 1489 1490 def __str__(self): 1491 return str(self.test) 1492 1493class DebugRunner(DocTestRunner): 1494 r"""Run doc tests but raise an exception as soon as there is a failure. 1495 1496 If an unexpected exception occurs, an UnexpectedException is raised. 1497 It contains the test, the example, and the original exception: 1498 1499 >>> runner = DebugRunner(verbose=False) 1500 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42', 1501 ... {}, 'foo', 'foo.py', 0) 1502 >>> try: 1503 ... runner.run(test) 1504 ... except UnexpectedException, failure: 1505 ... pass 1506 1507 >>> failure.test is test 1508 True 1509 1510 >>> failure.example.want 1511 '42\n' 1512 1513 >>> exc_info = failure.exc_info 1514 >>> raise exc_info[0], exc_info[1], exc_info[2] 1515 Traceback (most recent call last): 1516 ... 1517 KeyError 1518 1519 We wrap the original exception to give the calling application 1520 access to the test and example information. 1521 1522 If the output doesn't match, then a DocTestFailure is raised: 1523 1524 >>> test = DocTestParser().get_doctest(''' 1525 ... >>> x = 1 1526 ... >>> x 1527 ... 2 1528 ... ''', {}, 'foo', 'foo.py', 0) 1529 1530 >>> try: 1531 ... runner.run(test) 1532 ... except DocTestFailure, failure: 1533 ... pass 1534 1535 DocTestFailure objects provide access to the test: 1536 1537 >>> failure.test is test 1538 True 1539 1540 As well as to the example: 1541 1542 >>> failure.example.want 1543 '2\n' 1544 1545 and the actual output: 1546 1547 >>> failure.got 1548 '1\n' 1549 1550 If a failure or error occurs, the globals are left intact: 1551 1552 >>> del test.globs['__builtins__'] 1553 >>> test.globs 1554 {'x': 1} 1555 1556 >>> test = DocTestParser().get_doctest(''' 1557 ... >>> x = 2 1558 ... >>> raise KeyError 1559 ... ''', {}, 'foo', 'foo.py', 0) 1560 1561 >>> runner.run(test) 1562 Traceback (most recent call last): 1563 ... 1564 UnexpectedException: <DocTest foo from foo.py:0 (2 examples)> 1565 1566 >>> del test.globs['__builtins__'] 1567 >>> test.globs 1568 {'x': 2} 1569 1570 But the globals are cleared if there is no error: 1571 1572 >>> test = DocTestParser().get_doctest(''' 1573 ... >>> x = 2 1574 ... ''', {}, 'foo', 'foo.py', 0) 1575 1576 >>> runner.run(test) 1577 (0, 1) 1578 1579 >>> test.globs 1580 {} 1581 1582 """ 1583 1584 def run(self, test, compileflags=None, out=None, clear_globs=True): 1585 r = DocTestRunner.run(self, test, compileflags, out, False) 1586 if clear_globs: 1587 test.globs.clear() 1588 return r 1589 1590 def report_unexpected_exception(self, out, test, example, exc_info): 1591 raise UnexpectedException(test, example, exc_info) 1592 1593 def report_failure(self, out, test, example, got): 1594 raise DocTestFailure(test, example, got) 1595 1596###################################################################### 1597## 6. Test Functions 1598###################################################################### 1599# These should be backwards compatible. 1600 1601def testmod(m=None, name=None, globs=None, verbose=None, isprivate=None, 1602 report=True, optionflags=0, extraglobs=None, 1603 raise_on_error=False): 1604 """m=None, name=None, globs=None, verbose=None, isprivate=None, 1605 report=True, optionflags=0, extraglobs=None 1606 1607 Test examples in docstrings in functions and classes reachable 1608 from module m (or the current module if m is not supplied), starting 1609 with m.__doc__. Unless isprivate is specified, private names 1610 are not skipped. 1611 1612 Also test examples reachable from dict m.__test__ if it exists and is 1613 not None. m.__dict__ maps names to functions, classes and strings; 1614 function and class docstrings are tested even if the name is private; 1615 strings are tested directly, as if they were docstrings. 1616 1617 Return (#failures, #tests). 1618 1619 See doctest.__doc__ for an overview. 1620 1621 Optional keyword arg "name" gives the name of the module; by default 1622 use m.__name__. 1623 1624 Optional keyword arg "globs" gives a dict to be used as the globals 1625 when executing examples; by default, use m.__dict__. A copy of this 1626 dict is actually used for each docstring, so that each docstring's 1627 examples start with a clean slate. 1628 1629 Optional keyword arg "extraglobs" gives a dictionary that should be 1630 merged into the globals that are used to execute examples. By 1631 default, no extra globals are used. This is new in 2.4. 1632 1633 Optional keyword arg "verbose" prints lots of stuff if true, prints 1634 only failures if false; by default, it's true iff "-v" is in sys.argv. 1635 1636 Optional keyword arg "report" prints a summary at the end when true, 1637 else prints nothing at the end. In verbose mode, the summary is 1638 detailed, else very brief (in fact, empty if all tests passed). 1639 1640 Optional keyword arg "optionflags" or's together module constants, 1641 and defaults to 0. This is new in 2.3. Possible values: 1642 1643 DONT_ACCEPT_TRUE_FOR_1 1644 By default, if an expected output block contains just "1", 1645 an actual output block containing just "True" is considered 1646 to be a match, and similarly for "0" versus "False". When 1647 DONT_ACCEPT_TRUE_FOR_1 is specified, neither substitution 1648 is allowed. 1649 1650 DONT_ACCEPT_BLANKLINE 1651 By default, if an expected output block contains a line 1652 containing only the string "<BLANKLINE>", then that line 1653 will match a blank line in the actual output. When 1654 DONT_ACCEPT_BLANKLINE is specified, this substitution is 1655 not allowed. 1656 1657 NORMALIZE_WHITESPACE 1658 When NORMALIZE_WHITESPACE is specified, all sequences of 1659 whitespace are treated as equal. I.e., any sequence of 1660 whitespace within the expected output will match any 1661 sequence of whitespace within the actual output. 1662 1663 ELLIPSIS 1664 When ELLIPSIS is specified, then an ellipsis marker 1665 ("...") in the expected output can match any substring in 1666 the actual output. 1667 1668 UNIFIED_DIFF 1669 When UNIFIED_DIFF is specified, failures that involve 1670 multi-line expected and actual outputs will be displayed 1671 using a unified diff. 1672 1673 CONTEXT_DIFF 1674 When CONTEXT_DIFF is specified, failures that involve 1675 multi-line expected and actual outputs will be displayed 1676 using a context diff. 1677 1678 Optional keyword arg "raise_on_error" raises an exception on the 1679 first unexpected exception or failure. This allows failures to be 1680 post-mortem debugged. 1681 1682 Deprecated in Python 2.4: 1683 Optional keyword arg "isprivate" specifies a function used to 1684 determine whether a name is private. The default function is 1685 treat all functions as public. Optionally, "isprivate" can be 1686 set to doctest.is_private to skip over functions marked as private 1687 using the underscore naming convention; see its docs for details. 1688 """ 1689 1690 """ [XX] This is no longer true: 1691 Advanced tomfoolery: testmod runs methods of a local instance of 1692 class doctest.Tester, then merges the results into (or creates) 1693 global Tester instance doctest.master. Methods of doctest.master 1694 can be called directly too, if you want to do something unusual. 1695 Passing report=0 to testmod is especially useful then, to delay 1696 displaying a summary. Invoke doctest.master.summarize(verbose) 1697 when you're done fiddling. 1698 """ 1699 if isprivate is not None: 1700 warnings.warn("the isprivate argument is deprecated; " 1701 "examine DocTestFinder.find() lists instead", 1702 DeprecationWarning) 1703 1704 # If no module was given, then use __main__. 1705 if m is None: 1706 # DWA - m will still be None if this wasn't invoked from the command 1707 # line, in which case the following TypeError is about as good an error 1708 # as we should expect 1709 m = sys.modules.get('__main__') 1710 1711 # Check that we were actually given a module. 1712 if not inspect.ismodule(m): 1713 raise TypeError("testmod: module required; %r" % (m,)) 1714 1715 # If no name was given, then use the module's name. 1716 if name is None: 1717 name = m.__name__ 1718 1719 # Find, parse, and run all tests in the given module. 1720 finder = DocTestFinder(_namefilter=isprivate) 1721 1722 if raise_on_error: 1723 runner = DebugRunner(verbose=verbose, optionflags=optionflags) 1724 else: 1725 runner = DocTestRunner(verbose=verbose, optionflags=optionflags) 1726 1727 for test in finder.find(m, name, globs=globs, extraglobs=extraglobs): 1728 runner.run(test) 1729 1730 if report: 1731 runner.summarize() 1732 1733 return runner.failures, runner.tries 1734 1735def run_docstring_examples(f, globs, verbose=False, name="NoName", 1736 compileflags=None, optionflags=0): 1737 """ 1738 Test examples in the given object's docstring (`f`), using `globs` 1739 as globals. Optional argument `name` is used in failure messages. 1740 If the optional argument `verbose` is true, then generate output 1741 even if there are no failures. 1742 1743 `compileflags` gives the set of flags that should be used by the 1744 Python compiler when running the examples. If not specified, then 1745 it will default to the set of future-import flags that apply to 1746 `globs`. 1747 1748 Optional keyword arg `optionflags` specifies options for the 1749 testing and output. See the documentation for `testmod` for more 1750 information. 1751 """ 1752 # Find, parse, and run all tests in the given module. 1753 finder = DocTestFinder(verbose=verbose, recurse=False) 1754 runner = DocTestRunner(verbose=verbose, optionflags=optionflags) 1755 for test in finder.find(f, name, globs=globs): 1756 runner.run(test, compileflags=compileflags) 1757 1758###################################################################### 1759## 7. Tester 1760###################################################################### 1761# This is provided only for backwards compatibility. It's not 1762# actually used in any way. 1763 1764class Tester: 1765 def __init__(self, mod=None, globs=None, verbose=None, 1766 isprivate=None, optionflags=0): 1767 1768 warnings.warn("class Tester is deprecated; " 1769 "use class doctest.DocTestRunner instead", 1770 DeprecationWarning, stacklevel=2) 1771 if mod is None and globs is None: 1772 raise TypeError("Tester.__init__: must specify mod or globs") 1773 if mod is not None and not _ismodule(mod): 1774 raise TypeError("Tester.__init__: mod must be a module; %r" % 1775 (mod,)) 1776 if globs is None: 1777 globs = mod.__dict__ 1778 self.globs = globs 1779 1780 self.verbose = verbose 1781 self.isprivate = isprivate 1782 self.optionflags = optionflags 1783 self.testfinder = DocTestFinder(_namefilter=isprivate) 1784 self.testrunner = DocTestRunner(verbose=verbose, 1785 optionflags=optionflags) 1786 1787 def runstring(self, s, name): 1788 test = DocTestParser().get_doctest(s, self.globs, name, None, None) 1789 if self.verbose: 1790 print "Running string", name 1791 (f,t) = self.testrunner.run(test) 1792 if self.verbose: 1793 print f, "of", t, "examples failed in string", name 1794 return (f,t) 1795 1796 def rundoc(self, object, name=None, module=None): 1797 f = t = 0 1798 tests = self.testfinder.find(object, name, module=module, 1799 globs=self.globs) 1800 for test in tests: 1801 (f2, t2) = self.testrunner.run(test) 1802 (f,t) = (f+f2, t+t2) 1803 return (f,t) 1804 1805 def rundict(self, d, name, module=None): 1806 import new 1807 m = new.module(name) 1808 m.__dict__.update(d) 1809 if module is None: 1810 module = False 1811 return self.rundoc(m, name, module) 1812 1813 def run__test__(self, d, name): 1814 import new 1815 m = new.module(name) 1816 m.__test__ = d 1817 return self.rundoc(m, name, module) 1818 1819 def summarize(self, verbose=None): 1820 return self.testrunner.summarize(verbose) 1821 1822 def merge(self, other): 1823 d = self.testrunner._name2ft 1824 for name, (f, t) in other.testrunner._name2ft.items(): 1825 if name in d: 1826 print "*** Tester.merge: '" + name + "' in both" \ 1827 " testers; summing outcomes." 1828 f2, t2 = d[name] 1829 f = f + f2 1830 t = t + t2 1831 d[name] = f, t 1832 1833###################################################################### 1834## 8. Unittest Support 1835###################################################################### 1836 1837class DocTestCase(unittest.TestCase): 1838 1839 def __init__(self, test, optionflags=0, setUp=None, tearDown=None, 1840 checker=None): 1841 unittest.TestCase.__init__(self) 1842 self._dt_optionflags = optionflags 1843 self._dt_checker = checker 1844 self._dt_test = test 1845 self._dt_setUp = setUp 1846 self._dt_tearDown = tearDown 1847 1848 def setUp(self): 1849 if self._dt_setUp is not None: 1850 self._dt_setUp() 1851 1852 def tearDown(self): 1853 if self._dt_tearDown is not None: 1854 self._dt_tearDown() 1855 1856 def runTest(self): 1857 test = self._dt_test 1858 old = sys.stdout 1859 new = StringIO() 1860 runner = DocTestRunner(optionflags=self._dt_optionflags, 1861 checker=self._dt_checker, verbose=False) 1862 1863 try: 1864 runner.DIVIDER = "-"*70 1865 failures, tries = runner.run(test, out=new.write) 1866 finally: 1867 sys.stdout = old 1868 1869 if failures: 1870 raise self.failureException(self.format_failure(new.getvalue())) 1871 1872 def format_failure(self, err): 1873 test = self._dt_test 1874 if test.lineno is None: 1875 lineno = 'unknown line number' 1876 else: 1877 lineno = 'line %s' % test.lineno 1878 lname = '.'.join(test.name.split('.')[-1:]) 1879 return ('Failed doctest test for %s\n' 1880 ' File "%s", line %s, in %s\n\n%s' 1881 % (test.name, test.filename, lineno, lname, err) 1882 ) 1883 1884 def debug(self): 1885 r"""Run the test case without results and without catching exceptions 1886 1887 The unit test framework includes a debug method on test cases 1888 and test suites to support post-mortem debugging. The test code 1889 is run in such a way that errors are not caught. This way a 1890 caller can catch the errors and initiate post-mortem debugging. 1891 1892 The DocTestCase provides a debug method that raises 1893 UnexpectedException errors if there is an unexepcted 1894 exception: 1895 1896 >>> test = DocTestParser().get_doctest('>>> raise KeyError\n42', 1897 ... {}, 'foo', 'foo.py', 0) 1898 >>> case = DocTestCase(test) 1899 >>> try: 1900 ... case.debug() 1901 ... except UnexpectedException, failure: 1902 ... pass 1903 1904 The UnexpectedException contains the test, the example, and 1905 the original exception: 1906 1907 >>> failure.test is test 1908 True 1909 1910 >>> failure.example.want 1911 '42\n' 1912 1913 >>> exc_info = failure.exc_info 1914 >>> raise exc_info[0], exc_info[1], exc_info[2] 1915 Traceback (most recent call last): 1916 ... 1917 KeyError 1918 1919 If the output doesn't match, then a DocTestFailure is raised: 1920 1921 >>> test = DocTestParser().get_doctest(''' 1922 ... >>> x = 1 1923 ... >>> x 1924 ... 2 1925 ... ''', {}, 'foo', 'foo.py', 0) 1926 >>> case = DocTestCase(test) 1927 1928 >>> try: 1929 ... case.debug() 1930 ... except DocTestFailure, failure: 1931 ... pass 1932 1933 DocTestFailure objects provide access to the test: 1934 1935 >>> failure.test is test 1936 True 1937 1938 As well as to the example: 1939 1940 >>> failure.example.want 1941 '2\n' 1942 1943 and the actual output: 1944 1945 >>> failure.got 1946 '1\n' 1947 1948 """ 1949 1950 runner = DebugRunner(optionflags=self._dt_optionflags, 1951 checker=self._dt_checker, verbose=False) 1952 runner.run(self._dt_test, out=nooutput) 1953 1954 def id(self): 1955 return self._dt_test.name 1956 1957 def __repr__(self): 1958 name = self._dt_test.name.split('.') 1959 return "%s (%s)" % (name[-1], '.'.join(name[:-1])) 1960 1961 __str__ = __repr__ 1962 1963 def shortDescription(self): 1964 return "Doctest: " + self._dt_test.name 1965 1966def nooutput(*args): 1967 pass 1968 1969def DocTestSuite(module=None, globs=None, extraglobs=None, 1970 optionflags=0, test_finder=None, 1971 setUp=lambda: None, tearDown=lambda: None, 1972 checker=None): 1973 """ 1974 Convert doctest tests for a mudule to a unittest test suite. 1975 1976 This converts each documentation string in a module that 1977 contains doctest tests to a unittest test case. If any of the 1978 tests in a doc string fail, then the test case fails. An exception 1979 is raised showing the name of the file containing the test and a 1980 (sometimes approximate) line number. 1981 1982 The `module` argument provides the module to be tested. The argument 1983 can be either a module or a module name. 1984 1985 If no argument is given, the calling module is used. 1986 """ 1987 1988 if test_finder is None: 1989 test_finder = DocTestFinder() 1990 1991 module = _normalize_module(module) 1992 tests = test_finder.find(module, globs=globs, extraglobs=extraglobs) 1993 if globs is None: 1994 globs = module.__dict__ 1995 if not tests: # [XX] why do we want to do this? 1996 raise ValueError(module, "has no tests") 1997 1998 tests.sort() 1999 suite = unittest.TestSuite() 2000 for test in tests: 2001 if len(test.examples) == 0: 2002 continue 2003 if not test.filename: 2004 filename = module.__file__ 2005 if filename.endswith(".pyc"): 2006 filename = filename[:-1] 2007 elif filename.endswith(".pyo"): 2008 filename = filename[:-1] 2009 test.filename = filename 2010 suite.addTest(DocTestCase(test, optionflags, setUp, tearDown, 2011 checker)) 2012 2013 return suite 2014 2015class DocFileCase(DocTestCase): 2016 2017 def id(self): 2018 return '_'.join(self._dt_test.name.split('.')) 2019 2020 def __repr__(self): 2021 return self._dt_test.filename 2022 __str__ = __repr__ 2023 2024 def format_failure(self, err): 2025 return ('Failed doctest test for %s\n File "%s", line 0\n\n%s' 2026 % (self._dt_test.name, self._dt_test.filename, err) 2027 ) 2028 2029def DocFileTest(path, package=None, globs=None, 2030 setUp=None, tearDown=None, 2031 optionflags=0): 2032 package = _normalize_module(package) 2033 name = path.split('/')[-1] 2034 dir = os.path.split(package.__file__)[0] 2035 path = os.path.join(dir, *(path.split('/'))) 2036 doc = open(path).read() 2037 2038 if globs is None: 2039 globs = {} 2040 2041 test = DocTestParser().get_doctest(doc, globs, name, path, 0) 2042 2043 return DocFileCase(test, optionflags, setUp, tearDown) 2044 2045def DocFileSuite(*paths, **kw): 2046 """Creates a suite of doctest files. 2047 2048 One or more text file paths are given as strings. These should 2049 use "/" characters to separate path segments. Paths are relative 2050 to the directory of the calling module, or relative to the package 2051 passed as a keyword argument. 2052 2053 A number of options may be provided as keyword arguments: 2054 2055 package 2056 The name of a Python package. Text-file paths will be 2057 interpreted relative to the directory containing this package. 2058 The package may be supplied as a package object or as a dotted 2059 package name. 2060 2061 setUp 2062 The name of a set-up function. This is called before running the 2063 tests in each file. 2064 2065 tearDown 2066 The name of a tear-down function. This is called after running the 2067 tests in each file. 2068 2069 globs 2070 A dictionary containing initial global variables for the tests. 2071 """ 2072 suite = unittest.TestSuite() 2073 2074 # We do this here so that _normalize_module is called at the right 2075 # level. If it were called in DocFileTest, then this function 2076 # would be the caller and we might guess the package incorrectly. 2077 kw['package'] = _normalize_module(kw.get('package')) 2078 2079 for path in paths: 2080 suite.addTest(DocFileTest(path, **kw)) 2081 2082 return suite 2083 2084###################################################################### 2085## 9. Debugging Support 2086###################################################################### 2087 2088def script_from_examples(s): 2089 r"""Extract script from text with examples. 2090 2091 Converts text with examples to a Python script. Example input is 2092 converted to regular code. Example output and all other words 2093 are converted to comments: 2094 2095 >>> text = ''' 2096 ... Here are examples of simple math. 2097 ... 2098 ... Python has super accurate integer addition 2099 ... 2100 ... >>> 2 + 2 2101 ... 5 2102 ... 2103 ... And very friendly error messages: 2104 ... 2105 ... >>> 1/0 2106 ... To Infinity 2107 ... And 2108 ... Beyond 2109 ... 2110 ... You can use logic if you want: 2111 ... 2112 ... >>> if 0: 2113 ... ... blah 2114 ... ... blah 2115 ... ... 2116 ... 2117 ... Ho hum 2118 ... ''' 2119 2120 >>> print script_from_examples(text) 2121 # Here are examples of simple math. 2122 # 2123 # Python has super accurate integer addition 2124 # 2125 2 + 2 2126 # Expected: 2127 # 5 2128 # 2129 # And very friendly error messages: 2130 # 2131 1/0 2132 # Expected: 2133 # To Infinity 2134 # And 2135 # Beyond 2136 # 2137 # You can use logic if you want: 2138 # 2139 if 0: 2140 blah 2141 blah 2142 <BLANKLINE> 2143 # 2144 # Ho hum 2145 """ 2146 2147 return DocTestParser().get_program(s) 2148 2149def _want_comment(example): 2150 """ 2151 Return a comment containing the expected output for the given example. 2152 """ 2153 # Return the expected output, if any 2154 want = example.want 2155 if want: 2156 if want[-1] == '\n': 2157 want = want[:-1] 2158 want = "\n# ".join(want.split("\n")) 2159 want = "\n# Expected:\n# %s" % want 2160 return want 2161 2162def testsource(module, name): 2163 """Extract the test sources from a doctest docstring as a script. 2164 2165 Provide the module (or dotted name of the module) containing the 2166 test to be debugged and the name (within the module) of the object 2167 with the doc string with tests to be debugged. 2168 """ 2169 module = _normalize_module(module) 2170 tests = DocTestFinder().find(module) 2171 test = [t for t in tests if t.name == name] 2172 if not test: 2173 raise ValueError(name, "not found in tests") 2174 test = test[0] 2175 testsrc = script_from_examples(test.docstring) 2176 return testsrc 2177 2178def debug_src(src, pm=False, globs=None): 2179 """Debug a single doctest docstring, in argument `src`'""" 2180 testsrc = script_from_examples(src) 2181 debug_script(testsrc, pm, globs) 2182 2183def debug_script(src, pm=False, globs=None): 2184 "Debug a test script. `src` is the script, as a string." 2185 import pdb 2186 2187 srcfilename = tempfile.mktemp("doctestdebug.py") 2188 f = open(srcfilename, 'w') 2189 f.write(src) 2190 f.close() 2191 2192 if globs: 2193 globs = globs.copy() 2194 else: 2195 globs = {} 2196 2197 if pm: 2198 try: 2199 execfile(srcfilename, globs, globs) 2200 except: 2201 print sys.exc_info()[1] 2202 pdb.post_mortem(sys.exc_info()[2]) 2203 else: 2204 # Note that %r is vital here. '%s' instead can, e.g., cause 2205 # backslashes to get treated as metacharacters on Windows. 2206 pdb.run("execfile(%r)" % srcfilename, globs, globs) 2207 2208def debug(module, name, pm=False): 2209 """Debug a single doctest docstring. 2210 2211 Provide the module (or dotted name of the module) containing the 2212 test to be debugged and the name (within the module) of the object 2213 with the docstring with tests to be debugged. 2214 """ 2215 module = _normalize_module(module) 2216 testsrc = testsource(module, name) 2217 debug_script(testsrc, pm, module.__dict__) 2218 2219###################################################################### 2220## 10. Example Usage 2221###################################################################### 2222class _TestClass: 2223 """ 2224 A pointless class, for sanity-checking of docstring testing. 2225 2226 Methods: 2227 square() 2228 get() 2229 2230 >>> _TestClass(13).get() + _TestClass(-12).get() 2231 1 2232 >>> hex(_TestClass(13).square().get()) 2233 '0xa9' 2234 """ 2235 2236 def __init__(self, val): 2237 """val -> _TestClass object with associated value val. 2238 2239 >>> t = _TestClass(123) 2240 >>> print t.get() 2241 123 2242 """ 2243 2244 self.val = val 2245 2246 def square(self): 2247 """square() -> square TestClass's associated value 2248 2249 >>> _TestClass(13).square().get() 2250 169 2251 """ 2252 2253 self.val = self.val ** 2 2254 return self 2255 2256 def get(self): 2257 """get() -> return TestClass's associated value. 2258 2259 >>> x = _TestClass(-42) 2260 >>> print x.get() 2261 -42 2262 """ 2263 2264 return self.val 2265 2266__test__ = {"_TestClass": _TestClass, 2267 "string": r""" 2268 Example of a string object, searched as-is. 2269 >>> x = 1; y = 2 2270 >>> x + y, x * y 2271 (3, 2) 2272 """, 2273 "bool-int equivalence": r""" 2274 In 2.2, boolean expressions displayed 2275 0 or 1. By default, we still accept 2276 them. This can be disabled by passing 2277 DONT_ACCEPT_TRUE_FOR_1 to the new 2278 optionflags argument. 2279 >>> 4 == 4 2280 1 2281 >>> 4 == 4 2282 True 2283 >>> 4 > 4 2284 0 2285 >>> 4 > 4 2286 False 2287 """, 2288 "blank lines": r""" 2289 Blank lines can be marked with <BLANKLINE>: 2290 >>> print 'foo\n\nbar\n' 2291 foo 2292 <BLANKLINE> 2293 bar 2294 <BLANKLINE> 2295 """, 2296 } 2297# "ellipsis": r""" 2298# If the ellipsis flag is used, then '...' can be used to 2299# elide substrings in the desired output: 2300# >>> print range(1000) 2301# [0, 1, 2, ..., 999] 2302# """, 2303# "whitespace normalization": r""" 2304# If the whitespace normalization flag is used, then 2305# differences in whitespace are ignored. 2306# >>> print range(30) 2307# [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 2308# 15, 16, 17, 18, 19, 20, 21, 22, 23, 24, 25, 26, 2309# 27, 28, 29] 2310# """, 2311# } 2312 2313def test1(): r""" 2314>>> warnings.filterwarnings("ignore", "class Tester", DeprecationWarning, 2315... "doctest", 0) 2316>>> from doctest import Tester 2317>>> t = Tester(globs={'x': 42}, verbose=0) 2318>>> t.runstring(r''' 2319... >>> x = x * 2 2320... >>> print x 2321... 42 2322... ''', 'XYZ') 2323********************************************************************** 2324Failure in example: print x 2325from line #2 of XYZ 2326Expected: 42 2327Got: 84 2328(1, 2) 2329>>> t.runstring(">>> x = x * 2\n>>> print x\n84\n", 'example2') 2330(0, 2) 2331>>> t.summarize() 2332********************************************************************** 23331 items had failures: 2334 1 of 2 in XYZ 2335***Test Failed*** 1 failures. 2336(1, 4) 2337>>> t.summarize(verbose=1) 23381 items passed all tests: 2339 2 tests in example2 2340********************************************************************** 23411 items had failures: 2342 1 of 2 in XYZ 23434 tests in 2 items. 23443 passed and 1 failed. 2345***Test Failed*** 1 failures. 2346(1, 4) 2347""" 2348 2349def test2(): r""" 2350 >>> warnings.filterwarnings("ignore", "class Tester", 2351 ... DeprecationWarning, "doctest", 0) 2352 >>> t = Tester(globs={}, verbose=1) 2353 >>> test = r''' 2354 ... # just an example 2355 ... >>> x = 1 + 2 2356 ... >>> x 2357 ... 3 2358 ... ''' 2359 >>> t.runstring(test, "Example") 2360 Running string Example 2361 Trying: x = 1 + 2 2362 Expecting: nothing 2363 ok 2364 Trying: x 2365 Expecting: 3 2366 ok 2367 0 of 2 examples failed in string Example 2368 (0, 2) 2369""" 2370def test3(): r""" 2371 >>> warnings.filterwarnings("ignore", "class Tester", 2372 ... DeprecationWarning, "doctest", 0) 2373 >>> t = Tester(globs={}, verbose=0) 2374 >>> def _f(): 2375 ... '''Trivial docstring example. 2376 ... >>> assert 2 == 2 2377 ... ''' 2378 ... return 32 2379 ... 2380 >>> t.rundoc(_f) # expect 0 failures in 1 example 2381 (0, 1) 2382""" 2383def test4(): """ 2384 >>> import new 2385 >>> m1 = new.module('_m1') 2386 >>> m2 = new.module('_m2') 2387 >>> test_data = \""" 2388 ... def _f(): 2389 ... '''>>> assert 1 == 1 2390 ... ''' 2391 ... def g(): 2392 ... '''>>> assert 2 != 1 2393 ... ''' 2394 ... class H: 2395 ... '''>>> assert 2 > 1 2396 ... ''' 2397 ... def bar(self): 2398 ... '''>>> assert 1 < 2 2399 ... ''' 2400 ... \""" 2401 >>> exec test_data in m1.__dict__ 2402 >>> exec test_data in m2.__dict__ 2403 >>> m1.__dict__.update({"f2": m2._f, "g2": m2.g, "h2": m2.H}) 2404 2405 Tests that objects outside m1 are excluded: 2406 2407 >>> warnings.filterwarnings("ignore", "class Tester", 2408 ... DeprecationWarning, "doctest", 0) 2409 >>> t = Tester(globs={}, verbose=0) 2410 >>> t.rundict(m1.__dict__, "rundict_test", m1) # f2 and g2 and h2 skipped 2411 (0, 4) 2412 2413 Once more, not excluding stuff outside m1: 2414 2415 >>> t = Tester(globs={}, verbose=0) 2416 >>> t.rundict(m1.__dict__, "rundict_test_pvt") # None are skipped. 2417 (0, 8) 2418 2419 The exclusion of objects from outside the designated module is 2420 meant to be invoked automagically by testmod. 2421 2422 >>> testmod(m1, verbose=False) 2423 (0, 4) 2424""" 2425 2426def _test(): 2427 #import doctest 2428 #doctest.testmod(doctest, verbose=False, 2429 # optionflags=ELLIPSIS | NORMALIZE_WHITESPACE | 2430 # UNIFIED_DIFF) 2431 #print '~'*70 2432 r = unittest.TextTestRunner() 2433 r.run(DocTestSuite()) 2434 2435if __name__ == "__main__": 2436 _test() 2437