doctest

### doctest is a transcript checker, not an assertion framework `doctest` is a standard-library module that finds interactive-interpreter transcripts in text and runs them. It has no `assert` API, it does not collect functions named `test_*`, and it does not know anything about your test classes. It reads the `__doc__` string of a module, and of the classes, functions and methods defined in it — or a plain text file — and looks for the shape of a REPL session. ### The grammar of an example An **example** is three things in sequence: 1. a *source* line that begins with the prompt `>>> ` (three chevrons and one space), 2. zero or more *continuation* lines that begin with `... `, for multi-line statements, 3. the *expected output*: every line that follows, up to the first blank line or the next `>>>` prompt. Everything is measured relative to the indentation of the prompt, which is what lets an example sit inside an already-indented docstring without the leading spaces becoming part of the expected text. ### What "passing" means For each example doctest compiles the source, executes it in a namespace, and captures everything written to standard output while it runs — **including the value the REPL would echo**, which is that value's `repr()`. It then compares the captured text with the expected block as a **string**. Not `==`, not `assertEqual`: text. Four consequences follow directly, and each one is a real interview probe: * `>>> "ok"` must be followed by `'ok'` **with quotes**, because that is what `repr` prints. A bare `ok` fails. * An example with an *empty* expected block asserts that the statement prints nothing. `>>> bids = [4, 2]` passes silently and binds a name; `>>> bids` on the next line must be followed by `[4, 2]`. * Trailing spaces, line wrapping and the ordering of everything printed all matter, which is why `NORMALIZE_WHITESPACE` exists. * A genuinely blank line cannot appear inside expected output, because a blank line is the terminator. doctest reserves the marker `<BLANKLINE>` for it, and `DONT_ACCEPT_BLANKLINE` turns that convenience off. ### Expected exceptions An example may expect an exception. The expected block is written as the header line `Traceback (most recent call last):`, then an optional body, then the final `ExceptionType: message` line. The body is **ignored entirely** — you may paste real frames, write `...`, or leave it out — while the header and the final line are compared. That is a deliberate design choice: stack frames are file- and line-dependent, so pinning them would make every example fragile. The exception *message* is still compared, and `IGNORE_EXCEPTION_DETAIL` relaxes that down to the exception class when a message is likely to change. ### One namespace per docstring, shared in order All examples in a single docstring execute in the same globals mapping, in order, seeded with a shallow copy of the defining module's globals. That is what lets a docstring read like a session: an earlier example binds `live = sorted(...)` and a later one uses it. Two consequences worth naming out loud: * examples in a docstring are **order-dependent**; you cannot reorder them freely, and you cannot run one in isolation; * after a failure doctest keeps going (unless `FAIL_FAST` is set), so an example that raises unexpectedly leaves its name unbound and the following examples fail with `NameError` — one real defect can print as five failures. Different docstrings do **not** share state. Each gets its own copy of the module globals, so a name bound in one function's docstring is invisible in another's. ### Where doctest looks `doctest.testmod()` walks the module's own docstring plus the docstrings of the functions, classes and methods it defines, skipping objects that were imported from elsewhere. `doctest.testfile()` does the same for a text file, where the whole file is prose and the `>>>` blocks are the tests. Per-example behaviour is tuned with a directive comment on the source line — `# doctest: +ELLIPSIS`, `# doctest: +SKIP` — and run-wide behaviour with the `optionflags` argument or the `-o` command-line option. ### Why the exactness is both the feature and the price The whole value proposition is that a doctest **is** the documentation. A reader copies the example into a REPL and gets what the docstring promised, because the suite would have failed otherwise. Documentation cannot silently drift from behaviour. The identical property is the cost: an example whose printed form is not stable — a float carrying representation error, a set whose order depends on the hash seed, an object whose default `repr` embeds its address — fails for reasons that have nothing to do with correctness. That trade is the thing to understand before choosing where to use it.