<!DOCTYPE html PUBLIC
"-//W3C//DTD HTML 4.0 Transitional//EN">
<link rel=
"STYLESHEET" href=
"lib.css" type='text/css'
/>
<link rel=
"SHORTCUT ICON" href=
"../icons/pyfav.png" type=
"image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index'
/>
<link rel=
"first" href=
"lib.html" title='Python Library Reference'
/>
<link rel='contents' href='contents.html'
title=
"Contents" />
<link rel='index' href='genindex.html' title='Index'
/>
<link rel='last' href='about.html' title='About this document...'
/>
<link rel='help' href='about.html' title='About this document...'
/>
<link rel=
"next" href=
"module-unittest.html" />
<link rel=
"prev" href=
"module-pydoc.html" />
<link rel=
"parent" href=
"misc.html" />
<link rel=
"next" href=
"doctest-simple-testmod.html" />
<meta name='aesop' content='information'
/>
<title>5.2 doctest -- Test interactive Python examples
</title>
<div id='top-navigation-panel' xml:id='top-navigation-panel'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"5.1 pydoc "
href=
"module-pydoc.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"5. Miscellaneous Services"
href=
"misc.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"5.2.1 Simple Usage: Checking"
href=
"doctest-simple-testmod.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-pydoc.html">5.1 pydoc
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"misc.html">5. Miscellaneous Services
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"doctest-simple-testmod.html">5.2.1 Simple Usage: Checking
</A>
<!--End of Navigation Panel-->
<H1><A NAME=
"SECTION007200000000000000000">
5.2 <tt class=
"module">doctest
</tt> --
Test interactive Python examples
</A>
<A NAME=
"module-doctest"></A>
The
<tt class=
"module"><a href=
"module-doctest.html">doctest
</a></tt> 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
<LI>To check that a module's docstrings are up-to-date by verifying
that all interactive examples still work as documented.
<LI>To perform regression testing by verifying that interactive
examples from a test file or a test object work as expected.
<LI>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".
Here's a complete but small example module:
<div class=
"verbatim"><pre>
This is the "example
" module.
The example module supplies one function, factorial(). For example,
>>> factorial(5)
"""Return the factorial of n, an exact integer >= 0.
If the result is small enough to fit in an int, return an int.
>>> [factorial(n) for n in range(6)]
>>> [factorial(long(n)) for n in range(6)]
>>> 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
<div class=
"verbatim"><pre>
raise ValueError(
"n must be >= 0")
raise ValueError(
"n must be exact integer")
if n+
1 == n: # catch a value like
1e300
raise OverflowError(
"n too large")
if __name__ ==
"__main__":
If you run
<span class=
"file">example.py
</span> directly from the command line,
<tt class=
"module"><a href=
"module-doctest.html">doctest
</a></tt> works its magic:
<div class=
"verbatim"><pre>
There's no output! That's normal, and it means all the examples
worked. Pass
<b class=
"programopt">-v
</b> to the script, and
<tt class=
"module"><a href=
"module-doctest.html">doctest
</a></tt>
prints a detailed log of what it's trying, and prints a summary at the
<div class=
"verbatim"><pre>
[factorial(n) for n in range(
6)]
[factorial(long(n)) for n in range(
6)]
And so on, eventually ending with:
<div class=
"verbatim"><pre>
Traceback (most recent call last):
OverflowError: n too large
2 items passed all tests:
8 tests in __main__.factorial
That's all you need to know to start making productive use of
<tt class=
"module"><a href=
"module-doctest.html">doctest
</a></tt>! 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
<span class=
"file">Lib/test/test_doctest.py
</span>.
<p><br /></p><hr class='online-navigation'
/>
<div class='online-navigation'
>
<!--Table of Child-Links-->
<A NAME=
"CHILD_LINKS"><STRONG>Subsections
</STRONG></a>
<LI><A href=
"doctest-simple-testmod.html">5.2.1 Simple Usage: Checking Examples in
<LI><A href=
"doctest-simple-testfile.html">5.2.2 Simple Usage: Checking Examples in a Text
<LI><A href=
"doctest-how-it-works.html">5.2.3 How It Works
</a>
<LI><A href=
"doctest-which-docstrings.html">5.2.3.1 Which Docstrings Are Examined?
</a>
<LI><A href=
"doctest-finding-examples.html">5.2.3.2 How are Docstring Examples
<LI><A href=
"doctest-execution-context.html">5.2.3.3 What's the Execution Context?
</a>
<LI><A href=
"doctest-exceptions.html">5.2.3.4 What About Exceptions?
</a>
<LI><A href=
"doctest-options.html">5.2.3.5 Option Flags and Directives
</a>
<LI><A href=
"doctest-warnings.html">5.2.3.6 Warnings
</a>
<LI><A href=
"doctest-basic-api.html">5.2.4 Basic API
</a>
<LI><A href=
"doctest-unittest-api.html">5.2.5 Unittest API
</a>
<LI><A href=
"doctest-advanced-api.html">5.2.6 Advanced API
</a>
<LI><A href=
"doctest-DocTest.html">5.2.6.1 DocTest Objects
</a>
<LI><A href=
"doctest-Example.html">5.2.6.2 Example Objects
</a>
<LI><A href=
"doctest-DocTestFinder.html">5.2.6.3 DocTestFinder objects
</a>
<LI><A href=
"doctest-DocTestParser.html">5.2.6.4 DocTestParser objects
</a>
<LI><A href=
"doctest-DocTestRunner.html">5.2.6.5 DocTestRunner objects
</a>
<LI><A href=
"doctest-OutputChecker.html">5.2.6.6 OutputChecker objects
</a>
<LI><A href=
"doctest-debugging.html">5.2.7 Debugging
</a>
<LI><A href=
"doctest-soapbox.html">5.2.8 Soapbox
</a>
<!--End of Table of Child-Links-->
<div class='online-navigation'
>
<table align=
"center" width=
"100%" cellpadding=
"0" cellspacing=
"2">
<td class='online-navigation'
><a rel=
"prev" title=
"5.1 pydoc "
href=
"module-pydoc.html"><img src='../icons/previous.png'
border='
0' height='
32' alt='Previous Page' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"parent" title=
"5. Miscellaneous Services"
href=
"misc.html"><img src='../icons/up.png'
border='
0' height='
32' alt='Up One Level' width='
32'
/></A></td>
<td class='online-navigation'
><a rel=
"next" title=
"5.2.1 Simple Usage: Checking"
href=
"doctest-simple-testmod.html"><img src='../icons/next.png'
border='
0' height='
32' alt='Next Page' width='
32'
/></A></td>
<td align=
"center" width=
"100%">Python Library Reference
</td>
<td class='online-navigation'
><a rel=
"contents" title=
"Table of Contents"
href=
"contents.html"><img src='../icons/contents.png'
border='
0' height='
32' alt='Contents' width='
32'
/></A></td>
<td class='online-navigation'
><a href=
"modindex.html" title=
"Module Index"><img src='../icons/modules.png'
border='
0' height='
32' alt='Module Index' width='
32'
/></a></td>
<td class='online-navigation'
><a rel=
"index" title=
"Index"
href=
"genindex.html"><img src='../icons/index.png'
border='
0' height='
32' alt='Index' width='
32'
/></A></td>
<div class='online-navigation'
>
<b class=
"navlabel">Previous:
</b>
<a class=
"sectref" rel=
"prev" href=
"module-pydoc.html">5.1 pydoc
</A>
<b class=
"navlabel">Up:
</b>
<a class=
"sectref" rel=
"parent" href=
"misc.html">5. Miscellaneous Services
</A>
<b class=
"navlabel">Next:
</b>
<a class=
"sectref" rel=
"next" href=
"doctest-simple-testmod.html">5.2.1 Simple Usage: Checking
</A>
<span class=
"release-info">Release
2.4.2, documentation updated on
28 September
2005.
</span>
<!--End of Navigation Panel-->
See
<i><a href=
"about.html">About this document...
</a></i> for information on suggesting changes.