\section{\module{doctest} --- Test interactive Python examples} \declaremodule{standard}{doctest}\moduleauthor{Tim Peters}{tim@python.org}\sectionauthor{Tim Peters}{tim@python.org}\sectionauthor{Moshe Zadka}{moshez@debian.org}\sectionauthor{Edward Loper}{edloper@users.sourceforge.net} \modulesynopsis{A framework for verifying interactive Python examples.} The \refmodule{doctest} module searches for pieces of text that look likeinteractive Python sessions, and then executes those sessions toverify that they work exactly as shown. There are several common ways touse doctest: \begin{itemize}\item To check that a module's docstrings are up-to-date by verifying that all interactive examples still work as documented.\item To perform regression testing by verifying that interactive examples from a test file or a test object work as expected.\item To write tutorial documentation for a package, liberally illustrated with input-output examples. Depending on whether the examples or the expository text are emphasized, this has the flavor of "literate testing" or "executable documentation".\end{itemize} Here's a complete but small example module: \begin{verbatim}"""This is the "example" module. The example module supplies one function, factorial(). For example, >>> factorial(5)120""" def factorial(n): """Return the factorial of n, an exact integer >= 0. If the result is small enough to fit in an int, return an int. Else return a long. >>> [factorial(n) for n in range(6)] [1, 1, 2, 6, 24, 120] >>> [factorial(long(n)) for n in range(6)] [1, 1, 2, 6, 24, 120] >>> factorial(30) 265252859812191058636308480000000L >>> factorial(30L) 265252859812191058636308480000000L >>> factorial(-1) Traceback (most recent call last): ... ValueError: n must be >= 0 Factorials of floats are OK, but the float must be an exact integer: >>> factorial(30.1) Traceback (most recent call last): ... ValueError: n must be exact integer >>> factorial(30.0) 265252859812191058636308480000000L It must also not be ridiculously large: >>> factorial(1e100) Traceback (most recent call last): ... OverflowError: n too large """ \end{verbatim}% allow LaTeX to break here.\begin{verbatim} import math if not n >= 0: raise ValueError("n must be >= 0") if math.floor(n) != n: raise ValueError("n must be exact integer") if n+1 == n: # catch a value like 1e300 raise OverflowError("n too large") result = 1 factor = 2 while factor <= n: result *= factor factor += 1 return result def _test(): import doctest doctest.testmod() if __name__ == "__main__": _test()\end{verbatim} If you run \file{example.py} directly from the command line,\refmodule{doctest} works its magic: \begin{verbatim}$ python example.py$\end{verbatim} There's no output! That's normal, and it means all the examplesworked. Pass \programopt{-v} to the script, and \refmodule{doctest}prints a detailed log of what it's trying, and prints a summary at theend: \begin{verbatim}$ python example.py -vTrying: factorial(5)Expecting: 120okTrying: [factorial(n) for n in range(6)]Expecting: [1, 1, 2, 6, 24, 120]okTrying: [factorial(long(n)) for n in range(6)]Expecting: [1, 1, 2, 6, 24, 120]ok\end{verbatim} And so on, eventually ending with: \begin{verbatim}Trying: factorial(1e100)Expecting: Traceback (most recent call last): ... OverflowError: n too largeok1 items had no tests: __main__._test2 items passed all tests: 1 tests in __main__ 8 tests in __main__.factorial9 tests in 3 items.9 passed and 0 failed.Test passed.$\end{verbatim} That's all you need to know to start making productive use of\refmodule{doctest}! Jump in. The following sections provide fulldetails. Note that there are many examples of doctests inthe standard Python test suite and libraries. Especially useful examplescan be found in the standard test file \file{Lib/test/test_doctest.py}. \subsection{Simple Usage: Checking Examples in Docstrings\label{doctest-simple-testmod}} The simplest way to start using doctest (but not necessarily the wayyou'll continue to do it) is to end each module \module{M} with: \begin{verbatim}def _test(): import doctest doctest.testmod() if __name__ == "__main__": _test()\end{verbatim} \refmodule{doctest} then examines docstrings in module \module{M}. Running the module as a script causes the examples in the docstringsto get executed and verified: \begin{verbatim}python M.py\end{verbatim} This won't display anything unless an example fails, in which case thefailing example(s) and the cause(s) of the failure(s) are printed to stdout,and the final line of output is\samp{***Test Failed*** \var{N} failures.}, where \var{N} is thenumber of examples that failed. Run it with the \programopt{-v} switch instead: \begin{verbatim}python M.py -v\end{verbatim} and a detailed report of all examples tried is printed to standardoutput, along with assorted summaries at the end. You can force verbose mode by passing \code{verbose=True} to\function{testmod()}, orprohibit it by passing \code{verbose=False}. In either of those cases,\code{sys.argv} is not examined by \function{testmod()} (so passing\programopt{-v} or not has no effect). For more information on \function{testmod()}, seesection~\ref{doctest-basic-api}. \subsection{Simple Usage: Checking Examples in a Text File\label{doctest-simple-testfile}} Another simple application of doctest is testing interactive examplesin a text file. This can be done with the \function{testfile()}function: \begin{verbatim}import doctestdoctest.testfile("example.txt")\end{verbatim} That short script executes and verifies any interactive Pythonexamples contained in the file \file{example.txt}. The file contentis treated as if it were a single giant docstring; the file doesn'tneed to contain a Python program! For example, perhaps \file{example.txt}contains this: \begin{verbatim}The ``example`` module====================== Using ``factorial``------------------- This is an example text file in reStructuredText format. First import``factorial`` from the ``example`` module: >>> from example import factorial Now use it: >>> factorial(6) 120\end{verbatim} Running \code{doctest.testfile("example.txt")} then finds the errorin this documentation: \begin{verbatim}File "./example.txt", line 14, in example.txtFailed example: factorial(6)Expected: 120Got: 720\end{verbatim} As with \function{testmod()}, \function{testfile()} won't display anythingunless an example fails. If an example does fail, then the failingexample(s) and the cause(s) of the failure(s) are printed to stdout, usingthe same format as \function{testmod()}. By default, \function{testfile()} looks for files in the callingmodule's directory. See section~\ref{doctest-basic-api} for adescription of the optional arguments that can be used to tell it tolook for files in other locations. Like \function{testmod()}, \function{testfile()}'s verbosity can beset with the \programopt{-v} command-line switch or with the optionalkeyword argument \var{verbose}. For more information on \function{testfile()}, seesection~\ref{doctest-basic-api}. \subsection{How It Works\label{doctest-how-it-works}} This section examines in detail how doctest works: which docstrings itlooks at, how it finds interactive examples, what execution context ituses, how it handles exceptions, and how option flags can be used tocontrol its behavior. This is the information that you need to knowto write doctest examples; for information about actually runningdoctest on these examples, see the following sections. \subsubsection{Which Docstrings Are Examined?\label{doctest-which-docstrings}} The module docstring, and all function, class and method docstrings aresearched. Objects imported into the module are not searched. In addition, if \code{M.__test__} exists and "is true", it must be adict, and each entry maps a (string) name to a function object, classobject, or string. Function and class object docstrings found from\code{M.__test__} are searched, and strings are treated as if theywere docstrings. In output, a key \code{K} in \code{M.__test__} appearswith name \begin{verbatim}<name of M>.__test__.K\end{verbatim} Any classes found are recursively searched similarly, to test docstrings intheir contained methods and nested classes. \versionchanged[A "private name" concept is deprecated and no longer documented]{2.4} \subsubsection{How are Docstring Examples Recognized?\label{doctest-finding-examples}} In most cases a copy-and-paste of an interactive console session worksfine, but doctest isn't trying to do an exact emulation of any specificPython shell. All hard tab characters are expanded to spaces, using8-column tab stops. If you don't believe tabs should mean that, toobad: don't use hard tabs, or write your own \class{DocTestParser}class. \versionchanged[Expanding tabs to spaces is new; previous versions tried to preserve hard tabs, with confusing results]{2.4} \begin{verbatim}>>> # comments are ignored>>> x = 12>>> x12>>> if x == 13:... print "yes"... else:... print "no"... print "NO"... print "NO!!!"...noNONO!!!>>>\end{verbatim} Any expected output must immediately follow the final\code{'>>>~'} or \code{'...~'} line containing the code, andthe expected output (if any) extends to the next \code{'>>>~'}or all-whitespace line. The fine print: \begin{itemize} \item Expected output cannot contain an all-whitespace line, since such a line is taken to signal the end of expected output. If expected output does contain a blank line, put \code{<BLANKLINE>} in your doctest example each place a blank line is expected. \versionchanged[\code{<BLANKLINE>} was added; there was no way to use expected output containing empty lines in previous versions]{2.4} \item Output to stdout is captured, but not output to stderr (exception tracebacks are captured via a different means). \item If you continue a line via backslashing in an interactive session, or for any other reason use a backslash, you should use a raw docstring, which will preserve your backslashes exactly as you type them: \begin{verbatim}>>> def f(x):... r'''Backslashes in a raw docstring: m\n'''>>> print f.__doc__Backslashes in a raw docstring: m\n\end{verbatim} Otherwise, the backslash will be interpreted as part of the string. For example, the "{\textbackslash}" above would be interpreted as a newline character. Alternatively, you can double each backslash in the doctest version (and not use a raw string): \begin{verbatim}>>> def f(x):... '''Backslashes in a raw docstring: m\\n'''>>> print f.__doc__Backslashes in a raw docstring: m\n\end{verbatim} \item The starting column doesn't matter: \begin{verbatim} >>> assert "Easy!" >>> import math >>> math.floor(1.9) 1.0\end{verbatim} and as many leading whitespace characters are stripped from theexpected output as appeared in the initial \code{'>>>~'} linethat started the example.\end{itemize} \subsubsection{What's the Execution Context?\label{doctest-execution-context}} By default, each time \refmodule{doctest} finds a docstring to test, ituses a \emph{shallow copy} of \module{M}'s globals, so that running testsdoesn't change the module's real globals, and so that one test in\module{M} can't leave behind crumbs that accidentally allow another testto work. This means examples can freely use any names defined at top-levelin \module{M}, and names defined earlier in the docstring being run.Examples cannot see names defined in other docstrings. You can force use of your own dict as the execution context by passing\code{globs=your_dict} to \function{testmod()} or\function{testfile()} instead. \subsubsection{What About Exceptions?\label{doctest-exceptions}} No problem, provided that the traceback is the only output produced bythe example: just paste in the traceback.\footnote{Examples containing both expected output and an exception are not supported. Trying to guess where one ends and the other begins is too error-prone, and that also makes for a confusing test.}Since tracebacks contain details that are likely to change rapidly (forexample, exact file paths and line numbers), this is one case where doctestworks hard to be flexible in what it accepts. Simple example: \begin{verbatim}>>> [1, 2, 3].remove(42)Traceback (most recent call last): File "<stdin>", line 1, in ?ValueError: list.remove(x): x not in list\end{verbatim} That doctest succeeds if \exception{ValueError} is raised, with the\samp{list.remove(x): x not in list} detail as shown. The expected output for an exception must start with a tracebackheader, which may be either of the following two lines, indented thesame as the first line of the example: \begin{verbatim}Traceback (most recent call last):Traceback (innermost last):\end{verbatim} The traceback header is followed by an optional traceback stack, whosecontents are ignored by doctest. The traceback stack is typicallyomitted, or copied verbatim from an interactive session. The traceback stack is followed by the most interesting part: theline(s) containing the exception type and detail. This is usually thelast line of a traceback, but can extend across multiple lines if theexception has a multi-line detail: \begin{verbatim}>>> raise ValueError('multi\n line\ndetail')Traceback (most recent call last): File "<stdin>", line 1, in ?ValueError: multi linedetail\end{verbatim} The last three lines (starting with \exception{ValueError}) arecompared against the exception's type and detail, and the rest areignored. Best practice is to omit the traceback stack, unless it addssignificant documentation value to the example. So the last exampleis probably better as: \begin{verbatim}>>> raise ValueError('multi\n line\ndetail')Traceback (most recent call last): ...ValueError: multi linedetail\end{verbatim} Note that tracebacks are treated very specially. In particular, in therewritten example, the use of \samp{...} is independent of doctest's\constant{ELLIPSIS} option. The ellipsis in that example could be leftout, or could just as well be three (or three hundred) commas or digits,or an indented transcript of a Monty Python skit. Some details you should read once, but won't need to remember: \begin{itemize} \item Doctest can't guess whether your expected output came from an exception traceback or from ordinary printing. So, e.g., an example that expects \samp{ValueError: 42 is prime} will pass whether \exception{ValueError} is actually raised or if the example merely prints that traceback text. In practice, ordinary output rarely begins with a traceback header line, so this doesn't create real problems. \item Each line of the traceback stack (if present) must be indented further than the first line of the example, \emph{or} start with a non-alphanumeric character. The first line following the traceback header indented the same and starting with an alphanumeric is taken to be the start of the exception detail. Of course this does the right thing for genuine tracebacks. \item When the \constant{IGNORE_EXCEPTION_DETAIL} doctest option is is specified, everything following the leftmost colon is ignored. Lines 1–500 of 1949. Load more
\section{\module{doctest} --- Test interactive Python examples} \declaremodule{standard}{doctest} \moduleauthor{Tim Peters}{tim@python.org} \sectionauthor{Tim Peters}{tim@python.org} \sectionauthor{Moshe Zadka}{moshez@debian.org} \sectionauthor{Edward Loper}{edloper@users.sourceforge.net} \modulesynopsis{A framework for verifying interactive Python examples.} The \refmodule{doctest} module searches for pieces of text that look like interactive Python sessions, and then executes those sessions to verify that they work exactly as shown. There are several common ways to use doctest: \begin{itemize} \item To check that a module's docstrings are up-to-date by verifying that all interactive examples still work as documented. \item To perform regression testing by verifying that interactive examples from a test file or a test object work as expected. \item To write tutorial documentation for a package, liberally illustrated with input-output examples. Depending on whether the examples or the expository text are emphasized, this has the flavor of "literate testing" or "executable documentation". \end{itemize} Here's a complete but small example module: \begin{verbatim} """ This is the "example" module. The example module supplies one function, factorial(). For example, >>> factorial(5) 120 """ def factorial(n): """Return the factorial of n, an exact integer >= 0. If the result is small enough to fit in an int, return an int. Else return a long. >>> [factorial(n) for n in range(6)] [1, 1, 2, 6, 24, 120] >>> [factorial(long(n)) for n in range(6)] [1, 1, 2, 6, 24, 120] >>> factorial(30) 265252859812191058636308480000000L >>> factorial(30L) 265252859812191058636308480000000L >>> factorial(-1) Traceback (most recent call last): ... ValueError: n must be >= 0 Factorials of floats are OK, but the float must be an exact integer: >>> factorial(30.1) Traceback (most recent call last): ... ValueError: n must be exact integer >>> factorial(30.0) 265252859812191058636308480000000L It must also not be ridiculously large: >>> factorial(1e100) Traceback (most recent call last): ... OverflowError: n too large """ \end{verbatim} % allow LaTeX to break here. \begin{verbatim} import math if not n >= 0: raise ValueError("n must be >= 0") if math.floor(n) != n: raise ValueError("n must be exact integer") if n+1 == n: # catch a value like 1e300 raise OverflowError("n too large") result = 1 factor = 2 while factor <= n: result *= factor factor += 1 return result def _test(): import doctest doctest.testmod() if __name__ == "__main__": _test() \end{verbatim} If you run \file{example.py} directly from the command line, \refmodule{doctest} works its magic: \begin{verbatim} $ python example.py $ \end{verbatim} There's no output! That's normal, and it means all the examples worked. Pass \programopt{-v} to the script, and \refmodule{doctest} prints a detailed log of what it's trying, and prints a summary at the end: \begin{verbatim} $ python example.py -v Trying: factorial(5) Expecting: 120 ok Trying: [factorial(n) for n in range(6)] Expecting: [1, 1, 2, 6, 24, 120] ok Trying: [factorial(long(n)) for n in range(6)] Expecting: [1, 1, 2, 6, 24, 120] ok \end{verbatim} And so on, eventually ending with: \begin{verbatim} Trying: factorial(1e100) Expecting: Traceback (most recent call last): ... OverflowError: n too large ok 1 items had no tests: __main__._test 2 items passed all tests: 1 tests in __main__ 8 tests in __main__.factorial 9 tests in 3 items. 9 passed and 0 failed. Test passed. $ \end{verbatim} That's all you need to know to start making productive use of \refmodule{doctest}! Jump in. The following sections provide full details. Note that there are many examples of doctests in the standard Python test suite and libraries. Especially useful examples can be found in the standard test file \file{Lib/test/test_doctest.py}. \subsection{Simple Usage: Checking Examples in Docstrings\label{doctest-simple-testmod}} The simplest way to start using doctest (but not necessarily the way you'll continue to do it) is to end each module \module{M} with: \begin{verbatim} def _test(): import doctest doctest.testmod() if __name__ == "__main__": _test() \end{verbatim} \refmodule{doctest} then examines docstrings in module \module{M}. Running the module as a script causes the examples in the docstrings to get executed and verified: \begin{verbatim} python M.py \end{verbatim} This won't display anything unless an example fails, in which case the failing example(s) and the cause(s) of the failure(s) are printed to stdout, and the final line of output is \samp{***Test Failed*** \var{N} failures.}, where \var{N} is the number of examples that failed. Run it with the \programopt{-v} switch instead: \begin{verbatim} python M.py -v \end{verbatim} and a detailed report of all examples tried is printed to standard output, along with assorted summaries at the end. You can force verbose mode by passing \code{verbose=True} to \function{testmod()}, or prohibit it by passing \code{verbose=False}. In either of those cases, \code{sys.argv} is not examined by \function{testmod()} (so passing \programopt{-v} or not has no effect). For more information on \function{testmod()}, see section~\ref{doctest-basic-api}. \subsection{Simple Usage: Checking Examples in a Text File\label{doctest-simple-testfile}} Another simple application of doctest is testing interactive examples in a text file. This can be done with the \function{testfile()} function: \begin{verbatim} import doctest doctest.testfile("example.txt") \end{verbatim} That short script executes and verifies any interactive Python examples contained in the file \file{example.txt}. The file content is treated as if it were a single giant docstring; the file doesn't need to contain a Python program! For example, perhaps \file{example.txt} contains this: \begin{verbatim} The ``example`` module ====================== Using ``factorial`` ------------------- This is an example text file in reStructuredText format. First import ``factorial`` from the ``example`` module: >>> from example import factorial Now use it: >>> factorial(6) 120 \end{verbatim} Running \code{doctest.testfile("example.txt")} then finds the error in this documentation: \begin{verbatim} File "./example.txt", line 14, in example.txt Failed example: factorial(6) Expected: 120 Got: 720 \end{verbatim} As with \function{testmod()}, \function{testfile()} won't display anything unless an example fails. If an example does fail, then the failing example(s) and the cause(s) of the failure(s) are printed to stdout, using the same format as \function{testmod()}. By default, \function{testfile()} looks for files in the calling module's directory. See section~\ref{doctest-basic-api} for a description of the optional arguments that can be used to tell it to look for files in other locations. Like \function{testmod()}, \function{testfile()}'s verbosity can be set with the \programopt{-v} command-line switch or with the optional keyword argument \var{verbose}. For more information on \function{testfile()}, see section~\ref{doctest-basic-api}. \subsection{How It Works\label{doctest-how-it-works}} This section examines in detail how doctest works: which docstrings it looks at, how it finds interactive examples, what execution context it uses, how it handles exceptions, and how option flags can be used to control its behavior. This is the information that you need to know to write doctest examples; for information about actually running doctest on these examples, see the following sections. \subsubsection{Which Docstrings Are Examined?\label{doctest-which-docstrings}} The module docstring, and all function, class and method docstrings are searched. Objects imported into the module are not searched. In addition, if \code{M.__test__} exists and "is true", it must be a dict, and each entry maps a (string) name to a function object, class object, or string. Function and class object docstrings found from \code{M.__test__} are searched, and strings are treated as if they were docstrings. In output, a key \code{K} in \code{M.__test__} appears with name \begin{verbatim} <name of M>.__test__.K \end{verbatim} Any classes found are recursively searched similarly, to test docstrings in their contained methods and nested classes. \versionchanged[A "private name" concept is deprecated and no longer documented]{2.4} \subsubsection{How are Docstring Examples Recognized?\label{doctest-finding-examples}} In most cases a copy-and-paste of an interactive console session works fine, but doctest isn't trying to do an exact emulation of any specific Python shell. All hard tab characters are expanded to spaces, using 8-column tab stops. If you don't believe tabs should mean that, too bad: don't use hard tabs, or write your own \class{DocTestParser} class. \versionchanged[Expanding tabs to spaces is new; previous versions tried to preserve hard tabs, with confusing results]{2.4} \begin{verbatim} >>> # comments are ignored >>> x = 12 >>> x 12 >>> if x == 13: ... print "yes" ... else: ... print "no" ... print "NO" ... print "NO!!!" ... no NO NO!!! >>> \end{verbatim} Any expected output must immediately follow the final \code{'>>>~'} or \code{'...~'} line containing the code, and the expected output (if any) extends to the next \code{'>>>~'} or all-whitespace line. The fine print: \begin{itemize} \item Expected output cannot contain an all-whitespace line, since such a line is taken to signal the end of expected output. If expected output does contain a blank line, put \code{<BLANKLINE>} in your doctest example each place a blank line is expected. \versionchanged[\code{<BLANKLINE>} was added; there was no way to use expected output containing empty lines in previous versions]{2.4} \item Output to stdout is captured, but not output to stderr (exception tracebacks are captured via a different means). \item If you continue a line via backslashing in an interactive session, or for any other reason use a backslash, you should use a raw docstring, which will preserve your backslashes exactly as you type them: \begin{verbatim} >>> def f(x): ... r'''Backslashes in a raw docstring: m\n''' >>> print f.__doc__ Backslashes in a raw docstring: m\n \end{verbatim} Otherwise, the backslash will be interpreted as part of the string. For example, the "{\textbackslash}" above would be interpreted as a newline character. Alternatively, you can double each backslash in the doctest version (and not use a raw string): \begin{verbatim} >>> def f(x): ... '''Backslashes in a raw docstring: m\\n''' >>> print f.__doc__ Backslashes in a raw docstring: m\n \end{verbatim} \item The starting column doesn't matter: \begin{verbatim} >>> assert "Easy!" >>> import math >>> math.floor(1.9) 1.0 \end{verbatim} and as many leading whitespace characters are stripped from the expected output as appeared in the initial \code{'>>>~'} line that started the example. \end{itemize} \subsubsection{What's the Execution Context?\label{doctest-execution-context}} By default, each time \refmodule{doctest} finds a docstring to test, it uses a \emph{shallow copy} of \module{M}'s globals, so that running tests doesn't change the module's real globals, and so that one test in \module{M} can't leave behind crumbs that accidentally allow another test to work. This means examples can freely use any names defined at top-level in \module{M}, and names defined earlier in the docstring being run. Examples cannot see names defined in other docstrings. You can force use of your own dict as the execution context by passing \code{globs=your_dict} to \function{testmod()} or \function{testfile()} instead. \subsubsection{What About Exceptions?\label{doctest-exceptions}} No problem, provided that the traceback is the only output produced by the example: just paste in the traceback.\footnote{Examples containing both expected output and an exception are not supported. Trying to guess where one ends and the other begins is too error-prone, and that also makes for a confusing test.} Since tracebacks contain details that are likely to change rapidly (for example, exact file paths and line numbers), this is one case where doctest works hard to be flexible in what it accepts. Simple example: \begin{verbatim} >>> [1, 2, 3].remove(42) Traceback (most recent call last): File "<stdin>", line 1, in ? ValueError: list.remove(x): x not in list \end{verbatim} That doctest succeeds if \exception{ValueError} is raised, with the \samp{list.remove(x): x not in list} detail as shown. The expected output for an exception must start with a traceback header, which may be either of the following two lines, indented the same as the first line of the example: \begin{verbatim} Traceback (most recent call last): Traceback (innermost last): \end{verbatim} The traceback header is followed by an optional traceback stack, whose contents are ignored by doctest. The traceback stack is typically omitted, or copied verbatim from an interactive session. The traceback stack is followed by the most interesting part: the line(s) containing the exception type and detail. This is usually the last line of a traceback, but can extend across multiple lines if the exception has a multi-line detail: \begin{verbatim} >>> raise ValueError('multi\n line\ndetail') Traceback (most recent call last): File "<stdin>", line 1, in ? ValueError: multi line detail \end{verbatim} The last three lines (starting with \exception{ValueError}) are compared against the exception's type and detail, and the rest are ignored. Best practice is to omit the traceback stack, unless it adds significant documentation value to the example. So the last example is probably better as: \begin{verbatim} >>> raise ValueError('multi\n line\ndetail') Traceback (most recent call last): ... ValueError: multi line detail \end{verbatim} Note that tracebacks are treated very specially. In particular, in the rewritten example, the use of \samp{...} is independent of doctest's \constant{ELLIPSIS} option. The ellipsis in that example could be left out, or could just as well be three (or three hundred) commas or digits, or an indented transcript of a Monty Python skit. Some details you should read once, but won't need to remember: \begin{itemize} \item Doctest can't guess whether your expected output came from an exception traceback or from ordinary printing. So, e.g., an example that expects \samp{ValueError: 42 is prime} will pass whether \exception{ValueError} is actually raised or if the example merely prints that traceback text. In practice, ordinary output rarely begins with a traceback header line, so this doesn't create real problems. \item Each line of the traceback stack (if present) must be indented further than the first line of the example, \emph{or} start with a non-alphanumeric character. The first line following the traceback header indented the same and starting with an alphanumeric is taken to be the start of the exception detail. Of course this does the right thing for genuine tracebacks. \item When the \constant{IGNORE_EXCEPTION_DETAIL} doctest option is is specified, everything following the leftmost colon is ignored.