Baoding-FenShuaJiang
/
Green_GoodERP18_FSJ_Standard
Volgen 1
Ster 0
Wiki 捐赠
gooderp18绿色标准版
You can not select more than 25 topics Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
Branch: master
Branches Labels
${ item.name }
Maak branch ${ searchTerm }
van 'master'
${ noResults }
Green_GoodERP18_FSJ_Standard/python/Doc/html/library/doctest.html

2067 lines
204KB
Ruw Permalink Blame Geschiedenis 

  1. <!DOCTYPE html>

  2. 

  3. <html lang="en" data-content_root="../">

  4.   <head>

  5.     <meta charset="utf-8" />

  6.     <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />

  7. <meta property="og:title" content="doctest — Test interactive Python examples" />

  8. <meta property="og:type" content="website" />

  9. <meta property="og:url" content="https://docs.python.org/3/library/doctest.html" />

  10. <meta property="og:site_name" content="Python documentation" />

  11. <meta property="og:description" content="Source code: Lib/doctest.py The 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. Th..." />

  12. <meta property="og:image" content="https://docs.python.org/3/_static/og-image.png" />

  13. <meta property="og:image:alt" content="Python documentation" />

  14. <meta name="description" content="Source code: Lib/doctest.py The 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. Th..." />

  15. <meta property="og:image:width" content="200" />

  16. <meta property="og:image:height" content="200" />

  17. <meta name="theme-color" content="#3776ab" />

  18. 

  19.     <title>doctest — Test interactive Python examples &#8212; Python 3.12.3 documentation</title><meta name="viewport" content="width=device-width, initial-scale=1.0">

  20.     

  21.     <link rel="stylesheet" type="text/css" href="../_static/pygments.css?v=80d5e7a1" />

  22.     <link rel="stylesheet" type="text/css" href="../_static/pydoctheme.css?v=bb723527" />

  23.     <link id="pygments_dark_css" media="(prefers-color-scheme: dark)" rel="stylesheet" type="text/css" href="../_static/pygments_dark.css?v=b20cc3f5" />

  24.     

  25.     <script src="../_static/documentation_options.js?v=2c828074"></script>

  26.     <script src="../_static/doctools.js?v=888ff710"></script>

  27.     <script src="../_static/sphinx_highlight.js?v=dc90522c"></script>

  28.     

  29.     <script src="../_static/sidebar.js"></script>

  30.     

  31.     <link rel="search" type="application/opensearchdescription+xml"

  32.           title="Search within Python 3.12.3 documentation"

  33.           href="../_static/opensearch.xml"/>

  34.     <link rel="author" title="About these documents" href="../about.html" />

  35.     <link rel="index" title="Index" href="../genindex.html" />

  36.     <link rel="search" title="Search" href="../search.html" />

  37.     <link rel="copyright" title="Copyright" href="../copyright.html" />

  38.     <link rel="next" title="unittest — Unit testing framework" href="unittest.html" />

  39.     <link rel="prev" title="Python Development Mode" href="devmode.html" />

  40.     <link rel="canonical" href="https://docs.python.org/3/library/doctest.html" />

  41.     

  42.       

  43.     

  44. 

  45.     

  46.     <style>

  47.       @media only screen {

  48.         table.full-width-table {

  49.             width: 100%;

  50.         }

  51.       }

  52.     </style>

  53. <link rel="stylesheet" href="../_static/pydoctheme_dark.css" media="(prefers-color-scheme: dark)" id="pydoctheme_dark_css">

  54.     <link rel="shortcut icon" type="image/png" href="../_static/py.svg" />

  55.             <script type="text/javascript" src="../_static/copybutton.js"></script>

  56.             <script type="text/javascript" src="../_static/menu.js"></script>

  57.             <script type="text/javascript" src="../_static/search-focus.js"></script>

  58.             <script type="text/javascript" src="../_static/themetoggle.js"></script> 

  59. 

  60.   </head>

  61. <body>

  62. <div class="mobile-nav">

  63.     <input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"

  64.            aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />

  65.     <nav class="nav-content" role="navigation">

  66.         <label for="menuToggler" class="toggler__label">

  67.             <span></span>

  68.         </label>

  69.         <span class="nav-items-wrapper">

  70.             <a href="https://www.python.org/" class="nav-logo">

  71.                 <img src="../_static/py.svg" alt="Python logo"/>

  72.             </a>

  73.             <span class="version_switcher_placeholder"></span>

  74.             <form role="search" class="search" action="../search.html" method="get">

  75.                 <svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">

  76.                     <path fill-rule="nonzero" fill="currentColor" d="M15.5 14h-.79l-.28-.27a6.5 6.5 0 001.48-5.34c-.47-2.78-2.79-5-5.59-5.34a6.505 6.505 0 00-7.27 7.27c.34 2.8 2.56 5.12 5.34 5.59a6.5 6.5 0 005.34-1.48l.27.28v.79l4.25 4.25c.41.41 1.08.41 1.49 0 .41-.41.41-1.08 0-1.49L15.5 14zm-6 0C7.01 14 5 11.99 5 9.5S7.01 5 9.5 5 14 7.01 14 9.5 11.99 14 9.5 14z"></path>

  77.                 </svg>

  78.                 <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" />

  79.                 <input type="submit" value="Go"/>

  80.             </form>

  81.         </span>

  82.     </nav>

  83.     <div class="menu-wrapper">

  84.         <nav class="menu" role="navigation" aria-label="main navigation">

  85.             <div class="language_switcher_placeholder"></div>

  86.             

  87. <label class="theme-selector-label">

  88.     Theme

  89.     <select class="theme-selector" oninput="activateTheme(this.value)">

  90.         <option value="auto" selected>Auto</option>

  91.         <option value="light">Light</option>

  92.         <option value="dark">Dark</option>

  93.     </select>

  94. </label>

  95.   <div>

  96.     <h3><a href="../contents.html">Table of Contents</a></h3>

  97.     <ul>

  98. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> — Test interactive Python examples</a><ul>

  99. <li><a class="reference internal" href="#simple-usage-checking-examples-in-docstrings">Simple Usage: Checking Examples in Docstrings</a></li>

  100. <li><a class="reference internal" href="#simple-usage-checking-examples-in-a-text-file">Simple Usage: Checking Examples in a Text File</a></li>

  101. <li><a class="reference internal" href="#how-it-works">How It Works</a><ul>

  102. <li><a class="reference internal" href="#which-docstrings-are-examined">Which Docstrings Are Examined?</a></li>

  103. <li><a class="reference internal" href="#how-are-docstring-examples-recognized">How are Docstring Examples Recognized?</a></li>

  104. <li><a class="reference internal" href="#what-s-the-execution-context">What’s the Execution Context?</a></li>

  105. <li><a class="reference internal" href="#what-about-exceptions">What About Exceptions?</a></li>

  106. <li><a class="reference internal" href="#option-flags">Option Flags</a></li>

  107. <li><a class="reference internal" href="#directives">Directives</a></li>

  108. <li><a class="reference internal" href="#warnings">Warnings</a></li>

  109. </ul>

  110. </li>

  111. <li><a class="reference internal" href="#basic-api">Basic API</a></li>

  112. <li><a class="reference internal" href="#unittest-api">Unittest API</a></li>

  113. <li><a class="reference internal" href="#advanced-api">Advanced API</a><ul>

  114. <li><a class="reference internal" href="#doctest-objects">DocTest Objects</a></li>

  115. <li><a class="reference internal" href="#example-objects">Example Objects</a></li>

  116. <li><a class="reference internal" href="#doctestfinder-objects">DocTestFinder objects</a></li>

  117. <li><a class="reference internal" href="#doctestparser-objects">DocTestParser objects</a></li>

  118. <li><a class="reference internal" href="#doctestrunner-objects">DocTestRunner objects</a></li>

  119. <li><a class="reference internal" href="#outputchecker-objects">OutputChecker objects</a></li>

  120. </ul>

  121. </li>

  122. <li><a class="reference internal" href="#debugging">Debugging</a></li>

  123. <li><a class="reference internal" href="#soapbox">Soapbox</a></li>

  124. </ul>

  125. </li>

  126. </ul>

  127. 

  128.   </div>

  129.   <div>

  130.     <h4>Previous topic</h4>

  131.     <p class="topless"><a href="devmode.html"

  132.                           title="previous chapter">Python Development Mode</a></p>

  133.   </div>

  134.   <div>

  135.     <h4>Next topic</h4>

  136.     <p class="topless"><a href="unittest.html"

  137.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> — Unit testing framework</a></p>

  138.   </div>

  139.   <div role="note" aria-label="source link">

  140.     <h3>This Page</h3>

  141.     <ul class="this-page-menu">

  142.       <li><a href="../bugs.html">Report a Bug</a></li>

  143.       <li>

  144.         <a href="https://github.com/python/cpython/blob/main/Doc/library/doctest.rst"

  145.             rel="nofollow">Show Source

  146.         </a>

  147.       </li>

  148.     </ul>

  149.   </div>

  150.         </nav>

  151.     </div>

  152. </div>

  153. 

  154.   

  155.     <div class="related" role="navigation" aria-label="related navigation">

  156.       <h3>Navigation</h3>

  157.       <ul>

  158.         <li class="right" style="margin-right: 10px">

  159.           <a href="../genindex.html" title="General Index"

  160.              accesskey="I">index</a></li>

  161.         <li class="right" >

  162.           <a href="../py-modindex.html" title="Python Module Index"

  163.              >modules</a> |</li>

  164.         <li class="right" >

  165.           <a href="unittest.html" title="unittest — Unit testing framework"

  166.              accesskey="N">next</a> |</li>

  167.         <li class="right" >

  168.           <a href="devmode.html" title="Python Development Mode"

  169.              accesskey="P">previous</a> |</li>

  170. 

  171.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  172.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  173.           <li class="switchers">

  174.             <div class="language_switcher_placeholder"></div>

  175.             <div class="version_switcher_placeholder"></div>

  176.           </li>

  177.           <li>

  178.               

  179.           </li>

  180.     <li id="cpython-language-and-version">

  181.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  182.     </li>

  183. 

  184.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  185.           <li class="nav-item nav-item-2"><a href="development.html" accesskey="U">Development Tools</a> &#187;</li>

  186.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> — Test interactive Python examples</a></li>

  187.                 <li class="right">

  188.                     

  189. 

  190.     <div class="inline-search" role="search">

  191.         <form class="inline-search" action="../search.html" method="get">

  192.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  193.           <input type="submit" value="Go" />

  194.         </form>

  195.     </div>

  196.                      |

  197.                 </li>

  198.             <li class="right">

  199. <label class="theme-selector-label">

  200.     Theme

  201.     <select class="theme-selector" oninput="activateTheme(this.value)">

  202.         <option value="auto" selected>Auto</option>

  203.         <option value="light">Light</option>

  204.         <option value="dark">Dark</option>

  205.     </select>

  206. </label> |</li>

  207.             

  208.       </ul>

  209.     </div>    

  210. 

  211.     <div class="document">

  212.       <div class="documentwrapper">

  213.         <div class="bodywrapper">

  214.           <div class="body" role="main">

  215.             

  216.   <section id="module-doctest">

  217. <span id="doctest-test-interactive-python-examples"></span><h1><a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> — Test interactive Python examples<a class="headerlink" href="#module-doctest" title="Link to this heading">¶</a></h1>

  218. <p><strong>Source code:</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.12/Lib/doctest.py">Lib/doctest.py</a></p>

  219. <hr class="docutils" />

  220. <p>The <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> module searches for pieces of text that look like interactive

  221. Python sessions, and then executes those sessions to verify that they work

  222. exactly as shown.  There are several common ways to use doctest:</p>

  223. <ul class="simple">

  224. <li><p>To check that a module’s docstrings are up-to-date by verifying that all

  225. interactive examples still work as documented.</p></li>

  226. <li><p>To perform regression testing by verifying that interactive examples from a

  227. test file or a test object work as expected.</p></li>

  228. <li><p>To write tutorial documentation for a package, liberally illustrated with

  229. input-output examples.  Depending on whether the examples or the expository text

  230. are emphasized, this has the flavor of “literate testing” or “executable

  231. documentation”.</p></li>

  232. </ul>

  233. <p>Here’s a complete but small example module:</p>

  234. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>

  235. <span class="sd">This is the &quot;example&quot; module.</span>

  236. 

  237. <span class="sd">The example module supplies one function, factorial().  For example,</span>

  238. 

  239. <span class="sd">&gt;&gt;&gt; factorial(5)</span>

  240. <span class="sd">120</span>

  241. <span class="sd">&quot;&quot;&quot;</span>

  242. 

  243. <span class="k">def</span> <span class="nf">factorial</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>

  244. <span class="w">    </span><span class="sd">&quot;&quot;&quot;Return the factorial of n, an exact integer &gt;= 0.</span>

  245. 

  246. <span class="sd">    &gt;&gt;&gt; [factorial(n) for n in range(6)]</span>

  247. <span class="sd">    [1, 1, 2, 6, 24, 120]</span>

  248. <span class="sd">    &gt;&gt;&gt; factorial(30)</span>

  249. <span class="sd">    265252859812191058636308480000000</span>

  250. <span class="sd">    &gt;&gt;&gt; factorial(-1)</span>

  251. <span class="sd">    Traceback (most recent call last):</span>

  252. <span class="sd">        ...</span>

  253. <span class="sd">    ValueError: n must be &gt;= 0</span>

  254. 

  255. <span class="sd">    Factorials of floats are OK, but the float must be an exact integer:</span>

  256. <span class="sd">    &gt;&gt;&gt; factorial(30.1)</span>

  257. <span class="sd">    Traceback (most recent call last):</span>

  258. <span class="sd">        ...</span>

  259. <span class="sd">    ValueError: n must be exact integer</span>

  260. <span class="sd">    &gt;&gt;&gt; factorial(30.0)</span>

  261. <span class="sd">    265252859812191058636308480000000</span>

  262. 

  263. <span class="sd">    It must also not be ridiculously large:</span>

  264. <span class="sd">    &gt;&gt;&gt; factorial(1e100)</span>

  265. <span class="sd">    Traceback (most recent call last):</span>

  266. <span class="sd">        ...</span>

  267. <span class="sd">    OverflowError: n too large</span>

  268. <span class="sd">    &quot;&quot;&quot;</span>

  269. 

  270.     <span class="kn">import</span> <span class="nn">math</span>

  271.     <span class="k">if</span> <span class="ow">not</span> <span class="n">n</span> <span class="o">&gt;=</span> <span class="mi">0</span><span class="p">:</span>

  272.         <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;n must be &gt;= 0&quot;</span><span class="p">)</span>

  273.     <span class="k">if</span> <span class="n">math</span><span class="o">.</span><span class="n">floor</span><span class="p">(</span><span class="n">n</span><span class="p">)</span> <span class="o">!=</span> <span class="n">n</span><span class="p">:</span>

  274.         <span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">&quot;n must be exact integer&quot;</span><span class="p">)</span>

  275.     <span class="k">if</span> <span class="n">n</span><span class="o">+</span><span class="mi">1</span> <span class="o">==</span> <span class="n">n</span><span class="p">:</span>  <span class="c1"># catch a value like 1e300</span>

  276.         <span class="k">raise</span> <span class="ne">OverflowError</span><span class="p">(</span><span class="s2">&quot;n too large&quot;</span><span class="p">)</span>

  277.     <span class="n">result</span> <span class="o">=</span> <span class="mi">1</span>

  278.     <span class="n">factor</span> <span class="o">=</span> <span class="mi">2</span>

  279.     <span class="k">while</span> <span class="n">factor</span> <span class="o">&lt;=</span> <span class="n">n</span><span class="p">:</span>

  280.         <span class="n">result</span> <span class="o">*=</span> <span class="n">factor</span>

  281.         <span class="n">factor</span> <span class="o">+=</span> <span class="mi">1</span>

  282.     <span class="k">return</span> <span class="n">result</span>

  283. 

  284. 

  285. <span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">&quot;__main__&quot;</span><span class="p">:</span>

  286.     <span class="kn">import</span> <span class="nn">doctest</span>

  287.     <span class="n">doctest</span><span class="o">.</span><span class="n">testmod</span><span class="p">()</span>

  288. </pre></div>

  289. </div>

  290. <p>If you run <code class="file docutils literal notranslate"><span class="pre">example.py</span></code> directly from the command line, <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a>

  291. works its magic:</p>

  292. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>example.py

  293. <span class="gp">$</span>

  294. </pre></div>

  295. </div>

  296. <p>There’s no output!  That’s normal, and it means all the examples worked.  Pass

  297. <code class="docutils literal notranslate"><span class="pre">-v</span></code> to the script, and <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> prints a detailed log of what

  298. it’s trying, and prints a summary at the end:</p>

  299. <div class="highlight-shell-session notranslate"><div class="highlight"><pre><span></span><span class="gp">$ </span>python<span class="w"> </span>example.py<span class="w"> </span>-v

  300. <span class="go">Trying:</span>

  301. <span class="go">    factorial(5)</span>

  302. <span class="go">Expecting:</span>

  303. <span class="go">    120</span>

  304. <span class="go">ok</span>

  305. <span class="go">Trying:</span>

  306. <span class="go">    [factorial(n) for n in range(6)]</span>

  307. <span class="go">Expecting:</span>

  308. <span class="go">    [1, 1, 2, 6, 24, 120]</span>

  309. <span class="go">ok</span>

  310. </pre></div>

  311. </div>

  312. <p>And so on, eventually ending with:</p>

  313. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Trying:

  314.     factorial(1e100)

  315. Expecting:

  316.     Traceback (most recent call last):

  317.         ...

  318.     OverflowError: n too large

  319. ok

  320. 2 items passed all tests:

  321.    1 tests in __main__

  322.    8 tests in __main__.factorial

  323. 9 tests in 2 items.

  324. 9 passed and 0 failed.

  325. Test passed.

  326. $

  327. </pre></div>

  328. </div>

  329. <p>That’s all you need to know to start making productive use of <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a>!

  330. Jump in.  The following sections provide full details.  Note that there are many

  331. examples of doctests in the standard Python test suite and libraries.

  332. Especially useful examples can be found in the standard test file

  333. <code class="file docutils literal notranslate"><span class="pre">Lib/test/test_doctest/test_doctest.py</span></code>.</p>

  334. <section id="simple-usage-checking-examples-in-docstrings">

  335. <span id="doctest-simple-testmod"></span><h2>Simple Usage: Checking Examples in Docstrings<a class="headerlink" href="#simple-usage-checking-examples-in-docstrings" title="Link to this heading">¶</a></h2>

  336. <p>The simplest way to start using doctest (but not necessarily the way you’ll

  337. continue to do it) is to end each module <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code> with:</p>

  338. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">&quot;__main__&quot;</span><span class="p">:</span>

  339.     <span class="kn">import</span> <span class="nn">doctest</span>

  340.     <span class="n">doctest</span><span class="o">.</span><span class="n">testmod</span><span class="p">()</span>

  341. </pre></div>

  342. </div>

  343. <p><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> then examines docstrings in module <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code>.</p>

  344. <p>Running the module as a script causes the examples in the docstrings to get

  345. executed and verified:</p>

  346. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">M</span><span class="o">.</span><span class="n">py</span>

  347. </pre></div>

  348. </div>

  349. <p>This won’t display anything unless an example fails, in which case the failing

  350. example(s) and the cause(s) of the failure(s) are printed to stdout, and the

  351. final line of output is <code class="docutils literal notranslate"><span class="pre">***Test</span> <span class="pre">Failed***</span> <span class="pre">N</span> <span class="pre">failures.</span></code>, where <em>N</em> is the

  352. number of examples that failed.</p>

  353. <p>Run it with the <code class="docutils literal notranslate"><span class="pre">-v</span></code> switch instead:</p>

  354. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">M</span><span class="o">.</span><span class="n">py</span> <span class="o">-</span><span class="n">v</span>

  355. </pre></div>

  356. </div>

  357. <p>and a detailed report of all examples tried is printed to standard output, along

  358. with assorted summaries at the end.</p>

  359. <p>You can force verbose mode by passing <code class="docutils literal notranslate"><span class="pre">verbose=True</span></code> to <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a>, or

  360. prohibit it by passing <code class="docutils literal notranslate"><span class="pre">verbose=False</span></code>.  In either of those cases,

  361. <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code> is not examined by <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a> (so passing <code class="docutils literal notranslate"><span class="pre">-v</span></code> or not

  362. has no effect).</p>

  363. <p>There is also a command line shortcut for running <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a>.  You can

  364. instruct the Python interpreter to run the doctest module directly from the

  365. standard library and pass the module name(s) on the command line:</p>

  366. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">doctest</span> <span class="o">-</span><span class="n">v</span> <span class="n">example</span><span class="o">.</span><span class="n">py</span>

  367. </pre></div>

  368. </div>

  369. <p>This will import <code class="file docutils literal notranslate"><span class="pre">example.py</span></code> as a standalone module and run

  370. <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a> on it.  Note that this may not work correctly if the file is

  371. part of a package and imports other submodules from that package.</p>

  372. <p>For more information on <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a>, see section <a class="reference internal" href="#doctest-basic-api"><span class="std std-ref">Basic API</span></a>.</p>

  373. </section>

  374. <section id="simple-usage-checking-examples-in-a-text-file">

  375. <span id="doctest-simple-testfile"></span><h2>Simple Usage: Checking Examples in a Text File<a class="headerlink" href="#simple-usage-checking-examples-in-a-text-file" title="Link to this heading">¶</a></h2>

  376. <p>Another simple application of doctest is testing interactive examples in a text

  377. file.  This can be done with the <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a> function:</p>

  378. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">doctest</span>

  379. <span class="n">doctest</span><span class="o">.</span><span class="n">testfile</span><span class="p">(</span><span class="s2">&quot;example.txt&quot;</span><span class="p">)</span>

  380. </pre></div>

  381. </div>

  382. <p>That short script executes and verifies any interactive Python examples

  383. contained in the file <code class="file docutils literal notranslate"><span class="pre">example.txt</span></code>.  The file content is treated as if it

  384. were a single giant docstring; the file doesn’t need to contain a Python

  385. program!   For example, perhaps <code class="file docutils literal notranslate"><span class="pre">example.txt</span></code> contains this:</p>

  386. <div class="highlight-none notranslate"><div class="highlight"><pre><span></span>The ``example`` module

  387. ======================

  388. 

  389. Using ``factorial``

  390. -------------------

  391. 

  392. This is an example text file in reStructuredText format.  First import

  393. ``factorial`` from the ``example`` module:

  394. 

  395.     &gt;&gt;&gt; from example import factorial

  396. 

  397. Now use it:

  398. 

  399.     &gt;&gt;&gt; factorial(6)

  400.     120

  401. </pre></div>

  402. </div>

  403. <p>Running <code class="docutils literal notranslate"><span class="pre">doctest.testfile(&quot;example.txt&quot;)</span></code> then finds the error in this

  404. documentation:</p>

  405. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">File</span> <span class="s2">&quot;./example.txt&quot;</span><span class="p">,</span> <span class="n">line</span> <span class="mi">14</span><span class="p">,</span> <span class="ow">in</span> <span class="n">example</span><span class="o">.</span><span class="n">txt</span>

  406. <span class="n">Failed</span> <span class="n">example</span><span class="p">:</span>

  407.     <span class="n">factorial</span><span class="p">(</span><span class="mi">6</span><span class="p">)</span>

  408. <span class="n">Expected</span><span class="p">:</span>

  409.     <span class="mi">120</span>

  410. <span class="n">Got</span><span class="p">:</span>

  411.     <span class="mi">720</span>

  412. </pre></div>

  413. </div>

  414. <p>As with <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a>, <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a> won’t display anything unless an

  415. example fails.  If an example does fail, then the failing example(s) and the

  416. cause(s) of the failure(s) are printed to stdout, using the same format as

  417. <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a>.</p>

  418. <p>By default, <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a> looks for files in the calling module’s directory.

  419. See section <a class="reference internal" href="#doctest-basic-api"><span class="std std-ref">Basic API</span></a> for a description of the optional arguments

  420. that can be used to tell it to look for files in other locations.</p>

  421. <p>Like <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a>, <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a>’s verbosity can be set with the

  422. <code class="docutils literal notranslate"><span class="pre">-v</span></code> command-line switch or with the optional keyword argument

  423. <em>verbose</em>.</p>

  424. <p>There is also a command line shortcut for running <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a>.  You can

  425. instruct the Python interpreter to run the doctest module directly from the

  426. standard library and pass the file name(s) on the command line:</p>

  427. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">doctest</span> <span class="o">-</span><span class="n">v</span> <span class="n">example</span><span class="o">.</span><span class="n">txt</span>

  428. </pre></div>

  429. </div>

  430. <p>Because the file name does not end with <code class="file docutils literal notranslate"><span class="pre">.py</span></code>, <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> infers that

  431. it must be run with <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a>, not <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a>.</p>

  432. <p>For more information on <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a>, see section <a class="reference internal" href="#doctest-basic-api"><span class="std std-ref">Basic API</span></a>.</p>

  433. </section>

  434. <section id="how-it-works">

  435. <span id="doctest-how-it-works"></span><h2>How It Works<a class="headerlink" href="#how-it-works" title="Link to this heading">¶</a></h2>

  436. <p>This section examines in detail how doctest works: which docstrings it looks at,

  437. how it finds interactive examples, what execution context it uses, how it

  438. handles exceptions, and how option flags can be used to control its behavior.

  439. This is the information that you need to know to write doctest examples; for

  440. information about actually running doctest on these examples, see the following

  441. sections.</p>

  442. <section id="which-docstrings-are-examined">

  443. <span id="doctest-which-docstrings"></span><h3>Which Docstrings Are Examined?<a class="headerlink" href="#which-docstrings-are-examined" title="Link to this heading">¶</a></h3>

  444. <p>The module docstring, and all function, class and method docstrings are

  445. searched.  Objects imported into the module are not searched.</p>

  446. <p>In addition, there are cases when you want tests to be part of a module but not part

  447. of the help text, which requires that the tests not be included in the docstring.

  448. Doctest looks for a module-level variable called <code class="docutils literal notranslate"><span class="pre">__test__</span></code> and uses it to locate other

  449. tests. If <code class="docutils literal notranslate"><span class="pre">M.__test__</span></code> exists, it must be a dict, and each

  450. entry maps a (string) name to a function object, class object, or string.

  451. Function and class object docstrings found from <code class="docutils literal notranslate"><span class="pre">M.__test__</span></code> are searched, and

  452. strings are treated as if they were docstrings.  In output, a key <code class="docutils literal notranslate"><span class="pre">K</span></code> in

  453. <code class="docutils literal notranslate"><span class="pre">M.__test__</span></code> appears with name <code class="docutils literal notranslate"><span class="pre">M.__test__.K</span></code>.</p>

  454. <p>For example, place this block of code at the top of <code class="file docutils literal notranslate"><span class="pre">example.py</span></code>:</p>

  455. <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">__test__</span> <span class="o">=</span> <span class="p">{</span>

  456.     <span class="s1">&#39;numbers&#39;</span><span class="p">:</span> <span class="s2">&quot;&quot;&quot;</span>

  457. <span class="s2">&gt;&gt;&gt; factorial(6)</span>

  458. <span class="s2">720</span>

  459. 

  460. <span class="s2">&gt;&gt;&gt; [factorial(n) for n in range(6)]</span>

  461. <span class="s2">[1, 1, 2, 6, 24, 120]</span>

  462. <span class="s2">&quot;&quot;&quot;</span>

  463. <span class="p">}</span>

  464. </pre></div>

  465. </div>

  466. <p>The value of <code class="docutils literal notranslate"><span class="pre">example.__test__[&quot;numbers&quot;]</span></code> will be treated as a

  467. docstring and all the tests inside it will be run. It is

  468. important to note that the value can be mapped to a function,

  469. class object, or module; if so, <code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code>

  470. searches them recursively for docstrings, which are then scanned for tests.</p>

  471. <p>Any classes found are recursively searched similarly, to test docstrings in

  472. their contained methods and nested classes.</p>

  473. </section>

  474. <section id="how-are-docstring-examples-recognized">

  475. <span id="doctest-finding-examples"></span><h3>How are Docstring Examples Recognized?<a class="headerlink" href="#how-are-docstring-examples-recognized" title="Link to this heading">¶</a></h3>

  476. <p>In most cases a copy-and-paste of an interactive console session works fine,

  477. but doctest isn’t trying to do an exact emulation of any specific Python shell.</p>

  478. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="c1"># comments are ignored</span>

  479. <span class="gp">&gt;&gt;&gt; </span><span class="n">x</span> <span class="o">=</span> <span class="mi">12</span>

  480. <span class="gp">&gt;&gt;&gt; </span><span class="n">x</span>

  481. <span class="go">12</span>

  482. <span class="gp">&gt;&gt;&gt; </span><span class="k">if</span> <span class="n">x</span> <span class="o">==</span> <span class="mi">13</span><span class="p">:</span>

  483. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;yes&quot;</span><span class="p">)</span>

  484. <span class="gp">... </span><span class="k">else</span><span class="p">:</span>

  485. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;no&quot;</span><span class="p">)</span>

  486. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;NO&quot;</span><span class="p">)</span>

  487. <span class="gp">... </span>    <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;NO!!!&quot;</span><span class="p">)</span>

  488. <span class="gp">...</span>

  489. <span class="go">no</span>

  490. <span class="go">NO</span>

  491. <span class="go">NO!!!</span>

  492. <span class="gp">&gt;&gt;&gt;</span>

  493. </pre></div>

  494. </div>

  495. <p id="index-0">Any expected output must immediately follow the final <code class="docutils literal notranslate"><span class="pre">'&gt;&gt;&gt;</span> <span class="pre">'</span></code> or <code class="docutils literal notranslate"><span class="pre">'...</span> <span class="pre">'</span></code>

  496. line containing the code, and the expected output (if any) extends to the next

  497. <code class="docutils literal notranslate"><span class="pre">'&gt;&gt;&gt;</span> <span class="pre">'</span></code> or all-whitespace line.</p>

  498. <p>The fine print:</p>

  499. <ul>

  500. <li><p>Expected output cannot contain an all-whitespace line, since such a line is

  501. taken to signal the end of expected output.  If expected output does contain a

  502. blank line, put <code class="docutils literal notranslate"><span class="pre">&lt;BLANKLINE&gt;</span></code> in your doctest example each place a blank line

  503. is expected.</p></li>

  504. <li><p>All hard tab characters are expanded to spaces, using 8-column tab stops.

  505. Tabs in output generated by the tested code are not modified.  Because any

  506. hard tabs in the sample output <em>are</em> expanded, this means that if the code

  507. output includes hard tabs, the only way the doctest can pass is if the

  508. <a class="reference internal" href="#doctest.NORMALIZE_WHITESPACE" title="doctest.NORMALIZE_WHITESPACE"><code class="xref py py-const docutils literal notranslate"><span class="pre">NORMALIZE_WHITESPACE</span></code></a> option or <a class="reference internal" href="#doctest-directives"><span class="std std-ref">directive</span></a>

  509. is in effect.

  510. Alternatively, the test can be rewritten to capture the output and compare it

  511. to an expected value as part of the test.  This handling of tabs in the

  512. source was arrived at through trial and error, and has proven to be the least

  513. error prone way of handling them.  It is possible to use a different

  514. algorithm for handling tabs by writing a custom <a class="reference internal" href="#doctest.DocTestParser" title="doctest.DocTestParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestParser</span></code></a> class.</p></li>

  515. <li><p>Output to stdout is captured, but not output to stderr (exception tracebacks

  516. are captured via a different means).</p></li>

  517. <li><p>If you continue a line via backslashing in an interactive session, or for any

  518. other reason use a backslash, you should use a raw docstring, which will

  519. preserve your backslashes exactly as you type them:</p>

  520. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>

  521. <span class="gp">... </span><span class="w">    </span><span class="sa">r</span><span class="sd">&#39;&#39;&#39;Backslashes in a raw docstring: m\n&#39;&#39;&#39;</span>

  522. <span class="gp">...</span>

  523. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="vm">__doc__</span><span class="p">)</span>

  524. <span class="go">Backslashes in a raw docstring: m\n</span>

  525. </pre></div>

  526. </div>

  527. <p>Otherwise, the backslash will be interpreted as part of the string. For example,

  528. the <code class="docutils literal notranslate"><span class="pre">\n</span></code> above would be interpreted as a newline character.  Alternatively, you

  529. can double each backslash in the doctest version (and not use a raw string):</p>

  530. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>

  531. <span class="gp">... </span><span class="w">    </span><span class="sd">&#39;&#39;&#39;Backslashes in a raw docstring: m\\n&#39;&#39;&#39;</span>

  532. <span class="gp">...</span>

  533. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="n">f</span><span class="o">.</span><span class="vm">__doc__</span><span class="p">)</span>

  534. <span class="go">Backslashes in a raw docstring: m\n</span>

  535. </pre></div>

  536. </div>

  537. </li>

  538. <li><p>The starting column doesn’t matter:</p>

  539. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">assert</span> <span class="s2">&quot;Easy!&quot;</span>

  540. <span class="go">      &gt;&gt;&gt; import math</span>

  541. <span class="go">          &gt;&gt;&gt; math.floor(1.9)</span>

  542. <span class="go">          1</span>

  543. </pre></div>

  544. </div>

  545. <p>and as many leading whitespace characters are stripped from the expected output

  546. as appeared in the initial <code class="docutils literal notranslate"><span class="pre">'&gt;&gt;&gt;</span> <span class="pre">'</span></code> line that started the example.</p>

  547. </li>

  548. </ul>

  549. </section>

  550. <section id="what-s-the-execution-context">

  551. <span id="doctest-execution-context"></span><h3>What’s the Execution Context?<a class="headerlink" href="#what-s-the-execution-context" title="Link to this heading">¶</a></h3>

  552. <p>By default, each time <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> finds a docstring to test, it uses a

  553. <em>shallow copy</em> of <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code>’s globals, so that running tests doesn’t change the

  554. module’s real globals, and so that one test in <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code> can’t leave behind

  555. crumbs that accidentally allow another test to work.  This means examples can

  556. freely use any names defined at top-level in <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code>, and names defined earlier

  557. in the docstring being run. Examples cannot see names defined in other

  558. docstrings.</p>

  559. <p>You can force use of your own dict as the execution context by passing

  560. <code class="docutils literal notranslate"><span class="pre">globs=your_dict</span></code> to <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a> or <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a> instead.</p>

  561. </section>

  562. <section id="what-about-exceptions">

  563. <span id="doctest-exceptions"></span><h3>What About Exceptions?<a class="headerlink" href="#what-about-exceptions" title="Link to this heading">¶</a></h3>

  564. <p>No problem, provided that the traceback is the only output produced by the

  565. example:  just paste in the traceback. <a class="footnote-reference brackets" href="#id2" id="id1" role="doc-noteref"><span class="fn-bracket">[</span>1<span class="fn-bracket">]</span></a> Since tracebacks contain details

  566. that are likely to change rapidly (for example, exact file paths and line

  567. numbers), this is one case where doctest works hard to be flexible in what it

  568. accepts.</p>

  569. <p>Simple example:</p>

  570. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="p">[</span><span class="mi">1</span><span class="p">,</span> <span class="mi">2</span><span class="p">,</span> <span class="mi">3</span><span class="p">]</span><span class="o">.</span><span class="n">remove</span><span class="p">(</span><span class="mi">42</span><span class="p">)</span>

  571. <span class="gt">Traceback (most recent call last):</span>

  572.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  573. <span class="gr">ValueError</span>: <span class="n">list.remove(x): x not in list</span>

  574. </pre></div>

  575. </div>

  576. <p>That doctest succeeds if <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is raised, with the <code class="docutils literal notranslate"><span class="pre">list.remove(x):</span>

  577. <span class="pre">x</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">list</span></code> detail as shown.</p>

  578. <p>The expected output for an exception must start with a traceback header, which

  579. may be either of the following two lines, indented the same as the first line of

  580. the example:</p>

  581. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">Traceback</span> <span class="p">(</span><span class="n">most</span> <span class="n">recent</span> <span class="n">call</span> <span class="n">last</span><span class="p">):</span>

  582. <span class="n">Traceback</span> <span class="p">(</span><span class="n">innermost</span> <span class="n">last</span><span class="p">):</span>

  583. </pre></div>

  584. </div>

  585. <p>The traceback header is followed by an optional traceback stack, whose contents

  586. are ignored by doctest.  The traceback stack is typically omitted, or copied

  587. verbatim from an interactive session.</p>

  588. <p>The traceback stack is followed by the most interesting part: the line(s)

  589. containing the exception type and detail.  This is usually the last line of a

  590. traceback, but can extend across multiple lines if the exception has a

  591. multi-line detail:</p>

  592. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;multi</span><span class="se">\n</span><span class="s1">    line</span><span class="se">\n</span><span class="s1">detail&#39;</span><span class="p">)</span>

  593. <span class="gt">Traceback (most recent call last):</span>

  594.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>, in <span class="n">&lt;module&gt;</span>

  595. <span class="gr">ValueError</span>: <span class="n">multi</span>

  596. <span class="x">    line</span>

  597. <span class="x">detail</span>

  598. </pre></div>

  599. </div>

  600. <p>The last three lines (starting with <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>) are compared against the

  601. exception’s type and detail, and the rest are ignored.</p>

  602. <p>Best practice is to omit the traceback stack, unless it adds significant

  603. documentation value to the example.  So the last example is probably better as:</p>

  604. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">&#39;multi</span><span class="se">\n</span><span class="s1">    line</span><span class="se">\n</span><span class="s1">detail&#39;</span><span class="p">)</span>

  605. <span class="gt">Traceback (most recent call last):</span>

  606. <span class="w">    </span><span class="o">...</span>

  607. <span class="gr">ValueError</span>: <span class="n">multi</span>

  608. <span class="x">    line</span>

  609. <span class="x">detail</span>

  610. </pre></div>

  611. </div>

  612. <p>Note that tracebacks are treated very specially.  In particular, in the

  613. rewritten example, the use of <code class="docutils literal notranslate"><span class="pre">...</span></code> is independent of doctest’s

  614. <a class="reference internal" href="#doctest.ELLIPSIS" title="doctest.ELLIPSIS"><code class="xref py py-const docutils literal notranslate"><span class="pre">ELLIPSIS</span></code></a> option.  The ellipsis in that example could be left out, or

  615. could just as well be three (or three hundred) commas or digits, or an indented

  616. transcript of a Monty Python skit.</p>

  617. <p>Some details you should read once, but won’t need to remember:</p>

  618. <ul class="simple">

  619. <li><p>Doctest can’t guess whether your expected output came from an exception

  620. traceback or from ordinary printing.  So, e.g., an example that expects

  621. <code class="docutils literal notranslate"><span class="pre">ValueError:</span> <span class="pre">42</span> <span class="pre">is</span> <span class="pre">prime</span></code> will pass whether <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a> is actually

  622. raised or if the example merely prints that traceback text.  In practice,

  623. ordinary output rarely begins with a traceback header line, so this doesn’t

  624. create real problems.</p></li>

  625. <li><p>Each line of the traceback stack (if present) must be indented further than

  626. the first line of the example, <em>or</em> start with a non-alphanumeric character.

  627. The first line following the traceback header indented the same and starting

  628. with an alphanumeric is taken to be the start of the exception detail.  Of

  629. course this does the right thing for genuine tracebacks.</p></li>

  630. <li><p>When the <a class="reference internal" href="#doctest.IGNORE_EXCEPTION_DETAIL" title="doctest.IGNORE_EXCEPTION_DETAIL"><code class="xref py py-const docutils literal notranslate"><span class="pre">IGNORE_EXCEPTION_DETAIL</span></code></a> doctest option is specified,

  631. everything following the leftmost colon and any module information in the

  632. exception name is ignored.</p></li>

  633. <li><p>The interactive shell omits the traceback header line for some

  634. <a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a>s.  But doctest uses the traceback header line to

  635. distinguish exceptions from non-exceptions.  So in the rare case where you need

  636. to test a <a class="reference internal" href="exceptions.html#SyntaxError" title="SyntaxError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">SyntaxError</span></code></a> that omits the traceback header, you will need to

  637. manually add the traceback header line to your test example.</p></li>

  638. </ul>

  639. <ul id="index-1">

  640. <li><p>For some exceptions, Python displays the position of the error using <code class="docutils literal notranslate"><span class="pre">^</span></code>

  641. markers and tildes:</p>

  642. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="mi">1</span> <span class="o">+</span> <span class="kc">None</span>

  643.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>

  644. <span class="w">    </span><span class="mi">1</span> <span class="o">+</span> <span class="kc">None</span>

  645. <span class="w">    </span><span class="pm">~~^~~~~~</span>

  646. <span class="gr">TypeError</span>: <span class="n">unsupported operand type(s) for +: &#39;int&#39; and &#39;NoneType&#39;</span>

  647. </pre></div>

  648. </div>

  649. <p>Since the lines showing the position of the error come before the exception type

  650. and detail, they are not checked by doctest.  For example, the following test

  651. would pass, even though it puts the <code class="docutils literal notranslate"><span class="pre">^</span></code> marker in the wrong location:</p>

  652. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="mi">1</span> <span class="o">+</span> <span class="kc">None</span>

  653.   File <span class="nb">&quot;&lt;stdin&gt;&quot;</span>, line <span class="m">1</span>

  654. <span class="w">    </span><span class="mi">1</span> <span class="o">+</span> <span class="kc">None</span>

  655. <span class="w">    </span><span class="pm">^~~~~~~~</span>

  656. <span class="gr">TypeError</span>: <span class="n">unsupported operand type(s) for +: &#39;int&#39; and &#39;NoneType&#39;</span>

  657. </pre></div>

  658. </div>

  659. </li>

  660. </ul>

  661. </section>

  662. <section id="option-flags">

  663. <span id="doctest-options"></span><span id="option-flags-and-directives"></span><h3>Option Flags<a class="headerlink" href="#option-flags" title="Link to this heading">¶</a></h3>

  664. <p>A number of option flags control various aspects of doctest’s behavior.

  665. Symbolic names for the flags are supplied as module constants, which can be

  666. <a class="reference internal" href="../reference/expressions.html#bitwise"><span class="std std-ref">bitwise ORed</span></a> together and passed to various functions.

  667. The names can also be used in <a class="reference internal" href="#doctest-directives"><span class="std std-ref">doctest directives</span></a>,

  668. and may be passed to the doctest command line interface via the <code class="docutils literal notranslate"><span class="pre">-o</span></code> option.</p>

  669. <div class="versionadded">

  670. <p><span class="versionmodified added">New in version 3.4: </span>The <code class="docutils literal notranslate"><span class="pre">-o</span></code> command line option.</p>

  671. </div>

  672. <p>The first group of options define test semantics, controlling aspects of how

  673. doctest decides whether actual output matches an example’s expected output:</p>

  674. <dl class="py data">

  675. <dt class="sig sig-object py" id="doctest.DONT_ACCEPT_TRUE_FOR_1">

  676. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">DONT_ACCEPT_TRUE_FOR_1</span></span><a class="headerlink" href="#doctest.DONT_ACCEPT_TRUE_FOR_1" title="Link to this definition">¶</a></dt>

  677. <dd><p>By default, if an expected output block contains just <code class="docutils literal notranslate"><span class="pre">1</span></code>, an actual output

  678. block containing just <code class="docutils literal notranslate"><span class="pre">1</span></code> or just <code class="docutils literal notranslate"><span class="pre">True</span></code> is considered to be a match, and

  679. similarly for <code class="docutils literal notranslate"><span class="pre">0</span></code> versus <code class="docutils literal notranslate"><span class="pre">False</span></code>.  When <a class="reference internal" href="#doctest.DONT_ACCEPT_TRUE_FOR_1" title="doctest.DONT_ACCEPT_TRUE_FOR_1"><code class="xref py py-const docutils literal notranslate"><span class="pre">DONT_ACCEPT_TRUE_FOR_1</span></code></a> is

  680. specified, neither substitution is allowed.  The default behavior caters to that

  681. Python changed the return type of many functions from integer to boolean;

  682. doctests expecting “little integer” output still work in these cases.  This

  683. option will probably go away, but not for several years.</p>

  684. </dd></dl>

  685. 

  686. <dl class="py data" id="index-2">

  687. <dt class="sig sig-object py" id="doctest.DONT_ACCEPT_BLANKLINE">

  688. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">DONT_ACCEPT_BLANKLINE</span></span><a class="headerlink" href="#doctest.DONT_ACCEPT_BLANKLINE" title="Link to this definition">¶</a></dt>

  689. <dd><p>By default, if an expected output block contains a line containing only the

  690. string <code class="docutils literal notranslate"><span class="pre">&lt;BLANKLINE&gt;</span></code>, then that line will match a blank line in the actual

  691. output.  Because a genuinely blank line delimits the expected output, this is

  692. the only way to communicate that a blank line is expected.  When

  693. <a class="reference internal" href="#doctest.DONT_ACCEPT_BLANKLINE" title="doctest.DONT_ACCEPT_BLANKLINE"><code class="xref py py-const docutils literal notranslate"><span class="pre">DONT_ACCEPT_BLANKLINE</span></code></a> is specified, this substitution is not allowed.</p>

  694. </dd></dl>

  695. 

  696. <dl class="py data">

  697. <dt class="sig sig-object py" id="doctest.NORMALIZE_WHITESPACE">

  698. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">NORMALIZE_WHITESPACE</span></span><a class="headerlink" href="#doctest.NORMALIZE_WHITESPACE" title="Link to this definition">¶</a></dt>

  699. <dd><p>When specified, all sequences of whitespace (blanks and newlines) are treated as

  700. equal.  Any sequence of whitespace within the expected output will match any

  701. sequence of whitespace within the actual output. By default, whitespace must

  702. match exactly. <a class="reference internal" href="#doctest.NORMALIZE_WHITESPACE" title="doctest.NORMALIZE_WHITESPACE"><code class="xref py py-const docutils literal notranslate"><span class="pre">NORMALIZE_WHITESPACE</span></code></a> is especially useful when a line of

  703. expected output is very long, and you want to wrap it across multiple lines in

  704. your source.</p>

  705. </dd></dl>

  706. 

  707. <dl class="py data" id="index-3">

  708. <dt class="sig sig-object py" id="doctest.ELLIPSIS">

  709. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">ELLIPSIS</span></span><a class="headerlink" href="#doctest.ELLIPSIS" title="Link to this definition">¶</a></dt>

  710. <dd><p>When specified, an ellipsis marker (<code class="docutils literal notranslate"><span class="pre">...</span></code>) in the expected output can match

  711. any substring in the actual output.  This includes substrings that span line

  712. boundaries, and empty substrings, so it’s best to keep usage of this simple.

  713. Complicated uses can lead to the same kinds of “oops, it matched too much!”

  714. surprises that <code class="docutils literal notranslate"><span class="pre">.*</span></code> is prone to in regular expressions.</p>

  715. </dd></dl>

  716. 

  717. <dl class="py data">

  718. <dt class="sig sig-object py" id="doctest.IGNORE_EXCEPTION_DETAIL">

  719. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">IGNORE_EXCEPTION_DETAIL</span></span><a class="headerlink" href="#doctest.IGNORE_EXCEPTION_DETAIL" title="Link to this definition">¶</a></dt>

  720. <dd><p>When specified, doctests expecting exceptions pass so long as an exception

  721. of the expected type is raised, even if the details

  722. (message and fully qualified exception name) don’t match.</p>

  723. <p>For example, an example expecting <code class="docutils literal notranslate"><span class="pre">ValueError:</span> <span class="pre">42</span></code> will pass if the actual

  724. exception raised is <code class="docutils literal notranslate"><span class="pre">ValueError:</span> <span class="pre">3*14</span></code>, but will fail if, say, a

  725. <a class="reference internal" href="exceptions.html#TypeError" title="TypeError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">TypeError</span></code></a> is raised instead.

  726. It will also ignore any fully qualified name included before the

  727. exception class, which can vary between implementations and versions

  728. of Python and the code/libraries in use.

  729. Hence, all three of these variations will work with the flag specified:</p>

  730. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s1">&#39;message&#39;</span><span class="p">)</span>

  731. <span class="gt">Traceback (most recent call last):</span>

  732. <span class="gr">Exception</span>: <span class="n">message</span>

  733. 

  734. <span class="gp">&gt;&gt;&gt; </span><span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s1">&#39;message&#39;</span><span class="p">)</span>

  735. <span class="gt">Traceback (most recent call last):</span>

  736. <span class="gr">builtins.Exception</span>: <span class="n">message</span>

  737. 

  738. <span class="gp">&gt;&gt;&gt; </span><span class="k">raise</span> <span class="ne">Exception</span><span class="p">(</span><span class="s1">&#39;message&#39;</span><span class="p">)</span>

  739. <span class="gt">Traceback (most recent call last):</span>

  740. <span class="gr">__main__.Exception</span>: <span class="n">message</span>

  741. </pre></div>

  742. </div>

  743. <p>Note that <a class="reference internal" href="#doctest.ELLIPSIS" title="doctest.ELLIPSIS"><code class="xref py py-const docutils literal notranslate"><span class="pre">ELLIPSIS</span></code></a> can also be used to ignore the

  744. details of the exception message, but such a test may still fail based

  745. on whether the module name is present or matches exactly.</p>

  746. <div class="versionchanged">

  747. <p><span class="versionmodified changed">Changed in version 3.2: </span><a class="reference internal" href="#doctest.IGNORE_EXCEPTION_DETAIL" title="doctest.IGNORE_EXCEPTION_DETAIL"><code class="xref py py-const docutils literal notranslate"><span class="pre">IGNORE_EXCEPTION_DETAIL</span></code></a> now also ignores any information relating

  748. to the module containing the exception under test.</p>

  749. </div>

  750. </dd></dl>

  751. 

  752. <dl class="py data">

  753. <dt class="sig sig-object py" id="doctest.SKIP">

  754. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">SKIP</span></span><a class="headerlink" href="#doctest.SKIP" title="Link to this definition">¶</a></dt>

  755. <dd><p>When specified, do not run the example at all.  This can be useful in contexts

  756. where doctest examples serve as both documentation and test cases, and an

  757. example should be included for documentation purposes, but should not be

  758. checked.  E.g., the example’s output might be random; or the example might

  759. depend on resources which would be unavailable to the test driver.</p>

  760. <p>The SKIP flag can also be used for temporarily “commenting out” examples.</p>

  761. </dd></dl>

  762. 

  763. <dl class="py data">

  764. <dt class="sig sig-object py" id="doctest.COMPARISON_FLAGS">

  765. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">COMPARISON_FLAGS</span></span><a class="headerlink" href="#doctest.COMPARISON_FLAGS" title="Link to this definition">¶</a></dt>

  766. <dd><p>A bitmask or’ing together all the comparison flags above.</p>

  767. </dd></dl>

  768. 

  769. <p>The second group of options controls how test failures are reported:</p>

  770. <dl class="py data">

  771. <dt class="sig sig-object py" id="doctest.REPORT_UDIFF">

  772. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">REPORT_UDIFF</span></span><a class="headerlink" href="#doctest.REPORT_UDIFF" title="Link to this definition">¶</a></dt>

  773. <dd><p>When specified, failures that involve multi-line expected and actual outputs are

  774. displayed using a unified diff.</p>

  775. </dd></dl>

  776. 

  777. <dl class="py data">

  778. <dt class="sig sig-object py" id="doctest.REPORT_CDIFF">

  779. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">REPORT_CDIFF</span></span><a class="headerlink" href="#doctest.REPORT_CDIFF" title="Link to this definition">¶</a></dt>

  780. <dd><p>When specified, failures that involve multi-line expected and actual outputs

  781. will be displayed using a context diff.</p>

  782. </dd></dl>

  783. 

  784. <dl class="py data">

  785. <dt class="sig sig-object py" id="doctest.REPORT_NDIFF">

  786. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">REPORT_NDIFF</span></span><a class="headerlink" href="#doctest.REPORT_NDIFF" title="Link to this definition">¶</a></dt>

  787. <dd><p>When specified, differences are computed by <code class="docutils literal notranslate"><span class="pre">difflib.Differ</span></code>, using the same

  788. algorithm as the popular <code class="file docutils literal notranslate"><span class="pre">ndiff.py</span></code> utility. This is the only method that

  789. marks differences within lines as well as across lines.  For example, if a line

  790. of expected output contains digit <code class="docutils literal notranslate"><span class="pre">1</span></code> where actual output contains letter

  791. <code class="docutils literal notranslate"><span class="pre">l</span></code>, a line is inserted with a caret marking the mismatching column positions.</p>

  792. </dd></dl>

  793. 

  794. <dl class="py data">

  795. <dt class="sig sig-object py" id="doctest.REPORT_ONLY_FIRST_FAILURE">

  796. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">REPORT_ONLY_FIRST_FAILURE</span></span><a class="headerlink" href="#doctest.REPORT_ONLY_FIRST_FAILURE" title="Link to this definition">¶</a></dt>

  797. <dd><p>When specified, display the first failing example in each doctest, but suppress

  798. output for all remaining examples.  This will prevent doctest from reporting

  799. correct examples that break because of earlier failures; but it might also hide

  800. incorrect examples that fail independently of the first failure.  When

  801. <a class="reference internal" href="#doctest.REPORT_ONLY_FIRST_FAILURE" title="doctest.REPORT_ONLY_FIRST_FAILURE"><code class="xref py py-const docutils literal notranslate"><span class="pre">REPORT_ONLY_FIRST_FAILURE</span></code></a> is specified, the remaining examples are

  802. still run, and still count towards the total number of failures reported; only

  803. the output is suppressed.</p>

  804. </dd></dl>

  805. 

  806. <dl class="py data">

  807. <dt class="sig sig-object py" id="doctest.FAIL_FAST">

  808. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">FAIL_FAST</span></span><a class="headerlink" href="#doctest.FAIL_FAST" title="Link to this definition">¶</a></dt>

  809. <dd><p>When specified, exit after the first failing example and don’t attempt to run

  810. the remaining examples. Thus, the number of failures reported will be at most

  811. 1.  This flag may be useful during debugging, since examples after the first

  812. failure won’t even produce debugging output.</p>

  813. <p>The doctest command line accepts the option <code class="docutils literal notranslate"><span class="pre">-f</span></code> as a shorthand for <code class="docutils literal notranslate"><span class="pre">-o</span>

  814. <span class="pre">FAIL_FAST</span></code>.</p>

  815. <div class="versionadded">

  816. <p><span class="versionmodified added">New in version 3.4.</span></p>

  817. </div>

  818. </dd></dl>

  819. 

  820. <dl class="py data">

  821. <dt class="sig sig-object py" id="doctest.REPORTING_FLAGS">

  822. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">REPORTING_FLAGS</span></span><a class="headerlink" href="#doctest.REPORTING_FLAGS" title="Link to this definition">¶</a></dt>

  823. <dd><p>A bitmask or’ing together all the reporting flags above.</p>

  824. </dd></dl>

  825. 

  826. <p>There is also a way to register new option flag names, though this isn’t

  827. useful unless you intend to extend <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> internals via subclassing:</p>

  828. <dl class="py function">

  829. <dt class="sig sig-object py" id="doctest.register_optionflag">

  830. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">register_optionflag</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.register_optionflag" title="Link to this definition">¶</a></dt>

  831. <dd><p>Create a new option flag with a given name, and return the new flag’s integer

  832. value.  <a class="reference internal" href="#doctest.register_optionflag" title="doctest.register_optionflag"><code class="xref py py-func docutils literal notranslate"><span class="pre">register_optionflag()</span></code></a> can be used when subclassing

  833. <a class="reference internal" href="#doctest.OutputChecker" title="doctest.OutputChecker"><code class="xref py py-class docutils literal notranslate"><span class="pre">OutputChecker</span></code></a> or <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> to create new options that are

  834. supported by your subclasses.  <a class="reference internal" href="#doctest.register_optionflag" title="doctest.register_optionflag"><code class="xref py py-func docutils literal notranslate"><span class="pre">register_optionflag()</span></code></a> should always be

  835. called using the following idiom:</p>

  836. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">MY_FLAG</span> <span class="o">=</span> <span class="n">register_optionflag</span><span class="p">(</span><span class="s1">&#39;MY_FLAG&#39;</span><span class="p">)</span>

  837. </pre></div>

  838. </div>

  839. </dd></dl>

  840. 

  841. </section>

  842. <section id="directives">

  843. <span id="doctest-directives"></span><span id="index-4"></span><h3>Directives<a class="headerlink" href="#directives" title="Link to this heading">¶</a></h3>

  844. <p>Doctest directives may be used to modify the <a class="reference internal" href="#doctest-options"><span class="std std-ref">option flags</span></a> for an individual example.  Doctest directives are

  845. special Python comments following an example’s source code:</p>

  846. <pre>

  847. <strong id="grammar-token-doctest-directive">directive            </strong> ::=  &quot;#&quot; &quot;doctest:&quot; <a class="reference internal" href="#grammar-token-doctest-directive_options"><code class="xref docutils literal notranslate"><span class="pre">directive_options</span></code></a>

  848. <strong id="grammar-token-doctest-directive_options">directive_options    </strong> ::=  <a class="reference internal" href="#grammar-token-doctest-directive_option"><code class="xref docutils literal notranslate"><span class="pre">directive_option</span></code></a> (&quot;,&quot; <a class="reference internal" href="#grammar-token-doctest-directive_option"><code class="xref docutils literal notranslate"><span class="pre">directive_option</span></code></a>)*

  849. <strong id="grammar-token-doctest-directive_option">directive_option     </strong> ::=  <a class="reference internal" href="#grammar-token-doctest-on_or_off"><code class="xref docutils literal notranslate"><span class="pre">on_or_off</span></code></a> <a class="reference internal" href="#grammar-token-doctest-directive_option_name"><code class="xref docutils literal notranslate"><span class="pre">directive_option_name</span></code></a>

  850. <strong id="grammar-token-doctest-on_or_off">on_or_off            </strong> ::=  &quot;+&quot; | &quot;-&quot;

  851. <strong id="grammar-token-doctest-directive_option_name">directive_option_name</strong> ::=  &quot;DONT_ACCEPT_BLANKLINE&quot; | &quot;NORMALIZE_WHITESPACE&quot; | ...

  852. </pre>

  853. <p>Whitespace is not allowed between the <code class="docutils literal notranslate"><span class="pre">+</span></code> or <code class="docutils literal notranslate"><span class="pre">-</span></code> and the directive option

  854. name.  The directive option name can be any of the option flag names explained

  855. above.</p>

  856. <p>An example’s doctest directives modify doctest’s behavior for that single

  857. example.  Use <code class="docutils literal notranslate"><span class="pre">+</span></code> to enable the named behavior, or <code class="docutils literal notranslate"><span class="pre">-</span></code> to disable it.</p>

  858. <p>For example, this test passes:</p>

  859. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">20</span><span class="p">)))</span>  <span class="c1"># doctest: +NORMALIZE_WHITESPACE</span>

  860. <span class="go">[0,   1,  2,  3,  4,  5,  6,  7,  8,  9,</span>

  861. <span class="go">10,  11, 12, 13, 14, 15, 16, 17, 18, 19]</span>

  862. </pre></div>

  863. </div>

  864. <p>Without the directive it would fail, both because the actual output doesn’t have

  865. two blanks before the single-digit list elements, and because the actual output

  866. is on a single line.  This test also passes, and also requires a directive to do

  867. so:</p>

  868. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">20</span><span class="p">)))</span>  <span class="c1"># doctest: +ELLIPSIS</span>

  869. <span class="go">[0, 1, ..., 18, 19]</span>

  870. </pre></div>

  871. </div>

  872. <p>Multiple directives can be used on a single physical line, separated by

  873. commas:</p>

  874. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">20</span><span class="p">)))</span>  <span class="c1"># doctest: +ELLIPSIS, +NORMALIZE_WHITESPACE</span>

  875. <span class="go">[0,    1, ...,   18,    19]</span>

  876. </pre></div>

  877. </div>

  878. <p>If multiple directive comments are used for a single example, then they are

  879. combined:</p>

  880. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">20</span><span class="p">)))</span>  <span class="c1"># doctest: +ELLIPSIS</span>

  881. <span class="gp">... </span>                        <span class="c1"># doctest: +NORMALIZE_WHITESPACE</span>

  882. <span class="go">[0,    1, ...,   18,    19]</span>

  883. </pre></div>

  884. </div>

  885. <p>As the previous example shows, you can add <code class="docutils literal notranslate"><span class="pre">...</span></code> lines to your example

  886. containing only directives.  This can be useful when an example is too long for

  887. a directive to comfortably fit on the same line:</p>

  888. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">5</span><span class="p">))</span> <span class="o">+</span> <span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">10</span><span class="p">,</span> <span class="mi">20</span><span class="p">))</span> <span class="o">+</span> <span class="nb">list</span><span class="p">(</span><span class="nb">range</span><span class="p">(</span><span class="mi">30</span><span class="p">,</span> <span class="mi">40</span><span class="p">)))</span>

  889. <span class="gp">... </span><span class="c1"># doctest: +ELLIPSIS</span>

  890. <span class="go">[0, ..., 4, 10, ..., 19, 30, ..., 39]</span>

  891. </pre></div>

  892. </div>

  893. <p>Note that since all options are disabled by default, and directives apply only

  894. to the example they appear in, enabling options (via <code class="docutils literal notranslate"><span class="pre">+</span></code> in a directive) is

  895. usually the only meaningful choice.  However, option flags can also be passed to

  896. functions that run doctests, establishing different defaults.  In such cases,

  897. disabling an option via <code class="docutils literal notranslate"><span class="pre">-</span></code> in a directive can be useful.</p>

  898. </section>

  899. <section id="warnings">

  900. <span id="doctest-warnings"></span><h3>Warnings<a class="headerlink" href="#warnings" title="Link to this heading">¶</a></h3>

  901. <p><a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> is serious about requiring exact matches in expected output.  If

  902. even a single character doesn’t match, the test fails.  This will probably

  903. surprise you a few times, as you learn exactly what Python does and doesn’t

  904. guarantee about output.  For example, when printing a set, Python doesn’t

  905. guarantee that the element is printed in any particular order, so a test like</p>

  906. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">foo</span><span class="p">()</span>

  907. <span class="go">{&quot;Hermione&quot;, &quot;Harry&quot;}</span>

  908. </pre></div>

  909. </div>

  910. <p>is vulnerable!  One workaround is to do</p>

  911. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">foo</span><span class="p">()</span> <span class="o">==</span> <span class="p">{</span><span class="s2">&quot;Hermione&quot;</span><span class="p">,</span> <span class="s2">&quot;Harry&quot;</span><span class="p">}</span>

  912. <span class="go">True</span>

  913. </pre></div>

  914. </div>

  915. <p>instead.  Another is to do</p>

  916. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">d</span> <span class="o">=</span> <span class="nb">sorted</span><span class="p">(</span><span class="n">foo</span><span class="p">())</span>

  917. <span class="gp">&gt;&gt;&gt; </span><span class="n">d</span>

  918. <span class="go">[&#39;Harry&#39;, &#39;Hermione&#39;]</span>

  919. </pre></div>

  920. </div>

  921. <p>There are others, but you get the idea.</p>

  922. <p>Another bad idea is to print things that embed an object address, like</p>

  923. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="nb">id</span><span class="p">(</span><span class="mf">1.0</span><span class="p">)</span>  <span class="c1"># certain to fail some of the time  </span>

  924. <span class="go">7948648</span>

  925. <span class="gp">&gt;&gt;&gt; </span><span class="k">class</span> <span class="nc">C</span><span class="p">:</span> <span class="k">pass</span>

  926. <span class="gp">&gt;&gt;&gt; </span><span class="n">C</span><span class="p">()</span>  <span class="c1"># the default repr() for instances embeds an address   </span>

  927. <span class="go">&lt;C object at 0x00AC18F0&gt;</span>

  928. </pre></div>

  929. </div>

  930. <p>The <a class="reference internal" href="#doctest.ELLIPSIS" title="doctest.ELLIPSIS"><code class="xref py py-const docutils literal notranslate"><span class="pre">ELLIPSIS</span></code></a> directive gives a nice approach for the last example:</p>

  931. <div class="highlight-pycon notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="n">C</span><span class="p">()</span>  <span class="c1"># doctest: +ELLIPSIS</span>

  932. <span class="go">&lt;C object at 0x...&gt;</span>

  933. </pre></div>

  934. </div>

  935. <p>Floating-point numbers are also subject to small output variations across

  936. platforms, because Python defers to the platform C library for float formatting,

  937. and C libraries vary widely in quality here.</p>

  938. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="mf">1.</span><span class="o">/</span><span class="mi">7</span>  <span class="c1"># risky</span>

  939. <span class="go">0.14285714285714285</span>

  940. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="mf">1.</span><span class="o">/</span><span class="mi">7</span><span class="p">)</span> <span class="c1"># safer</span>

  941. <span class="go">0.142857142857</span>

  942. <span class="gp">&gt;&gt;&gt; </span><span class="nb">print</span><span class="p">(</span><span class="nb">round</span><span class="p">(</span><span class="mf">1.</span><span class="o">/</span><span class="mi">7</span><span class="p">,</span> <span class="mi">6</span><span class="p">))</span> <span class="c1"># much safer</span>

  943. <span class="go">0.142857</span>

  944. </pre></div>

  945. </div>

  946. <p>Numbers of the form <code class="docutils literal notranslate"><span class="pre">I/2.**J</span></code> are safe across all platforms, and I often

  947. contrive doctest examples to produce numbers of that form:</p>

  948. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="mf">3.</span><span class="o">/</span><span class="mi">4</span>  <span class="c1"># utterly safe</span>

  949. <span class="go">0.75</span>

  950. </pre></div>

  951. </div>

  952. <p>Simple fractions are also easier for people to understand, and that makes for

  953. better documentation.</p>

  954. </section>

  955. </section>

  956. <section id="basic-api">

  957. <span id="doctest-basic-api"></span><h2>Basic API<a class="headerlink" href="#basic-api" title="Link to this heading">¶</a></h2>

  958. <p>The functions <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a> and <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a> provide a simple interface to

  959. doctest that should be sufficient for most basic uses.  For a less formal

  960. introduction to these two functions, see sections <a class="reference internal" href="#doctest-simple-testmod"><span class="std std-ref">Simple Usage: Checking Examples in Docstrings</span></a>

  961. and <a class="reference internal" href="#doctest-simple-testfile"><span class="std std-ref">Simple Usage: Checking Examples in a Text File</span></a>.</p>

  962. <dl class="py function">

  963. <dt class="sig sig-object py" id="doctest.testfile">

  964. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">testfile</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">module_relative</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">package</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">globs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">report</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">optionflags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">extraglobs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">raise_on_error</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parser</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DocTestParser()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.testfile" title="Link to this definition">¶</a></dt>

  965. <dd><p>All arguments except <em>filename</em> are optional, and should be specified in keyword

  966. form.</p>

  967. <p>Test examples in the file named <em>filename</em>.  Return <code class="docutils literal notranslate"><span class="pre">(failure_count,</span>

  968. <span class="pre">test_count)</span></code>.</p>

  969. <p>Optional argument <em>module_relative</em> specifies how the filename should be

  970. interpreted:</p>

  971. <ul class="simple">

  972. <li><p>If <em>module_relative</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), then <em>filename</em> specifies an

  973. OS-independent module-relative path.  By default, this path is relative to the

  974. calling module’s directory; but if the <em>package</em> argument is specified, then it

  975. is relative to that package.  To ensure OS-independence, <em>filename</em> should use

  976. <code class="docutils literal notranslate"><span class="pre">/</span></code> characters to separate path segments, and may not be an absolute path

  977. (i.e., it may not begin with <code class="docutils literal notranslate"><span class="pre">/</span></code>).</p></li>

  978. <li><p>If <em>module_relative</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, then <em>filename</em> specifies an OS-specific

  979. path.  The path may be absolute or relative; relative paths are resolved with

  980. respect to the current working directory.</p></li>

  981. </ul>

  982. <p>Optional argument <em>name</em> gives the name of the test; by default, or if <code class="docutils literal notranslate"><span class="pre">None</span></code>,

  983. <code class="docutils literal notranslate"><span class="pre">os.path.basename(filename)</span></code> is used.</p>

  984. <p>Optional argument <em>package</em> is a Python package or the name of a Python package

  985. whose directory should be used as the base directory for a module-relative

  986. filename.  If no package is specified, then the calling module’s directory is

  987. used as the base directory for module-relative filenames.  It is an error to

  988. specify <em>package</em> if <em>module_relative</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>

  989. <p>Optional argument <em>globs</em> gives a dict to be used as the globals when executing

  990. examples.  A new shallow copy of this dict is created for the doctest, so its

  991. examples start with a clean slate. By default, or if <code class="docutils literal notranslate"><span class="pre">None</span></code>, a new empty dict

  992. is used.</p>

  993. <p>Optional argument <em>extraglobs</em> gives a dict merged into the globals used to

  994. execute examples.  This works like <a class="reference internal" href="stdtypes.html#dict.update" title="dict.update"><code class="xref py py-meth docutils literal notranslate"><span class="pre">dict.update()</span></code></a>:  if <em>globs</em> and

  995. <em>extraglobs</em> have a common key, the associated value in <em>extraglobs</em> appears in

  996. the combined dict.  By default, or if <code class="docutils literal notranslate"><span class="pre">None</span></code>, no extra globals are used.  This

  997. is an advanced feature that allows parameterization of doctests.  For example, a

  998. doctest can be written for a base class, using a generic name for the class,

  999. then reused to test any number of subclasses by passing an <em>extraglobs</em> dict

  1000. mapping the generic name to the subclass to be tested.</p>

  1001. <p>Optional argument <em>verbose</em> prints lots of stuff if true, and prints only

  1002. failures if false; by default, or if <code class="docutils literal notranslate"><span class="pre">None</span></code>, it’s true if and only if <code class="docutils literal notranslate"><span class="pre">'-v'</span></code>

  1003. is in <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code>.</p>

  1004. <p>Optional argument <em>report</em> prints a summary at the end when true, else prints

  1005. nothing at the end.  In verbose mode, the summary is detailed, else the summary

  1006. is very brief (in fact, empty if all tests passed).</p>

  1007. <p>Optional argument <em>optionflags</em> (default value 0) takes the

  1008. <a class="reference internal" href="../reference/expressions.html#bitwise"><span class="std std-ref">bitwise OR</span></a> of option flags.

  1009. See section <a class="reference internal" href="#doctest-options"><span class="std std-ref">Option Flags</span></a>.</p>

  1010. <p>Optional argument <em>raise_on_error</em> defaults to false.  If true, an exception is

  1011. raised upon the first failure or unexpected exception in an example.  This

  1012. allows failures to be post-mortem debugged. Default behavior is to continue

  1013. running examples.</p>

  1014. <p>Optional argument <em>parser</em> specifies a <a class="reference internal" href="#doctest.DocTestParser" title="doctest.DocTestParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestParser</span></code></a> (or subclass) that

  1015. should be used to extract tests from the files.  It defaults to a normal parser

  1016. (i.e., <code class="docutils literal notranslate"><span class="pre">DocTestParser()</span></code>).</p>

  1017. <p>Optional argument <em>encoding</em> specifies an encoding that should be used to

  1018. convert the file to unicode.</p>

  1019. </dd></dl>

  1020. 

  1021. <dl class="py function">

  1022. <dt class="sig sig-object py" id="doctest.testmod">

  1023. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">testmod</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">m</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">globs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">report</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">optionflags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">extraglobs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">raise_on_error</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exclude_empty</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.testmod" title="Link to this definition">¶</a></dt>

  1024. <dd><p>All arguments are optional, and all except for <em>m</em> should be specified in

  1025. keyword form.</p>

  1026. <p>Test examples in docstrings in functions and classes reachable from module <em>m</em>

  1027. (or module <a class="reference internal" href="__main__.html#module-__main__" title="__main__: The environment where top-level code is run. Covers command-line interfaces, import-time behavior, and ``__name__ == '__main__'``."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> if <em>m</em> is not supplied or is <code class="docutils literal notranslate"><span class="pre">None</span></code>), starting with

  1028. <code class="docutils literal notranslate"><span class="pre">m.__doc__</span></code>.</p>

  1029. <p>Also test examples reachable from dict <code class="docutils literal notranslate"><span class="pre">m.__test__</span></code>, if it exists.

  1030. <code class="docutils literal notranslate"><span class="pre">m.__test__</span></code> maps names (strings) to functions, classes and

  1031. strings; function and class docstrings are searched for examples; strings are

  1032. searched directly, as if they were docstrings.</p>

  1033. <p>Only docstrings attached to objects belonging to module <em>m</em> are searched.</p>

  1034. <p>Return <code class="docutils literal notranslate"><span class="pre">(failure_count,</span> <span class="pre">test_count)</span></code>.</p>

  1035. <p>Optional argument <em>name</em> gives the name of the module; by default, or if

  1036. <code class="docutils literal notranslate"><span class="pre">None</span></code>, <code class="docutils literal notranslate"><span class="pre">m.__name__</span></code> is used.</p>

  1037. <p>Optional argument <em>exclude_empty</em> defaults to false.  If true, objects for which

  1038. no doctests are found are excluded from consideration. The default is a backward

  1039. compatibility hack, so that code still using

  1040. <a class="reference internal" href="#doctest.DocTestRunner.summarize" title="doctest.DocTestRunner.summarize"><code class="xref py py-meth docutils literal notranslate"><span class="pre">doctest.master.summarize</span></code></a> in

  1041. conjunction with <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a> continues to get output for objects with no

  1042. tests. The <em>exclude_empty</em> argument to the newer <a class="reference internal" href="#doctest.DocTestFinder" title="doctest.DocTestFinder"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestFinder</span></code></a>

  1043. constructor defaults to true.</p>

  1044. <p>Optional arguments <em>extraglobs</em>, <em>verbose</em>, <em>report</em>, <em>optionflags</em>,

  1045. <em>raise_on_error</em>, and <em>globs</em> are the same as for function <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a>

  1046. above, except that <em>globs</em> defaults to <code class="docutils literal notranslate"><span class="pre">m.__dict__</span></code>.</p>

  1047. </dd></dl>

  1048. 

  1049. <dl class="py function">

  1050. <dt class="sig sig-object py" id="doctest.run_docstring_examples">

  1051. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">run_docstring_examples</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">f</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">globs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'NoName'</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compileflags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">optionflags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.run_docstring_examples" title="Link to this definition">¶</a></dt>

  1052. <dd><p>Test examples associated with object <em>f</em>; for example, <em>f</em> may be a string,

  1053. a module, a function, or a class object.</p>

  1054. <p>A shallow copy of dictionary argument <em>globs</em> is used for the execution context.</p>

  1055. <p>Optional argument <em>name</em> is used in failure messages, and defaults to

  1056. <code class="docutils literal notranslate"><span class="pre">&quot;NoName&quot;</span></code>.</p>

  1057. <p>If optional argument <em>verbose</em> is true, output is generated even if there are no

  1058. failures.  By default, output is generated only in case of an example failure.</p>

  1059. <p>Optional argument <em>compileflags</em> gives the set of flags that should be used by

  1060. the Python compiler when running the examples.  By default, or if <code class="docutils literal notranslate"><span class="pre">None</span></code>,

  1061. flags are deduced corresponding to the set of future features found in <em>globs</em>.</p>

  1062. <p>Optional argument <em>optionflags</em> works as for function <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a> above.</p>

  1063. </dd></dl>

  1064. 

  1065. </section>

  1066. <section id="unittest-api">

  1067. <span id="doctest-unittest-api"></span><h2>Unittest API<a class="headerlink" href="#unittest-api" title="Link to this heading">¶</a></h2>

  1068. <p>As your collection of doctest’ed modules grows, you’ll want a way to run all

  1069. their doctests systematically.  <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> provides two functions that can

  1070. be used to create <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> test suites from modules and text files

  1071. containing doctests.  To integrate with <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> test discovery, include

  1072. a <a class="reference internal" href="unittest.html#load-tests-protocol"><span class="std std-ref">load_tests</span></a> function in your test module:</p>

  1073. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">unittest</span>

  1074. <span class="kn">import</span> <span class="nn">doctest</span>

  1075. <span class="kn">import</span> <span class="nn">my_module_with_doctests</span>

  1076. 

  1077. <span class="k">def</span> <span class="nf">load_tests</span><span class="p">(</span><span class="n">loader</span><span class="p">,</span> <span class="n">tests</span><span class="p">,</span> <span class="n">ignore</span><span class="p">):</span>

  1078.     <span class="n">tests</span><span class="o">.</span><span class="n">addTests</span><span class="p">(</span><span class="n">doctest</span><span class="o">.</span><span class="n">DocTestSuite</span><span class="p">(</span><span class="n">my_module_with_doctests</span><span class="p">))</span>

  1079.     <span class="k">return</span> <span class="n">tests</span>

  1080. </pre></div>

  1081. </div>

  1082. <p>There are two main functions for creating <a class="reference internal" href="unittest.html#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code></a> instances

  1083. from text files and modules with doctests:</p>

  1084. <dl class="py function">

  1085. <dt class="sig sig-object py" id="doctest.DocFileSuite">

  1086. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">DocFileSuite</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="o"><span class="pre">*</span></span><span class="n"><span class="pre">paths</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">module_relative</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">package</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">setUp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tearDown</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">globs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">optionflags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parser</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DocTestParser()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">encoding</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocFileSuite" title="Link to this definition">¶</a></dt>

  1087. <dd><p>Convert doctest tests from one or more text files to a

  1088. <a class="reference internal" href="unittest.html#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code></a>.</p>

  1089. <p>The returned <a class="reference internal" href="unittest.html#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code></a> is to be run by the unittest framework

  1090. and runs the interactive examples in each file.  If an example in any file

  1091. fails, then the synthesized unit test fails, and a <a class="reference internal" href="#doctest.failureException" title="doctest.failureException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">failureException</span></code></a>

  1092. exception is raised showing the name of the file containing the test and a

  1093. (sometimes approximate) line number.</p>

  1094. <p>Pass one or more paths (as strings) to text files to be examined.</p>

  1095. <p>Options may be provided as keyword arguments:</p>

  1096. <p>Optional argument <em>module_relative</em> specifies how the filenames in <em>paths</em>

  1097. should be interpreted:</p>

  1098. <ul class="simple">

  1099. <li><p>If <em>module_relative</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code> (the default), then each filename in

  1100. <em>paths</em> specifies an OS-independent module-relative path.  By default, this

  1101. path is relative to the calling module’s directory; but if the <em>package</em>

  1102. argument is specified, then it is relative to that package.  To ensure

  1103. OS-independence, each filename should use <code class="docutils literal notranslate"><span class="pre">/</span></code> characters to separate path

  1104. segments, and may not be an absolute path (i.e., it may not begin with

  1105. <code class="docutils literal notranslate"><span class="pre">/</span></code>).</p></li>

  1106. <li><p>If <em>module_relative</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, then each filename in <em>paths</em> specifies

  1107. an OS-specific path.  The path may be absolute or relative; relative paths

  1108. are resolved with respect to the current working directory.</p></li>

  1109. </ul>

  1110. <p>Optional argument <em>package</em> is a Python package or the name of a Python

  1111. package whose directory should be used as the base directory for

  1112. module-relative filenames in <em>paths</em>.  If no package is specified, then the

  1113. calling module’s directory is used as the base directory for module-relative

  1114. filenames.  It is an error to specify <em>package</em> if <em>module_relative</em> is

  1115. <code class="docutils literal notranslate"><span class="pre">False</span></code>.</p>

  1116. <p>Optional argument <em>setUp</em> specifies a set-up function for the test suite.

  1117. This is called before running the tests in each file.  The <em>setUp</em> function

  1118. will be passed a <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> object.  The setUp function can access the

  1119. test globals as the <em>globs</em> attribute of the test passed.</p>

  1120. <p>Optional argument <em>tearDown</em> specifies a tear-down function for the test

  1121. suite.  This is called after running the tests in each file.  The <em>tearDown</em>

  1122. function will be passed a <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> object.  The setUp function can

  1123. access the test globals as the <em>globs</em> attribute of the test passed.</p>

  1124. <p>Optional argument <em>globs</em> is a dictionary containing the initial global

  1125. variables for the tests.  A new copy of this dictionary is created for each

  1126. test.  By default, <em>globs</em> is a new empty dictionary.</p>

  1127. <p>Optional argument <em>optionflags</em> specifies the default doctest options for the

  1128. tests, created by or-ing together individual option flags.  See section

  1129. <a class="reference internal" href="#doctest-options"><span class="std std-ref">Option Flags</span></a>. See function <a class="reference internal" href="#doctest.set_unittest_reportflags" title="doctest.set_unittest_reportflags"><code class="xref py py-func docutils literal notranslate"><span class="pre">set_unittest_reportflags()</span></code></a> below

  1130. for a better way to set reporting options.</p>

  1131. <p>Optional argument <em>parser</em> specifies a <a class="reference internal" href="#doctest.DocTestParser" title="doctest.DocTestParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestParser</span></code></a> (or subclass)

  1132. that should be used to extract tests from the files.  It defaults to a normal

  1133. parser (i.e., <code class="docutils literal notranslate"><span class="pre">DocTestParser()</span></code>).</p>

  1134. <p>Optional argument <em>encoding</em> specifies an encoding that should be used to

  1135. convert the file to unicode.</p>

  1136. <p>The global <code class="docutils literal notranslate"><span class="pre">__file__</span></code> is added to the globals provided to doctests loaded

  1137. from a text file using <a class="reference internal" href="#doctest.DocFileSuite" title="doctest.DocFileSuite"><code class="xref py py-func docutils literal notranslate"><span class="pre">DocFileSuite()</span></code></a>.</p>

  1138. </dd></dl>

  1139. 

  1140. <dl class="py function">

  1141. <dt class="sig sig-object py" id="doctest.DocTestSuite">

  1142. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">DocTestSuite</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">module</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">globs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">extraglobs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">test_finder</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">setUp</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">tearDown</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">optionflags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">checker</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestSuite" title="Link to this definition">¶</a></dt>

  1143. <dd><p>Convert doctest tests for a module to a <a class="reference internal" href="unittest.html#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code></a>.</p>

  1144. <p>The returned <a class="reference internal" href="unittest.html#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code></a> is to be run by the unittest framework

  1145. and runs each doctest in the module.  If any of the doctests fail, then the

  1146. synthesized unit test fails, and a <a class="reference internal" href="#doctest.failureException" title="doctest.failureException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">failureException</span></code></a> exception is raised

  1147. showing the name of the file containing the test and a (sometimes approximate)

  1148. line number.</p>

  1149. <p>Optional argument <em>module</em> provides the module to be tested.  It can be a module

  1150. object or a (possibly dotted) module name.  If not specified, the module calling

  1151. this function is used.</p>

  1152. <p>Optional argument <em>globs</em> is a dictionary containing the initial global

  1153. variables for the tests.  A new copy of this dictionary is created for each

  1154. test.  By default, <em>globs</em> is a new empty dictionary.</p>

  1155. <p>Optional argument <em>extraglobs</em> specifies an extra set of global variables, which

  1156. is merged into <em>globs</em>.  By default, no extra globals are used.</p>

  1157. <p>Optional argument <em>test_finder</em> is the <a class="reference internal" href="#doctest.DocTestFinder" title="doctest.DocTestFinder"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestFinder</span></code></a> object (or a

  1158. drop-in replacement) that is used to extract doctests from the module.</p>

  1159. <p>Optional arguments <em>setUp</em>, <em>tearDown</em>, and <em>optionflags</em> are the same as for

  1160. function <a class="reference internal" href="#doctest.DocFileSuite" title="doctest.DocFileSuite"><code class="xref py py-func docutils literal notranslate"><span class="pre">DocFileSuite()</span></code></a> above.</p>

  1161. <p>This function uses the same search technique as <a class="reference internal" href="#doctest.testmod" title="doctest.testmod"><code class="xref py py-func docutils literal notranslate"><span class="pre">testmod()</span></code></a>.</p>

  1162. <div class="versionchanged">

  1163. <p><span class="versionmodified changed">Changed in version 3.5: </span><a class="reference internal" href="#doctest.DocTestSuite" title="doctest.DocTestSuite"><code class="xref py py-func docutils literal notranslate"><span class="pre">DocTestSuite()</span></code></a> returns an empty <a class="reference internal" href="unittest.html#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code></a> if <em>module</em>

  1164. contains no docstrings instead of raising <a class="reference internal" href="exceptions.html#ValueError" title="ValueError"><code class="xref py py-exc docutils literal notranslate"><span class="pre">ValueError</span></code></a>.</p>

  1165. </div>

  1166. </dd></dl>

  1167. 

  1168. <dl class="py exception">

  1169. <dt class="sig sig-object py" id="doctest.failureException">

  1170. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">failureException</span></span><a class="headerlink" href="#doctest.failureException" title="Link to this definition">¶</a></dt>

  1171. <dd><p>When doctests which have been converted to unit tests by <a class="reference internal" href="#doctest.DocFileSuite" title="doctest.DocFileSuite"><code class="xref py py-func docutils literal notranslate"><span class="pre">DocFileSuite()</span></code></a>

  1172. or <a class="reference internal" href="#doctest.DocTestSuite" title="doctest.DocTestSuite"><code class="xref py py-func docutils literal notranslate"><span class="pre">DocTestSuite()</span></code></a> fail, this exception is raised showing the name of

  1173. the file containing the test and a (sometimes approximate) line number.</p>

  1174. </dd></dl>

  1175. 

  1176. <p>Under the covers, <a class="reference internal" href="#doctest.DocTestSuite" title="doctest.DocTestSuite"><code class="xref py py-func docutils literal notranslate"><span class="pre">DocTestSuite()</span></code></a> creates a <a class="reference internal" href="unittest.html#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code></a> out

  1177. of <code class="xref py py-class docutils literal notranslate"><span class="pre">doctest.DocTestCase</span></code> instances, and <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</span></code> is a

  1178. subclass of <a class="reference internal" href="unittest.html#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a>. <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</span></code> isn’t documented

  1179. here (it’s an internal detail), but studying its code can answer questions about

  1180. the exact details of <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> integration.</p>

  1181. <p>Similarly, <a class="reference internal" href="#doctest.DocFileSuite" title="doctest.DocFileSuite"><code class="xref py py-func docutils literal notranslate"><span class="pre">DocFileSuite()</span></code></a> creates a <a class="reference internal" href="unittest.html#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code></a> out of

  1182. <code class="xref py py-class docutils literal notranslate"><span class="pre">doctest.DocFileCase</span></code> instances, and <code class="xref py py-class docutils literal notranslate"><span class="pre">DocFileCase</span></code> is a subclass

  1183. of <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</span></code>.</p>

  1184. <p>So both ways of creating a <a class="reference internal" href="unittest.html#unittest.TestSuite" title="unittest.TestSuite"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestSuite</span></code></a> run instances of

  1185. <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</span></code>.  This is important for a subtle reason: when you run

  1186. <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> functions yourself, you can control the <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> options in

  1187. use directly, by passing option flags to <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> functions.  However, if

  1188. you’re writing a <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> framework, <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> ultimately controls

  1189. when and how tests get run.  The framework author typically wants to control

  1190. <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> reporting options (perhaps, e.g., specified by command line

  1191. options), but there’s no way to pass options through <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> to

  1192. <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> test runners.</p>

  1193. <p>For this reason, <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> also supports a notion of <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a>

  1194. reporting flags specific to <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> support, via this function:</p>

  1195. <dl class="py function">

  1196. <dt class="sig sig-object py" id="doctest.set_unittest_reportflags">

  1197. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">set_unittest_reportflags</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">flags</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.set_unittest_reportflags" title="Link to this definition">¶</a></dt>

  1198. <dd><p>Set the <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> reporting flags to use.</p>

  1199. <p>Argument <em>flags</em> takes the <a class="reference internal" href="../reference/expressions.html#bitwise"><span class="std std-ref">bitwise OR</span></a> of option flags.  See

  1200. section <a class="reference internal" href="#doctest-options"><span class="std std-ref">Option Flags</span></a>.  Only “reporting flags” can be used.</p>

  1201. <p>This is a module-global setting, and affects all future doctests run by module

  1202. <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a>:  the <code class="xref py py-meth docutils literal notranslate"><span class="pre">runTest()</span></code> method of <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</span></code> looks at

  1203. the option flags specified for the test case when the <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</span></code>

  1204. instance was constructed.  If no reporting flags were specified (which is the

  1205. typical and expected case), <code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code>’s <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> reporting flags are

  1206. <a class="reference internal" href="../reference/expressions.html#bitwise"><span class="std std-ref">bitwise ORed</span></a> into the option flags, and the option flags

  1207. so augmented are passed to the <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> instance created to

  1208. run the doctest.  If any reporting flags were specified when the

  1209. <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</span></code> instance was constructed, <code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code>’s

  1210. <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> reporting flags are ignored.</p>

  1211. <p>The value of the <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> reporting flags in effect before the function

  1212. was called is returned by the function.</p>

  1213. </dd></dl>

  1214. 

  1215. </section>

  1216. <section id="advanced-api">

  1217. <span id="doctest-advanced-api"></span><h2>Advanced API<a class="headerlink" href="#advanced-api" title="Link to this heading">¶</a></h2>

  1218. <p>The basic API is a simple wrapper that’s intended to make doctest easy to use.

  1219. It is fairly flexible, and should meet most users’ needs; however, if you

  1220. require more fine-grained control over testing, or wish to extend doctest’s

  1221. capabilities, then you should use the advanced API.</p>

  1222. <p>The advanced API revolves around two container classes, which are used to store

  1223. the interactive examples extracted from doctest cases:</p>

  1224. <ul class="simple">

  1225. <li><p><a class="reference internal" href="#doctest.Example" title="doctest.Example"><code class="xref py py-class docutils literal notranslate"><span class="pre">Example</span></code></a>: A single Python <a class="reference internal" href="../glossary.html#term-statement"><span class="xref std std-term">statement</span></a>, paired with its expected

  1226. output.</p></li>

  1227. <li><p><a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a>: A collection of <a class="reference internal" href="#doctest.Example" title="doctest.Example"><code class="xref py py-class docutils literal notranslate"><span class="pre">Example</span></code></a>s, typically extracted

  1228. from a single docstring or text file.</p></li>

  1229. </ul>

  1230. <p>Additional processing classes are defined to find, parse, and run, and check

  1231. doctest examples:</p>

  1232. <ul class="simple">

  1233. <li><p><a class="reference internal" href="#doctest.DocTestFinder" title="doctest.DocTestFinder"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestFinder</span></code></a>: Finds all docstrings in a given module, and uses a

  1234. <a class="reference internal" href="#doctest.DocTestParser" title="doctest.DocTestParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestParser</span></code></a> to create a <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> from every docstring that

  1235. contains interactive examples.</p></li>

  1236. <li><p><a class="reference internal" href="#doctest.DocTestParser" title="doctest.DocTestParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestParser</span></code></a>: Creates a <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> object from a string (such

  1237. as an object’s docstring).</p></li>

  1238. <li><p><a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a>: Executes the examples in a <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a>, and uses

  1239. an <a class="reference internal" href="#doctest.OutputChecker" title="doctest.OutputChecker"><code class="xref py py-class docutils literal notranslate"><span class="pre">OutputChecker</span></code></a> to verify their output.</p></li>

  1240. <li><p><a class="reference internal" href="#doctest.OutputChecker" title="doctest.OutputChecker"><code class="xref py py-class docutils literal notranslate"><span class="pre">OutputChecker</span></code></a>: Compares the actual output from a doctest example with

  1241. the expected output, and decides whether they match.</p></li>

  1242. </ul>

  1243. <p>The relationships among these processing classes are summarized in the following

  1244. diagram:</p>

  1245. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span>                            <span class="nb">list</span> <span class="n">of</span><span class="p">:</span>

  1246. <span class="o">+------+</span>                   <span class="o">+---------+</span>

  1247. <span class="o">|</span><span class="n">module</span><span class="o">|</span> <span class="o">--</span><span class="n">DocTestFinder</span><span class="o">-&gt;</span> <span class="o">|</span> <span class="n">DocTest</span> <span class="o">|</span> <span class="o">--</span><span class="n">DocTestRunner</span><span class="o">-&gt;</span> <span class="n">results</span>

  1248. <span class="o">+------+</span>    <span class="o">|</span>        <span class="o">^</span>     <span class="o">+---------+</span>     <span class="o">|</span>       <span class="o">^</span>    <span class="p">(</span><span class="n">printed</span><span class="p">)</span>

  1249.             <span class="o">|</span>        <span class="o">|</span>     <span class="o">|</span> <span class="n">Example</span> <span class="o">|</span>     <span class="o">|</span>       <span class="o">|</span>

  1250.             <span class="n">v</span>        <span class="o">|</span>     <span class="o">|</span>   <span class="o">...</span>   <span class="o">|</span>     <span class="n">v</span>       <span class="o">|</span>

  1251.            <span class="n">DocTestParser</span>   <span class="o">|</span> <span class="n">Example</span> <span class="o">|</span>   <span class="n">OutputChecker</span>

  1252.                            <span class="o">+---------+</span>

  1253. </pre></div>

  1254. </div>

  1255. <section id="doctest-objects">

  1256. <span id="doctest-doctest"></span><h3>DocTest Objects<a class="headerlink" href="#doctest-objects" title="Link to this heading">¶</a></h3>

  1257. <dl class="py class">

  1258. <dt class="sig sig-object py" id="doctest.DocTest">

  1259. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">DocTest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">examples</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">globs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lineno</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">docstring</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTest" title="Link to this definition">¶</a></dt>

  1260. <dd><p>A collection of doctest examples that should be run in a single namespace.  The

  1261. constructor arguments are used to initialize the attributes of the same names.</p>

  1262. <p><a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> defines the following attributes.  They are initialized by

  1263. the constructor, and should not be modified directly.</p>

  1264. <dl class="py attribute">

  1265. <dt class="sig sig-object py" id="doctest.DocTest.examples">

  1266. <span class="sig-name descname"><span class="pre">examples</span></span><a class="headerlink" href="#doctest.DocTest.examples" title="Link to this definition">¶</a></dt>

  1267. <dd><p>A list of <a class="reference internal" href="#doctest.Example" title="doctest.Example"><code class="xref py py-class docutils literal notranslate"><span class="pre">Example</span></code></a> objects encoding the individual interactive Python

  1268. examples that should be run by this test.</p>

  1269. </dd></dl>

  1270. 

  1271. <dl class="py attribute">

  1272. <dt class="sig sig-object py" id="doctest.DocTest.globs">

  1273. <span class="sig-name descname"><span class="pre">globs</span></span><a class="headerlink" href="#doctest.DocTest.globs" title="Link to this definition">¶</a></dt>

  1274. <dd><p>The namespace (aka globals) that the examples should be run in. This is a

  1275. dictionary mapping names to values.  Any changes to the namespace made by the

  1276. examples (such as binding new variables) will be reflected in <a class="reference internal" href="#doctest.DocTest.globs" title="doctest.DocTest.globs"><code class="xref py py-attr docutils literal notranslate"><span class="pre">globs</span></code></a>

  1277. after the test is run.</p>

  1278. </dd></dl>

  1279. 

  1280. <dl class="py attribute">

  1281. <dt class="sig sig-object py" id="doctest.DocTest.name">

  1282. <span class="sig-name descname"><span class="pre">name</span></span><a class="headerlink" href="#doctest.DocTest.name" title="Link to this definition">¶</a></dt>

  1283. <dd><p>A string name identifying the <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a>.  Typically, this is the name

  1284. of the object or file that the test was extracted from.</p>

  1285. </dd></dl>

  1286. 

  1287. <dl class="py attribute">

  1288. <dt class="sig sig-object py" id="doctest.DocTest.filename">

  1289. <span class="sig-name descname"><span class="pre">filename</span></span><a class="headerlink" href="#doctest.DocTest.filename" title="Link to this definition">¶</a></dt>

  1290. <dd><p>The name of the file that this <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> was extracted from; or

  1291. <code class="docutils literal notranslate"><span class="pre">None</span></code> if the filename is unknown, or if the <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> was not

  1292. extracted from a file.</p>

  1293. </dd></dl>

  1294. 

  1295. <dl class="py attribute">

  1296. <dt class="sig sig-object py" id="doctest.DocTest.lineno">

  1297. <span class="sig-name descname"><span class="pre">lineno</span></span><a class="headerlink" href="#doctest.DocTest.lineno" title="Link to this definition">¶</a></dt>

  1298. <dd><p>The line number within <a class="reference internal" href="#doctest.DocTest.filename" title="doctest.DocTest.filename"><code class="xref py py-attr docutils literal notranslate"><span class="pre">filename</span></code></a> where this <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> begins, or

  1299. <code class="docutils literal notranslate"><span class="pre">None</span></code> if the line number is unavailable.  This line number is zero-based

  1300. with respect to the beginning of the file.</p>

  1301. </dd></dl>

  1302. 

  1303. <dl class="py attribute">

  1304. <dt class="sig sig-object py" id="doctest.DocTest.docstring">

  1305. <span class="sig-name descname"><span class="pre">docstring</span></span><a class="headerlink" href="#doctest.DocTest.docstring" title="Link to this definition">¶</a></dt>

  1306. <dd><p>The string that the test was extracted from, or <code class="docutils literal notranslate"><span class="pre">None</span></code> if the string is

  1307. unavailable, or if the test was not extracted from a string.</p>

  1308. </dd></dl>

  1309. 

  1310. </dd></dl>

  1311. 

  1312. </section>

  1313. <section id="example-objects">

  1314. <span id="doctest-example"></span><h3>Example Objects<a class="headerlink" href="#example-objects" title="Link to this heading">¶</a></h3>

  1315. <dl class="py class">

  1316. <dt class="sig sig-object py" id="doctest.Example">

  1317. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">Example</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">source</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">want</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_msg</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lineno</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">indent</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">options</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.Example" title="Link to this definition">¶</a></dt>

  1318. <dd><p>A single interactive example, consisting of a Python statement and its expected

  1319. output.  The constructor arguments are used to initialize the attributes of

  1320. the same names.</p>

  1321. <p><a class="reference internal" href="#doctest.Example" title="doctest.Example"><code class="xref py py-class docutils literal notranslate"><span class="pre">Example</span></code></a> defines the following attributes.  They are initialized by

  1322. the constructor, and should not be modified directly.</p>

  1323. <dl class="py attribute">

  1324. <dt class="sig sig-object py" id="doctest.Example.source">

  1325. <span class="sig-name descname"><span class="pre">source</span></span><a class="headerlink" href="#doctest.Example.source" title="Link to this definition">¶</a></dt>

  1326. <dd><p>A string containing the example’s source code.  This source code consists of a

  1327. single Python statement, and always ends with a newline; the constructor adds

  1328. a newline when necessary.</p>

  1329. </dd></dl>

  1330. 

  1331. <dl class="py attribute">

  1332. <dt class="sig sig-object py" id="doctest.Example.want">

  1333. <span class="sig-name descname"><span class="pre">want</span></span><a class="headerlink" href="#doctest.Example.want" title="Link to this definition">¶</a></dt>

  1334. <dd><p>The expected output from running the example’s source code (either from

  1335. stdout, or a traceback in case of exception).  <a class="reference internal" href="#doctest.Example.want" title="doctest.Example.want"><code class="xref py py-attr docutils literal notranslate"><span class="pre">want</span></code></a> ends with a

  1336. newline unless no output is expected, in which case it’s an empty string.  The

  1337. constructor adds a newline when necessary.</p>

  1338. </dd></dl>

  1339. 

  1340. <dl class="py attribute">

  1341. <dt class="sig sig-object py" id="doctest.Example.exc_msg">

  1342. <span class="sig-name descname"><span class="pre">exc_msg</span></span><a class="headerlink" href="#doctest.Example.exc_msg" title="Link to this definition">¶</a></dt>

  1343. <dd><p>The exception message generated by the example, if the example is expected to

  1344. generate an exception; or <code class="docutils literal notranslate"><span class="pre">None</span></code> if it is not expected to generate an

  1345. exception.  This exception message is compared against the return value of

  1346. <a class="reference internal" href="traceback.html#traceback.format_exception_only" title="traceback.format_exception_only"><code class="xref py py-func docutils literal notranslate"><span class="pre">traceback.format_exception_only()</span></code></a>.  <a class="reference internal" href="#doctest.Example.exc_msg" title="doctest.Example.exc_msg"><code class="xref py py-attr docutils literal notranslate"><span class="pre">exc_msg</span></code></a> ends with a newline

  1347. unless it’s <code class="docutils literal notranslate"><span class="pre">None</span></code>.  The constructor adds a newline if needed.</p>

  1348. </dd></dl>

  1349. 

  1350. <dl class="py attribute">

  1351. <dt class="sig sig-object py" id="doctest.Example.lineno">

  1352. <span class="sig-name descname"><span class="pre">lineno</span></span><a class="headerlink" href="#doctest.Example.lineno" title="Link to this definition">¶</a></dt>

  1353. <dd><p>The line number within the string containing this example where the example

  1354. begins.  This line number is zero-based with respect to the beginning of the

  1355. containing string.</p>

  1356. </dd></dl>

  1357. 

  1358. <dl class="py attribute">

  1359. <dt class="sig sig-object py" id="doctest.Example.indent">

  1360. <span class="sig-name descname"><span class="pre">indent</span></span><a class="headerlink" href="#doctest.Example.indent" title="Link to this definition">¶</a></dt>

  1361. <dd><p>The example’s indentation in the containing string, i.e., the number of space

  1362. characters that precede the example’s first prompt.</p>

  1363. </dd></dl>

  1364. 

  1365. <dl class="py attribute">

  1366. <dt class="sig sig-object py" id="doctest.Example.options">

  1367. <span class="sig-name descname"><span class="pre">options</span></span><a class="headerlink" href="#doctest.Example.options" title="Link to this definition">¶</a></dt>

  1368. <dd><p>A dictionary mapping from option flags to <code class="docutils literal notranslate"><span class="pre">True</span></code> or <code class="docutils literal notranslate"><span class="pre">False</span></code>, which is used

  1369. to override default options for this example.  Any option flags not contained

  1370. in this dictionary are left at their default value (as specified by the

  1371. <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a>’s <a class="reference internal" href="#doctest-options"><span class="std std-ref">optionflags</span></a>).

  1372. By default, no options are set.</p>

  1373. </dd></dl>

  1374. 

  1375. </dd></dl>

  1376. 

  1377. </section>

  1378. <section id="doctestfinder-objects">

  1379. <span id="doctest-doctestfinder"></span><h3>DocTestFinder objects<a class="headerlink" href="#doctestfinder-objects" title="Link to this heading">¶</a></h3>

  1380. <dl class="py class">

  1381. <dt class="sig sig-object py" id="doctest.DocTestFinder">

  1382. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">DocTestFinder</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">parser</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">DocTestParser()</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">recurse</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exclude_empty</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestFinder" title="Link to this definition">¶</a></dt>

  1383. <dd><p>A processing class used to extract the <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a>s that are relevant to

  1384. a given object, from its docstring and the docstrings of its contained objects.

  1385. <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a>s can be extracted from modules, classes, functions,

  1386. methods, staticmethods, classmethods, and properties.</p>

  1387. <p>The optional argument <em>verbose</em> can be used to display the objects searched by

  1388. the finder.  It defaults to <code class="docutils literal notranslate"><span class="pre">False</span></code> (no output).</p>

  1389. <p>The optional argument <em>parser</em> specifies the <a class="reference internal" href="#doctest.DocTestParser" title="doctest.DocTestParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestParser</span></code></a> object (or a

  1390. drop-in replacement) that is used to extract doctests from docstrings.</p>

  1391. <p>If the optional argument <em>recurse</em> is false, then <a class="reference internal" href="#doctest.DocTestFinder.find" title="doctest.DocTestFinder.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">DocTestFinder.find()</span></code></a>

  1392. will only examine the given object, and not any contained objects.</p>

  1393. <p>If the optional argument <em>exclude_empty</em> is false, then

  1394. <a class="reference internal" href="#doctest.DocTestFinder.find" title="doctest.DocTestFinder.find"><code class="xref py py-meth docutils literal notranslate"><span class="pre">DocTestFinder.find()</span></code></a> will include tests for objects with empty docstrings.</p>

  1395. <p><a class="reference internal" href="#doctest.DocTestFinder" title="doctest.DocTestFinder"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestFinder</span></code></a> defines the following method:</p>

  1396. <dl class="py method">

  1397. <dt class="sig sig-object py" id="doctest.DocTestFinder.find">

  1398. <span class="sig-name descname"><span class="pre">find</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="pre">obj[,</span> <span class="pre">name][,</span> <span class="pre">module][,</span> <span class="pre">globs][,</span> <span class="pre">extraglobs]</span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestFinder.find" title="Link to this definition">¶</a></dt>

  1399. <dd><p>Return a list of the <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a>s that are defined by <em>obj</em>’s

  1400. docstring, or by any of its contained objects’ docstrings.</p>

  1401. <p>The optional argument <em>name</em> specifies the object’s name; this name will be

  1402. used to construct names for the returned <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a>s.  If <em>name</em> is

  1403. not specified, then <code class="docutils literal notranslate"><span class="pre">obj.__name__</span></code> is used.</p>

  1404. <p>The optional parameter <em>module</em> is the module that contains the given object.

  1405. If the module is not specified or is <code class="docutils literal notranslate"><span class="pre">None</span></code>, then the test finder will attempt

  1406. to automatically determine the correct module.  The object’s module is used:</p>

  1407. <ul class="simple">

  1408. <li><p>As a default namespace, if <em>globs</em> is not specified.</p></li>

  1409. <li><p>To prevent the DocTestFinder from extracting DocTests from objects that are

  1410. imported from other modules.  (Contained objects with modules other than

  1411. <em>module</em> are ignored.)</p></li>

  1412. <li><p>To find the name of the file containing the object.</p></li>

  1413. <li><p>To help find the line number of the object within its file.</p></li>

  1414. </ul>

  1415. <p>If <em>module</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, no attempt to find the module will be made.  This is

  1416. obscure, of use mostly in testing doctest itself: if <em>module</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, or

  1417. is <code class="docutils literal notranslate"><span class="pre">None</span></code> but cannot be found automatically, then all objects are considered

  1418. to belong to the (non-existent) module, so all contained objects will

  1419. (recursively) be searched for doctests.</p>

  1420. <p>The globals for each <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> is formed by combining <em>globs</em> and

  1421. <em>extraglobs</em> (bindings in <em>extraglobs</em> override bindings in <em>globs</em>).  A new

  1422. shallow copy of the globals dictionary is created for each <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a>.

  1423. If <em>globs</em> is not specified, then it defaults to the module’s <em>__dict__</em>, if

  1424. specified, or <code class="docutils literal notranslate"><span class="pre">{}</span></code> otherwise.  If <em>extraglobs</em> is not specified, then it

  1425. defaults to <code class="docutils literal notranslate"><span class="pre">{}</span></code>.</p>

  1426. </dd></dl>

  1427. 

  1428. </dd></dl>

  1429. 

  1430. </section>

  1431. <section id="doctestparser-objects">

  1432. <span id="doctest-doctestparser"></span><h3>DocTestParser objects<a class="headerlink" href="#doctestparser-objects" title="Link to this heading">¶</a></h3>

  1433. <dl class="py class">

  1434. <dt class="sig sig-object py" id="doctest.DocTestParser">

  1435. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">DocTestParser</span></span><a class="headerlink" href="#doctest.DocTestParser" title="Link to this definition">¶</a></dt>

  1436. <dd><p>A processing class used to extract interactive examples from a string, and use

  1437. them to create a <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> object.</p>

  1438. <p><a class="reference internal" href="#doctest.DocTestParser" title="doctest.DocTestParser"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestParser</span></code></a> defines the following methods:</p>

  1439. <dl class="py method">

  1440. <dt class="sig sig-object py" id="doctest.DocTestParser.get_doctest">

  1441. <span class="sig-name descname"><span class="pre">get_doctest</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">globs</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">filename</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">lineno</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestParser.get_doctest" title="Link to this definition">¶</a></dt>

  1442. <dd><p>Extract all doctest examples from the given string, and collect them into a

  1443. <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> object.</p>

  1444. <p><em>globs</em>, <em>name</em>, <em>filename</em>, and <em>lineno</em> are attributes for the new

  1445. <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> object.  See the documentation for <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> for more

  1446. information.</p>

  1447. </dd></dl>

  1448. 

  1449. <dl class="py method">

  1450. <dt class="sig sig-object py" id="doctest.DocTestParser.get_examples">

  1451. <span class="sig-name descname"><span class="pre">get_examples</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'&lt;string&gt;'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestParser.get_examples" title="Link to this definition">¶</a></dt>

  1452. <dd><p>Extract all doctest examples from the given string, and return them as a list

  1453. of <a class="reference internal" href="#doctest.Example" title="doctest.Example"><code class="xref py py-class docutils literal notranslate"><span class="pre">Example</span></code></a> objects.  Line numbers are 0-based.  The optional argument

  1454. <em>name</em> is a name identifying this string, and is only used for error messages.</p>

  1455. </dd></dl>

  1456. 

  1457. <dl class="py method">

  1458. <dt class="sig sig-object py" id="doctest.DocTestParser.parse">

  1459. <span class="sig-name descname"><span class="pre">parse</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">string</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">'&lt;string&gt;'</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestParser.parse" title="Link to this definition">¶</a></dt>

  1460. <dd><p>Divide the given string into examples and intervening text, and return them as

  1461. a list of alternating <a class="reference internal" href="#doctest.Example" title="doctest.Example"><code class="xref py py-class docutils literal notranslate"><span class="pre">Example</span></code></a>s and strings. Line numbers for the

  1462. <a class="reference internal" href="#doctest.Example" title="doctest.Example"><code class="xref py py-class docutils literal notranslate"><span class="pre">Example</span></code></a>s are 0-based.  The optional argument <em>name</em> is a name

  1463. identifying this string, and is only used for error messages.</p>

  1464. </dd></dl>

  1465. 

  1466. </dd></dl>

  1467. 

  1468. </section>

  1469. <section id="doctestrunner-objects">

  1470. <span id="doctest-doctestrunner"></span><h3>DocTestRunner objects<a class="headerlink" href="#doctestrunner-objects" title="Link to this heading">¶</a></h3>

  1471. <dl class="py class">

  1472. <dt class="sig sig-object py" id="doctest.DocTestRunner">

  1473. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">DocTestRunner</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">checker</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">optionflags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner" title="Link to this definition">¶</a></dt>

  1474. <dd><p>A processing class used to execute and verify the interactive examples in a

  1475. <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a>.</p>

  1476. <p>The comparison between expected outputs and actual outputs is done by an

  1477. <a class="reference internal" href="#doctest.OutputChecker" title="doctest.OutputChecker"><code class="xref py py-class docutils literal notranslate"><span class="pre">OutputChecker</span></code></a>.  This comparison may be customized with a number of

  1478. option flags; see section <a class="reference internal" href="#doctest-options"><span class="std std-ref">Option Flags</span></a> for more information.  If the

  1479. option flags are insufficient, then the comparison may also be customized by

  1480. passing a subclass of <a class="reference internal" href="#doctest.OutputChecker" title="doctest.OutputChecker"><code class="xref py py-class docutils literal notranslate"><span class="pre">OutputChecker</span></code></a> to the constructor.</p>

  1481. <p>The test runner’s display output can be controlled in two ways. First, an output

  1482. function can be passed to <a class="reference internal" href="#doctest.DocTestRunner.run" title="doctest.DocTestRunner.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">run()</span></code></a>; this function will be called

  1483. with strings that should be displayed.  It defaults to <code class="docutils literal notranslate"><span class="pre">sys.stdout.write</span></code>.  If

  1484. capturing the output is not sufficient, then the display output can be also

  1485. customized by subclassing DocTestRunner, and overriding the methods

  1486. <a class="reference internal" href="#doctest.DocTestRunner.report_start" title="doctest.DocTestRunner.report_start"><code class="xref py py-meth docutils literal notranslate"><span class="pre">report_start()</span></code></a>, <a class="reference internal" href="#doctest.DocTestRunner.report_success" title="doctest.DocTestRunner.report_success"><code class="xref py py-meth docutils literal notranslate"><span class="pre">report_success()</span></code></a>,

  1487. <a class="reference internal" href="#doctest.DocTestRunner.report_unexpected_exception" title="doctest.DocTestRunner.report_unexpected_exception"><code class="xref py py-meth docutils literal notranslate"><span class="pre">report_unexpected_exception()</span></code></a>, and <a class="reference internal" href="#doctest.DocTestRunner.report_failure" title="doctest.DocTestRunner.report_failure"><code class="xref py py-meth docutils literal notranslate"><span class="pre">report_failure()</span></code></a>.</p>

  1488. <p>The optional keyword argument <em>checker</em> specifies the <a class="reference internal" href="#doctest.OutputChecker" title="doctest.OutputChecker"><code class="xref py py-class docutils literal notranslate"><span class="pre">OutputChecker</span></code></a>

  1489. object (or drop-in replacement) that should be used to compare the expected

  1490. outputs to the actual outputs of doctest examples.</p>

  1491. <p>The optional keyword argument <em>verbose</em> controls the <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a>’s

  1492. verbosity.  If <em>verbose</em> is <code class="docutils literal notranslate"><span class="pre">True</span></code>, then information is printed about each

  1493. example, as it is run.  If <em>verbose</em> is <code class="docutils literal notranslate"><span class="pre">False</span></code>, then only failures are

  1494. printed.  If <em>verbose</em> is unspecified, or <code class="docutils literal notranslate"><span class="pre">None</span></code>, then verbose output is used

  1495. iff the command-line switch <code class="docutils literal notranslate"><span class="pre">-v</span></code> is used.</p>

  1496. <p>The optional keyword argument <em>optionflags</em> can be used to control how the test

  1497. runner compares expected output to actual output, and how it displays failures.

  1498. For more information, see section <a class="reference internal" href="#doctest-options"><span class="std std-ref">Option Flags</span></a>.</p>

  1499. <p><a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> defines the following methods:</p>

  1500. <dl class="py method">

  1501. <dt class="sig sig-object py" id="doctest.DocTestRunner.report_start">

  1502. <span class="sig-name descname"><span class="pre">report_start</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">out</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">test</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">example</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.report_start" title="Link to this definition">¶</a></dt>

  1503. <dd><p>Report that the test runner is about to process the given example. This method

  1504. is provided to allow subclasses of <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> to customize their

  1505. output; it should not be called directly.</p>

  1506. <p><em>example</em> is the example about to be processed.  <em>test</em> is the test

  1507. <em>containing example</em>.  <em>out</em> is the output function that was passed to

  1508. <a class="reference internal" href="#doctest.DocTestRunner.run" title="doctest.DocTestRunner.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">DocTestRunner.run()</span></code></a>.</p>

  1509. </dd></dl>

  1510. 

  1511. <dl class="py method">

  1512. <dt class="sig sig-object py" id="doctest.DocTestRunner.report_success">

  1513. <span class="sig-name descname"><span class="pre">report_success</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">out</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">test</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">example</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">got</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.report_success" title="Link to this definition">¶</a></dt>

  1514. <dd><p>Report that the given example ran successfully.  This method is provided to

  1515. allow subclasses of <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> to customize their output; it

  1516. should not be called directly.</p>

  1517. <p><em>example</em> is the example about to be processed.  <em>got</em> is the actual output

  1518. from the example.  <em>test</em> is the test containing <em>example</em>.  <em>out</em> is the

  1519. output function that was passed to <a class="reference internal" href="#doctest.DocTestRunner.run" title="doctest.DocTestRunner.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">DocTestRunner.run()</span></code></a>.</p>

  1520. </dd></dl>

  1521. 

  1522. <dl class="py method">

  1523. <dt class="sig sig-object py" id="doctest.DocTestRunner.report_failure">

  1524. <span class="sig-name descname"><span class="pre">report_failure</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">out</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">test</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">example</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">got</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.report_failure" title="Link to this definition">¶</a></dt>

  1525. <dd><p>Report that the given example failed.  This method is provided to allow

  1526. subclasses of <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> to customize their output; it should not

  1527. be called directly.</p>

  1528. <p><em>example</em> is the example about to be processed.  <em>got</em> is the actual output

  1529. from the example.  <em>test</em> is the test containing <em>example</em>.  <em>out</em> is the

  1530. output function that was passed to <a class="reference internal" href="#doctest.DocTestRunner.run" title="doctest.DocTestRunner.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">DocTestRunner.run()</span></code></a>.</p>

  1531. </dd></dl>

  1532. 

  1533. <dl class="py method">

  1534. <dt class="sig sig-object py" id="doctest.DocTestRunner.report_unexpected_exception">

  1535. <span class="sig-name descname"><span class="pre">report_unexpected_exception</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">out</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">test</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">example</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_info</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.report_unexpected_exception" title="Link to this definition">¶</a></dt>

  1536. <dd><p>Report that the given example raised an unexpected exception. This method is

  1537. provided to allow subclasses of <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> to customize their

  1538. output; it should not be called directly.</p>

  1539. <p><em>example</em> is the example about to be processed. <em>exc_info</em> is a tuple

  1540. containing information about the unexpected exception (as returned by

  1541. <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>). <em>test</em> is the test containing <em>example</em>.  <em>out</em> is the

  1542. output function that was passed to <a class="reference internal" href="#doctest.DocTestRunner.run" title="doctest.DocTestRunner.run"><code class="xref py py-meth docutils literal notranslate"><span class="pre">DocTestRunner.run()</span></code></a>.</p>

  1543. </dd></dl>

  1544. 

  1545. <dl class="py method">

  1546. <dt class="sig sig-object py" id="doctest.DocTestRunner.run">

  1547. <span class="sig-name descname"><span class="pre">run</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">test</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">compileflags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">out</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">clear_globs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">True</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.run" title="Link to this definition">¶</a></dt>

  1548. <dd><p>Run the examples in <em>test</em> (a <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> object), and display the

  1549. results using the writer function <em>out</em>.</p>

  1550. <p>The examples are run in the namespace <code class="docutils literal notranslate"><span class="pre">test.globs</span></code>.  If <em>clear_globs</em> is

  1551. true (the default), then this namespace will be cleared after the test runs,

  1552. to help with garbage collection. If you would like to examine the namespace

  1553. after the test completes, then use <em>clear_globs=False</em>.</p>

  1554. <p><em>compileflags</em> gives the set of flags that should be used by the Python

  1555. compiler when running the examples.  If not specified, then it will default to

  1556. the set of future-import flags that apply to <em>globs</em>.</p>

  1557. <p>The output of each example is checked using the <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a>’s

  1558. output checker, and the results are formatted by the

  1559. <code class="xref py py-meth docutils literal notranslate"><span class="pre">DocTestRunner.report_*()</span></code> methods.</p>

  1560. </dd></dl>

  1561. 

  1562. <dl class="py method">

  1563. <dt class="sig sig-object py" id="doctest.DocTestRunner.summarize">

  1564. <span class="sig-name descname"><span class="pre">summarize</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.summarize" title="Link to this definition">¶</a></dt>

  1565. <dd><p>Print a summary of all the test cases that have been run by this DocTestRunner,

  1566. and return a <a class="reference internal" href="../glossary.html#term-named-tuple"><span class="xref std std-term">named tuple</span></a> <code class="docutils literal notranslate"><span class="pre">TestResults(failed,</span> <span class="pre">attempted)</span></code>.</p>

  1567. <p>The optional <em>verbose</em> argument controls how detailed the summary is.  If the

  1568. verbosity is not specified, then the <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a>’s verbosity is

  1569. used.</p>

  1570. </dd></dl>

  1571. 

  1572. </dd></dl>

  1573. 

  1574. </section>

  1575. <section id="outputchecker-objects">

  1576. <span id="doctest-outputchecker"></span><h3>OutputChecker objects<a class="headerlink" href="#outputchecker-objects" title="Link to this heading">¶</a></h3>

  1577. <dl class="py class">

  1578. <dt class="sig sig-object py" id="doctest.OutputChecker">

  1579. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">OutputChecker</span></span><a class="headerlink" href="#doctest.OutputChecker" title="Link to this definition">¶</a></dt>

  1580. <dd><p>A class used to check the whether the actual output from a doctest example

  1581. matches the expected output.  <a class="reference internal" href="#doctest.OutputChecker" title="doctest.OutputChecker"><code class="xref py py-class docutils literal notranslate"><span class="pre">OutputChecker</span></code></a> defines two methods:

  1582. <a class="reference internal" href="#doctest.OutputChecker.check_output" title="doctest.OutputChecker.check_output"><code class="xref py py-meth docutils literal notranslate"><span class="pre">check_output()</span></code></a>, which compares a given pair of outputs, and returns <code class="docutils literal notranslate"><span class="pre">True</span></code>

  1583. if they match; and <a class="reference internal" href="#doctest.OutputChecker.output_difference" title="doctest.OutputChecker.output_difference"><code class="xref py py-meth docutils literal notranslate"><span class="pre">output_difference()</span></code></a>, which returns a string describing

  1584. the differences between two outputs.</p>

  1585. <p><a class="reference internal" href="#doctest.OutputChecker" title="doctest.OutputChecker"><code class="xref py py-class docutils literal notranslate"><span class="pre">OutputChecker</span></code></a> defines the following methods:</p>

  1586. <dl class="py method">

  1587. <dt class="sig sig-object py" id="doctest.OutputChecker.check_output">

  1588. <span class="sig-name descname"><span class="pre">check_output</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">want</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">got</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">optionflags</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.OutputChecker.check_output" title="Link to this definition">¶</a></dt>

  1589. <dd><p>Return <code class="docutils literal notranslate"><span class="pre">True</span></code> iff the actual output from an example (<em>got</em>) matches the

  1590. expected output (<em>want</em>).  These strings are always considered to match if

  1591. they are identical; but depending on what option flags the test runner is

  1592. using, several non-exact match types are also possible.  See section

  1593. <a class="reference internal" href="#doctest-options"><span class="std std-ref">Option Flags</span></a> for more information about option flags.</p>

  1594. </dd></dl>

  1595. 

  1596. <dl class="py method">

  1597. <dt class="sig sig-object py" id="doctest.OutputChecker.output_difference">

  1598. <span class="sig-name descname"><span class="pre">output_difference</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">example</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">got</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">optionflags</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.OutputChecker.output_difference" title="Link to this definition">¶</a></dt>

  1599. <dd><p>Return a string describing the differences between the expected output for a

  1600. given example (<em>example</em>) and the actual output (<em>got</em>).  <em>optionflags</em> is the

  1601. set of option flags used to compare <em>want</em> and <em>got</em>.</p>

  1602. </dd></dl>

  1603. 

  1604. </dd></dl>

  1605. 

  1606. </section>

  1607. </section>

  1608. <section id="debugging">

  1609. <span id="doctest-debugging"></span><h2>Debugging<a class="headerlink" href="#debugging" title="Link to this heading">¶</a></h2>

  1610. <p>Doctest provides several mechanisms for debugging doctest examples:</p>

  1611. <ul>

  1612. <li><p>Several functions convert doctests to executable Python programs, which can be

  1613. run under the Python debugger, <a class="reference internal" href="pdb.html#module-pdb" title="pdb: The Python debugger for interactive interpreters."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pdb</span></code></a>.</p></li>

  1614. <li><p>The <a class="reference internal" href="#doctest.DebugRunner" title="doctest.DebugRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DebugRunner</span></code></a> class is a subclass of <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> that

  1615. raises an exception for the first failing example, containing information about

  1616. that example. This information can be used to perform post-mortem debugging on

  1617. the example.</p></li>

  1618. <li><p>The <a class="reference internal" href="unittest.html#module-unittest" title="unittest: Unit testing framework for Python."><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code></a> cases generated by <a class="reference internal" href="#doctest.DocTestSuite" title="doctest.DocTestSuite"><code class="xref py py-func docutils literal notranslate"><span class="pre">DocTestSuite()</span></code></a> support the

  1619. <a class="reference internal" href="#doctest.debug" title="doctest.debug"><code class="xref py py-meth docutils literal notranslate"><span class="pre">debug()</span></code></a> method defined by <a class="reference internal" href="unittest.html#unittest.TestCase" title="unittest.TestCase"><code class="xref py py-class docutils literal notranslate"><span class="pre">unittest.TestCase</span></code></a>.</p></li>

  1620. <li><p>You can add a call to <a class="reference internal" href="pdb.html#pdb.set_trace" title="pdb.set_trace"><code class="xref py py-func docutils literal notranslate"><span class="pre">pdb.set_trace()</span></code></a> in a doctest example, and you’ll

  1621. drop into the Python debugger when that line is executed.  Then you can inspect

  1622. current values of variables, and so on.  For example, suppose <code class="file docutils literal notranslate"><span class="pre">a.py</span></code>

  1623. contains just this module docstring:</p>

  1624. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="sd">&quot;&quot;&quot;</span>

  1625. <span class="sd">&gt;&gt;&gt; def f(x):</span>

  1626. <span class="sd">...     g(x*2)</span>

  1627. <span class="sd">&gt;&gt;&gt; def g(x):</span>

  1628. <span class="sd">...     print(x+3)</span>

  1629. <span class="sd">...     import pdb; pdb.set_trace()</span>

  1630. <span class="sd">&gt;&gt;&gt; f(3)</span>

  1631. <span class="sd">9</span>

  1632. <span class="sd">&quot;&quot;&quot;</span>

  1633. </pre></div>

  1634. </div>

  1635. <p>Then an interactive Python session may look like this:</p>

  1636. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">&gt;&gt;&gt; </span><span class="kn">import</span> <span class="nn">a</span><span class="o">,</span> <span class="nn">doctest</span>

  1637. <span class="gp">&gt;&gt;&gt; </span><span class="n">doctest</span><span class="o">.</span><span class="n">testmod</span><span class="p">(</span><span class="n">a</span><span class="p">)</span>

  1638. <span class="go">--Return--</span>

  1639. <span class="go">&gt; &lt;doctest a[1]&gt;(3)g()-&gt;None</span>

  1640. <span class="go">-&gt; import pdb; pdb.set_trace()</span>

  1641. <span class="go">(Pdb) list</span>

  1642. <span class="go">  1     def g(x):</span>

  1643. <span class="go">  2         print(x+3)</span>

  1644. <span class="go">  3  -&gt;     import pdb; pdb.set_trace()</span>

  1645. <span class="go">[EOF]</span>

  1646. <span class="go">(Pdb) p x</span>

  1647. <span class="go">6</span>

  1648. <span class="go">(Pdb) step</span>

  1649. <span class="go">--Return--</span>

  1650. <span class="go">&gt; &lt;doctest a[0]&gt;(2)f()-&gt;None</span>

  1651. <span class="go">-&gt; g(x*2)</span>

  1652. <span class="go">(Pdb) list</span>

  1653. <span class="go">  1     def f(x):</span>

  1654. <span class="go">  2  -&gt;     g(x*2)</span>

  1655. <span class="go">[EOF]</span>

  1656. <span class="go">(Pdb) p x</span>

  1657. <span class="go">3</span>

  1658. <span class="go">(Pdb) step</span>

  1659. <span class="go">--Return--</span>

  1660. <span class="go">&gt; &lt;doctest a[2]&gt;(1)?()-&gt;None</span>

  1661. <span class="go">-&gt; f(3)</span>

  1662. <span class="go">(Pdb) cont</span>

  1663. <span class="go">(0, 3)</span>

  1664. <span class="gp">&gt;&gt;&gt;</span>

  1665. </pre></div>

  1666. </div>

  1667. </li>

  1668. </ul>

  1669. <p>Functions that convert doctests to Python code, and possibly run the synthesized

  1670. code under the debugger:</p>

  1671. <dl class="py function">

  1672. <dt class="sig sig-object py" id="doctest.script_from_examples">

  1673. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">script_from_examples</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">s</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.script_from_examples" title="Link to this definition">¶</a></dt>

  1674. <dd><p>Convert text with examples to a script.</p>

  1675. <p>Argument <em>s</em> is a string containing doctest examples.  The string is converted

  1676. to a Python script, where doctest examples in <em>s</em> are converted to regular code,

  1677. and everything else is converted to Python comments.  The generated script is

  1678. returned as a string. For example,</p>

  1679. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">doctest</span>

  1680. <span class="nb">print</span><span class="p">(</span><span class="n">doctest</span><span class="o">.</span><span class="n">script_from_examples</span><span class="p">(</span><span class="sa">r</span><span class="s2">&quot;&quot;&quot;</span>

  1681. <span class="s2">    Set x and y to 1 and 2.</span>

  1682. <span class="s2">    &gt;&gt;&gt; x, y = 1, 2</span>

  1683. 

  1684. <span class="s2">    Print their sum:</span>

  1685. <span class="s2">    &gt;&gt;&gt; print(x+y)</span>

  1686. <span class="s2">    3</span>

  1687. <span class="s2">&quot;&quot;&quot;</span><span class="p">))</span>

  1688. </pre></div>

  1689. </div>

  1690. <p>displays:</p>

  1691. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Set x and y to 1 and 2.</span>

  1692. <span class="n">x</span><span class="p">,</span> <span class="n">y</span> <span class="o">=</span> <span class="mi">1</span><span class="p">,</span> <span class="mi">2</span>

  1693. <span class="c1">#</span>

  1694. <span class="c1"># Print their sum:</span>

  1695. <span class="nb">print</span><span class="p">(</span><span class="n">x</span><span class="o">+</span><span class="n">y</span><span class="p">)</span>

  1696. <span class="c1"># Expected:</span>

  1697. <span class="c1">## 3</span>

  1698. </pre></div>

  1699. </div>

  1700. <p>This function is used internally by other functions (see below), but can also be

  1701. useful when you want to transform an interactive Python session into a Python

  1702. script.</p>

  1703. </dd></dl>

  1704. 

  1705. <dl class="py function">

  1706. <dt class="sig sig-object py" id="doctest.testsource">

  1707. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">testsource</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">module</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.testsource" title="Link to this definition">¶</a></dt>

  1708. <dd><p>Convert the doctest for an object to a script.</p>

  1709. <p>Argument <em>module</em> is a module object, or dotted name of a module, containing the

  1710. object whose doctests are of interest.  Argument <em>name</em> is the name (within the

  1711. module) of the object with the doctests of interest.  The result is a string,

  1712. containing the object’s docstring converted to a Python script, as described for

  1713. <a class="reference internal" href="#doctest.script_from_examples" title="doctest.script_from_examples"><code class="xref py py-func docutils literal notranslate"><span class="pre">script_from_examples()</span></code></a> above.  For example, if module <code class="file docutils literal notranslate"><span class="pre">a.py</span></code>

  1714. contains a top-level function <code class="xref py py-func docutils literal notranslate"><span class="pre">f()</span></code>, then</p>

  1715. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">a</span><span class="o">,</span> <span class="nn">doctest</span>

  1716. <span class="nb">print</span><span class="p">(</span><span class="n">doctest</span><span class="o">.</span><span class="n">testsource</span><span class="p">(</span><span class="n">a</span><span class="p">,</span> <span class="s2">&quot;a.f&quot;</span><span class="p">))</span>

  1717. </pre></div>

  1718. </div>

  1719. <p>prints a script version of function <code class="xref py py-func docutils literal notranslate"><span class="pre">f()</span></code>’s docstring, with doctests

  1720. converted to code, and the rest placed in comments.</p>

  1721. </dd></dl>

  1722. 

  1723. <dl class="py function">

  1724. <dt class="sig sig-object py" id="doctest.debug">

  1725. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">debug</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">module</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">name</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pm</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.debug" title="Link to this definition">¶</a></dt>

  1726. <dd><p>Debug the doctests for an object.</p>

  1727. <p>The <em>module</em> and <em>name</em> arguments are the same as for function

  1728. <a class="reference internal" href="#doctest.testsource" title="doctest.testsource"><code class="xref py py-func docutils literal notranslate"><span class="pre">testsource()</span></code></a> above.  The synthesized Python script for the named object’s

  1729. docstring is written to a temporary file, and then that file is run under the

  1730. control of the Python debugger, <a class="reference internal" href="pdb.html#module-pdb" title="pdb: The Python debugger for interactive interpreters."><code class="xref py py-mod docutils literal notranslate"><span class="pre">pdb</span></code></a>.</p>

  1731. <p>A shallow copy of <code class="docutils literal notranslate"><span class="pre">module.__dict__</span></code> is used for both local and global

  1732. execution context.</p>

  1733. <p>Optional argument <em>pm</em> controls whether post-mortem debugging is used.  If <em>pm</em>

  1734. has a true value, the script file is run directly, and the debugger gets

  1735. involved only if the script terminates via raising an unhandled exception.  If

  1736. it does, then post-mortem debugging is invoked, via <a class="reference internal" href="pdb.html#pdb.post_mortem" title="pdb.post_mortem"><code class="xref py py-func docutils literal notranslate"><span class="pre">pdb.post_mortem()</span></code></a>,

  1737. passing the traceback object from the unhandled exception.  If <em>pm</em> is not

  1738. specified, or is false, the script is run under the debugger from the start, via

  1739. passing an appropriate <a class="reference internal" href="functions.html#exec" title="exec"><code class="xref py py-func docutils literal notranslate"><span class="pre">exec()</span></code></a> call to <a class="reference internal" href="pdb.html#pdb.run" title="pdb.run"><code class="xref py py-func docutils literal notranslate"><span class="pre">pdb.run()</span></code></a>.</p>

  1740. </dd></dl>

  1741. 

  1742. <dl class="py function">

  1743. <dt class="sig sig-object py" id="doctest.debug_src">

  1744. <span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">debug_src</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">src</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">pm</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">False</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">globs</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.debug_src" title="Link to this definition">¶</a></dt>

  1745. <dd><p>Debug the doctests in a string.</p>

  1746. <p>This is like function <a class="reference internal" href="#doctest.debug" title="doctest.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a> above, except that a string containing

  1747. doctest examples is specified directly, via the <em>src</em> argument.</p>

  1748. <p>Optional argument <em>pm</em> has the same meaning as in function <a class="reference internal" href="#doctest.debug" title="doctest.debug"><code class="xref py py-func docutils literal notranslate"><span class="pre">debug()</span></code></a> above.</p>

  1749. <p>Optional argument <em>globs</em> gives a dictionary to use as both local and global

  1750. execution context.  If not specified, or <code class="docutils literal notranslate"><span class="pre">None</span></code>, an empty dictionary is used.

  1751. If specified, a shallow copy of the dictionary is used.</p>

  1752. </dd></dl>

  1753. 

  1754. <p>The <a class="reference internal" href="#doctest.DebugRunner" title="doctest.DebugRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DebugRunner</span></code></a> class, and the special exceptions it may raise, are of

  1755. most interest to testing framework authors, and will only be sketched here.  See

  1756. the source code, and especially <a class="reference internal" href="#doctest.DebugRunner" title="doctest.DebugRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DebugRunner</span></code></a>’s docstring (which is a

  1757. doctest!) for more details:</p>

  1758. <dl class="py class">

  1759. <dt class="sig sig-object py" id="doctest.DebugRunner">

  1760. <em class="property"><span class="pre">class</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">DebugRunner</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">checker</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">verbose</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">None</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">optionflags</span></span><span class="o"><span class="pre">=</span></span><span class="default_value"><span class="pre">0</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DebugRunner" title="Link to this definition">¶</a></dt>

  1761. <dd><p>A subclass of <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> that raises an exception as soon as a

  1762. failure is encountered.  If an unexpected exception occurs, an

  1763. <a class="reference internal" href="#doctest.UnexpectedException" title="doctest.UnexpectedException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnexpectedException</span></code></a> exception is raised, containing the test, the

  1764. example, and the original exception.  If the output doesn’t match, then a

  1765. <a class="reference internal" href="#doctest.DocTestFailure" title="doctest.DocTestFailure"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DocTestFailure</span></code></a> exception is raised, containing the test, the example, and

  1766. the actual output.</p>

  1767. <p>For information about the constructor parameters and methods, see the

  1768. documentation for <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> in section <a class="reference internal" href="#doctest-advanced-api"><span class="std std-ref">Advanced API</span></a>.</p>

  1769. </dd></dl>

  1770. 

  1771. <p>There are two exceptions that may be raised by <a class="reference internal" href="#doctest.DebugRunner" title="doctest.DebugRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DebugRunner</span></code></a> instances:</p>

  1772. <dl class="py exception">

  1773. <dt class="sig sig-object py" id="doctest.DocTestFailure">

  1774. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">DocTestFailure</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">test</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">example</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">got</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestFailure" title="Link to this definition">¶</a></dt>

  1775. <dd><p>An exception raised by <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> to signal that a doctest example’s

  1776. actual output did not match its expected output. The constructor arguments are

  1777. used to initialize the attributes of the same names.</p>

  1778. </dd></dl>

  1779. 

  1780. <p><a class="reference internal" href="#doctest.DocTestFailure" title="doctest.DocTestFailure"><code class="xref py py-exc docutils literal notranslate"><span class="pre">DocTestFailure</span></code></a> defines the following attributes:</p>

  1781. <dl class="py attribute">

  1782. <dt class="sig sig-object py" id="doctest.DocTestFailure.test">

  1783. <span class="sig-prename descclassname"><span class="pre">DocTestFailure.</span></span><span class="sig-name descname"><span class="pre">test</span></span><a class="headerlink" href="#doctest.DocTestFailure.test" title="Link to this definition">¶</a></dt>

  1784. <dd><p>The <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> object that was being run when the example failed.</p>

  1785. </dd></dl>

  1786. 

  1787. <dl class="py attribute">

  1788. <dt class="sig sig-object py" id="doctest.DocTestFailure.example">

  1789. <span class="sig-prename descclassname"><span class="pre">DocTestFailure.</span></span><span class="sig-name descname"><span class="pre">example</span></span><a class="headerlink" href="#doctest.DocTestFailure.example" title="Link to this definition">¶</a></dt>

  1790. <dd><p>The <a class="reference internal" href="#doctest.Example" title="doctest.Example"><code class="xref py py-class docutils literal notranslate"><span class="pre">Example</span></code></a> that failed.</p>

  1791. </dd></dl>

  1792. 

  1793. <dl class="py attribute">

  1794. <dt class="sig sig-object py" id="doctest.DocTestFailure.got">

  1795. <span class="sig-prename descclassname"><span class="pre">DocTestFailure.</span></span><span class="sig-name descname"><span class="pre">got</span></span><a class="headerlink" href="#doctest.DocTestFailure.got" title="Link to this definition">¶</a></dt>

  1796. <dd><p>The example’s actual output.</p>

  1797. </dd></dl>

  1798. 

  1799. <dl class="py exception">

  1800. <dt class="sig sig-object py" id="doctest.UnexpectedException">

  1801. <em class="property"><span class="pre">exception</span><span class="w"> </span></em><span class="sig-prename descclassname"><span class="pre">doctest.</span></span><span class="sig-name descname"><span class="pre">UnexpectedException</span></span><span class="sig-paren">(</span><em class="sig-param"><span class="n"><span class="pre">test</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">example</span></span></em>, <em class="sig-param"><span class="n"><span class="pre">exc_info</span></span></em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.UnexpectedException" title="Link to this definition">¶</a></dt>

  1802. <dd><p>An exception raised by <a class="reference internal" href="#doctest.DocTestRunner" title="doctest.DocTestRunner"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestRunner</span></code></a> to signal that a doctest

  1803. example raised an unexpected exception.  The constructor arguments are used

  1804. to initialize the attributes of the same names.</p>

  1805. </dd></dl>

  1806. 

  1807. <p><a class="reference internal" href="#doctest.UnexpectedException" title="doctest.UnexpectedException"><code class="xref py py-exc docutils literal notranslate"><span class="pre">UnexpectedException</span></code></a> defines the following attributes:</p>

  1808. <dl class="py attribute">

  1809. <dt class="sig sig-object py" id="doctest.UnexpectedException.test">

  1810. <span class="sig-prename descclassname"><span class="pre">UnexpectedException.</span></span><span class="sig-name descname"><span class="pre">test</span></span><a class="headerlink" href="#doctest.UnexpectedException.test" title="Link to this definition">¶</a></dt>

  1811. <dd><p>The <a class="reference internal" href="#doctest.DocTest" title="doctest.DocTest"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTest</span></code></a> object that was being run when the example failed.</p>

  1812. </dd></dl>

  1813. 

  1814. <dl class="py attribute">

  1815. <dt class="sig sig-object py" id="doctest.UnexpectedException.example">

  1816. <span class="sig-prename descclassname"><span class="pre">UnexpectedException.</span></span><span class="sig-name descname"><span class="pre">example</span></span><a class="headerlink" href="#doctest.UnexpectedException.example" title="Link to this definition">¶</a></dt>

  1817. <dd><p>The <a class="reference internal" href="#doctest.Example" title="doctest.Example"><code class="xref py py-class docutils literal notranslate"><span class="pre">Example</span></code></a> that failed.</p>

  1818. </dd></dl>

  1819. 

  1820. <dl class="py attribute">

  1821. <dt class="sig sig-object py" id="doctest.UnexpectedException.exc_info">

  1822. <span class="sig-prename descclassname"><span class="pre">UnexpectedException.</span></span><span class="sig-name descname"><span class="pre">exc_info</span></span><a class="headerlink" href="#doctest.UnexpectedException.exc_info" title="Link to this definition">¶</a></dt>

  1823. <dd><p>A tuple containing information about the unexpected exception, as returned by

  1824. <a class="reference internal" href="sys.html#sys.exc_info" title="sys.exc_info"><code class="xref py py-func docutils literal notranslate"><span class="pre">sys.exc_info()</span></code></a>.</p>

  1825. </dd></dl>

  1826. 

  1827. </section>

  1828. <section id="soapbox">

  1829. <span id="doctest-soapbox"></span><h2>Soapbox<a class="headerlink" href="#soapbox" title="Link to this heading">¶</a></h2>

  1830. <p>As mentioned in the introduction, <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a> has grown to have three primary

  1831. uses:</p>

  1832. <ol class="arabic simple">

  1833. <li><p>Checking examples in docstrings.</p></li>

  1834. <li><p>Regression testing.</p></li>

  1835. <li><p>Executable documentation / literate testing.</p></li>

  1836. </ol>

  1837. <p>These uses have different requirements, and it is important to distinguish them.

  1838. In particular, filling your docstrings with obscure test cases makes for bad

  1839. documentation.</p>

  1840. <p>When writing a docstring, choose docstring examples with care. There’s an art to

  1841. this that needs to be learned—it may not be natural at first.  Examples should

  1842. add genuine value to the documentation.  A good example can often be worth many

  1843. words. If done with care, the examples will be invaluable for your users, and

  1844. will pay back the time it takes to collect them many times over as the years go

  1845. by and things change.  I’m still amazed at how often one of my <a class="reference internal" href="#module-doctest" title="doctest: Test pieces of code within docstrings."><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code></a>

  1846. examples stops working after a “harmless” change.</p>

  1847. <p>Doctest also makes an excellent tool for regression testing, especially if you

  1848. don’t skimp on explanatory text.  By interleaving prose and examples, it becomes

  1849. much easier to keep track of what’s actually being tested, and why.  When a test

  1850. fails, good prose can make it much easier to figure out what the problem is, and

  1851. how it should be fixed.  It’s true that you could write extensive comments in

  1852. code-based testing, but few programmers do. Many have found that using doctest

  1853. approaches instead leads to much clearer tests.  Perhaps this is simply because

  1854. doctest makes writing prose a little easier than writing code, while writing

  1855. comments in code is a little harder.  I think it goes deeper than just that:

  1856. the natural attitude when writing a doctest-based test is that you want to

  1857. explain the fine points of your software, and illustrate them with examples.

  1858. This in turn naturally leads to test files that start with the simplest

  1859. features, and logically progress to complications and edge cases.  A coherent

  1860. narrative is the result, instead of a collection of isolated functions that test

  1861. isolated bits of functionality seemingly at random.  It’s a different attitude,

  1862. and produces different results, blurring the distinction between testing and

  1863. explaining.</p>

  1864. <p>Regression testing is best confined to dedicated objects or files.  There are

  1865. several options for organizing tests:</p>

  1866. <ul class="simple">

  1867. <li><p>Write text files containing test cases as interactive examples, and test the

  1868. files using <a class="reference internal" href="#doctest.testfile" title="doctest.testfile"><code class="xref py py-func docutils literal notranslate"><span class="pre">testfile()</span></code></a> or <a class="reference internal" href="#doctest.DocFileSuite" title="doctest.DocFileSuite"><code class="xref py py-func docutils literal notranslate"><span class="pre">DocFileSuite()</span></code></a>.  This is recommended,

  1869. although is easiest to do for new projects, designed from the start to use

  1870. doctest.</p></li>

  1871. <li><p>Define functions named <code class="docutils literal notranslate"><span class="pre">_regrtest_topic</span></code> that consist of single docstrings,

  1872. containing test cases for the named topics.  These functions can be included in

  1873. the same file as the module, or separated out into a separate test file.</p></li>

  1874. <li><p>Define a <code class="docutils literal notranslate"><span class="pre">__test__</span></code> dictionary mapping from regression test topics to

  1875. docstrings containing test cases.</p></li>

  1876. </ul>

  1877. <p>When you have placed your tests in a module, the module can itself be the test

  1878. runner.  When a test fails, you can arrange for your test runner to re-run only

  1879. the failing doctest while you debug the problem.  Here is a minimal example of

  1880. such a test runner:</p>

  1881. <div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s1">&#39;__main__&#39;</span><span class="p">:</span>

  1882.     <span class="kn">import</span> <span class="nn">doctest</span>

  1883.     <span class="n">flags</span> <span class="o">=</span> <span class="n">doctest</span><span class="o">.</span><span class="n">REPORT_NDIFF</span><span class="o">|</span><span class="n">doctest</span><span class="o">.</span><span class="n">FAIL_FAST</span>

  1884.     <span class="k">if</span> <span class="nb">len</span><span class="p">(</span><span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">)</span> <span class="o">&gt;</span> <span class="mi">1</span><span class="p">:</span>

  1885.         <span class="n">name</span> <span class="o">=</span> <span class="n">sys</span><span class="o">.</span><span class="n">argv</span><span class="p">[</span><span class="mi">1</span><span class="p">]</span>

  1886.         <span class="k">if</span> <span class="n">name</span> <span class="ow">in</span> <span class="nb">globals</span><span class="p">():</span>

  1887.             <span class="n">obj</span> <span class="o">=</span> <span class="nb">globals</span><span class="p">()[</span><span class="n">name</span><span class="p">]</span>

  1888.         <span class="k">else</span><span class="p">:</span>

  1889.             <span class="n">obj</span> <span class="o">=</span> <span class="n">__test__</span><span class="p">[</span><span class="n">name</span><span class="p">]</span>

  1890.         <span class="n">doctest</span><span class="o">.</span><span class="n">run_docstring_examples</span><span class="p">(</span><span class="n">obj</span><span class="p">,</span> <span class="nb">globals</span><span class="p">(),</span> <span class="n">name</span><span class="o">=</span><span class="n">name</span><span class="p">,</span>

  1891.                                        <span class="n">optionflags</span><span class="o">=</span><span class="n">flags</span><span class="p">)</span>

  1892.     <span class="k">else</span><span class="p">:</span>

  1893.         <span class="n">fail</span><span class="p">,</span> <span class="n">total</span> <span class="o">=</span> <span class="n">doctest</span><span class="o">.</span><span class="n">testmod</span><span class="p">(</span><span class="n">optionflags</span><span class="o">=</span><span class="n">flags</span><span class="p">)</span>

  1894.         <span class="nb">print</span><span class="p">(</span><span class="s2">&quot;</span><span class="si">{}</span><span class="s2"> failures out of </span><span class="si">{}</span><span class="s2"> tests&quot;</span><span class="o">.</span><span class="n">format</span><span class="p">(</span><span class="n">fail</span><span class="p">,</span> <span class="n">total</span><span class="p">))</span>

  1895. </pre></div>

  1896. </div>

  1897. <p class="rubric">Footnotes</p>

  1898. <aside class="footnote-list brackets">

  1899. <aside class="footnote brackets" id="id2" role="doc-footnote">

  1900. <span class="label"><span class="fn-bracket">[</span><a role="doc-backlink" href="#id1">1</a><span class="fn-bracket">]</span></span>

  1901. <p>Examples containing both expected output and an exception are not supported.

  1902. Trying to guess where one ends and the other begins is too error-prone, and that

  1903. also makes for a confusing test.</p>

  1904. </aside>

  1905. </aside>

  1906. </section>

  1907. </section>

  1908. 

  1909. 

  1910.             <div class="clearer"></div>

  1911.           </div>

  1912.         </div>

  1913.       </div>

  1914.       <div class="sphinxsidebar" role="navigation" aria-label="main navigation">

  1915.         <div class="sphinxsidebarwrapper">

  1916.   <div>

  1917.     <h3><a href="../contents.html">Table of Contents</a></h3>

  1918.     <ul>

  1919. <li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> — Test interactive Python examples</a><ul>

  1920. <li><a class="reference internal" href="#simple-usage-checking-examples-in-docstrings">Simple Usage: Checking Examples in Docstrings</a></li>

  1921. <li><a class="reference internal" href="#simple-usage-checking-examples-in-a-text-file">Simple Usage: Checking Examples in a Text File</a></li>

  1922. <li><a class="reference internal" href="#how-it-works">How It Works</a><ul>

  1923. <li><a class="reference internal" href="#which-docstrings-are-examined">Which Docstrings Are Examined?</a></li>

  1924. <li><a class="reference internal" href="#how-are-docstring-examples-recognized">How are Docstring Examples Recognized?</a></li>

  1925. <li><a class="reference internal" href="#what-s-the-execution-context">What’s the Execution Context?</a></li>

  1926. <li><a class="reference internal" href="#what-about-exceptions">What About Exceptions?</a></li>

  1927. <li><a class="reference internal" href="#option-flags">Option Flags</a></li>

  1928. <li><a class="reference internal" href="#directives">Directives</a></li>

  1929. <li><a class="reference internal" href="#warnings">Warnings</a></li>

  1930. </ul>

  1931. </li>

  1932. <li><a class="reference internal" href="#basic-api">Basic API</a></li>

  1933. <li><a class="reference internal" href="#unittest-api">Unittest API</a></li>

  1934. <li><a class="reference internal" href="#advanced-api">Advanced API</a><ul>

  1935. <li><a class="reference internal" href="#doctest-objects">DocTest Objects</a></li>

  1936. <li><a class="reference internal" href="#example-objects">Example Objects</a></li>

  1937. <li><a class="reference internal" href="#doctestfinder-objects">DocTestFinder objects</a></li>

  1938. <li><a class="reference internal" href="#doctestparser-objects">DocTestParser objects</a></li>

  1939. <li><a class="reference internal" href="#doctestrunner-objects">DocTestRunner objects</a></li>

  1940. <li><a class="reference internal" href="#outputchecker-objects">OutputChecker objects</a></li>

  1941. </ul>

  1942. </li>

  1943. <li><a class="reference internal" href="#debugging">Debugging</a></li>

  1944. <li><a class="reference internal" href="#soapbox">Soapbox</a></li>

  1945. </ul>

  1946. </li>

  1947. </ul>

  1948. 

  1949.   </div>

  1950.   <div>

  1951.     <h4>Previous topic</h4>

  1952.     <p class="topless"><a href="devmode.html"

  1953.                           title="previous chapter">Python Development Mode</a></p>

  1954.   </div>

  1955.   <div>

  1956.     <h4>Next topic</h4>

  1957.     <p class="topless"><a href="unittest.html"

  1958.                           title="next chapter"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> — Unit testing framework</a></p>

  1959.   </div>

  1960.   <div role="note" aria-label="source link">

  1961.     <h3>This Page</h3>

  1962.     <ul class="this-page-menu">

  1963.       <li><a href="../bugs.html">Report a Bug</a></li>

  1964.       <li>

  1965.         <a href="https://github.com/python/cpython/blob/main/Doc/library/doctest.rst"

  1966.             rel="nofollow">Show Source

  1967.         </a>

  1968.       </li>

  1969.     </ul>

  1970.   </div>

  1971.         </div>

  1972. <div id="sidebarbutton" title="Collapse sidebar">

  1973. <span>«</span>

  1974. </div>

  1975. 

  1976.       </div>

  1977.       <div class="clearer"></div>

  1978.     </div>  

  1979.     <div class="related" role="navigation" aria-label="related navigation">

  1980.       <h3>Navigation</h3>

  1981.       <ul>

  1982.         <li class="right" style="margin-right: 10px">

  1983.           <a href="../genindex.html" title="General Index"

  1984.              >index</a></li>

  1985.         <li class="right" >

  1986.           <a href="../py-modindex.html" title="Python Module Index"

  1987.              >modules</a> |</li>

  1988.         <li class="right" >

  1989.           <a href="unittest.html" title="unittest — Unit testing framework"

  1990.              >next</a> |</li>

  1991.         <li class="right" >

  1992.           <a href="devmode.html" title="Python Development Mode"

  1993.              >previous</a> |</li>

  1994. 

  1995.           <li><img src="../_static/py.svg" alt="Python logo" style="vertical-align: middle; margin-top: -1px"/></li>

  1996.           <li><a href="https://www.python.org/">Python</a> &#187;</li>

  1997.           <li class="switchers">

  1998.             <div class="language_switcher_placeholder"></div>

  1999.             <div class="version_switcher_placeholder"></div>

  2000.           </li>

  2001.           <li>

  2002.               

  2003.           </li>

  2004.     <li id="cpython-language-and-version">

  2005.       <a href="../index.html">3.12.3 Documentation</a> &#187;

  2006.     </li>

  2007. 

  2008.           <li class="nav-item nav-item-1"><a href="index.html" >The Python Standard Library</a> &#187;</li>

  2009.           <li class="nav-item nav-item-2"><a href="development.html" >Development Tools</a> &#187;</li>

  2010.         <li class="nav-item nav-item-this"><a href=""><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> — Test interactive Python examples</a></li>

  2011.                 <li class="right">

  2012.                     

  2013. 

  2014.     <div class="inline-search" role="search">

  2015.         <form class="inline-search" action="../search.html" method="get">

  2016.           <input placeholder="Quick search" aria-label="Quick search" type="search" name="q" id="search-box" />

  2017.           <input type="submit" value="Go" />

  2018.         </form>

  2019.     </div>

  2020.                      |

  2021.                 </li>

  2022.             <li class="right">

  2023. <label class="theme-selector-label">

  2024.     Theme

  2025.     <select class="theme-selector" oninput="activateTheme(this.value)">

  2026.         <option value="auto" selected>Auto</option>

  2027.         <option value="light">Light</option>

  2028.         <option value="dark">Dark</option>

  2029.     </select>

  2030. </label> |</li>

  2031.             

  2032.       </ul>

  2033.     </div>  

  2034.     <div class="footer">

  2035.     &copy; 

  2036.       <a href="../copyright.html">

  2037.     

  2038.     Copyright

  2039.     

  2040.       </a>

  2041.      2001-2024, Python Software Foundation.

  2042.     <br />

  2043.     This page is licensed under the Python Software Foundation License Version 2.

  2044.     <br />

  2045.     Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.

  2046.     <br />

  2047.     

  2048.       See <a href="/license.html">History and License</a> for more information.<br />

  2049.     

  2050.     

  2051.     <br />

  2052. 

  2053.     The Python Software Foundation is a non-profit corporation.

  2054. <a href="https://www.python.org/psf/donations/">Please donate.</a>

  2055. <br />

  2056.     <br />

  2057.       Last updated on Apr 09, 2024 (13:47 UTC).

  2058.     

  2059.       <a href="/bugs.html">Found a bug</a>?

  2060.     

  2061.     <br />

  2062. 

  2063.     Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.2.6.

  2064.     </div>

  2065. 

  2066.   </body>

  2067. </html>
上海开阖软件有限公司 沪ICP备12045867号-1