Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1 | :mod:`doctest` --- Test interactive Python examples |
| 2 | =================================================== |
| 3 | |
| 4 | .. module:: doctest |
| 5 | :synopsis: Test pieces of code within docstrings. |
| 6 | .. moduleauthor:: Tim Peters <tim@python.org> |
| 7 | .. sectionauthor:: Tim Peters <tim@python.org> |
| 8 | .. sectionauthor:: Moshe Zadka <moshez@debian.org> |
| 9 | .. sectionauthor:: Edward Loper <edloper@users.sourceforge.net> |
| 10 | |
| 11 | |
| 12 | The :mod:`doctest` module searches for pieces of text that look like interactive |
| 13 | Python sessions, and then executes those sessions to verify that they work |
| 14 | exactly as shown. There are several common ways to use doctest: |
| 15 | |
| 16 | * To check that a module's docstrings are up-to-date by verifying that all |
| 17 | interactive examples still work as documented. |
| 18 | |
| 19 | * To perform regression testing by verifying that interactive examples from a |
| 20 | test file or a test object work as expected. |
| 21 | |
| 22 | * To write tutorial documentation for a package, liberally illustrated with |
| 23 | input-output examples. Depending on whether the examples or the expository text |
| 24 | are emphasized, this has the flavor of "literate testing" or "executable |
| 25 | documentation". |
| 26 | |
| 27 | Here's a complete but small example module:: |
| 28 | |
| 29 | """ |
| 30 | This is the "example" module. |
| 31 | |
| 32 | The example module supplies one function, factorial(). For example, |
| 33 | |
| 34 | >>> factorial(5) |
| 35 | 120 |
| 36 | """ |
| 37 | |
| 38 | def factorial(n): |
| 39 | """Return the factorial of n, an exact integer >= 0. |
| 40 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 41 | >>> [factorial(n) for n in range(6)] |
| 42 | [1, 1, 2, 6, 24, 120] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 43 | >>> factorial(30) |
Georg Brandl | 5c10664 | 2007-11-29 17:41:05 +0000 | [diff] [blame] | 44 | 265252859812191058636308480000000 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 45 | >>> factorial(-1) |
| 46 | Traceback (most recent call last): |
| 47 | ... |
| 48 | ValueError: n must be >= 0 |
| 49 | |
| 50 | Factorials of floats are OK, but the float must be an exact integer: |
| 51 | >>> factorial(30.1) |
| 52 | Traceback (most recent call last): |
| 53 | ... |
| 54 | ValueError: n must be exact integer |
| 55 | >>> factorial(30.0) |
Georg Brandl | 5c10664 | 2007-11-29 17:41:05 +0000 | [diff] [blame] | 56 | 265252859812191058636308480000000 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 57 | |
| 58 | It must also not be ridiculously large: |
| 59 | >>> factorial(1e100) |
| 60 | Traceback (most recent call last): |
| 61 | ... |
| 62 | OverflowError: n too large |
| 63 | """ |
| 64 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 65 | import math |
| 66 | if not n >= 0: |
| 67 | raise ValueError("n must be >= 0") |
| 68 | if math.floor(n) != n: |
| 69 | raise ValueError("n must be exact integer") |
| 70 | if n+1 == n: # catch a value like 1e300 |
| 71 | raise OverflowError("n too large") |
| 72 | result = 1 |
| 73 | factor = 2 |
| 74 | while factor <= n: |
| 75 | result *= factor |
| 76 | factor += 1 |
| 77 | return result |
| 78 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 79 | |
| 80 | if __name__ == "__main__": |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 81 | import doctest |
| 82 | doctest.testmod() |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 83 | |
| 84 | If you run :file:`example.py` directly from the command line, :mod:`doctest` |
| 85 | works its magic:: |
| 86 | |
| 87 | $ python example.py |
| 88 | $ |
| 89 | |
| 90 | There's no output! That's normal, and it means all the examples worked. Pass |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 91 | ``-v`` to the script, and :mod:`doctest` prints a detailed log of what |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 92 | it's trying, and prints a summary at the end:: |
| 93 | |
| 94 | $ python example.py -v |
| 95 | Trying: |
| 96 | factorial(5) |
| 97 | Expecting: |
| 98 | 120 |
| 99 | ok |
| 100 | Trying: |
| 101 | [factorial(n) for n in range(6)] |
| 102 | Expecting: |
| 103 | [1, 1, 2, 6, 24, 120] |
| 104 | ok |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 105 | |
| 106 | And so on, eventually ending with:: |
| 107 | |
| 108 | Trying: |
| 109 | factorial(1e100) |
| 110 | Expecting: |
| 111 | Traceback (most recent call last): |
| 112 | ... |
| 113 | OverflowError: n too large |
| 114 | ok |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 115 | 2 items passed all tests: |
| 116 | 1 tests in __main__ |
| 117 | 8 tests in __main__.factorial |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 118 | 9 tests in 2 items. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 119 | 9 passed and 0 failed. |
| 120 | Test passed. |
| 121 | $ |
| 122 | |
| 123 | That's all you need to know to start making productive use of :mod:`doctest`! |
| 124 | Jump in. The following sections provide full details. Note that there are many |
| 125 | examples of doctests in the standard Python test suite and libraries. |
| 126 | Especially useful examples can be found in the standard test file |
| 127 | :file:`Lib/test/test_doctest.py`. |
| 128 | |
| 129 | |
| 130 | .. _doctest-simple-testmod: |
| 131 | |
| 132 | Simple Usage: Checking Examples in Docstrings |
| 133 | --------------------------------------------- |
| 134 | |
| 135 | The simplest way to start using doctest (but not necessarily the way you'll |
| 136 | continue to do it) is to end each module :mod:`M` with:: |
| 137 | |
Guido van Rossum | 04110fb | 2007-08-24 16:32:05 +0000 | [diff] [blame] | 138 | if __name__ == "__main__": |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 139 | import doctest |
| 140 | doctest.testmod() |
| 141 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 142 | :mod:`doctest` then examines docstrings in module :mod:`M`. |
| 143 | |
| 144 | Running the module as a script causes the examples in the docstrings to get |
| 145 | executed and verified:: |
| 146 | |
| 147 | python M.py |
| 148 | |
| 149 | This won't display anything unless an example fails, in which case the failing |
| 150 | example(s) and the cause(s) of the failure(s) are printed to stdout, and the |
| 151 | final line of output is ``***Test Failed*** N failures.``, where *N* is the |
| 152 | number of examples that failed. |
| 153 | |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 154 | Run it with the ``-v`` switch instead:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 155 | |
| 156 | python M.py -v |
| 157 | |
| 158 | and a detailed report of all examples tried is printed to standard output, along |
| 159 | with assorted summaries at the end. |
| 160 | |
| 161 | You can force verbose mode by passing ``verbose=True`` to :func:`testmod`, or |
| 162 | prohibit it by passing ``verbose=False``. In either of those cases, |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 163 | ``sys.argv`` is not examined by :func:`testmod` (so passing ``-v`` or not |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 164 | has no effect). |
| 165 | |
Georg Brandl | 3183585 | 2008-05-12 17:38:56 +0000 | [diff] [blame] | 166 | There is also a command line shortcut for running :func:`testmod`. You can |
| 167 | instruct the Python interpreter to run the doctest module directly from the |
| 168 | standard library and pass the module name(s) on the command line:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 169 | |
| 170 | python -m doctest -v example.py |
| 171 | |
| 172 | This will import :file:`example.py` as a standalone module and run |
| 173 | :func:`testmod` on it. Note that this may not work correctly if the file is |
| 174 | part of a package and imports other submodules from that package. |
| 175 | |
| 176 | For more information on :func:`testmod`, see section :ref:`doctest-basic-api`. |
| 177 | |
| 178 | |
| 179 | .. _doctest-simple-testfile: |
| 180 | |
| 181 | Simple Usage: Checking Examples in a Text File |
| 182 | ---------------------------------------------- |
| 183 | |
| 184 | Another simple application of doctest is testing interactive examples in a text |
| 185 | file. This can be done with the :func:`testfile` function:: |
| 186 | |
| 187 | import doctest |
| 188 | doctest.testfile("example.txt") |
| 189 | |
| 190 | That short script executes and verifies any interactive Python examples |
| 191 | contained in the file :file:`example.txt`. The file content is treated as if it |
| 192 | were a single giant docstring; the file doesn't need to contain a Python |
| 193 | program! For example, perhaps :file:`example.txt` contains this:: |
| 194 | |
| 195 | The ``example`` module |
| 196 | ====================== |
| 197 | |
| 198 | Using ``factorial`` |
| 199 | ------------------- |
| 200 | |
| 201 | This is an example text file in reStructuredText format. First import |
| 202 | ``factorial`` from the ``example`` module: |
| 203 | |
| 204 | >>> from example import factorial |
| 205 | |
| 206 | Now use it: |
| 207 | |
| 208 | >>> factorial(6) |
| 209 | 120 |
| 210 | |
| 211 | Running ``doctest.testfile("example.txt")`` then finds the error in this |
| 212 | documentation:: |
| 213 | |
| 214 | File "./example.txt", line 14, in example.txt |
| 215 | Failed example: |
| 216 | factorial(6) |
| 217 | Expected: |
| 218 | 120 |
| 219 | Got: |
| 220 | 720 |
| 221 | |
| 222 | As with :func:`testmod`, :func:`testfile` won't display anything unless an |
| 223 | example fails. If an example does fail, then the failing example(s) and the |
| 224 | cause(s) of the failure(s) are printed to stdout, using the same format as |
| 225 | :func:`testmod`. |
| 226 | |
| 227 | By default, :func:`testfile` looks for files in the calling module's directory. |
| 228 | See section :ref:`doctest-basic-api` for a description of the optional arguments |
| 229 | that can be used to tell it to look for files in other locations. |
| 230 | |
| 231 | Like :func:`testmod`, :func:`testfile`'s verbosity can be set with the |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 232 | ``-v`` command-line switch or with the optional keyword argument |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 233 | *verbose*. |
| 234 | |
Georg Brandl | 3183585 | 2008-05-12 17:38:56 +0000 | [diff] [blame] | 235 | There is also a command line shortcut for running :func:`testfile`. You can |
| 236 | instruct the Python interpreter to run the doctest module directly from the |
| 237 | standard library and pass the file name(s) on the command line:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 238 | |
| 239 | python -m doctest -v example.txt |
| 240 | |
| 241 | Because the file name does not end with :file:`.py`, :mod:`doctest` infers that |
| 242 | it must be run with :func:`testfile`, not :func:`testmod`. |
| 243 | |
| 244 | For more information on :func:`testfile`, see section :ref:`doctest-basic-api`. |
| 245 | |
| 246 | |
| 247 | .. _doctest-how-it-works: |
| 248 | |
| 249 | How It Works |
| 250 | ------------ |
| 251 | |
| 252 | This section examines in detail how doctest works: which docstrings it looks at, |
| 253 | how it finds interactive examples, what execution context it uses, how it |
| 254 | handles exceptions, and how option flags can be used to control its behavior. |
| 255 | This is the information that you need to know to write doctest examples; for |
| 256 | information about actually running doctest on these examples, see the following |
| 257 | sections. |
| 258 | |
| 259 | |
| 260 | .. _doctest-which-docstrings: |
| 261 | |
| 262 | Which Docstrings Are Examined? |
| 263 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 264 | |
| 265 | The module docstring, and all function, class and method docstrings are |
| 266 | searched. Objects imported into the module are not searched. |
| 267 | |
| 268 | In addition, if ``M.__test__`` exists and "is true", it must be a dict, and each |
| 269 | entry maps a (string) name to a function object, class object, or string. |
| 270 | Function and class object docstrings found from ``M.__test__`` are searched, and |
| 271 | strings are treated as if they were docstrings. In output, a key ``K`` in |
| 272 | ``M.__test__`` appears with name :: |
| 273 | |
| 274 | <name of M>.__test__.K |
| 275 | |
| 276 | Any classes found are recursively searched similarly, to test docstrings in |
| 277 | their contained methods and nested classes. |
| 278 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 279 | |
| 280 | .. _doctest-finding-examples: |
| 281 | |
| 282 | How are Docstring Examples Recognized? |
| 283 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 284 | |
R. David Murray | 9691e59 | 2010-06-15 23:46:40 +0000 | [diff] [blame] | 285 | In most cases a copy-and-paste of an interactive console session works fine, |
| 286 | but doctest isn't trying to do an exact emulation of any specific Python shell. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 287 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 288 | :: |
| 289 | |
| 290 | >>> # comments are ignored |
| 291 | >>> x = 12 |
| 292 | >>> x |
| 293 | 12 |
| 294 | >>> if x == 13: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 295 | ... print("yes") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 296 | ... else: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 297 | ... print("no") |
| 298 | ... print("NO") |
| 299 | ... print("NO!!!") |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 300 | ... |
| 301 | no |
| 302 | NO |
| 303 | NO!!! |
| 304 | >>> |
| 305 | |
| 306 | Any expected output must immediately follow the final ``'>>> '`` or ``'... '`` |
| 307 | line containing the code, and the expected output (if any) extends to the next |
| 308 | ``'>>> '`` or all-whitespace line. |
| 309 | |
| 310 | The fine print: |
| 311 | |
| 312 | * Expected output cannot contain an all-whitespace line, since such a line is |
| 313 | taken to signal the end of expected output. If expected output does contain a |
| 314 | blank line, put ``<BLANKLINE>`` in your doctest example each place a blank line |
| 315 | is expected. |
| 316 | |
R. David Murray | 9691e59 | 2010-06-15 23:46:40 +0000 | [diff] [blame] | 317 | * All hard tab characters are expanded to spaces, using 8-column tab stops. |
| 318 | Tabs in output generated by the tested code are not modified. Because any |
| 319 | hard tabs in the sample output *are* expanded, this means that if the code |
| 320 | output includes hard tabs, the only way the doctest can pass is if the |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 321 | :const:`NORMALIZE_WHITESPACE` option or :ref:`directive <doctest-directives>` |
| 322 | is in effect. |
R. David Murray | 9691e59 | 2010-06-15 23:46:40 +0000 | [diff] [blame] | 323 | Alternatively, the test can be rewritten to capture the output and compare it |
| 324 | to an expected value as part of the test. This handling of tabs in the |
| 325 | source was arrived at through trial and error, and has proven to be the least |
| 326 | error prone way of handling them. It is possible to use a different |
| 327 | algorithm for handling tabs by writing a custom :class:`DocTestParser` class. |
| 328 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 329 | * Output to stdout is captured, but not output to stderr (exception tracebacks |
| 330 | are captured via a different means). |
| 331 | |
| 332 | * If you continue a line via backslashing in an interactive session, or for any |
| 333 | other reason use a backslash, you should use a raw docstring, which will |
| 334 | preserve your backslashes exactly as you type them:: |
| 335 | |
| 336 | >>> def f(x): |
| 337 | ... r'''Backslashes in a raw docstring: m\n''' |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 338 | >>> print(f.__doc__) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 339 | Backslashes in a raw docstring: m\n |
| 340 | |
| 341 | Otherwise, the backslash will be interpreted as part of the string. For example, |
Ezio Melotti | 694f233 | 2012-09-20 09:47:03 +0300 | [diff] [blame] | 342 | the ``\n`` above would be interpreted as a newline character. Alternatively, you |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 343 | can double each backslash in the doctest version (and not use a raw string):: |
| 344 | |
| 345 | >>> def f(x): |
| 346 | ... '''Backslashes in a raw docstring: m\\n''' |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 347 | >>> print(f.__doc__) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 348 | Backslashes in a raw docstring: m\n |
| 349 | |
| 350 | * The starting column doesn't matter:: |
| 351 | |
| 352 | >>> assert "Easy!" |
| 353 | >>> import math |
| 354 | >>> math.floor(1.9) |
R. David Murray | 7c5714f | 2009-11-23 03:13:23 +0000 | [diff] [blame] | 355 | 1 |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 356 | |
| 357 | and as many leading whitespace characters are stripped from the expected output |
| 358 | as appeared in the initial ``'>>> '`` line that started the example. |
| 359 | |
| 360 | |
| 361 | .. _doctest-execution-context: |
| 362 | |
| 363 | What's the Execution Context? |
| 364 | ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ |
| 365 | |
| 366 | By default, each time :mod:`doctest` finds a docstring to test, it uses a |
| 367 | *shallow copy* of :mod:`M`'s globals, so that running tests doesn't change the |
| 368 | module's real globals, and so that one test in :mod:`M` can't leave behind |
| 369 | crumbs that accidentally allow another test to work. This means examples can |
| 370 | freely use any names defined at top-level in :mod:`M`, and names defined earlier |
| 371 | in the docstring being run. Examples cannot see names defined in other |
| 372 | docstrings. |
| 373 | |
| 374 | You can force use of your own dict as the execution context by passing |
| 375 | ``globs=your_dict`` to :func:`testmod` or :func:`testfile` instead. |
| 376 | |
| 377 | |
| 378 | .. _doctest-exceptions: |
| 379 | |
| 380 | What About Exceptions? |
| 381 | ^^^^^^^^^^^^^^^^^^^^^^ |
| 382 | |
| 383 | No problem, provided that the traceback is the only output produced by the |
| 384 | example: just paste in the traceback. [#]_ Since tracebacks contain details |
| 385 | that are likely to change rapidly (for example, exact file paths and line |
| 386 | numbers), this is one case where doctest works hard to be flexible in what it |
| 387 | accepts. |
| 388 | |
| 389 | Simple example:: |
| 390 | |
| 391 | >>> [1, 2, 3].remove(42) |
| 392 | Traceback (most recent call last): |
| 393 | File "<stdin>", line 1, in ? |
| 394 | ValueError: list.remove(x): x not in list |
| 395 | |
| 396 | That doctest succeeds if :exc:`ValueError` is raised, with the ``list.remove(x): |
| 397 | x not in list`` detail as shown. |
| 398 | |
| 399 | The expected output for an exception must start with a traceback header, which |
| 400 | may be either of the following two lines, indented the same as the first line of |
| 401 | the example:: |
| 402 | |
| 403 | Traceback (most recent call last): |
| 404 | Traceback (innermost last): |
| 405 | |
| 406 | The traceback header is followed by an optional traceback stack, whose contents |
| 407 | are ignored by doctest. The traceback stack is typically omitted, or copied |
| 408 | verbatim from an interactive session. |
| 409 | |
| 410 | The traceback stack is followed by the most interesting part: the line(s) |
| 411 | containing the exception type and detail. This is usually the last line of a |
| 412 | traceback, but can extend across multiple lines if the exception has a |
| 413 | multi-line detail:: |
| 414 | |
| 415 | >>> raise ValueError('multi\n line\ndetail') |
| 416 | Traceback (most recent call last): |
| 417 | File "<stdin>", line 1, in ? |
| 418 | ValueError: multi |
| 419 | line |
| 420 | detail |
| 421 | |
| 422 | The last three lines (starting with :exc:`ValueError`) are compared against the |
| 423 | exception's type and detail, and the rest are ignored. |
| 424 | |
| 425 | Best practice is to omit the traceback stack, unless it adds significant |
| 426 | documentation value to the example. So the last example is probably better as:: |
| 427 | |
| 428 | >>> raise ValueError('multi\n line\ndetail') |
| 429 | Traceback (most recent call last): |
| 430 | ... |
| 431 | ValueError: multi |
| 432 | line |
| 433 | detail |
| 434 | |
| 435 | Note that tracebacks are treated very specially. In particular, in the |
| 436 | rewritten example, the use of ``...`` is independent of doctest's |
| 437 | :const:`ELLIPSIS` option. The ellipsis in that example could be left out, or |
| 438 | could just as well be three (or three hundred) commas or digits, or an indented |
| 439 | transcript of a Monty Python skit. |
| 440 | |
| 441 | Some details you should read once, but won't need to remember: |
| 442 | |
| 443 | * Doctest can't guess whether your expected output came from an exception |
| 444 | traceback or from ordinary printing. So, e.g., an example that expects |
| 445 | ``ValueError: 42 is prime`` will pass whether :exc:`ValueError` is actually |
| 446 | raised or if the example merely prints that traceback text. In practice, |
| 447 | ordinary output rarely begins with a traceback header line, so this doesn't |
| 448 | create real problems. |
| 449 | |
| 450 | * Each line of the traceback stack (if present) must be indented further than |
| 451 | the first line of the example, *or* start with a non-alphanumeric character. |
| 452 | The first line following the traceback header indented the same and starting |
| 453 | with an alphanumeric is taken to be the start of the exception detail. Of |
| 454 | course this does the right thing for genuine tracebacks. |
| 455 | |
Nick Coghlan | 5e76e94 | 2010-06-12 13:42:46 +0000 | [diff] [blame] | 456 | * When the :const:`IGNORE_EXCEPTION_DETAIL` doctest option is specified, |
| 457 | everything following the leftmost colon and any module information in the |
| 458 | exception name is ignored. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 459 | |
| 460 | * The interactive shell omits the traceback header line for some |
| 461 | :exc:`SyntaxError`\ s. But doctest uses the traceback header line to |
| 462 | distinguish exceptions from non-exceptions. So in the rare case where you need |
| 463 | to test a :exc:`SyntaxError` that omits the traceback header, you will need to |
| 464 | manually add the traceback header line to your test example. |
| 465 | |
| 466 | * For some :exc:`SyntaxError`\ s, Python displays the character position of the |
| 467 | syntax error, using a ``^`` marker:: |
| 468 | |
| 469 | >>> 1 1 |
| 470 | File "<stdin>", line 1 |
| 471 | 1 1 |
| 472 | ^ |
| 473 | SyntaxError: invalid syntax |
| 474 | |
| 475 | Since the lines showing the position of the error come before the exception type |
| 476 | and detail, they are not checked by doctest. For example, the following test |
| 477 | would pass, even though it puts the ``^`` marker in the wrong location:: |
| 478 | |
| 479 | >>> 1 1 |
| 480 | Traceback (most recent call last): |
| 481 | File "<stdin>", line 1 |
| 482 | 1 1 |
| 483 | ^ |
| 484 | SyntaxError: invalid syntax |
| 485 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 486 | |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 487 | .. _option-flags-and-directives: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 488 | .. _doctest-options: |
| 489 | |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 490 | Option Flags |
| 491 | ^^^^^^^^^^^^ |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 492 | |
| 493 | A number of option flags control various aspects of doctest's behavior. |
| 494 | Symbolic names for the flags are supplied as module constants, which can be |
| 495 | or'ed together and passed to various functions. The names can also be used in |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 496 | :ref:`doctest directives <doctest-directives>`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 497 | |
| 498 | The first group of options define test semantics, controlling aspects of how |
| 499 | doctest decides whether actual output matches an example's expected output: |
| 500 | |
| 501 | |
| 502 | .. data:: DONT_ACCEPT_TRUE_FOR_1 |
| 503 | |
| 504 | By default, if an expected output block contains just ``1``, an actual output |
| 505 | block containing just ``1`` or just ``True`` is considered to be a match, and |
| 506 | similarly for ``0`` versus ``False``. When :const:`DONT_ACCEPT_TRUE_FOR_1` is |
| 507 | specified, neither substitution is allowed. The default behavior caters to that |
| 508 | Python changed the return type of many functions from integer to boolean; |
| 509 | doctests expecting "little integer" output still work in these cases. This |
| 510 | option will probably go away, but not for several years. |
| 511 | |
| 512 | |
| 513 | .. data:: DONT_ACCEPT_BLANKLINE |
| 514 | |
| 515 | By default, if an expected output block contains a line containing only the |
| 516 | string ``<BLANKLINE>``, then that line will match a blank line in the actual |
| 517 | output. Because a genuinely blank line delimits the expected output, this is |
| 518 | the only way to communicate that a blank line is expected. When |
| 519 | :const:`DONT_ACCEPT_BLANKLINE` is specified, this substitution is not allowed. |
| 520 | |
| 521 | |
| 522 | .. data:: NORMALIZE_WHITESPACE |
| 523 | |
| 524 | When specified, all sequences of whitespace (blanks and newlines) are treated as |
| 525 | equal. Any sequence of whitespace within the expected output will match any |
| 526 | sequence of whitespace within the actual output. By default, whitespace must |
| 527 | match exactly. :const:`NORMALIZE_WHITESPACE` is especially useful when a line of |
| 528 | expected output is very long, and you want to wrap it across multiple lines in |
| 529 | your source. |
| 530 | |
| 531 | |
| 532 | .. data:: ELLIPSIS |
| 533 | |
| 534 | When specified, an ellipsis marker (``...``) in the expected output can match |
| 535 | any substring in the actual output. This includes substrings that span line |
| 536 | boundaries, and empty substrings, so it's best to keep usage of this simple. |
| 537 | Complicated uses can lead to the same kinds of "oops, it matched too much!" |
| 538 | surprises that ``.*`` is prone to in regular expressions. |
| 539 | |
| 540 | |
| 541 | .. data:: IGNORE_EXCEPTION_DETAIL |
| 542 | |
| 543 | When specified, an example that expects an exception passes if an exception of |
| 544 | the expected type is raised, even if the exception detail does not match. For |
| 545 | example, an example expecting ``ValueError: 42`` will pass if the actual |
| 546 | exception raised is ``ValueError: 3*14``, but will fail, e.g., if |
| 547 | :exc:`TypeError` is raised. |
| 548 | |
Nick Coghlan | 5e76e94 | 2010-06-12 13:42:46 +0000 | [diff] [blame] | 549 | It will also ignore the module name used in Python 3 doctest reports. Hence |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 550 | both of these variations will work with the flag specified, regardless of |
| 551 | whether the test is run under Python 2.7 or Python 3.2 (or later versions):: |
Nick Coghlan | 5e76e94 | 2010-06-12 13:42:46 +0000 | [diff] [blame] | 552 | |
| 553 | >>> raise CustomError('message') #doctest: +IGNORE_EXCEPTION_DETAIL |
| 554 | Traceback (most recent call last): |
| 555 | CustomError: message |
| 556 | |
| 557 | >>> raise CustomError('message') #doctest: +IGNORE_EXCEPTION_DETAIL |
| 558 | Traceback (most recent call last): |
| 559 | my_module.CustomError: message |
| 560 | |
| 561 | Note that :const:`ELLIPSIS` can also be used to ignore the |
| 562 | details of the exception message, but such a test may still fail based |
| 563 | on whether or not the module details are printed as part of the |
| 564 | exception name. Using :const:`IGNORE_EXCEPTION_DETAIL` and the details |
| 565 | from Python 2.3 is also the only clear way to write a doctest that doesn't |
| 566 | care about the exception detail yet continues to pass under Python 2.3 or |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 567 | earlier (those releases do not support :ref:`doctest directives |
| 568 | <doctest-directives>` and ignore them as irrelevant comments). For example:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 569 | |
| 570 | >>> (1, 2)[3] = 'moo' #doctest: +IGNORE_EXCEPTION_DETAIL |
| 571 | Traceback (most recent call last): |
| 572 | File "<stdin>", line 1, in ? |
| 573 | TypeError: object doesn't support item assignment |
| 574 | |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 575 | passes under Python 2.3 and later Python versions with the flag specified, |
| 576 | even though the detail |
Nick Coghlan | 5e76e94 | 2010-06-12 13:42:46 +0000 | [diff] [blame] | 577 | changed in Python 2.4 to say "does not" instead of "doesn't". |
| 578 | |
| 579 | .. versionchanged:: 3.2 |
Georg Brandl | 67b21b7 | 2010-08-17 15:07:14 +0000 | [diff] [blame] | 580 | :const:`IGNORE_EXCEPTION_DETAIL` now also ignores any information relating |
| 581 | to the module containing the exception under test. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 582 | |
| 583 | |
| 584 | .. data:: SKIP |
| 585 | |
| 586 | When specified, do not run the example at all. This can be useful in contexts |
| 587 | where doctest examples serve as both documentation and test cases, and an |
| 588 | example should be included for documentation purposes, but should not be |
| 589 | checked. E.g., the example's output might be random; or the example might |
| 590 | depend on resources which would be unavailable to the test driver. |
| 591 | |
| 592 | The SKIP flag can also be used for temporarily "commenting out" examples. |
| 593 | |
| 594 | |
| 595 | .. data:: COMPARISON_FLAGS |
| 596 | |
| 597 | A bitmask or'ing together all the comparison flags above. |
| 598 | |
| 599 | The second group of options controls how test failures are reported: |
| 600 | |
| 601 | |
| 602 | .. data:: REPORT_UDIFF |
| 603 | |
| 604 | When specified, failures that involve multi-line expected and actual outputs are |
| 605 | displayed using a unified diff. |
| 606 | |
| 607 | |
| 608 | .. data:: REPORT_CDIFF |
| 609 | |
| 610 | When specified, failures that involve multi-line expected and actual outputs |
| 611 | will be displayed using a context diff. |
| 612 | |
| 613 | |
| 614 | .. data:: REPORT_NDIFF |
| 615 | |
| 616 | When specified, differences are computed by ``difflib.Differ``, using the same |
| 617 | algorithm as the popular :file:`ndiff.py` utility. This is the only method that |
| 618 | marks differences within lines as well as across lines. For example, if a line |
| 619 | of expected output contains digit ``1`` where actual output contains letter |
| 620 | ``l``, a line is inserted with a caret marking the mismatching column positions. |
| 621 | |
| 622 | |
| 623 | .. data:: REPORT_ONLY_FIRST_FAILURE |
| 624 | |
| 625 | When specified, display the first failing example in each doctest, but suppress |
| 626 | output for all remaining examples. This will prevent doctest from reporting |
| 627 | correct examples that break because of earlier failures; but it might also hide |
| 628 | incorrect examples that fail independently of the first failure. When |
| 629 | :const:`REPORT_ONLY_FIRST_FAILURE` is specified, the remaining examples are |
| 630 | still run, and still count towards the total number of failures reported; only |
| 631 | the output is suppressed. |
| 632 | |
| 633 | |
| 634 | .. data:: REPORTING_FLAGS |
| 635 | |
| 636 | A bitmask or'ing together all the reporting flags above. |
| 637 | |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 638 | |
| 639 | There is also a way to register new option flag names, though this isn't |
| 640 | useful unless you intend to extend :mod:`doctest` internals via subclassing: |
| 641 | |
| 642 | |
| 643 | .. function:: register_optionflag(name) |
| 644 | |
| 645 | Create a new option flag with a given name, and return the new flag's integer |
| 646 | value. :func:`register_optionflag` can be used when subclassing |
| 647 | :class:`OutputChecker` or :class:`DocTestRunner` to create new options that are |
| 648 | supported by your subclasses. :func:`register_optionflag` should always be |
| 649 | called using the following idiom:: |
| 650 | |
| 651 | MY_FLAG = register_optionflag('MY_FLAG') |
| 652 | |
| 653 | |
| 654 | .. _doctest-directives: |
| 655 | |
| 656 | Directives |
| 657 | ^^^^^^^^^^ |
| 658 | |
| 659 | Doctest directives may be used to modify the :ref:`option flags |
| 660 | <doctest-options>` for an individual example. Doctest directives are |
| 661 | special Python comments following an example's source code: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 662 | |
| 663 | .. productionlist:: doctest |
| 664 | directive: "#" "doctest:" `directive_options` |
| 665 | directive_options: `directive_option` ("," `directive_option`)\* |
| 666 | directive_option: `on_or_off` `directive_option_name` |
| 667 | on_or_off: "+" \| "-" |
| 668 | directive_option_name: "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ... |
| 669 | |
| 670 | Whitespace is not allowed between the ``+`` or ``-`` and the directive option |
| 671 | name. The directive option name can be any of the option flag names explained |
| 672 | above. |
| 673 | |
| 674 | An example's doctest directives modify doctest's behavior for that single |
| 675 | example. Use ``+`` to enable the named behavior, or ``-`` to disable it. |
| 676 | |
Nick Coghlan | 8f80e0a | 2012-10-03 12:21:44 +0530 | [diff] [blame] | 677 | .. note:: |
Nick Coghlan | 0b26ccf | 2012-10-03 13:52:48 +0530 | [diff] [blame] | 678 | Due to an `unfortunate limitation`_ of our current documentation |
| 679 | publishing process, syntax highlighting has been disabled in the examples |
| 680 | below in order to ensure the doctest directives are correctly displayed. |
Nick Coghlan | 8f80e0a | 2012-10-03 12:21:44 +0530 | [diff] [blame] | 681 | |
Nick Coghlan | 0b26ccf | 2012-10-03 13:52:48 +0530 | [diff] [blame] | 682 | .. _unfortunate limitation: http://bugs.python.org/issue12947 |
Nick Coghlan | 8f80e0a | 2012-10-03 12:21:44 +0530 | [diff] [blame] | 683 | |
Nick Coghlan | 0b26ccf | 2012-10-03 13:52:48 +0530 | [diff] [blame] | 684 | For example, this test passes: |
| 685 | |
| 686 | .. code-block:: text |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 687 | |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 688 | >>> print(list(range(20))) #doctest: +NORMALIZE_WHITESPACE |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 689 | [0, 1, 2, 3, 4, 5, 6, 7, 8, 9, |
| 690 | 10, 11, 12, 13, 14, 15, 16, 17, 18, 19] |
| 691 | |
| 692 | Without the directive it would fail, both because the actual output doesn't have |
| 693 | two blanks before the single-digit list elements, and because the actual output |
| 694 | is on a single line. This test also passes, and also requires a directive to do |
Nick Coghlan | 0b26ccf | 2012-10-03 13:52:48 +0530 | [diff] [blame] | 695 | so: |
| 696 | |
| 697 | .. code-block:: text |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 698 | |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 699 | >>> print(list(range(20))) # doctest: +ELLIPSIS |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 700 | [0, 1, ..., 18, 19] |
| 701 | |
Nick Coghlan | 0b26ccf | 2012-10-03 13:52:48 +0530 | [diff] [blame] | 702 | Multiple directives can be used on a single physical line, separated by |
| 703 | commas: |
| 704 | |
| 705 | .. code-block:: text |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 706 | |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 707 | >>> print(list(range(20))) # doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 708 | [0, 1, ..., 18, 19] |
| 709 | |
| 710 | If multiple directive comments are used for a single example, then they are |
Nick Coghlan | 0b26ccf | 2012-10-03 13:52:48 +0530 | [diff] [blame] | 711 | combined: |
| 712 | |
| 713 | .. code-block:: text |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 714 | |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 715 | >>> print(list(range(20))) # doctest: +ELLIPSIS |
| 716 | ... # doctest: +NORMALIZE_WHITESPACE |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 717 | [0, 1, ..., 18, 19] |
| 718 | |
| 719 | As the previous example shows, you can add ``...`` lines to your example |
| 720 | containing only directives. This can be useful when an example is too long for |
Nick Coghlan | 0b26ccf | 2012-10-03 13:52:48 +0530 | [diff] [blame] | 721 | a directive to comfortably fit on the same line: |
| 722 | |
| 723 | .. code-block:: text |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 724 | |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 725 | >>> print(list(range(5)) + list(range(10, 20)) + list(range(30, 40))) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 726 | ... # doctest: +ELLIPSIS |
Georg Brandl | 8f80a5b | 2010-03-21 09:25:54 +0000 | [diff] [blame] | 727 | [0, ..., 4, 10, ..., 19, 30, ..., 39] |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 728 | |
| 729 | Note that since all options are disabled by default, and directives apply only |
| 730 | to the example they appear in, enabling options (via ``+`` in a directive) is |
| 731 | usually the only meaningful choice. However, option flags can also be passed to |
| 732 | functions that run doctests, establishing different defaults. In such cases, |
| 733 | disabling an option via ``-`` in a directive can be useful. |
| 734 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 735 | |
| 736 | .. _doctest-warnings: |
| 737 | |
| 738 | Warnings |
| 739 | ^^^^^^^^ |
| 740 | |
| 741 | :mod:`doctest` is serious about requiring exact matches in expected output. If |
| 742 | even a single character doesn't match, the test fails. This will probably |
| 743 | surprise you a few times, as you learn exactly what Python does and doesn't |
| 744 | guarantee about output. For example, when printing a dict, Python doesn't |
| 745 | guarantee that the key-value pairs will be printed in any particular order, so a |
Christian Heimes | 5b5e81c | 2007-12-31 16:14:33 +0000 | [diff] [blame] | 746 | test like :: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 747 | |
| 748 | >>> foo() |
| 749 | {"Hermione": "hippogryph", "Harry": "broomstick"} |
| 750 | |
| 751 | is vulnerable! One workaround is to do :: |
| 752 | |
| 753 | >>> foo() == {"Hermione": "hippogryph", "Harry": "broomstick"} |
| 754 | True |
| 755 | |
| 756 | instead. Another is to do :: |
| 757 | |
Ezio Melotti | 8f7649e | 2009-09-13 04:48:45 +0000 | [diff] [blame] | 758 | >>> d = sorted(foo().items()) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 759 | >>> d |
| 760 | [('Harry', 'broomstick'), ('Hermione', 'hippogryph')] |
| 761 | |
| 762 | There are others, but you get the idea. |
| 763 | |
| 764 | Another bad idea is to print things that embed an object address, like :: |
| 765 | |
| 766 | >>> id(1.0) # certain to fail some of the time |
| 767 | 7948648 |
| 768 | >>> class C: pass |
| 769 | >>> C() # the default repr() for instances embeds an address |
| 770 | <__main__.C instance at 0x00AC18F0> |
| 771 | |
Chris Jerdonek | 3650ea2 | 2012-10-10 06:52:08 -0700 | [diff] [blame] | 772 | The :const:`ELLIPSIS` directive gives a nice approach for the last example: |
| 773 | |
| 774 | .. code-block:: text |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 775 | |
| 776 | >>> C() #doctest: +ELLIPSIS |
| 777 | <__main__.C instance at 0x...> |
| 778 | |
| 779 | Floating-point numbers are also subject to small output variations across |
| 780 | platforms, because Python defers to the platform C library for float formatting, |
| 781 | and C libraries vary widely in quality here. :: |
| 782 | |
| 783 | >>> 1./7 # risky |
| 784 | 0.14285714285714285 |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 785 | >>> print(1./7) # safer |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 786 | 0.142857142857 |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 787 | >>> print(round(1./7, 6)) # much safer |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 788 | 0.142857 |
| 789 | |
| 790 | Numbers of the form ``I/2.**J`` are safe across all platforms, and I often |
| 791 | contrive doctest examples to produce numbers of that form:: |
| 792 | |
| 793 | >>> 3./4 # utterly safe |
| 794 | 0.75 |
| 795 | |
| 796 | Simple fractions are also easier for people to understand, and that makes for |
| 797 | better documentation. |
| 798 | |
| 799 | |
| 800 | .. _doctest-basic-api: |
| 801 | |
| 802 | Basic API |
| 803 | --------- |
| 804 | |
| 805 | The functions :func:`testmod` and :func:`testfile` provide a simple interface to |
| 806 | doctest that should be sufficient for most basic uses. For a less formal |
| 807 | introduction to these two functions, see sections :ref:`doctest-simple-testmod` |
| 808 | and :ref:`doctest-simple-testfile`. |
| 809 | |
| 810 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 811 | .. function:: testfile(filename, module_relative=True, name=None, package=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, parser=DocTestParser(), encoding=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 812 | |
| 813 | All arguments except *filename* are optional, and should be specified in keyword |
| 814 | form. |
| 815 | |
| 816 | Test examples in the file named *filename*. Return ``(failure_count, |
| 817 | test_count)``. |
| 818 | |
| 819 | Optional argument *module_relative* specifies how the filename should be |
| 820 | interpreted: |
| 821 | |
| 822 | * If *module_relative* is ``True`` (the default), then *filename* specifies an |
| 823 | OS-independent module-relative path. By default, this path is relative to the |
| 824 | calling module's directory; but if the *package* argument is specified, then it |
| 825 | is relative to that package. To ensure OS-independence, *filename* should use |
| 826 | ``/`` characters to separate path segments, and may not be an absolute path |
| 827 | (i.e., it may not begin with ``/``). |
| 828 | |
| 829 | * If *module_relative* is ``False``, then *filename* specifies an OS-specific |
| 830 | path. The path may be absolute or relative; relative paths are resolved with |
| 831 | respect to the current working directory. |
| 832 | |
| 833 | Optional argument *name* gives the name of the test; by default, or if ``None``, |
| 834 | ``os.path.basename(filename)`` is used. |
| 835 | |
| 836 | Optional argument *package* is a Python package or the name of a Python package |
| 837 | whose directory should be used as the base directory for a module-relative |
| 838 | filename. If no package is specified, then the calling module's directory is |
| 839 | used as the base directory for module-relative filenames. It is an error to |
| 840 | specify *package* if *module_relative* is ``False``. |
| 841 | |
| 842 | Optional argument *globs* gives a dict to be used as the globals when executing |
| 843 | examples. A new shallow copy of this dict is created for the doctest, so its |
| 844 | examples start with a clean slate. By default, or if ``None``, a new empty dict |
| 845 | is used. |
| 846 | |
| 847 | Optional argument *extraglobs* gives a dict merged into the globals used to |
| 848 | execute examples. This works like :meth:`dict.update`: if *globs* and |
| 849 | *extraglobs* have a common key, the associated value in *extraglobs* appears in |
| 850 | the combined dict. By default, or if ``None``, no extra globals are used. This |
| 851 | is an advanced feature that allows parameterization of doctests. For example, a |
| 852 | doctest can be written for a base class, using a generic name for the class, |
| 853 | then reused to test any number of subclasses by passing an *extraglobs* dict |
| 854 | mapping the generic name to the subclass to be tested. |
| 855 | |
| 856 | Optional argument *verbose* prints lots of stuff if true, and prints only |
| 857 | failures if false; by default, or if ``None``, it's true if and only if ``'-v'`` |
| 858 | is in ``sys.argv``. |
| 859 | |
| 860 | Optional argument *report* prints a summary at the end when true, else prints |
| 861 | nothing at the end. In verbose mode, the summary is detailed, else the summary |
| 862 | is very brief (in fact, empty if all tests passed). |
| 863 | |
| 864 | Optional argument *optionflags* or's together option flags. See section |
| 865 | :ref:`doctest-options`. |
| 866 | |
| 867 | Optional argument *raise_on_error* defaults to false. If true, an exception is |
| 868 | raised upon the first failure or unexpected exception in an example. This |
| 869 | allows failures to be post-mortem debugged. Default behavior is to continue |
| 870 | running examples. |
| 871 | |
| 872 | Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) that |
| 873 | should be used to extract tests from the files. It defaults to a normal parser |
| 874 | (i.e., ``DocTestParser()``). |
| 875 | |
| 876 | Optional argument *encoding* specifies an encoding that should be used to |
| 877 | convert the file to unicode. |
| 878 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 879 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 880 | .. function:: testmod(m=None, name=None, globs=None, verbose=None, report=True, optionflags=0, extraglobs=None, raise_on_error=False, exclude_empty=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 881 | |
| 882 | All arguments are optional, and all except for *m* should be specified in |
| 883 | keyword form. |
| 884 | |
| 885 | Test examples in docstrings in functions and classes reachable from module *m* |
| 886 | (or module :mod:`__main__` if *m* is not supplied or is ``None``), starting with |
| 887 | ``m.__doc__``. |
| 888 | |
| 889 | Also test examples reachable from dict ``m.__test__``, if it exists and is not |
| 890 | ``None``. ``m.__test__`` maps names (strings) to functions, classes and |
| 891 | strings; function and class docstrings are searched for examples; strings are |
| 892 | searched directly, as if they were docstrings. |
| 893 | |
| 894 | Only docstrings attached to objects belonging to module *m* are searched. |
| 895 | |
| 896 | Return ``(failure_count, test_count)``. |
| 897 | |
| 898 | Optional argument *name* gives the name of the module; by default, or if |
| 899 | ``None``, ``m.__name__`` is used. |
| 900 | |
| 901 | Optional argument *exclude_empty* defaults to false. If true, objects for which |
| 902 | no doctests are found are excluded from consideration. The default is a backward |
| 903 | compatibility hack, so that code still using :meth:`doctest.master.summarize` in |
| 904 | conjunction with :func:`testmod` continues to get output for objects with no |
| 905 | tests. The *exclude_empty* argument to the newer :class:`DocTestFinder` |
| 906 | constructor defaults to true. |
| 907 | |
| 908 | Optional arguments *extraglobs*, *verbose*, *report*, *optionflags*, |
| 909 | *raise_on_error*, and *globs* are the same as for function :func:`testfile` |
| 910 | above, except that *globs* defaults to ``m.__dict__``. |
| 911 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 912 | |
| 913 | There's also a function to run the doctests associated with a single object. |
| 914 | This function is provided for backward compatibility. There are no plans to |
| 915 | deprecate it, but it's rarely useful: |
| 916 | |
| 917 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 918 | .. function:: run_docstring_examples(f, globs, verbose=False, name="NoName", compileflags=None, optionflags=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 919 | |
| 920 | Test examples associated with object *f*; for example, *f* may be a module, |
| 921 | function, or class object. |
| 922 | |
| 923 | A shallow copy of dictionary argument *globs* is used for the execution context. |
| 924 | |
| 925 | Optional argument *name* is used in failure messages, and defaults to |
| 926 | ``"NoName"``. |
| 927 | |
| 928 | If optional argument *verbose* is true, output is generated even if there are no |
| 929 | failures. By default, output is generated only in case of an example failure. |
| 930 | |
| 931 | Optional argument *compileflags* gives the set of flags that should be used by |
| 932 | the Python compiler when running the examples. By default, or if ``None``, |
| 933 | flags are deduced corresponding to the set of future features found in *globs*. |
| 934 | |
| 935 | Optional argument *optionflags* works as for function :func:`testfile` above. |
| 936 | |
| 937 | |
| 938 | .. _doctest-unittest-api: |
| 939 | |
| 940 | Unittest API |
| 941 | ------------ |
| 942 | |
| 943 | As your collection of doctest'ed modules grows, you'll want a way to run all |
Georg Brandl | 3183585 | 2008-05-12 17:38:56 +0000 | [diff] [blame] | 944 | their doctests systematically. :mod:`doctest` provides two functions that can |
| 945 | be used to create :mod:`unittest` test suites from modules and text files |
Georg Brandl | a851483 | 2010-07-10 12:20:38 +0000 | [diff] [blame] | 946 | containing doctests. To integrate with :mod:`unittest` test discovery, include |
| 947 | a :func:`load_tests` function in your test module:: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 948 | |
| 949 | import unittest |
| 950 | import doctest |
Georg Brandl | a851483 | 2010-07-10 12:20:38 +0000 | [diff] [blame] | 951 | import my_module_with_doctests |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 952 | |
Georg Brandl | a851483 | 2010-07-10 12:20:38 +0000 | [diff] [blame] | 953 | def load_tests(loader, tests, ignore): |
| 954 | tests.addTests(doctest.DocTestSuite(my_module_with_doctests)) |
R. David Murray | 796343b | 2010-12-13 22:50:30 +0000 | [diff] [blame] | 955 | return tests |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 956 | |
| 957 | There are two main functions for creating :class:`unittest.TestSuite` instances |
| 958 | from text files and modules with doctests: |
| 959 | |
| 960 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 961 | .. function:: DocFileSuite(*paths, module_relative=True, package=None, setUp=None, tearDown=None, globs=None, optionflags=0, parser=DocTestParser(), encoding=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 962 | |
| 963 | Convert doctest tests from one or more text files to a |
| 964 | :class:`unittest.TestSuite`. |
| 965 | |
| 966 | The returned :class:`unittest.TestSuite` is to be run by the unittest framework |
| 967 | and runs the interactive examples in each file. If an example in any file |
| 968 | fails, then the synthesized unit test fails, and a :exc:`failureException` |
| 969 | exception is raised showing the name of the file containing the test and a |
| 970 | (sometimes approximate) line number. |
| 971 | |
| 972 | Pass one or more paths (as strings) to text files to be examined. |
| 973 | |
| 974 | Options may be provided as keyword arguments: |
| 975 | |
| 976 | Optional argument *module_relative* specifies how the filenames in *paths* |
| 977 | should be interpreted: |
| 978 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 979 | * If *module_relative* is ``True`` (the default), then each filename in |
| 980 | *paths* specifies an OS-independent module-relative path. By default, this |
| 981 | path is relative to the calling module's directory; but if the *package* |
| 982 | argument is specified, then it is relative to that package. To ensure |
| 983 | OS-independence, each filename should use ``/`` characters to separate path |
| 984 | segments, and may not be an absolute path (i.e., it may not begin with |
| 985 | ``/``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 986 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 987 | * If *module_relative* is ``False``, then each filename in *paths* specifies |
| 988 | an OS-specific path. The path may be absolute or relative; relative paths |
| 989 | are resolved with respect to the current working directory. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 990 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 991 | Optional argument *package* is a Python package or the name of a Python |
| 992 | package whose directory should be used as the base directory for |
| 993 | module-relative filenames in *paths*. If no package is specified, then the |
| 994 | calling module's directory is used as the base directory for module-relative |
| 995 | filenames. It is an error to specify *package* if *module_relative* is |
| 996 | ``False``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 997 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 998 | Optional argument *setUp* specifies a set-up function for the test suite. |
| 999 | This is called before running the tests in each file. The *setUp* function |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1000 | will be passed a :class:`DocTest` object. The setUp function can access the |
| 1001 | test globals as the *globs* attribute of the test passed. |
| 1002 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 1003 | Optional argument *tearDown* specifies a tear-down function for the test |
| 1004 | suite. This is called after running the tests in each file. The *tearDown* |
| 1005 | function will be passed a :class:`DocTest` object. The setUp function can |
| 1006 | access the test globals as the *globs* attribute of the test passed. |
| 1007 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1008 | Optional argument *globs* is a dictionary containing the initial global |
| 1009 | variables for the tests. A new copy of this dictionary is created for each |
| 1010 | test. By default, *globs* is a new empty dictionary. |
| 1011 | |
| 1012 | Optional argument *optionflags* specifies the default doctest options for the |
| 1013 | tests, created by or-ing together individual option flags. See section |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 1014 | :ref:`doctest-options`. See function :func:`set_unittest_reportflags` below |
| 1015 | for a better way to set reporting options. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1016 | |
Benjamin Peterson | d23f822 | 2009-04-05 19:13:16 +0000 | [diff] [blame] | 1017 | Optional argument *parser* specifies a :class:`DocTestParser` (or subclass) |
| 1018 | that should be used to extract tests from the files. It defaults to a normal |
| 1019 | parser (i.e., ``DocTestParser()``). |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1020 | |
| 1021 | Optional argument *encoding* specifies an encoding that should be used to |
| 1022 | convert the file to unicode. |
| 1023 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 1024 | The global ``__file__`` is added to the globals provided to doctests loaded |
| 1025 | from a text file using :func:`DocFileSuite`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1026 | |
| 1027 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1028 | .. function:: DocTestSuite(module=None, globs=None, extraglobs=None, test_finder=None, setUp=None, tearDown=None, checker=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1029 | |
| 1030 | Convert doctest tests for a module to a :class:`unittest.TestSuite`. |
| 1031 | |
| 1032 | The returned :class:`unittest.TestSuite` is to be run by the unittest framework |
| 1033 | and runs each doctest in the module. If any of the doctests fail, then the |
| 1034 | synthesized unit test fails, and a :exc:`failureException` exception is raised |
| 1035 | showing the name of the file containing the test and a (sometimes approximate) |
| 1036 | line number. |
| 1037 | |
| 1038 | Optional argument *module* provides the module to be tested. It can be a module |
| 1039 | object or a (possibly dotted) module name. If not specified, the module calling |
| 1040 | this function is used. |
| 1041 | |
| 1042 | Optional argument *globs* is a dictionary containing the initial global |
| 1043 | variables for the tests. A new copy of this dictionary is created for each |
| 1044 | test. By default, *globs* is a new empty dictionary. |
| 1045 | |
| 1046 | Optional argument *extraglobs* specifies an extra set of global variables, which |
| 1047 | is merged into *globs*. By default, no extra globals are used. |
| 1048 | |
| 1049 | Optional argument *test_finder* is the :class:`DocTestFinder` object (or a |
| 1050 | drop-in replacement) that is used to extract doctests from the module. |
| 1051 | |
| 1052 | Optional arguments *setUp*, *tearDown*, and *optionflags* are the same as for |
| 1053 | function :func:`DocFileSuite` above. |
| 1054 | |
Georg Brandl | 55ac8f0 | 2007-09-01 13:51:09 +0000 | [diff] [blame] | 1055 | This function uses the same search technique as :func:`testmod`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1056 | |
R David Murray | 5abd76a | 2012-09-10 10:15:58 -0400 | [diff] [blame] | 1057 | .. note:: |
| 1058 | Unlike :func:`testmod` and :class:`DocTestFinder`, this function raises |
| 1059 | a :exc:`ValueError` if *module* contains no docstrings. You can prevent |
| 1060 | this error by passing a :class:`DocTestFinder` instance as the |
| 1061 | *test_finder* argument with its *exclude_empty* keyword argument set |
| 1062 | to ``False``:: |
| 1063 | |
| 1064 | >>> finder = doctest.DocTestFinder(exclude_empty=False) |
| 1065 | >>> suite = doctest.DocTestSuite(test_finder=finder) |
| 1066 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1067 | |
| 1068 | Under the covers, :func:`DocTestSuite` creates a :class:`unittest.TestSuite` out |
| 1069 | of :class:`doctest.DocTestCase` instances, and :class:`DocTestCase` is a |
| 1070 | subclass of :class:`unittest.TestCase`. :class:`DocTestCase` isn't documented |
| 1071 | here (it's an internal detail), but studying its code can answer questions about |
| 1072 | the exact details of :mod:`unittest` integration. |
| 1073 | |
| 1074 | Similarly, :func:`DocFileSuite` creates a :class:`unittest.TestSuite` out of |
| 1075 | :class:`doctest.DocFileCase` instances, and :class:`DocFileCase` is a subclass |
| 1076 | of :class:`DocTestCase`. |
| 1077 | |
| 1078 | So both ways of creating a :class:`unittest.TestSuite` run instances of |
| 1079 | :class:`DocTestCase`. This is important for a subtle reason: when you run |
| 1080 | :mod:`doctest` functions yourself, you can control the :mod:`doctest` options in |
| 1081 | use directly, by passing option flags to :mod:`doctest` functions. However, if |
| 1082 | you're writing a :mod:`unittest` framework, :mod:`unittest` ultimately controls |
| 1083 | when and how tests get run. The framework author typically wants to control |
| 1084 | :mod:`doctest` reporting options (perhaps, e.g., specified by command line |
| 1085 | options), but there's no way to pass options through :mod:`unittest` to |
| 1086 | :mod:`doctest` test runners. |
| 1087 | |
| 1088 | For this reason, :mod:`doctest` also supports a notion of :mod:`doctest` |
| 1089 | reporting flags specific to :mod:`unittest` support, via this function: |
| 1090 | |
| 1091 | |
| 1092 | .. function:: set_unittest_reportflags(flags) |
| 1093 | |
| 1094 | Set the :mod:`doctest` reporting flags to use. |
| 1095 | |
| 1096 | Argument *flags* or's together option flags. See section |
| 1097 | :ref:`doctest-options`. Only "reporting flags" can be used. |
| 1098 | |
| 1099 | This is a module-global setting, and affects all future doctests run by module |
| 1100 | :mod:`unittest`: the :meth:`runTest` method of :class:`DocTestCase` looks at |
| 1101 | the option flags specified for the test case when the :class:`DocTestCase` |
| 1102 | instance was constructed. If no reporting flags were specified (which is the |
| 1103 | typical and expected case), :mod:`doctest`'s :mod:`unittest` reporting flags are |
| 1104 | or'ed into the option flags, and the option flags so augmented are passed to the |
| 1105 | :class:`DocTestRunner` instance created to run the doctest. If any reporting |
| 1106 | flags were specified when the :class:`DocTestCase` instance was constructed, |
| 1107 | :mod:`doctest`'s :mod:`unittest` reporting flags are ignored. |
| 1108 | |
| 1109 | The value of the :mod:`unittest` reporting flags in effect before the function |
| 1110 | was called is returned by the function. |
| 1111 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1112 | |
| 1113 | .. _doctest-advanced-api: |
| 1114 | |
| 1115 | Advanced API |
| 1116 | ------------ |
| 1117 | |
| 1118 | The basic API is a simple wrapper that's intended to make doctest easy to use. |
| 1119 | It is fairly flexible, and should meet most users' needs; however, if you |
| 1120 | require more fine-grained control over testing, or wish to extend doctest's |
| 1121 | capabilities, then you should use the advanced API. |
| 1122 | |
| 1123 | The advanced API revolves around two container classes, which are used to store |
| 1124 | the interactive examples extracted from doctest cases: |
| 1125 | |
Ezio Melotti | 0639d5a | 2009-12-19 23:26:38 +0000 | [diff] [blame] | 1126 | * :class:`Example`: A single Python :term:`statement`, paired with its expected |
Christian Heimes | d8654cf | 2007-12-02 15:22:16 +0000 | [diff] [blame] | 1127 | output. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1128 | |
| 1129 | * :class:`DocTest`: A collection of :class:`Example`\ s, typically extracted |
| 1130 | from a single docstring or text file. |
| 1131 | |
| 1132 | Additional processing classes are defined to find, parse, and run, and check |
| 1133 | doctest examples: |
| 1134 | |
| 1135 | * :class:`DocTestFinder`: Finds all docstrings in a given module, and uses a |
| 1136 | :class:`DocTestParser` to create a :class:`DocTest` from every docstring that |
| 1137 | contains interactive examples. |
| 1138 | |
| 1139 | * :class:`DocTestParser`: Creates a :class:`DocTest` object from a string (such |
| 1140 | as an object's docstring). |
| 1141 | |
| 1142 | * :class:`DocTestRunner`: Executes the examples in a :class:`DocTest`, and uses |
| 1143 | an :class:`OutputChecker` to verify their output. |
| 1144 | |
| 1145 | * :class:`OutputChecker`: Compares the actual output from a doctest example with |
| 1146 | the expected output, and decides whether they match. |
| 1147 | |
| 1148 | The relationships among these processing classes are summarized in the following |
| 1149 | diagram:: |
| 1150 | |
| 1151 | list of: |
| 1152 | +------+ +---------+ |
| 1153 | |module| --DocTestFinder-> | DocTest | --DocTestRunner-> results |
| 1154 | +------+ | ^ +---------+ | ^ (printed) |
| 1155 | | | | Example | | | |
| 1156 | v | | ... | v | |
| 1157 | DocTestParser | Example | OutputChecker |
| 1158 | +---------+ |
| 1159 | |
| 1160 | |
| 1161 | .. _doctest-doctest: |
| 1162 | |
| 1163 | DocTest Objects |
| 1164 | ^^^^^^^^^^^^^^^ |
| 1165 | |
| 1166 | |
| 1167 | .. class:: DocTest(examples, globs, name, filename, lineno, docstring) |
| 1168 | |
| 1169 | A collection of doctest examples that should be run in a single namespace. The |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1170 | constructor arguments are used to initialize the attributes of the same names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1171 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1172 | |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1173 | :class:`DocTest` defines the following attributes. They are initialized by |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1174 | the constructor, and should not be modified directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1175 | |
| 1176 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1177 | .. attribute:: examples |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1178 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1179 | A list of :class:`Example` objects encoding the individual interactive Python |
| 1180 | examples that should be run by this test. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1181 | |
| 1182 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1183 | .. attribute:: globs |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1184 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1185 | The namespace (aka globals) that the examples should be run in. This is a |
| 1186 | dictionary mapping names to values. Any changes to the namespace made by the |
| 1187 | examples (such as binding new variables) will be reflected in :attr:`globs` |
| 1188 | after the test is run. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1189 | |
| 1190 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1191 | .. attribute:: name |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1192 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1193 | A string name identifying the :class:`DocTest`. Typically, this is the name |
| 1194 | of the object or file that the test was extracted from. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1195 | |
| 1196 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1197 | .. attribute:: filename |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1198 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1199 | The name of the file that this :class:`DocTest` was extracted from; or |
| 1200 | ``None`` if the filename is unknown, or if the :class:`DocTest` was not |
| 1201 | extracted from a file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1202 | |
| 1203 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1204 | .. attribute:: lineno |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1205 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1206 | The line number within :attr:`filename` where this :class:`DocTest` begins, or |
| 1207 | ``None`` if the line number is unavailable. This line number is zero-based |
| 1208 | with respect to the beginning of the file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1209 | |
| 1210 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1211 | .. attribute:: docstring |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1212 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1213 | The string that the test was extracted from, or 'None' if the string is |
| 1214 | unavailable, or if the test was not extracted from a string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1215 | |
| 1216 | |
| 1217 | .. _doctest-example: |
| 1218 | |
| 1219 | Example Objects |
| 1220 | ^^^^^^^^^^^^^^^ |
| 1221 | |
| 1222 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1223 | .. class:: Example(source, want, exc_msg=None, lineno=0, indent=0, options=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1224 | |
| 1225 | A single interactive example, consisting of a Python statement and its expected |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1226 | output. The constructor arguments are used to initialize the attributes of |
| 1227 | the same names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1228 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1229 | |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1230 | :class:`Example` defines the following attributes. They are initialized by |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1231 | the constructor, and should not be modified directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1232 | |
| 1233 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1234 | .. attribute:: source |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1235 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1236 | A string containing the example's source code. This source code consists of a |
| 1237 | single Python statement, and always ends with a newline; the constructor adds |
| 1238 | a newline when necessary. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1239 | |
| 1240 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1241 | .. attribute:: want |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1242 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1243 | The expected output from running the example's source code (either from |
| 1244 | stdout, or a traceback in case of exception). :attr:`want` ends with a |
| 1245 | newline unless no output is expected, in which case it's an empty string. The |
| 1246 | constructor adds a newline when necessary. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1247 | |
| 1248 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1249 | .. attribute:: exc_msg |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1250 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1251 | The exception message generated by the example, if the example is expected to |
| 1252 | generate an exception; or ``None`` if it is not expected to generate an |
| 1253 | exception. This exception message is compared against the return value of |
| 1254 | :func:`traceback.format_exception_only`. :attr:`exc_msg` ends with a newline |
| 1255 | unless it's ``None``. The constructor adds a newline if needed. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1256 | |
| 1257 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1258 | .. attribute:: lineno |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1259 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1260 | The line number within the string containing this example where the example |
| 1261 | begins. This line number is zero-based with respect to the beginning of the |
| 1262 | containing string. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1263 | |
| 1264 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1265 | .. attribute:: indent |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1266 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1267 | The example's indentation in the containing string, i.e., the number of space |
| 1268 | characters that precede the example's first prompt. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1269 | |
| 1270 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1271 | .. attribute:: options |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1272 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1273 | A dictionary mapping from option flags to ``True`` or ``False``, which is used |
| 1274 | to override default options for this example. Any option flags not contained |
| 1275 | in this dictionary are left at their default value (as specified by the |
| 1276 | :class:`DocTestRunner`'s :attr:`optionflags`). By default, no options are set. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1277 | |
| 1278 | |
| 1279 | .. _doctest-doctestfinder: |
| 1280 | |
| 1281 | DocTestFinder objects |
| 1282 | ^^^^^^^^^^^^^^^^^^^^^ |
| 1283 | |
| 1284 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1285 | .. class:: DocTestFinder(verbose=False, parser=DocTestParser(), recurse=True, exclude_empty=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1286 | |
| 1287 | A processing class used to extract the :class:`DocTest`\ s that are relevant to |
| 1288 | a given object, from its docstring and the docstrings of its contained objects. |
| 1289 | :class:`DocTest`\ s can currently be extracted from the following object types: |
| 1290 | modules, functions, classes, methods, staticmethods, classmethods, and |
| 1291 | properties. |
| 1292 | |
| 1293 | The optional argument *verbose* can be used to display the objects searched by |
| 1294 | the finder. It defaults to ``False`` (no output). |
| 1295 | |
| 1296 | The optional argument *parser* specifies the :class:`DocTestParser` object (or a |
| 1297 | drop-in replacement) that is used to extract doctests from docstrings. |
| 1298 | |
| 1299 | If the optional argument *recurse* is false, then :meth:`DocTestFinder.find` |
| 1300 | will only examine the given object, and not any contained objects. |
| 1301 | |
| 1302 | If the optional argument *exclude_empty* is false, then |
| 1303 | :meth:`DocTestFinder.find` will include tests for objects with empty docstrings. |
| 1304 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1305 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1306 | :class:`DocTestFinder` defines the following method: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1307 | |
| 1308 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1309 | .. method:: find(obj[, name][, module][, globs][, extraglobs]) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1310 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1311 | Return a list of the :class:`DocTest`\ s that are defined by *obj*'s |
| 1312 | docstring, or by any of its contained objects' docstrings. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1313 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1314 | The optional argument *name* specifies the object's name; this name will be |
| 1315 | used to construct names for the returned :class:`DocTest`\ s. If *name* is |
| 1316 | not specified, then ``obj.__name__`` is used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1317 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1318 | The optional parameter *module* is the module that contains the given object. |
| 1319 | If the module is not specified or is None, then the test finder will attempt |
| 1320 | to automatically determine the correct module. The object's module is used: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1321 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1322 | * As a default namespace, if *globs* is not specified. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1323 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1324 | * To prevent the DocTestFinder from extracting DocTests from objects that are |
| 1325 | imported from other modules. (Contained objects with modules other than |
| 1326 | *module* are ignored.) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1327 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1328 | * To find the name of the file containing the object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1329 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1330 | * To help find the line number of the object within its file. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1331 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1332 | If *module* is ``False``, no attempt to find the module will be made. This is |
| 1333 | obscure, of use mostly in testing doctest itself: if *module* is ``False``, or |
| 1334 | is ``None`` but cannot be found automatically, then all objects are considered |
| 1335 | to belong to the (non-existent) module, so all contained objects will |
| 1336 | (recursively) be searched for doctests. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1337 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1338 | The globals for each :class:`DocTest` is formed by combining *globs* and |
| 1339 | *extraglobs* (bindings in *extraglobs* override bindings in *globs*). A new |
| 1340 | shallow copy of the globals dictionary is created for each :class:`DocTest`. |
| 1341 | If *globs* is not specified, then it defaults to the module's *__dict__*, if |
| 1342 | specified, or ``{}`` otherwise. If *extraglobs* is not specified, then it |
| 1343 | defaults to ``{}``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1344 | |
| 1345 | |
| 1346 | .. _doctest-doctestparser: |
| 1347 | |
| 1348 | DocTestParser objects |
| 1349 | ^^^^^^^^^^^^^^^^^^^^^ |
| 1350 | |
| 1351 | |
| 1352 | .. class:: DocTestParser() |
| 1353 | |
| 1354 | A processing class used to extract interactive examples from a string, and use |
| 1355 | them to create a :class:`DocTest` object. |
| 1356 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1357 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1358 | :class:`DocTestParser` defines the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1359 | |
| 1360 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1361 | .. method:: get_doctest(string, globs, name, filename, lineno) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1362 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1363 | Extract all doctest examples from the given string, and collect them into a |
| 1364 | :class:`DocTest` object. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1365 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1366 | *globs*, *name*, *filename*, and *lineno* are attributes for the new |
| 1367 | :class:`DocTest` object. See the documentation for :class:`DocTest` for more |
| 1368 | information. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1369 | |
| 1370 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1371 | .. method:: get_examples(string, name='<string>') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1372 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1373 | Extract all doctest examples from the given string, and return them as a list |
| 1374 | of :class:`Example` objects. Line numbers are 0-based. The optional argument |
| 1375 | *name* is a name identifying this string, and is only used for error messages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1376 | |
| 1377 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1378 | .. method:: parse(string, name='<string>') |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1379 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1380 | Divide the given string into examples and intervening text, and return them as |
| 1381 | a list of alternating :class:`Example`\ s and strings. Line numbers for the |
| 1382 | :class:`Example`\ s are 0-based. The optional argument *name* is a name |
| 1383 | identifying this string, and is only used for error messages. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1384 | |
| 1385 | |
| 1386 | .. _doctest-doctestrunner: |
| 1387 | |
| 1388 | DocTestRunner objects |
| 1389 | ^^^^^^^^^^^^^^^^^^^^^ |
| 1390 | |
| 1391 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1392 | .. class:: DocTestRunner(checker=None, verbose=None, optionflags=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1393 | |
| 1394 | A processing class used to execute and verify the interactive examples in a |
| 1395 | :class:`DocTest`. |
| 1396 | |
| 1397 | The comparison between expected outputs and actual outputs is done by an |
| 1398 | :class:`OutputChecker`. This comparison may be customized with a number of |
| 1399 | option flags; see section :ref:`doctest-options` for more information. If the |
| 1400 | option flags are insufficient, then the comparison may also be customized by |
| 1401 | passing a subclass of :class:`OutputChecker` to the constructor. |
| 1402 | |
| 1403 | The test runner's display output can be controlled in two ways. First, an output |
| 1404 | function can be passed to :meth:`TestRunner.run`; this function will be called |
| 1405 | with strings that should be displayed. It defaults to ``sys.stdout.write``. If |
| 1406 | capturing the output is not sufficient, then the display output can be also |
| 1407 | customized by subclassing DocTestRunner, and overriding the methods |
| 1408 | :meth:`report_start`, :meth:`report_success`, |
| 1409 | :meth:`report_unexpected_exception`, and :meth:`report_failure`. |
| 1410 | |
| 1411 | The optional keyword argument *checker* specifies the :class:`OutputChecker` |
| 1412 | object (or drop-in replacement) that should be used to compare the expected |
| 1413 | outputs to the actual outputs of doctest examples. |
| 1414 | |
| 1415 | The optional keyword argument *verbose* controls the :class:`DocTestRunner`'s |
| 1416 | verbosity. If *verbose* is ``True``, then information is printed about each |
| 1417 | example, as it is run. If *verbose* is ``False``, then only failures are |
| 1418 | printed. If *verbose* is unspecified, or ``None``, then verbose output is used |
Éric Araujo | 713d303 | 2010-11-18 16:38:46 +0000 | [diff] [blame] | 1419 | iff the command-line switch ``-v`` is used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1420 | |
| 1421 | The optional keyword argument *optionflags* can be used to control how the test |
| 1422 | runner compares expected output to actual output, and how it displays failures. |
| 1423 | For more information, see section :ref:`doctest-options`. |
| 1424 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1425 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1426 | :class:`DocTestParser` defines the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1427 | |
| 1428 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1429 | .. method:: report_start(out, test, example) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1430 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1431 | Report that the test runner is about to process the given example. This method |
| 1432 | is provided to allow subclasses of :class:`DocTestRunner` to customize their |
| 1433 | output; it should not be called directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1434 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1435 | *example* is the example about to be processed. *test* is the test |
| 1436 | *containing example*. *out* is the output function that was passed to |
| 1437 | :meth:`DocTestRunner.run`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1438 | |
| 1439 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1440 | .. method:: report_success(out, test, example, got) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1441 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1442 | Report that the given example ran successfully. This method is provided to |
| 1443 | allow subclasses of :class:`DocTestRunner` to customize their output; it |
| 1444 | should not be called directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1445 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1446 | *example* is the example about to be processed. *got* is the actual output |
| 1447 | from the example. *test* is the test containing *example*. *out* is the |
| 1448 | output function that was passed to :meth:`DocTestRunner.run`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1449 | |
| 1450 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1451 | .. method:: report_failure(out, test, example, got) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1452 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1453 | Report that the given example failed. This method is provided to allow |
| 1454 | subclasses of :class:`DocTestRunner` to customize their output; it should not |
| 1455 | be called directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1456 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1457 | *example* is the example about to be processed. *got* is the actual output |
| 1458 | from the example. *test* is the test containing *example*. *out* is the |
| 1459 | output function that was passed to :meth:`DocTestRunner.run`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1460 | |
| 1461 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1462 | .. method:: report_unexpected_exception(out, test, example, exc_info) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1463 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1464 | Report that the given example raised an unexpected exception. This method is |
| 1465 | provided to allow subclasses of :class:`DocTestRunner` to customize their |
| 1466 | output; it should not be called directly. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1467 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1468 | *example* is the example about to be processed. *exc_info* is a tuple |
| 1469 | containing information about the unexpected exception (as returned by |
| 1470 | :func:`sys.exc_info`). *test* is the test containing *example*. *out* is the |
| 1471 | output function that was passed to :meth:`DocTestRunner.run`. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1472 | |
| 1473 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1474 | .. method:: run(test, compileflags=None, out=None, clear_globs=True) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1475 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1476 | Run the examples in *test* (a :class:`DocTest` object), and display the |
| 1477 | results using the writer function *out*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1478 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1479 | The examples are run in the namespace ``test.globs``. If *clear_globs* is |
| 1480 | true (the default), then this namespace will be cleared after the test runs, |
| 1481 | to help with garbage collection. If you would like to examine the namespace |
| 1482 | after the test completes, then use *clear_globs=False*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1483 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1484 | *compileflags* gives the set of flags that should be used by the Python |
| 1485 | compiler when running the examples. If not specified, then it will default to |
| 1486 | the set of future-import flags that apply to *globs*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1487 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1488 | The output of each example is checked using the :class:`DocTestRunner`'s |
| 1489 | output checker, and the results are formatted by the |
| 1490 | :meth:`DocTestRunner.report_\*` methods. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1491 | |
| 1492 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1493 | .. method:: summarize(verbose=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1494 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1495 | Print a summary of all the test cases that have been run by this DocTestRunner, |
| 1496 | and return a :term:`named tuple` ``TestResults(failed, attempted)``. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1497 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1498 | The optional *verbose* argument controls how detailed the summary is. If the |
| 1499 | verbosity is not specified, then the :class:`DocTestRunner`'s verbosity is |
| 1500 | used. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1501 | |
| 1502 | .. _doctest-outputchecker: |
| 1503 | |
| 1504 | OutputChecker objects |
| 1505 | ^^^^^^^^^^^^^^^^^^^^^ |
| 1506 | |
| 1507 | |
| 1508 | .. class:: OutputChecker() |
| 1509 | |
| 1510 | A class used to check the whether the actual output from a doctest example |
| 1511 | matches the expected output. :class:`OutputChecker` defines two methods: |
| 1512 | :meth:`check_output`, which compares a given pair of outputs, and returns true |
| 1513 | if they match; and :meth:`output_difference`, which returns a string describing |
| 1514 | the differences between two outputs. |
| 1515 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1516 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1517 | :class:`OutputChecker` defines the following methods: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1518 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1519 | .. method:: check_output(want, got, optionflags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1520 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1521 | Return ``True`` iff the actual output from an example (*got*) matches the |
| 1522 | expected output (*want*). These strings are always considered to match if |
| 1523 | they are identical; but depending on what option flags the test runner is |
| 1524 | using, several non-exact match types are also possible. See section |
| 1525 | :ref:`doctest-options` for more information about option flags. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1526 | |
| 1527 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1528 | .. method:: output_difference(example, got, optionflags) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1529 | |
Benjamin Peterson | e41251e | 2008-04-25 01:59:09 +0000 | [diff] [blame] | 1530 | Return a string describing the differences between the expected output for a |
| 1531 | given example (*example*) and the actual output (*got*). *optionflags* is the |
| 1532 | set of option flags used to compare *want* and *got*. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1533 | |
| 1534 | |
| 1535 | .. _doctest-debugging: |
| 1536 | |
| 1537 | Debugging |
| 1538 | --------- |
| 1539 | |
| 1540 | Doctest provides several mechanisms for debugging doctest examples: |
| 1541 | |
| 1542 | * Several functions convert doctests to executable Python programs, which can be |
| 1543 | run under the Python debugger, :mod:`pdb`. |
| 1544 | |
| 1545 | * The :class:`DebugRunner` class is a subclass of :class:`DocTestRunner` that |
| 1546 | raises an exception for the first failing example, containing information about |
| 1547 | that example. This information can be used to perform post-mortem debugging on |
| 1548 | the example. |
| 1549 | |
| 1550 | * The :mod:`unittest` cases generated by :func:`DocTestSuite` support the |
| 1551 | :meth:`debug` method defined by :class:`unittest.TestCase`. |
| 1552 | |
| 1553 | * You can add a call to :func:`pdb.set_trace` in a doctest example, and you'll |
| 1554 | drop into the Python debugger when that line is executed. Then you can inspect |
| 1555 | current values of variables, and so on. For example, suppose :file:`a.py` |
| 1556 | contains just this module docstring:: |
| 1557 | |
| 1558 | """ |
| 1559 | >>> def f(x): |
| 1560 | ... g(x*2) |
| 1561 | >>> def g(x): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1562 | ... print(x+3) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1563 | ... import pdb; pdb.set_trace() |
| 1564 | >>> f(3) |
| 1565 | 9 |
| 1566 | """ |
| 1567 | |
| 1568 | Then an interactive Python session may look like this:: |
| 1569 | |
| 1570 | >>> import a, doctest |
| 1571 | >>> doctest.testmod(a) |
| 1572 | --Return-- |
| 1573 | > <doctest a[1]>(3)g()->None |
| 1574 | -> import pdb; pdb.set_trace() |
| 1575 | (Pdb) list |
| 1576 | 1 def g(x): |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1577 | 2 print(x+3) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1578 | 3 -> import pdb; pdb.set_trace() |
| 1579 | [EOF] |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1580 | (Pdb) p x |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1581 | 6 |
| 1582 | (Pdb) step |
| 1583 | --Return-- |
| 1584 | > <doctest a[0]>(2)f()->None |
| 1585 | -> g(x*2) |
| 1586 | (Pdb) list |
| 1587 | 1 def f(x): |
| 1588 | 2 -> g(x*2) |
| 1589 | [EOF] |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1590 | (Pdb) p x |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1591 | 3 |
| 1592 | (Pdb) step |
| 1593 | --Return-- |
| 1594 | > <doctest a[2]>(1)?()->None |
| 1595 | -> f(3) |
| 1596 | (Pdb) cont |
| 1597 | (0, 3) |
| 1598 | >>> |
| 1599 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1600 | |
| 1601 | Functions that convert doctests to Python code, and possibly run the synthesized |
| 1602 | code under the debugger: |
| 1603 | |
| 1604 | |
| 1605 | .. function:: script_from_examples(s) |
| 1606 | |
| 1607 | Convert text with examples to a script. |
| 1608 | |
| 1609 | Argument *s* is a string containing doctest examples. The string is converted |
| 1610 | to a Python script, where doctest examples in *s* are converted to regular code, |
| 1611 | and everything else is converted to Python comments. The generated script is |
| 1612 | returned as a string. For example, :: |
| 1613 | |
| 1614 | import doctest |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1615 | print(doctest.script_from_examples(r""" |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1616 | Set x and y to 1 and 2. |
| 1617 | >>> x, y = 1, 2 |
| 1618 | |
| 1619 | Print their sum: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1620 | >>> print(x+y) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1621 | 3 |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1622 | """)) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1623 | |
| 1624 | displays:: |
| 1625 | |
| 1626 | # Set x and y to 1 and 2. |
| 1627 | x, y = 1, 2 |
| 1628 | # |
| 1629 | # Print their sum: |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1630 | print(x+y) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1631 | # Expected: |
| 1632 | ## 3 |
| 1633 | |
| 1634 | This function is used internally by other functions (see below), but can also be |
| 1635 | useful when you want to transform an interactive Python session into a Python |
| 1636 | script. |
| 1637 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1638 | |
| 1639 | .. function:: testsource(module, name) |
| 1640 | |
| 1641 | Convert the doctest for an object to a script. |
| 1642 | |
| 1643 | Argument *module* is a module object, or dotted name of a module, containing the |
| 1644 | object whose doctests are of interest. Argument *name* is the name (within the |
| 1645 | module) of the object with the doctests of interest. The result is a string, |
| 1646 | containing the object's docstring converted to a Python script, as described for |
| 1647 | :func:`script_from_examples` above. For example, if module :file:`a.py` |
| 1648 | contains a top-level function :func:`f`, then :: |
| 1649 | |
| 1650 | import a, doctest |
Georg Brandl | 6911e3c | 2007-09-04 07:15:32 +0000 | [diff] [blame] | 1651 | print(doctest.testsource(a, "a.f")) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1652 | |
| 1653 | prints a script version of function :func:`f`'s docstring, with doctests |
| 1654 | converted to code, and the rest placed in comments. |
| 1655 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1656 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1657 | .. function:: debug(module, name, pm=False) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1658 | |
| 1659 | Debug the doctests for an object. |
| 1660 | |
| 1661 | The *module* and *name* arguments are the same as for function |
| 1662 | :func:`testsource` above. The synthesized Python script for the named object's |
| 1663 | docstring is written to a temporary file, and then that file is run under the |
| 1664 | control of the Python debugger, :mod:`pdb`. |
| 1665 | |
| 1666 | A shallow copy of ``module.__dict__`` is used for both local and global |
| 1667 | execution context. |
| 1668 | |
| 1669 | Optional argument *pm* controls whether post-mortem debugging is used. If *pm* |
| 1670 | has a true value, the script file is run directly, and the debugger gets |
| 1671 | involved only if the script terminates via raising an unhandled exception. If |
| 1672 | it does, then post-mortem debugging is invoked, via :func:`pdb.post_mortem`, |
| 1673 | passing the traceback object from the unhandled exception. If *pm* is not |
| 1674 | specified, or is false, the script is run under the debugger from the start, via |
| 1675 | passing an appropriate :func:`exec` call to :func:`pdb.run`. |
| 1676 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1677 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1678 | .. function:: debug_src(src, pm=False, globs=None) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1679 | |
| 1680 | Debug the doctests in a string. |
| 1681 | |
| 1682 | This is like function :func:`debug` above, except that a string containing |
| 1683 | doctest examples is specified directly, via the *src* argument. |
| 1684 | |
| 1685 | Optional argument *pm* has the same meaning as in function :func:`debug` above. |
| 1686 | |
| 1687 | Optional argument *globs* gives a dictionary to use as both local and global |
| 1688 | execution context. If not specified, or ``None``, an empty dictionary is used. |
| 1689 | If specified, a shallow copy of the dictionary is used. |
| 1690 | |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1691 | |
| 1692 | The :class:`DebugRunner` class, and the special exceptions it may raise, are of |
| 1693 | most interest to testing framework authors, and will only be sketched here. See |
| 1694 | the source code, and especially :class:`DebugRunner`'s docstring (which is a |
| 1695 | doctest!) for more details: |
| 1696 | |
| 1697 | |
Georg Brandl | c2a4f4f | 2009-04-10 09:03:43 +0000 | [diff] [blame] | 1698 | .. class:: DebugRunner(checker=None, verbose=None, optionflags=0) |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1699 | |
| 1700 | A subclass of :class:`DocTestRunner` that raises an exception as soon as a |
| 1701 | failure is encountered. If an unexpected exception occurs, an |
| 1702 | :exc:`UnexpectedException` exception is raised, containing the test, the |
| 1703 | example, and the original exception. If the output doesn't match, then a |
| 1704 | :exc:`DocTestFailure` exception is raised, containing the test, the example, and |
| 1705 | the actual output. |
| 1706 | |
| 1707 | For information about the constructor parameters and methods, see the |
| 1708 | documentation for :class:`DocTestRunner` in section :ref:`doctest-advanced-api`. |
| 1709 | |
| 1710 | There are two exceptions that may be raised by :class:`DebugRunner` instances: |
| 1711 | |
| 1712 | |
| 1713 | .. exception:: DocTestFailure(test, example, got) |
| 1714 | |
Georg Brandl | 7cb1319 | 2010-08-03 12:06:29 +0000 | [diff] [blame] | 1715 | An exception raised by :class:`DocTestRunner` to signal that a doctest example's |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1716 | actual output did not match its expected output. The constructor arguments are |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1717 | used to initialize the attributes of the same names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1718 | |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1719 | :exc:`DocTestFailure` defines the following attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1720 | |
| 1721 | |
| 1722 | .. attribute:: DocTestFailure.test |
| 1723 | |
| 1724 | The :class:`DocTest` object that was being run when the example failed. |
| 1725 | |
| 1726 | |
| 1727 | .. attribute:: DocTestFailure.example |
| 1728 | |
| 1729 | The :class:`Example` that failed. |
| 1730 | |
| 1731 | |
| 1732 | .. attribute:: DocTestFailure.got |
| 1733 | |
| 1734 | The example's actual output. |
| 1735 | |
| 1736 | |
| 1737 | .. exception:: UnexpectedException(test, example, exc_info) |
| 1738 | |
Georg Brandl | 7cb1319 | 2010-08-03 12:06:29 +0000 | [diff] [blame] | 1739 | An exception raised by :class:`DocTestRunner` to signal that a doctest |
| 1740 | example raised an unexpected exception. The constructor arguments are used |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1741 | to initialize the attributes of the same names. |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1742 | |
Senthil Kumaran | a6bac95 | 2011-07-04 11:28:30 -0700 | [diff] [blame] | 1743 | :exc:`UnexpectedException` defines the following attributes: |
Georg Brandl | 116aa62 | 2007-08-15 14:28:22 +0000 | [diff] [blame] | 1744 | |
| 1745 | |
| 1746 | .. attribute:: UnexpectedException.test |
| 1747 | |
| 1748 | The :class:`DocTest` object that was being run when the example failed. |
| 1749 | |
| 1750 | |
| 1751 | .. attribute:: UnexpectedException.example |
| 1752 | |
| 1753 | The :class:`Example` that failed. |
| 1754 | |
| 1755 | |
| 1756 | .. attribute:: UnexpectedException.exc_info |
| 1757 | |
| 1758 | A tuple containing information about the unexpected exception, as returned by |
| 1759 | :func:`sys.exc_info`. |
| 1760 | |
| 1761 | |
| 1762 | .. _doctest-soapbox: |
| 1763 | |
| 1764 | Soapbox |
| 1765 | ------- |
| 1766 | |
| 1767 | As mentioned in the introduction, :mod:`doctest` has grown to have three primary |
| 1768 | uses: |
| 1769 | |
| 1770 | #. Checking examples in docstrings. |
| 1771 | |
| 1772 | #. Regression testing. |
| 1773 | |
| 1774 | #. Executable documentation / literate testing. |
| 1775 | |
| 1776 | These uses have different requirements, and it is important to distinguish them. |
| 1777 | In particular, filling your docstrings with obscure test cases makes for bad |
| 1778 | documentation. |
| 1779 | |
| 1780 | When writing a docstring, choose docstring examples with care. There's an art to |
| 1781 | this that needs to be learned---it may not be natural at first. Examples should |
| 1782 | add genuine value to the documentation. A good example can often be worth many |
| 1783 | words. If done with care, the examples will be invaluable for your users, and |
| 1784 | will pay back the time it takes to collect them many times over as the years go |
| 1785 | by and things change. I'm still amazed at how often one of my :mod:`doctest` |
| 1786 | examples stops working after a "harmless" change. |
| 1787 | |
| 1788 | Doctest also makes an excellent tool for regression testing, especially if you |
| 1789 | don't skimp on explanatory text. By interleaving prose and examples, it becomes |
| 1790 | much easier to keep track of what's actually being tested, and why. When a test |
| 1791 | fails, good prose can make it much easier to figure out what the problem is, and |
| 1792 | how it should be fixed. It's true that you could write extensive comments in |
| 1793 | code-based testing, but few programmers do. Many have found that using doctest |
| 1794 | approaches instead leads to much clearer tests. Perhaps this is simply because |
| 1795 | doctest makes writing prose a little easier than writing code, while writing |
| 1796 | comments in code is a little harder. I think it goes deeper than just that: |
| 1797 | the natural attitude when writing a doctest-based test is that you want to |
| 1798 | explain the fine points of your software, and illustrate them with examples. |
| 1799 | This in turn naturally leads to test files that start with the simplest |
| 1800 | features, and logically progress to complications and edge cases. A coherent |
| 1801 | narrative is the result, instead of a collection of isolated functions that test |
| 1802 | isolated bits of functionality seemingly at random. It's a different attitude, |
| 1803 | and produces different results, blurring the distinction between testing and |
| 1804 | explaining. |
| 1805 | |
| 1806 | Regression testing is best confined to dedicated objects or files. There are |
| 1807 | several options for organizing tests: |
| 1808 | |
| 1809 | * Write text files containing test cases as interactive examples, and test the |
| 1810 | files using :func:`testfile` or :func:`DocFileSuite`. This is recommended, |
| 1811 | although is easiest to do for new projects, designed from the start to use |
| 1812 | doctest. |
| 1813 | |
| 1814 | * Define functions named ``_regrtest_topic`` that consist of single docstrings, |
| 1815 | containing test cases for the named topics. These functions can be included in |
| 1816 | the same file as the module, or separated out into a separate test file. |
| 1817 | |
| 1818 | * Define a ``__test__`` dictionary mapping from regression test topics to |
| 1819 | docstrings containing test cases. |
| 1820 | |
| 1821 | .. rubric:: Footnotes |
| 1822 | |
| 1823 | .. [#] Examples containing both expected output and an exception are not supported. |
| 1824 | Trying to guess where one ends and the other begins is too error-prone, and that |
| 1825 | also makes for a confusing test. |