1436 lines
178 KiB
HTML
1436 lines
178 KiB
HTML
|
||
<!DOCTYPE html>
|
||
|
||
<html xmlns="http://www.w3.org/1999/xhtml" lang="zh_CN">
|
||
<head>
|
||
<meta charset="utf-8" /><meta name="generator" content="Docutils 0.17.1: http://docutils.sourceforge.net/" />
|
||
|
||
<title>doctest --- 测试交互式的 Python 示例 — Python 3.8.20 文档</title><meta name="viewport" content="width=device-width, initial-scale=1.0">
|
||
|
||
<link rel="stylesheet" href="../_static/pydoctheme.css" type="text/css" />
|
||
<link rel="stylesheet" href="../_static/pygments.css" type="text/css" />
|
||
|
||
<script id="documentation_options" data-url_root="../" src="../_static/documentation_options.js"></script>
|
||
<script src="../_static/jquery.js"></script>
|
||
<script src="../_static/underscore.js"></script>
|
||
<script src="../_static/doctools.js"></script>
|
||
<script src="../_static/language_data.js"></script>
|
||
<script src="../_static/translations.js"></script>
|
||
|
||
<script src="../_static/sidebar.js"></script>
|
||
|
||
<link rel="search" type="application/opensearchdescription+xml"
|
||
title="在 Python 3.8.20 文档 中搜索"
|
||
href="../_static/opensearch.xml"/>
|
||
<link rel="author" title="关于这些文档" href="../about.html" />
|
||
<link rel="index" title="索引" href="../genindex.html" />
|
||
<link rel="search" title="搜索" href="../search.html" />
|
||
<link rel="copyright" title="版权所有" href="../copyright.html" />
|
||
<link rel="next" title="unittest --- 单元测试框架" href="unittest.html" />
|
||
<link rel="prev" title="pydoc --- 文档生成器和在线帮助系统" href="pydoc.html" />
|
||
<link rel="canonical" href="https://docs.python.org/3/library/doctest.html" />
|
||
|
||
|
||
|
||
|
||
|
||
<style>
|
||
@media only screen {
|
||
table.full-width-table {
|
||
width: 100%;
|
||
}
|
||
}
|
||
</style>
|
||
<link rel="shortcut icon" type="image/png" href="../_static/py.svg" />
|
||
<script type="text/javascript" src="../_static/copybutton.js"></script>
|
||
<script type="text/javascript" src="../_static/menu.js"></script>
|
||
|
||
</head>
|
||
<body>
|
||
<div class="mobile-nav">
|
||
<input type="checkbox" id="menuToggler" class="toggler__input" aria-controls="navigation"
|
||
aria-pressed="false" aria-expanded="false" role="button" aria-label="Menu" />
|
||
<label for="menuToggler" class="toggler__label">
|
||
<span></span>
|
||
</label>
|
||
<nav class="nav-content" role="navigation">
|
||
<a href="https://www.python.org/" class="nav-logo">
|
||
<img src="../_static/py.svg" alt="Logo"/>
|
||
</a>
|
||
<div class="version_switcher_placeholder"></div>
|
||
<form role="search" class="search" action="../search.html" method="get">
|
||
<svg xmlns="http://www.w3.org/2000/svg" width="20" height="20" viewBox="0 0 24 24" class="search-icon">
|
||
<path fill-rule="nonzero"
|
||
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" fill="#444"></path>
|
||
</svg>
|
||
<input type="text" name="q" aria-label="快速搜索"/>
|
||
<input type="submit" value="转向"/>
|
||
</form>
|
||
</nav>
|
||
<div class="menu-wrapper">
|
||
<nav class="menu" role="navigation" aria-label="main navigation">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> --- 测试交互式的 Python 示例</a><ul>
|
||
<li><a class="reference internal" href="#simple-usage-checking-examples-in-docstrings">简单用法：检查Docstrings中的示例</a></li>
|
||
<li><a class="reference internal" href="#simple-usage-checking-examples-in-a-text-file">简单的用法：检查文本文件中的例子</a></li>
|
||
<li><a class="reference internal" href="#how-it-works">它是如何工作的</a><ul>
|
||
<li><a class="reference internal" href="#which-docstrings-are-examined">哪些文件串被检查了？</a></li>
|
||
<li><a class="reference internal" href="#how-are-docstring-examples-recognized">文档串的例子是如何被识别的？</a></li>
|
||
<li><a class="reference internal" href="#what-s-the-execution-context">什么是执行上下文？</a></li>
|
||
<li><a class="reference internal" href="#what-about-exceptions">异常如何处理？</a></li>
|
||
<li><a class="reference internal" href="#option-flags">选项标记</a></li>
|
||
<li><a class="reference internal" href="#directives">指令</a></li>
|
||
<li><a class="reference internal" href="#warnings">警告</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#basic-api">基本API</a></li>
|
||
<li><a class="reference internal" href="#unittest-api">Unittest API</a></li>
|
||
<li><a class="reference internal" href="#advanced-api">高级 API</a><ul>
|
||
<li><a class="reference internal" href="#doctest-objects">DocTest 对象</a></li>
|
||
<li><a class="reference internal" href="#example-objects">Example 对象</a></li>
|
||
<li><a class="reference internal" href="#doctestfinder-objects">DocTestFinder 对象</a></li>
|
||
<li><a class="reference internal" href="#doctestparser-objects">DocTestParser 对象</a></li>
|
||
<li><a class="reference internal" href="#doctestrunner-objects">DocTestRunner 对象</a></li>
|
||
<li><a class="reference internal" href="#outputchecker-objects">OutputChecker 对象</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#debugging">调试</a></li>
|
||
<li><a class="reference internal" href="#soapbox">肥皂盒</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="pydoc.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pydoc</span></code> --- 文档生成器和在线帮助系统</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="unittest.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> --- 单元测试框架</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/doctest.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</nav>
|
||
</div>
|
||
</div>
|
||
|
||
<div id="outdated-warning" style="padding: .5em; text-align: center; background-color: #FFBABA; color: #6A0E0E;">
|
||
这个文档所针对的是一个已不再受支持的 Python 旧版本。
|
||
你应当升级版本，并阅读
|
||
<a href="/3/library/doctest.html"> Python 当前稳定版本的文档</a>.
|
||
</div>
|
||
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
accesskey="I">索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="unittest.html" title="unittest --- 单元测试框架"
|
||
accesskey="N">下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="pydoc.html" title="pydoc --- 文档生成器和在线帮助系统"
|
||
accesskey="P">上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="development.html" accesskey="U">开发工具</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
|
||
<div class="document">
|
||
<div class="documentwrapper">
|
||
<div class="bodywrapper">
|
||
<div class="body" role="main">
|
||
|
||
<section id="module-doctest">
|
||
<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> --- 测试交互式的 Python 示例<a class="headerlink" href="#module-doctest" title="永久链接至标题">¶</a></h1>
|
||
<p><strong>源代码：</strong> <a class="reference external" href="https://github.com/python/cpython/tree/3.8/Lib/doctest.py">Lib/doctest.py</a></p>
|
||
<hr class="docutils" />
|
||
<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> 模块寻找像Python交互式代码的文本，然后执行这些代码来确保它们的确就像展示的那样正确运行，有许多方法来使用doctest：</p>
|
||
<ul class="simple">
|
||
<li><p>通过验证所有交互式示例仍然按照记录的方式工作，以此来检查模块的文档字符串是否是最新的。</p></li>
|
||
<li><p>通过验证来自一个测试文件或一个测试对象的交互式示例按预期工作，来进行回归测试。</p></li>
|
||
<li><p>为一个包写指导性的文档，用输入输出的例子来说明。 取决于是强调例子还是说明性的文字，这有一种 "文本测试 "或 "可执行文档 "的风格。</p></li>
|
||
</ul>
|
||
<p>下面是一个小却完整的示例模块:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="sd">"""</span>
|
||
<span class="sd">This is the "example" module.</span>
|
||
|
||
<span class="sd">The example module supplies one function, factorial(). For example,</span>
|
||
|
||
<span class="sd">>>> factorial(5)</span>
|
||
<span class="sd">120</span>
|
||
<span class="sd">"""</span>
|
||
|
||
<span class="k">def</span> <span class="nf">factorial</span><span class="p">(</span><span class="n">n</span><span class="p">):</span>
|
||
<span class="w"> </span><span class="sd">"""Return the factorial of n, an exact integer >= 0.</span>
|
||
|
||
<span class="sd"> >>> [factorial(n) for n in range(6)]</span>
|
||
<span class="sd"> [1, 1, 2, 6, 24, 120]</span>
|
||
<span class="sd"> >>> factorial(30)</span>
|
||
<span class="sd"> 265252859812191058636308480000000</span>
|
||
<span class="sd"> >>> factorial(-1)</span>
|
||
<span class="sd"> Traceback (most recent call last):</span>
|
||
<span class="sd"> ...</span>
|
||
<span class="sd"> ValueError: n must be >= 0</span>
|
||
|
||
<span class="sd"> Factorials of floats are OK, but the float must be an exact integer:</span>
|
||
<span class="sd"> >>> factorial(30.1)</span>
|
||
<span class="sd"> Traceback (most recent call last):</span>
|
||
<span class="sd"> ...</span>
|
||
<span class="sd"> ValueError: n must be exact integer</span>
|
||
<span class="sd"> >>> factorial(30.0)</span>
|
||
<span class="sd"> 265252859812191058636308480000000</span>
|
||
|
||
<span class="sd"> It must also not be ridiculously large:</span>
|
||
<span class="sd"> >>> factorial(1e100)</span>
|
||
<span class="sd"> Traceback (most recent call last):</span>
|
||
<span class="sd"> ...</span>
|
||
<span class="sd"> OverflowError: n too large</span>
|
||
<span class="sd"> """</span>
|
||
|
||
<span class="kn">import</span> <span class="nn">math</span>
|
||
<span class="k">if</span> <span class="ow">not</span> <span class="n">n</span> <span class="o">>=</span> <span class="mi">0</span><span class="p">:</span>
|
||
<span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">"n must be >= 0"</span><span class="p">)</span>
|
||
<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>
|
||
<span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s2">"n must be exact integer"</span><span class="p">)</span>
|
||
<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>
|
||
<span class="k">raise</span> <span class="ne">OverflowError</span><span class="p">(</span><span class="s2">"n too large"</span><span class="p">)</span>
|
||
<span class="n">result</span> <span class="o">=</span> <span class="mi">1</span>
|
||
<span class="n">factor</span> <span class="o">=</span> <span class="mi">2</span>
|
||
<span class="k">while</span> <span class="n">factor</span> <span class="o"><=</span> <span class="n">n</span><span class="p">:</span>
|
||
<span class="n">result</span> <span class="o">*=</span> <span class="n">factor</span>
|
||
<span class="n">factor</span> <span class="o">+=</span> <span class="mi">1</span>
|
||
<span class="k">return</span> <span class="n">result</span>
|
||
|
||
|
||
<span class="k">if</span> <span class="vm">__name__</span> <span class="o">==</span> <span class="s2">"__main__"</span><span class="p">:</span>
|
||
<span class="kn">import</span> <span class="nn">doctest</span>
|
||
<span class="n">doctest</span><span class="o">.</span><span class="n">testmod</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果你直接在命令行里运行 <code class="file docutils literal notranslate"><span class="pre">example.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> 将发挥它的作用。</p>
|
||
<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="gp">$</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>没有输出！ 这很正常，这意味着所有的例子都成功了。 把 <code class="docutils literal notranslate"><span class="pre">-v</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> 会打印出它所尝试的详细日志，并在最后打印出一个总结。</p>
|
||
<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
|
||
<span class="go">Trying:</span>
|
||
<span class="go"> factorial(5)</span>
|
||
<span class="go">Expecting:</span>
|
||
<span class="go"> 120</span>
|
||
<span class="go">ok</span>
|
||
<span class="go">Trying:</span>
|
||
<span class="go"> [factorial(n) for n in range(6)]</span>
|
||
<span class="go">Expecting:</span>
|
||
<span class="go"> [1, 1, 2, 6, 24, 120]</span>
|
||
<span class="go">ok</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>以此类推，最终以：</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>Trying:
|
||
factorial(1e100)
|
||
Expecting:
|
||
Traceback (most recent call last):
|
||
...
|
||
OverflowError: n too large
|
||
ok
|
||
2 items passed all tests:
|
||
1 tests in __main__
|
||
8 tests in __main__.factorial
|
||
9 tests in 2 items.
|
||
9 passed and 0 failed.
|
||
Test passed.
|
||
$
|
||
</pre></div>
|
||
</div>
|
||
<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> 你所需要知道的一切！开始上手吧。 下面的章节提供了完整的细节。 请注意，在标准的 Python 测试套件和库中有许多 doctest 的例子。特别有用的例子可以在标准测试文件 <code class="file docutils literal notranslate"><span class="pre">Lib/test/test_doctest.py</span></code> 中找到。</p>
|
||
<section id="simple-usage-checking-examples-in-docstrings">
|
||
<span id="doctest-simple-testmod"></span><h2>简单用法：检查Docstrings中的示例<a class="headerlink" href="#simple-usage-checking-examples-in-docstrings" title="永久链接至标题">¶</a></h2>
|
||
<p>开始使用doctest的最简单方法（但不一定是你将继续这样做的方式）是结束每个模块 <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code> 使用:</p>
|
||
<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">"__main__"</span><span class="p">:</span>
|
||
<span class="kn">import</span> <span class="nn">doctest</span>
|
||
<span class="n">doctest</span><span class="o">.</span><span class="n">testmod</span><span class="p">()</span>
|
||
</pre></div>
|
||
</div>
|
||
<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> 会随后检查模块 <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code> 中的文档字符串。</p>
|
||
<p>以脚本形式运行该模块会使文档中的例子得到执行和验证:</p>
|
||
<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>
|
||
</pre></div>
|
||
</div>
|
||
<p>这不会显示任何东西，除非一个例子失败了，在这种情况下，失败的例子和失败的原因会被打印到stdout，最后一行的输出是 <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>，其中 <em>N</em> 是失败的例子的数量。</p>
|
||
<p>用 <code class="docutils literal notranslate"><span class="pre">-v</span></code> 来运行它来切换，而不是:</p>
|
||
<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>
|
||
</pre></div>
|
||
</div>
|
||
<p>并将所有尝试过的例子的详细报告打印到标准输出，最后还有各种总结。</p>
|
||
<p>你可以通过向 <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> 传递 <code class="docutils literal notranslate"><span class="pre">verbose=True</span></code> 来强制执行 verbose 模式，或者通过传递 <code class="docutils literal notranslate"><span class="pre">verbose=False</span></code> 来禁止它。 在这两种情况下，<code class="docutils literal notranslate"><span class="pre">sys.argv</span></code> 都不会被 <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> 检查（所以传递 <code class="docutils literal notranslate"><span class="pre">-v</span></code> 或不传递都没有影响）。</p>
|
||
<p>还有一个命令行快捷方式用于运行 <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>。 你可以指示Python解释器直接从标准库中运行doctest模块，并在命令行中传递模块名称:</p>
|
||
<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>
|
||
</pre></div>
|
||
</div>
|
||
<p>这将导入 <code class="file docutils literal notranslate"><span class="pre">example.py</span></code> 作为一个独立的模块，并对其运行 <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>
|
||
<p>关于 <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-basic-api"><span class="std std-ref">基本API</span></a> 部分。</p>
|
||
</section>
|
||
<section id="simple-usage-checking-examples-in-a-text-file">
|
||
<span id="doctest-simple-testfile"></span><h2>简单的用法：检查文本文件中的例子<a class="headerlink" href="#simple-usage-checking-examples-in-a-text-file" title="永久链接至标题">¶</a></h2>
|
||
<p>doctest 的另一个简单应用是测试文本文件中的交互式例子。 这可以用 <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> 函数来完成:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">doctest</span>
|
||
<span class="n">doctest</span><span class="o">.</span><span class="n">testfile</span><span class="p">(</span><span class="s2">"example.txt"</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>这个简短的脚本执行并验证文件 <code class="file docutils literal notranslate"><span class="pre">example.txt</span></code> 中包含的任何交互式 Python 示例。该文件的内容被当作一个巨大的文档串来处理；该文件不需要包含一个Python程序！例如，也许 <code class="file docutils literal notranslate"><span class="pre">example.txt</span></code> 包含以下内容:</p>
|
||
<div class="highlight-none notranslate"><div class="highlight"><pre><span></span>The ``example`` module
|
||
======================
|
||
|
||
Using ``factorial``
|
||
-------------------
|
||
|
||
This is an example text file in reStructuredText format. First import
|
||
``factorial`` from the ``example`` module:
|
||
|
||
>>> from example import factorial
|
||
|
||
Now use it:
|
||
|
||
>>> factorial(6)
|
||
120
|
||
</pre></div>
|
||
</div>
|
||
<p>运行 <code class="docutils literal notranslate"><span class="pre">doctest.testfile("example.txt")</span></code>，然后发现这个文档中的错误:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="n">File</span> <span class="s2">"./example.txt"</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>
|
||
<span class="n">Failed</span> <span class="n">example</span><span class="p">:</span>
|
||
<span class="n">factorial</span><span class="p">(</span><span class="mi">6</span><span class="p">)</span>
|
||
<span class="n">Expected</span><span class="p">:</span>
|
||
<span class="mi">120</span>
|
||
<span class="n">Got</span><span class="p">:</span>
|
||
<span class="mi">720</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>与 <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> 不会显示任何东西，除非一个例子失败。 如果一个例子失败了，那么失败的例子和失败的原因将被打印到stdout，使用的格式与 <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>
|
||
<p>默认情况下，<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> 在调用模块的目录中寻找文件。参见章节 <a class="reference internal" href="#doctest-basic-api"><span class="std std-ref">基本API</span></a>，了解可用于告诉它在其他位置寻找文件的可选参数的描述。</p>
|
||
<p>像 <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> 的详细程度可以通过命令行 <code class="docutils literal notranslate"><span class="pre">-v</span></code> 切换或可选的关键字参数 <em>verbose</em> 来设置。</p>
|
||
<p>还有一个命令行快捷方式用于运行 <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>。 你可以指示Python解释器直接从标准库中运行doctest模块，并在命令行中传递文件名:</p>
|
||
<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>
|
||
</pre></div>
|
||
</div>
|
||
<p>因为文件名没有以 <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> 推断它必须用 <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> 运行，而不是 <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>
|
||
<p>关于 <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> 的更多信息，请参见 <a class="reference internal" href="#doctest-basic-api"><span class="std std-ref">基本API</span></a> 一节。</p>
|
||
</section>
|
||
<section id="how-it-works">
|
||
<span id="doctest-how-it-works"></span><h2>它是如何工作的<a class="headerlink" href="#how-it-works" title="永久链接至标题">¶</a></h2>
|
||
<p>这一节详细研究了doctest的工作原理：它查看哪些文档串，它如何找到交互式的用例，它使用什么执行环境，它如何处理异常，以及如何用选项标志来控制其行为。这是你写doctest例子所需要知道的信息；关于在这些例子上实际运行doctest的信息，请看下面的章节。</p>
|
||
<section id="which-docstrings-are-examined">
|
||
<span id="doctest-which-docstrings"></span><h3>哪些文件串被检查了？<a class="headerlink" href="#which-docstrings-are-examined" title="永久链接至标题">¶</a></h3>
|
||
<p>模块的文档串以及所有函数、类和方法的文档串都将被搜索。 导入模块的对象不被搜索。</p>
|
||
<p>此外，如果 <code class="docutils literal notranslate"><span class="pre">M.__test__</span></code> 存在并且 "为真值"，则它必须是一个字典，其中每个条目都将一个（字符串）名称映射到一个函数对象、类对象或字符串。 从 <code class="docutils literal notranslate"><span class="pre">M.__test__</span></code> 找到的函数和类对象的文档字符串会被搜索，而字符串会被当作文档字符串来处理。 在输出时，每个键 <code class="docutils literal notranslate"><span class="pre">K</span></code> 在 <code class="docutils literal notranslate"><span class="pre">M.__test__</span></code> 中都显示为其名称</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="o"><</span><span class="n">name</span> <span class="n">of</span> <span class="n">M</span><span class="o">>.</span><span class="n">__test__</span><span class="o">.</span><span class="n">K</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>任何发现的类都会以类似的方式进行递归搜索，以测试其包含的方法和嵌套类中的文档串。</p>
|
||
<div class="impl-detail compound">
|
||
<p><strong>CPython implementation detail:</strong> Prior to version 3.4, extension modules written in C were not fully
|
||
searched by doctest.</p>
|
||
</div>
|
||
</section>
|
||
<section id="how-are-docstring-examples-recognized">
|
||
<span id="doctest-finding-examples"></span><h3>文档串的例子是如何被识别的？<a class="headerlink" href="#how-are-docstring-examples-recognized" title="永久链接至标题">¶</a></h3>
|
||
<p>在大多数情况下，对交互式控制台会话的复制和粘贴功能工作得很好，但是 doctest 并不试图对任何特定的 Python shell 进行精确的模拟。</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="c1"># comments are ignored</span>
|
||
<span class="gp">>>> </span><span class="n">x</span> <span class="o">=</span> <span class="mi">12</span>
|
||
<span class="gp">>>> </span><span class="n">x</span>
|
||
<span class="go">12</span>
|
||
<span class="gp">>>> </span><span class="k">if</span> <span class="n">x</span> <span class="o">==</span> <span class="mi">13</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">"yes"</span><span class="p">)</span>
|
||
<span class="gp">... </span><span class="k">else</span><span class="p">:</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">"no"</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">"NO"</span><span class="p">)</span>
|
||
<span class="gp">... </span> <span class="nb">print</span><span class="p">(</span><span class="s2">"NO!!!"</span><span class="p">)</span>
|
||
<span class="gp">...</span>
|
||
<span class="go">no</span>
|
||
<span class="go">NO</span>
|
||
<span class="go">NO!!!</span>
|
||
<span class="gp">>>></span>
|
||
</pre></div>
|
||
</div>
|
||
<p id="index-0">任何预期的输出必须紧随包含代码的最后 <code class="docutils literal notranslate"><span class="pre">'>>></span> <span class="pre">'</span></code> 或 <code class="docutils literal notranslate"><span class="pre">'...</span> <span class="pre">'</span></code> 行，预期的输出（如果有的话）延伸到下一 <code class="docutils literal notranslate"><span class="pre">'>>></span> <span class="pre">'</span></code> 行或全空白行。</p>
|
||
<p>fine输出：</p>
|
||
<ul>
|
||
<li><p>预期输出不能包含一个全白的行，因为这样的行被认为是预期输出的结束信号。 如果预期的输出包含一个空行，在你的测试例子中，在每一个预期有空行的地方加上 <code class="docutils literal notranslate"><span class="pre"><BLANKLINE></span></code>。</p></li>
|
||
<li><p>所有硬制表符都被扩展为空格，使用 8 列的制表符。由测试代码生成的输出中的制表符不会被修改。 因为样本输出中的任何硬制表符都会被扩展，这意味着如果代码输出包括硬制表符，文档测试通过的唯一方法是 <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> 选项或者 <a class="reference internal" href="#doctest-directives"><span class="std std-ref">指令</span></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> 类，可以使用一个不同的算法来处理标签。</p></li>
|
||
<li><p>向stdout的输出被捕获，但不向stderr输出（异常回溯通过不同的方式被捕获）。</p></li>
|
||
<li><p>如果你在交互式会话中通过反斜线续行，或出于任何其他原因使用反斜线，你应该使用原始文件串，它将完全保留你输入的反斜线:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
|
||
<span class="gp">... </span><span class="w"> </span><span class="sa">r</span><span class="sd">'''Backslashes in a raw docstring: m\n'''</span>
|
||
<span class="gp">>>> </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>
|
||
<span class="go">Backslashes in a raw docstring: m\n</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>否则，反斜杠将被解释为字符串的一部分。例如，上面的 <code class="docutils literal notranslate"><span class="pre">\n</span></code> 会被解释为一个换行符。 另外，你可以在doctest版本中把每个反斜杠加倍（而不使用原始字符串）:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">def</span> <span class="nf">f</span><span class="p">(</span><span class="n">x</span><span class="p">):</span>
|
||
<span class="gp">... </span><span class="w"> </span><span class="sd">'''Backslashes in a raw docstring: m\\n'''</span>
|
||
<span class="gp">>>> </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>
|
||
<span class="go">Backslashes in a raw docstring: m\n</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
<li><p>起始列并不重要:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">assert</span> <span class="s2">"Easy!"</span>
|
||
<span class="go"> >>> import math</span>
|
||
<span class="go"> >>> math.floor(1.9)</span>
|
||
<span class="go"> 1</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>并从预期的输出中剥离出与开始该例子的初始 <code class="docutils literal notranslate"><span class="pre">'>>></span> <span class="pre">'</span></code> 行中出现的同样多的前导空白字符。</p>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="what-s-the-execution-context">
|
||
<span id="doctest-execution-context"></span><h3>什么是执行上下文？<a class="headerlink" href="#what-s-the-execution-context" title="永久链接至标题">¶</a></h3>
|
||
<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> 找到要测试的文档串时，它都会使用 <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code> 的*浅层副本*，这样运行测试就不会改变模块的真正全局变量，而且 <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code> 的一个测试也不会留下临时变量，从而意外地让另一个测试通过。这意味着例子可以自由地使用 <code class="xref py py-mod docutils literal notranslate"><span class="pre">M</span></code> 中的任何顶级定义的名字，以及正在运行的文档串中早期定义的名字。用例不能看到其他文档串中定义的名字。</p>
|
||
<p>你可以通过将 <code class="docutils literal notranslate"><span class="pre">globs=your_dict</span></code> 传递给 <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> 来强制使用你自己的dict作为执行环境。</p>
|
||
</section>
|
||
<section id="what-about-exceptions">
|
||
<span id="doctest-exceptions"></span><h3>异常如何处理？<a class="headerlink" href="#what-about-exceptions" title="永久链接至标题">¶</a></h3>
|
||
<p>没问题，只要回溯是这个例子产生的唯一输出：只要粘贴回溯即可。<a class="footnote-reference brackets" href="#id2" id="id1">1</a> 由于回溯所包含的细节可能会迅速变化（例如，确切的文件路径和行号），这是doctest努力使其接受的内容具有灵活性的一种情况。</p>
|
||
<p>简单实例:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
|
||
<span class="gr">ValueError</span>: <span class="n">list.remove(x): x not in list</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果 <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> 被触发，该测试就会成功，<code class="docutils literal notranslate"><span class="pre">list.remove(x):</span> <span class="pre">x</span> <span class="pre">not</span> <span class="pre">in</span> <span class="pre">list</span></code> 的细节如图所示。</p>
|
||
<p>异常的预期输出必须以回溯头开始，可以是以下两行中的任何一行，缩进程度与例子中的第一行相同:</p>
|
||
<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>
|
||
<span class="n">Traceback</span> <span class="p">(</span><span class="n">innermost</span> <span class="n">last</span><span class="p">):</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>回溯头的后面是一个可选的回溯堆栈，其内容被doctest忽略。 回溯堆栈通常是省略的，或者从交互式会话中逐字复制的。</p>
|
||
<p>回溯堆栈的后面是最有用的部分：包含异常类型和细节的一行（几行）。 这通常是回溯的最后一行，但如果异常有多行细节，则可以延伸到多行:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">'multi</span><span class="se">\n</span><span class="s1"> line</span><span class="se">\n</span><span class="s1">detail'</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
|
||
<span class="gr">ValueError</span>: <span class="n">multi</span>
|
||
<span class="x"> line</span>
|
||
<span class="x">detail</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>最后三行（以 <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>
|
||
<p>最佳实践是省略回溯栈，除非它为这个例子增加了重要的文档价值。 因此，最后一个例子可能更好，因为:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">raise</span> <span class="ne">ValueError</span><span class="p">(</span><span class="s1">'multi</span><span class="se">\n</span><span class="s1"> line</span><span class="se">\n</span><span class="s1">detail'</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="w"> </span><span class="o">...</span>
|
||
<span class="gr">ValueError</span>: <span class="n">multi</span>
|
||
<span class="x"> line</span>
|
||
<span class="x">detail</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>请注意，回溯的处理方式非常特别。 特别是，在重写的例子中，<code class="docutils literal notranslate"><span class="pre">...</span></code> 的使用与 doctest 的 <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> 选项无关。 该例子中的省略号可以不写，也可以是三个（或三百个）逗号或数字，或者是一个缩进的 Monty Python 短剧的剧本。</p>
|
||
<p>有些细节你应该读一遍，但不需要记住：</p>
|
||
<ul class="simple">
|
||
<li><p>Doctest 不能猜测你的预期输出是来自异常回溯还是来自普通打印。 因此，例如，一个期望 <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> 的用例将通过测试，无论 <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></li>
|
||
<li><p>回溯堆栈的每一行（如果有的话）必须比例子的第一行缩进， <em>或者</em> 以一个非字母数字的字符开始。回溯头之后的第一行缩进程度相同，并且以字母数字开始，被认为是异常细节的开始。当然，这对真正的回溯来说是正确的事情。</p></li>
|
||
<li><p>当 <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 选项被指定时，最左边的冒号后面的所有内容以及异常名称中的任何模块信息都被忽略。</p></li>
|
||
<li><p>交互式 shell 省略了一些 <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> 的回溯头行。但 doctest 使用回溯头行来区分异常和非异常。所以在罕见的情况下，如果你需要测试一个省略了回溯头的 <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>，你将需要手动添加回溯头行到你的测试用例中。</p></li>
|
||
</ul>
|
||
<ul id="index-1">
|
||
<li><p>对于一些 <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>，Python 使用 <code class="docutils literal notranslate"><span class="pre">^</span></code> 标记显示语法错误的字符位置:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="mi">1</span> <span class="mi">1</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>
|
||
<span class="w"> </span><span class="mi">1</span> <span class="mi">1</span>
|
||
<span class="w"> </span><span class="pm">^</span>
|
||
<span class="gr">SyntaxError</span>: <span class="n">invalid syntax</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>由于显示错误位置的行在异常类型和细节之前，它们不被doctest检查。 例如，下面的测试会通过，尽管它把 <code class="docutils literal notranslate"><span class="pre">^</span></code> 标记放在了错误的位置:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="mi">1</span> <span class="mi">1</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>
|
||
<span class="w"> </span><span class="mi">1</span> <span class="mi">1</span>
|
||
<span class="w"> </span><span class="pm">^</span>
|
||
<span class="gr">SyntaxError</span>: <span class="n">invalid syntax</span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
</section>
|
||
<section id="option-flags">
|
||
<span id="doctest-options"></span><span id="option-flags-and-directives"></span><h3>选项标记<a class="headerlink" href="#option-flags" title="永久链接至标题">¶</a></h3>
|
||
<p>一系列选项旗标控制着 doctest 的各方面行为。 旗标的符号名称以模块常量的形式提供，可以一起 <a class="reference internal" href="../reference/expressions.html#bitwise"><span class="std std-ref">bitwise ORed</span></a> 并传递给各种函数。 这些名称也可以在 <a class="reference internal" href="#doctest-directives"><span class="std std-ref">doctest directives</span></a> 中使用，并且可以通过 <code class="docutils literal notranslate"><span class="pre">-o</span></code> 选项传递给 doctest 命令行接口。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.4 新版功能: </span>命令行选项 <code class="docutils literal notranslate"><span class="pre">-o</span></code> 。</p>
|
||
</div>
|
||
<p>第一组选项定义了测试语义，控制doctest如何决定实际输出是否与用例的预期输出相匹配方面的问题。</p>
|
||
<dl class="data">
|
||
<dt id="doctest.DONT_ACCEPT_TRUE_FOR_1">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">DONT_ACCEPT_TRUE_FOR_1</code><a class="headerlink" href="#doctest.DONT_ACCEPT_TRUE_FOR_1" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>默认情况下，如果一个预期的输出块只包含 <code class="docutils literal notranslate"><span class="pre">1</span></code>，那么实际的输出块只包含 <code class="docutils literal notranslate"><span class="pre">1</span></code> 或只包含 <code class="docutils literal notranslate"><span class="pre">True</span></code> 就被认为是匹配的，同样，<code class="docutils literal notranslate"><span class="pre">0</span></code> 与 <code class="docutils literal notranslate"><span class="pre">False</span></code> 也是如此。 当 <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> 被指定时，两种替换都不允许。 默认行为是为了适应 Python 将许多函数的返回类型从整数改为布尔值；期望 "小整数" 输出的测试在这些情况下仍然有效。 这个选项可能会消失，但不会在几年内消失。</p>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-2"></span><dl class="data">
|
||
<dt id="doctest.DONT_ACCEPT_BLANKLINE">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">DONT_ACCEPT_BLANKLINE</code><a class="headerlink" href="#doctest.DONT_ACCEPT_BLANKLINE" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>默认情况下，如果一个预期输出块包含一个只包含字符串 <code class="docutils literal notranslate"><span class="pre"><BLANKLINE></span></code> 的行，那么该行将与实际输出中的一个空行相匹配。 因为一个真正的空行是对预期输出的限定，这是传达预期空行的唯一方法。 当 <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> 被指定时，这种替换是不允许的。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="doctest.NORMALIZE_WHITESPACE">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">NORMALIZE_WHITESPACE</code><a class="headerlink" href="#doctest.NORMALIZE_WHITESPACE" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当指定时，所有的空白序列（空白和换行）都被视为相等。预期输出中的任何空白序列将与实际输出中的任何空白序列匹配。默认情况下，空白必须完全匹配。 <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> 在预期输出非常长的一行，而你想把它包在源代码的多行中时特别有用。</p>
|
||
</dd></dl>
|
||
|
||
<span class="target" id="index-3"></span><dl class="data">
|
||
<dt id="doctest.ELLIPSIS">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">ELLIPSIS</code><a class="headerlink" href="#doctest.ELLIPSIS" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当指定时，预期输出中的省略号（ <code class="docutils literal notranslate"><span class="pre">...</span></code> ）可以匹配实际输出中的任何子串。这包括跨行的子串和空子串，所以最好保持简单的用法。复杂的用法会导致与 <code class="docutils literal notranslate"><span class="pre">.*</span></code> 在正则表达式中容易出现的 "oops, it matched too much!"相同的意外情况。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="doctest.IGNORE_EXCEPTION_DETAIL">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">IGNORE_EXCEPTION_DETAIL</code><a class="headerlink" href="#doctest.IGNORE_EXCEPTION_DETAIL" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当被指定时，如果一个预期的异常类型被触发，即使异常细节不匹配，期望异常的用例也会通过。 例如，如果实际引发的异常是 <code class="docutils literal notranslate"><span class="pre">ValueError:</span> <span class="pre">42</span></code>，期待 <code class="docutils literal notranslate"><span class="pre">ValueError:</span> <span class="pre">3*14</span></code> 的用例将通过，但例如，如果 <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> 触发将导致失败。</p>
|
||
<p>它也会忽略Python 3 doctest报告中使用的模块名称。因此，无论测试是在Python 2.7还是Python 3.2 (或更高版本)下运行，这两种变化都会在指定的标志下工作:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="k">raise</span> <span class="n">CustomError</span><span class="p">(</span><span class="s1">'message'</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="gr">CustomError</span>: <span class="n">message</span>
|
||
|
||
<span class="gp">>>> </span><span class="k">raise</span> <span class="n">CustomError</span><span class="p">(</span><span class="s1">'message'</span><span class="p">)</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
<span class="gr">my_module.CustomError</span>: <span class="n">message</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>注意 <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> 也可以用来忽略异常信息的细节，但这样的测试仍然可能失败，因为模块的细节可能被打印为异常名称的一部分。使用 <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> 和 Python 2.3 的细节也是唯一明确的方法，可以编写一个不关心异常细节但在 Python 2.3 或更早的版本中继续通过的 doctest (这些版本不支持 <a class="reference internal" href="#doctest-directives"><span class="std std-ref">doctest directives</span></a> 并将其作为无关的注释忽略)。例如:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="s1">'moo'</span>
|
||
<span class="gt">Traceback (most recent call last):</span>
|
||
File <span class="nb">"<stdin>"</span>, line <span class="m">1</span>, in <span class="n"><module></span>
|
||
<span class="gr">TypeError</span>: <span class="n">object doesn't support item assignment</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>在Python 2.3及以后的Python版本中，在指定了标志的情况下通过，尽管这个细节在Python 2.4中改变为 "does not" 而不是 "doesn't"。</p>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 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> 现在也忽略了与包含被测异常的模块有关的任何信息。</p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="doctest.SKIP">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">SKIP</code><a class="headerlink" href="#doctest.SKIP" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当指定时，完全不运行这个用例。 这在doctest用例既是文档又是测试案例的情况下很有用，一个例子应该包括在文档中，但不应该被检查。例如，这个例子的输出可能是随机的；或者这个例子可能依赖于测试驱动程序所不能使用的资源。</p>
|
||
<p>SKIP标志也可用于临时 "注释" 用例。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="doctest.COMPARISON_FLAGS">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">COMPARISON_FLAGS</code><a class="headerlink" href="#doctest.COMPARISON_FLAGS" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个比特或运算将上述所有的比较标志放在一起。</p>
|
||
</dd></dl>
|
||
|
||
<p>第二组选项控制测试失败的报告方式：</p>
|
||
<dl class="data">
|
||
<dt id="doctest.REPORT_UDIFF">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">REPORT_UDIFF</code><a class="headerlink" href="#doctest.REPORT_UDIFF" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当指定时，涉及多行预期和实际输出的故障将使用统一的差异来显示。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="doctest.REPORT_CDIFF">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">REPORT_CDIFF</code><a class="headerlink" href="#doctest.REPORT_CDIFF" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当指定时，涉及多行预期和实际输出的故障将使用上下文差异来显示。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="doctest.REPORT_NDIFF">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">REPORT_NDIFF</code><a class="headerlink" href="#doctest.REPORT_NDIFF" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当指定时，差异由 <code class="docutils literal notranslate"><span class="pre">difflib.Differ</span></code> 来计算，使用与流行的:file:<cite>ndiff.py`工具相同的算法。这是唯一一种标记行内和行间差异的方法。 例如，如果一行预期输出包含数字 ``1`</cite> ，而实际输出包含字母 <code class="docutils literal notranslate"><span class="pre">l</span></code> ，那么就会插入一行，用圆点标记不匹配的列位置。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="doctest.REPORT_ONLY_FIRST_FAILURE">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">REPORT_ONLY_FIRST_FAILURE</code><a class="headerlink" href="#doctest.REPORT_ONLY_FIRST_FAILURE" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当指定时，在每个 doctest 中显示第一个失败的用例，但隐藏所有其余用例的输出。 这将防止 doctest 报告由于先前的失败而中断的正确用例；但也可能隐藏独立于第一个失败的不正确用例。 当 <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> 被指定时，其余的用例仍然被运行，并且仍然计入报告的失败总数；只是输出被隐藏了。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="doctest.FAIL_FAST">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">FAIL_FAST</code><a class="headerlink" href="#doctest.FAIL_FAST" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>当指定时，在第一个失败的用例后退出，不尝试运行其余的用例。因此，报告的失败次数最多为1。这个标志在调试时可能很有用，因为第一个失败后的用例甚至不会产生调试输出。</p>
|
||
<p>doctest 命令行接受选项 <code class="docutils literal notranslate"><span class="pre">-f</span></code> 作为 <code class="docutils literal notranslate"><span class="pre">-o</span> <span class="pre">FAIL_FAST</span></code> 的简洁形式。</p>
|
||
<div class="versionadded">
|
||
<p><span class="versionmodified added">3.4 新版功能.</span></p>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<dl class="data">
|
||
<dt id="doctest.REPORTING_FLAGS">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">REPORTING_FLAGS</code><a class="headerlink" href="#doctest.REPORTING_FLAGS" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个比特或操作将上述所有的报告标志组合在一起。</p>
|
||
</dd></dl>
|
||
|
||
<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> 内部。</p>
|
||
<dl class="function">
|
||
<dt id="doctest.register_optionflag">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">register_optionflag</code><span class="sig-paren">(</span><em class="sig-param">name</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.register_optionflag" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用给定的名称创建一个新的选项标志，并返回新标志的整数值。 <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> 可以在继承 <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> 或 <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> 时使用，以创建子类支持的新选项。 <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> 应始终使用以下方式调用:</p>
|
||
<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">'MY_FLAG'</span><span class="p">)</span>
|
||
</pre></div>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="directives">
|
||
<span id="doctest-directives"></span><span id="index-4"></span><h3>指令<a class="headerlink" href="#directives" title="永久链接至标题">¶</a></h3>
|
||
<p>Doctest指令可以用来修改单个例子的 <a class="reference internal" href="#doctest-options"><span class="std std-ref">option flags</span></a> 。 Doctest指令是在一个用例的源代码后面的特殊Python注释。</p>
|
||
<pre>
|
||
<strong id="grammar-token-directive">directive </strong> ::= "#" "doctest:" <a class="reference internal" href="#grammar-token-directive-options"><code class="xref docutils literal notranslate"><span class="pre">directive_options</span></code></a>
|
||
<strong id="grammar-token-directive-options">directive_options </strong> ::= <a class="reference internal" href="#grammar-token-directive-option"><code class="xref docutils literal notranslate"><span class="pre">directive_option</span></code></a> ("," <a class="reference internal" href="#grammar-token-directive-option"><code class="xref docutils literal notranslate"><span class="pre">directive_option</span></code></a>)\*
|
||
<strong id="grammar-token-directive-option">directive_option </strong> ::= <a class="reference internal" href="#grammar-token-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-directive-option-name"><code class="xref docutils literal notranslate"><span class="pre">directive_option_name</span></code></a>
|
||
<strong id="grammar-token-on-or-off">on_or_off </strong> ::= "+" \| "-"
|
||
<strong id="grammar-token-directive-option-name">directive_option_name</strong> ::= "DONT_ACCEPT_BLANKLINE" \| "NORMALIZE_WHITESPACE" \| ...
|
||
</pre>
|
||
<p><code class="docutils literal notranslate"><span class="pre">+</span></code> 或 <code class="docutils literal notranslate"><span class="pre">-</span></code> 与指令选项名称之间不允许有空格。 指令选项名称可以是上面解释的任何一个选项标志名称。</p>
|
||
<p>一个用例的 doctest 指令可以修改 doctest 对该用例的行为。 使用 <code class="docutils literal notranslate"><span class="pre">+</span></code> 来启用指定的行为，或者使用 <code class="docutils literal notranslate"><span class="pre">-</span></code> 来禁用它。</p>
|
||
<p>例如，这个测试将会通过:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="go">[0, 1, 2, 3, 4, 5, 6, 7, 8, 9,</span>
|
||
<span class="go">10, 11, 12, 13, 14, 15, 16, 17, 18, 19]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果没有这个指令，它就会失败，这是因为实际的输出在个位数的列表元素前没有两个空格，也因为实际的输出是在单行上。 这个测试也通过了，而且也需要一个指令来完成:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="go">[0, 1, ..., 18, 19]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>在一个物理行上可以使用多个指令，用逗号分隔:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="go">[0, 1, ..., 18, 19]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>如果在一个用例中使用了多个指令注释，那么它们将被合并:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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="gp">... </span>
|
||
<span class="go">[0, 1, ..., 18, 19]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>正如前面的例子所示，你可以在你的用例中添加只包含指令的行。 当一个用例太长，指令不能舒适地放在同一行时，这可能很有用:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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>
|
||
<span class="gp">... </span>
|
||
<span class="go">[0, ..., 4, 10, ..., 19, 30, ..., 39]</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>请注意，由于所有的选项都是默认禁用的，而指令只适用于它们出现的用例，所以启用选项 (通过指令中的 <code class="docutils literal notranslate"><span class="pre">+</span></code>) 通常是唯一有意义的选择。 然而，选项标志也可以被传递给运行测试的函数，建立不同的默认值。 在这种情况下，通过指令中的 <code class="docutils literal notranslate"><span class="pre">-</span></code> 来禁用一个选项可能是有用的。</p>
|
||
</section>
|
||
<section id="warnings">
|
||
<span id="doctest-warnings"></span><h3>警告<a class="headerlink" href="#warnings" title="永久链接至标题">¶</a></h3>
|
||
<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> 是严格地要求在预期输出中完全匹配。 如果哪怕只有一个字符不匹配，测试就会失败。 这可能会让你吃惊几次，在你确切地了解到 Python 对输出的保证和不保证之前。 例如，当打印一个集合时，Python 不保证元素以任何特定的顺序被打印出来，所以像:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">foo</span><span class="p">()</span>
|
||
<span class="go">{"Hermione", "Harry"}</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>是不可靠的！一个变通方法是用:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">foo</span><span class="p">()</span> <span class="o">==</span> <span class="p">{</span><span class="s2">"Hermione"</span><span class="p">,</span> <span class="s2">"Harry"</span><span class="p">}</span>
|
||
<span class="go">True</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>来取代。另一个是使用</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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>
|
||
<span class="gp">>>> </span><span class="n">d</span>
|
||
<span class="go">['Harry', 'Hermione']</span>
|
||
</pre></div>
|
||
</div>
|
||
<div class="admonition note">
|
||
<p class="admonition-title">注解</p>
|
||
<p>在 Python 3.6 之前，当打印一个 dict 时，Python 并不保证键值对以任何特定的顺序被打印。</p>
|
||
</div>
|
||
<p>还有其他的问题，但你会明白的。</p>
|
||
<p>另一个不好的做法是打印嵌入了对象地址的变量，如:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </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>
|
||
<span class="go">7948648</span>
|
||
<span class="gp">>>> </span><span class="k">class</span> <span class="nc">C</span><span class="p">:</span> <span class="k">pass</span>
|
||
<span class="gp">>>> </span><span class="n">C</span><span class="p">()</span> <span class="c1"># the default repr() for instances embeds an address</span>
|
||
<span class="go"><__main__.C instance at 0x00AC18F0></span>
|
||
</pre></div>
|
||
</div>
|
||
<p><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> 指令为最后一个例子提供了一个不错的方法:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="n">C</span><span class="p">()</span>
|
||
<span class="go"><__main__.C instance at 0x...></span>
|
||
</pre></div>
|
||
</div>
|
||
<p>浮点数在不同的平台上也会有小的输出变化，因为Python在浮点数的格式化上依赖于平台的C库，而C库在这个问题上的质量差异很大。:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="mf">1.</span><span class="o">/</span><span class="mi">7</span> <span class="c1"># risky</span>
|
||
<span class="go">0.14285714285714285</span>
|
||
<span class="gp">>>> </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>
|
||
<span class="go">0.142857142857</span>
|
||
<span class="gp">>>> </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>
|
||
<span class="go">0.142857</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>形式 <code class="docutils literal notranslate"><span class="pre">I/2.**J</span></code> 的数字在所有的平台上都是安全的，我经常设计一些测试的用例来产生该形式的数:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="mf">3.</span><span class="o">/</span><span class="mi">4</span> <span class="c1"># utterly safe</span>
|
||
<span class="go">0.75</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>简单的分数也更容易让人理解，这也使得文件更加完善。</p>
|
||
</section>
|
||
</section>
|
||
<section id="basic-api">
|
||
<span id="doctest-basic-api"></span><h2>基本API<a class="headerlink" href="#basic-api" title="永久链接至标题">¶</a></h2>
|
||
<p>函数 <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> 为 doctest 提供了一个简单的接口，应该足以满足大多数基本用途。关于这两个函数的不太正式的介绍，请参见 <a class="reference internal" href="#doctest-simple-testmod"><span class="std std-ref">简单用法：检查Docstrings中的示例</span></a> 和 <a class="reference internal" href="#doctest-simple-testfile"><span class="std std-ref">简单的用法：检查文本文件中的例子</span></a> 部分。</p>
|
||
<dl class="function">
|
||
<dt id="doctest.testfile">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">testfile</code><span class="sig-paren">(</span><em class="sig-param">filename</em>, <em class="sig-param">module_relative=True</em>, <em class="sig-param">name=None</em>, <em class="sig-param">package=None</em>, <em class="sig-param">globs=None</em>, <em class="sig-param">verbose=None</em>, <em class="sig-param">report=True</em>, <em class="sig-param">optionflags=0</em>, <em class="sig-param">extraglobs=None</em>, <em class="sig-param">raise_on_error=False</em>, <em class="sig-param">parser=DocTestParser()</em>, <em class="sig-param">encoding=None</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.testfile" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>除了*filename*，所有的参数都是可选的，而且应该以关键字的形式指定。</p>
|
||
<p>测试名为 <em>filename</em> 的文件中的用例。 返回 <code class="docutils literal notranslate"><span class="pre">(failure_count,</span> <span class="pre">test_count)</span></code>。</p>
|
||
<p>可选参数 <em>module_relative</em> 指定了文件名的解释方式。</p>
|
||
<ul class="simple">
|
||
<li><p>如果 <em>module_relative</em> 是 <code class="docutils literal notranslate"><span class="pre">True</span></code> (默认)，那么 <em>filename</em> 指定一个独立于操作系统的模块相对路径。 默认情况下，这个路径是相对于调用模块的目录的；但是如果指定了 <em>package</em> 参数，那么它就是相对于该包的。 为了保证操作系统的独立性， <em>filename</em> 应该使用字符来分隔路径段，并且不能是一个绝对路径 (即不能以 <code class="docutils literal notranslate"><span class="pre">/</span></code> 开始)。</p></li>
|
||
<li><p>如果 <em>module_relative</em> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code>，那么 <em>filename</em> 指定了一个操作系统特定的路径。路径可以是绝对的，也可以是相对的；相对路径是相对于当前工作目录而言的。</p></li>
|
||
</ul>
|
||
<p>可选参数 <em>name</em> 给出了测试的名称；默认情况下，或者如果是 <code class="docutils literal notranslate"><span class="pre">None</span></code>，那么使用 <code class="docutils literal notranslate"><span class="pre">os.path.basename(filename)</span></code>。</p>
|
||
<p>可选参数 <em>package</em> 是一个 Python 包或一个 Python 包的名字，其目录应被用作模块相关文件名的基础目录。 如果没有指定包，那么调用模块的目录将作为模块相关文件名的基础目录。如果 <em>module_relative</em> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code>，那么指定 <em>package</em> 是错误的。</p>
|
||
<p>可选参数 <em>globs</em> 给出了一个在执行示例时用作全局变量的dict。 这个dict的一个新的浅层副本将为doctest创建，因此它的用例将从一个干净的地方开始。默认情况下，或者如果为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，使用一个新的空dict。</p>
|
||
<p>可选参数 <em>extraglobs</em> 给出了一个合并到用于执行用例全局变量中的dict。 这就像 <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> 一样：如果 <em>globs</em> 和 <em>extraglobs</em> 有一个共同的键，那么 <em>extraglobs</em> 中的相关值会出现在合并的dict中。 默认情况下，或者为 <code class="docutils literal notranslate"><span class="pre">None</span></code> ，则不使用额外的全局变量。这是一个高级功能，允许对 doctest 进行参数化。例如，可以为一个基类写一个测试，使用该类的通用名称，然后通过传递一个 <em>extraglobs</em> dict，将通用名称映射到要测试的子类，从而重复用于测试任何数量的子类。</p>
|
||
<p>可选的参数 <em>verbose</em> 如果为真值会打印很多东西，如果为假值则只打印失败信息；默认情况下，或者为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，只有当 <code class="docutils literal notranslate"><span class="pre">'-v'</span></code> 在 <code class="docutils literal notranslate"><span class="pre">sys.argv</span></code> 中时才为真值。</p>
|
||
<p>可选参数 <em>report</em> 为True时，在结尾处打印一个总结，否则在结尾处什么都不打印。 在verbose模式下，总结是详细的，否则总结是非常简短的（事实上，如果所有的测试都通过了，总结就是空的）。</p>
|
||
<p>可选参数 <em>optionflags</em> （默认值为0）是选项标志的 <a class="reference internal" href="../reference/expressions.html#bitwise"><span class="std std-ref">bitwise OR</span></a> 。参见章节 <a class="reference internal" href="#doctest-options"><span class="std std-ref">选项标记</span></a> 。</p>
|
||
<p>可选参数 <em>raise_on_error</em> 默认为False。 如果是True，在一个用例中第一次出现失败或意外的异常时，会触发一个异常。这允许对失败进行事后调试。默认行为是继续运行例子。</p>
|
||
<p>可选参数 <em>parser</em> 指定一个 <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> （或子类），它应该被用来从文件中提取测试。它默认为一个普通的解析器（即 <code class="docutils literal notranslate"><span class="pre">DocTestParser()</span></code>）。</p>
|
||
<p>可选参数 <em>encoding</em> 指定了一个编码，应该用来将文件转换为unicode。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="doctest.testmod">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">testmod</code><span class="sig-paren">(</span><em class="sig-param">m=None</em>, <em class="sig-param">name=None</em>, <em class="sig-param">globs=None</em>, <em class="sig-param">verbose=None</em>, <em class="sig-param">report=True</em>, <em class="sig-param">optionflags=0</em>, <em class="sig-param">extraglobs=None</em>, <em class="sig-param">raise_on_error=False</em>, <em class="sig-param">exclude_empty=False</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.testmod" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>所有的参数都是可选的，除了 <em>m</em> 之外，都应该以关键字的形式指定。</p>
|
||
<p>测试从模块 <em>m</em> （或模块 <a class="reference internal" href="__main__.html#module-__main__" title="__main__: The environment where the top-level script is run."><code class="xref py py-mod docutils literal notranslate"><span class="pre">__main__</span></code></a> ，如果 <em>m</em> 没有被提供或为 <code class="docutils literal notranslate"><span class="pre">None</span></code> ）可达到的函数和类的文档串中的用例，从 <code class="docutils literal notranslate"><span class="pre">m.__doc__</span></code> 开始。</p>
|
||
<p>也测试从dict <code class="docutils literal notranslate"><span class="pre">m.__test__</span></code> 可达到的用例，如果它存在并且不是 <code class="docutils literal notranslate"><span class="pre">None</span></code> 。 <code class="docutils literal notranslate"><span class="pre">m.__test__</span></code> 将名字（字符串）映射到函数、类和字符串；函数和类的文档串被搜索到的用例；字符串被直接搜索到，就像它们是文档串一样。</p>
|
||
<p>只搜索附属于模块 <em>m</em> 中的对象的文档串。</p>
|
||
<p>返回 <code class="docutils literal notranslate"><span class="pre">(failure_count,</span> <span class="pre">test_count)</span></code> 。</p>
|
||
<p>可选参数 <em>name</em> 给出了模块的名称；默认情况下，或者如果为 <code class="docutils literal notranslate"><span class="pre">None</span></code> ，则为 <code class="docutils literal notranslate"><span class="pre">m.__name__</span></code> 。</p>
|
||
<p>可选参数 <em>exclude_empty</em> 默认为假值。 如果为真值，没有找到任何 doctest 的对象将被排除在考虑范围之外。 默认情况下是向后兼容，所以仍然使用 <code class="xref py py-meth docutils literal notranslate"><span class="pre">doctest.master.summarize()</span></code> 和 <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.DocTestFinder" title="doctest.DocTestFinder"><code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestFinder</span></code></a> 构造器的 <em>exclude_empty</em> 参数默认为真值。</p>
|
||
<p>可选参数 <em>extraglobs</em> 、 <em>verbose</em> 、 <em>report</em> 、 <em>optionflags</em> 、 <em>raise_on_error</em> 和 <em>globs</em> 与上述函数 <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> 的参数相同，只是 <em>globs</em> 默认为 <code class="docutils literal notranslate"><span class="pre">m.__dict__</span></code> 。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="doctest.run_docstring_examples">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">run_docstring_examples</code><span class="sig-paren">(</span><em class="sig-param">f</em>, <em class="sig-param">globs</em>, <em class="sig-param">verbose=False</em>, <em class="sig-param">name="NoName"</em>, <em class="sig-param">compileflags=None</em>, <em class="sig-param">optionflags=0</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.run_docstring_examples" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>与对象 <em>f</em> 相关的测试用例；例如， <em>f</em> 可以是一个字符串、一个模块、一个函数或一个类对象。</p>
|
||
<p>dict 参数 <em>globs</em> 的浅层拷贝被用于执行环境。</p>
|
||
<p>可选参数 <em>name</em> 在失败信息中使用，默认为 <code class="docutils literal notranslate"><span class="pre">"NoName"</span></code> 。</p>
|
||
<p>如果可选参数 <em>verbose</em> 为真，即使没有失败也会产生输出。 默认情况下，只有在用例失败的情况下才会产生输出。</p>
|
||
<p>可选参数 <em>compileflags</em> 给出了Python编译器在运行例子时应该使用的标志集。默认情况下，或者如果为 <code class="docutils literal notranslate"><span class="pre">None</span></code> ，标志是根据 <em>globs</em> 中发现的未来特征集推导出来的。</p>
|
||
<p>可选参数 <em>optionflags</em> 的作用与上述 <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> 函数中的相同。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="unittest-api">
|
||
<span id="doctest-unittest-api"></span><h2>Unittest API<a class="headerlink" href="#unittest-api" title="永久链接至标题">¶</a></h2>
|
||
<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> 提供了两个函数，可以用来从模块和包含测试的文本文件中创建 <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> 测试套件。 要与 <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> 测试发现集成，请在你的测试模块中包含一个 <code class="xref py py-func docutils literal notranslate"><span class="pre">load_tests()</span></code> 函数：:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">unittest</span>
|
||
<span class="kn">import</span> <span class="nn">doctest</span>
|
||
<span class="kn">import</span> <span class="nn">my_module_with_doctests</span>
|
||
|
||
<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>
|
||
<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>
|
||
<span class="k">return</span> <span class="n">tests</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>有两个主要函数用于从文本文件和带doctest的模块中创建 <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>
|
||
<dl class="function">
|
||
<dt id="doctest.DocFileSuite">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">DocFileSuite</code><span class="sig-paren">(</span><em class="sig-param">*paths</em>, <em class="sig-param">module_relative=True</em>, <em class="sig-param">package=None</em>, <em class="sig-param">setUp=None</em>, <em class="sig-param">tearDown=None</em>, <em class="sig-param">globs=None</em>, <em class="sig-param">optionflags=0</em>, <em class="sig-param">parser=DocTestParser()</em>, <em class="sig-param">encoding=None</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocFileSuite" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将一个或多个文本文件中的doctest测试转换为一个 <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>
|
||
<p>返回的 <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> 将由 unittest 框架运行，并运行每个文件中的交互式示例。如果任何文件中的用例失败了，那么合成的单元测试就会失败，并触发一个 <code class="xref py py-exc docutils literal notranslate"><span class="pre">failureException</span></code> 异常，显示包含该测试的文件名和一个（有时是近似的）行号。</p>
|
||
<p>传递一个或多个要检查的文本文件的路径（作为字符串）。</p>
|
||
<p>选项可以作为关键字参数提供：</p>
|
||
<p>可选参数 <em>module_relative</em> 指定了 <em>paths</em> 中的文件名应该如何解释。</p>
|
||
<ul class="simple">
|
||
<li><p>如果 <em>module_relative</em> 是 <code class="docutils literal notranslate"><span class="pre">True</span></code> （默认值），那么 <em>paths</em> 中的每个文件名都指定了一个独立于操作系统的模块相对路径。 默认情况下，这个路径是相对于调用模块的目录的；但是如果指定了 <em>package</em> 参数，那么它就是相对于该包的。 为了保证操作系统的独立性，每个文件名都应该使用字符来分隔路径段，并且不能是绝对路径（即不能以 <code class="docutils literal notranslate"><span class="pre">/</span></code> 开始）。</p></li>
|
||
<li><p>如果 <em>module_relative</em> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code> ，那么 <em>paths</em> 中的每个文件名都指定了一个操作系统特定的路径。 路径可以是绝对的，也可以是相对的；相对路径是关于当前工作目录的解析。</p></li>
|
||
</ul>
|
||
<p>可选参数 <em>package</em> 是一个Python包或一个Python包的名字，其目录应该被用作 <em>paths</em> 中模块相关文件名的基本目录。 如果没有指定包，那么调用模块的目录将作为模块相关文件名的基础目录。 如果 <em>module_relative</em> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code> ，那么指定 <em>package</em> 是错误的。</p>
|
||
<p>可选的参数 <em>setUp</em> 为测试套件指定了一个设置函数。在运行每个文件中的测试之前，它被调用。 <em>setUp</em> 函数将被传递给一个 <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> 对象。 setUp函数可以通过测试的 <em>globs</em> 属性访问测试的全局变量。</p>
|
||
<p>可选的参数 <em>tearDown</em> 指定了测试套件的卸载函数。 在运行每个文件中的测试后，它会被调用。 <em>tearDown</em> 函数将被传递一个 <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> 对象。 setUp函数可以通过测试的 <em>globs</em> 属性访问测试的全局变量。</p>
|
||
<p>可选参数 <em>globs</em> 是一个包含测试的初始全局变量的字典。 这个字典的一个新副本为每个测试创建。 默认情况下， <em>globs</em> 是一个新的空字典。</p>
|
||
<p>可选参数 <em>optionflags</em> 为测试指定默认的doctest选项，通过将各个选项的标志连接在一起创建。 参见章节 <a class="reference internal" href="#doctest-options"><span class="std std-ref">选项标记</span></a> 。参见下面的函数 <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> ，以了解设置报告选项的更好方法。</p>
|
||
<p>可选参数 <em>parser</em> 指定一个 <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> （或子类），它应该被用来从文件中提取测试。它默认为一个普通的解析器（即 <code class="docutils literal notranslate"><span class="pre">DocTestParser()</span></code>）。</p>
|
||
<p>可选参数 <em>encoding</em> 指定了一个编码，应该用来将文件转换为unicode。</p>
|
||
<p>该全局 <code class="docutils literal notranslate"><span class="pre">__file__</span></code> 被添加到提供给用 <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> 从文本文件加载的doctest的全局变量中。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="doctest.DocTestSuite">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">DocTestSuite</code><span class="sig-paren">(</span><em class="sig-param">module=None</em>, <em class="sig-param">globs=None</em>, <em class="sig-param">extraglobs=None</em>, <em class="sig-param">test_finder=None</em>, <em class="sig-param">setUp=None</em>, <em class="sig-param">tearDown=None</em>, <em class="sig-param">checker=None</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestSuite" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将一个模块的doctest测试转换为 <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>
|
||
<p>返回的 <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> 将由 unittest 框架运行，并运行模块中的每个 doctest。 如果任何一个测试失败，那么合成的单元测试就会失败，并触发一个 <code class="xref py py-exc docutils literal notranslate"><span class="pre">failureException</span></code> 异常，显示包含该测试的文件名和一个（有时是近似的）行号。</p>
|
||
<p>可选参数 <em>module</em> 提供了要测试的模块。 它可以是一个模块对象或一个（可能是带点的）模块名称。 如果没有指定，则使用调用此函数的模块。</p>
|
||
<p>可选参数 <em>globs</em> 是一个包含测试的初始全局变量的字典。 这个字典的一个新副本为每个测试创建。 默认情况下， <em>globs</em> 是一个新的空字典。</p>
|
||
<p>可选参数 <em>extraglobs</em> 指定了一组额外的全局变量，这些变量被合并到 <em>globs</em> 中。 默认情况下，不使用额外的全局变量。</p>
|
||
<p>可选参数 <em>test_finder</em> 是 <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> 对象（或一个可替换的对象），用于从模块中提取测试。</p>
|
||
<p>可选参数 <em>setUp</em> 、 <em>tearDown</em> 和 <em>optionflags</em> 与上述函数 <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>
|
||
<p>这个函数使用与 <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>
|
||
<div class="versionchanged">
|
||
<p><span class="versionmodified changed">在 3.5 版更改: </span>如果 <em>module</em> 不包含任何文件串，则 <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> 返回一个空的 <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>，而不是触发 <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>
|
||
</div>
|
||
</dd></dl>
|
||
|
||
<p><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> 从 <code class="xref py py-class docutils literal notranslate"><span class="pre">doctest.DocTestCase</span></code> 实例中创建一个 <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> ，而 <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</span></code> 是 <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> 在这里没有记录（这是一个内部细节），但研究其代码可以回答关于 <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> 集成的实际细节问题。</p>
|
||
<p>同样， <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> 从 <code class="xref py py-class docutils literal notranslate"><span class="pre">doctest.DocFileCase</span></code> 实例中创建一个 <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> ，并且 <code class="xref py py-class docutils literal notranslate"><span class="pre">DocFileCase</span></code> 是 <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</span></code> 的一个子类。</p>
|
||
<p>所以这两种创建 <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> 的方式都是运行 <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</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> 函数时，你可以直接控制使用中的 <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> 选项，通过传递选项标志给 <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> 函数。 然而，如果你正在编写一个 <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> 框架， <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> 最终会控制测试的运行时间和方式。 框架作者通常希望控制 <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> 的报告选项（也许，例如，由命令行选项指定），但没有办法通过 <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> 向 <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> 测试运行者传递选项。</p>
|
||
<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> 也支持一个概念，即 <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> 报告特定于 <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> 支持的标志，通过这个函数：</p>
|
||
<dl class="function">
|
||
<dt id="doctest.set_unittest_reportflags">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">set_unittest_reportflags</code><span class="sig-paren">(</span><em class="sig-param">flags</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.set_unittest_reportflags" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 报告标志。</p>
|
||
<p>参数 <em>flags</em> 是选项标志的 <a class="reference internal" href="../reference/expressions.html#bitwise"><span class="std std-ref">bitwise OR</span></a> 。 参见章节 <a class="reference internal" href="#doctest-options"><span class="std std-ref">选项标记</span></a> 。 只有 "报告标志" 可以被使用。</p>
|
||
<p>这是一个模块的全局设置，并影响所有未来由模块 <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> 运行的测试： <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</span></code> 的 <code class="xref py py-meth docutils literal notranslate"><span class="pre">runTest()</span></code> 方法会查看 <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</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> 的 <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> 报告标志被 <a class="reference internal" href="../reference/expressions.html#bitwise"><span class="std std-ref">bitwise ORed</span></a> 到选项标志中，这样增加的选项标志被传递给 <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> 实例来运行doctest。 如果在构建 <code class="xref py py-class docutils literal notranslate"><span class="pre">DocTestCase</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> 的 <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> 报告标志会被忽略。</p>
|
||
<p><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> 报告标志的值在调用该函数之前是有效的，由该函数返回。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="advanced-api">
|
||
<span id="doctest-advanced-api"></span><h2>高级 API<a class="headerlink" href="#advanced-api" title="永久链接至标题">¶</a></h2>
|
||
<p>基本 API 是一个简单的封装，旨在使 doctest 易于使用。它相当灵活，应该能满足大多数用户的需求；但是，如果你需要对测试进行更精细的控制，或者希望扩展 doctest 的功能，那么你应该使用高级 API 。</p>
|
||
<p>高级API围绕着两个容器类，用于存储从 doctest 案例中提取的交互式用例:</p>
|
||
<ul class="simple">
|
||
<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>: 一个单一的 Python <a class="reference internal" href="../glossary.html#term-statement"><span class="xref std std-term">statement</span></a> ，与它的预期输出配对。</p></li>
|
||
<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 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 的集合，通常从一个文档字符串或文本文件中提取。</p></li>
|
||
</ul>
|
||
<p>定义了额外的处理类来寻找、解析和运行，并检查 doctest 的用例。</p>
|
||
<ul class="simple">
|
||
<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> : 查找给定模块中的所有文档串，并使用 <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> 从每个包含交互式用例的文档串中创建一个 <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></li>
|
||
<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> : 从一个字符串（如一个对象的文档串）创建一个 <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></li>
|
||
<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> : 执行 <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 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> 来验证其输出。</p></li>
|
||
<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> : 将一个测试用例的实际输出与预期输出进行比较，并决定它们是否匹配。</p></li>
|
||
</ul>
|
||
<p>这些处理类之间的关系总结在下图中:</p>
|
||
<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>
|
||
<span class="o">+------+</span> <span class="o">+---------+</span>
|
||
<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">-></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">-></span> <span class="n">results</span>
|
||
<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>
|
||
<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>
|
||
<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>
|
||
<span class="n">DocTestParser</span> <span class="o">|</span> <span class="n">Example</span> <span class="o">|</span> <span class="n">OutputChecker</span>
|
||
<span class="o">+---------+</span>
|
||
</pre></div>
|
||
</div>
|
||
<section id="doctest-objects">
|
||
<span id="doctest-doctest"></span><h3>DocTest 对象<a class="headerlink" href="#doctest-objects" title="永久链接至标题">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="doctest.DocTest">
|
||
<em class="property">class </em><code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">DocTest</code><span class="sig-paren">(</span><em class="sig-param">examples</em>, <em class="sig-param">globs</em>, <em class="sig-param">name</em>, <em class="sig-param">filename</em>, <em class="sig-param">lineno</em>, <em class="sig-param">docstring</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTest" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>应该在单一命名空间中运行的doctest用例的集合。构造函数参数被用来初始化相同名称的属性。</p>
|
||
<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> 定义了以下属性。 它们由构造函数初始化，不应该被直接修改。</p>
|
||
<dl class="attribute">
|
||
<dt id="doctest.DocTest.examples">
|
||
<code class="sig-name descname">examples</code><a class="headerlink" href="#doctest.DocTest.examples" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 对象的列表，它编码了应该由该测试运行的单个交互式 Python 用例。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.DocTest.globs">
|
||
<code class="sig-name descname">globs</code><a class="headerlink" href="#doctest.DocTest.globs" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>例子应该运行的命名空间（又称 globals ）。这是一个将名字映射到数值的字典。例子对名字空间的任何改变（比如绑定新的变量）将在测试运行后反映在 <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> 中。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.DocTest.name">
|
||
<code class="sig-name descname">name</code><a class="headerlink" href="#doctest.DocTest.name" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 的字符串名称。 通常情况下，这是从测试中提取的对象或文件的名称。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.DocTest.filename">
|
||
<code class="sig-name descname">filename</code><a class="headerlink" href="#doctest.DocTest.filename" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 被提取的文件名；或者为 <code class="docutils literal notranslate"><span class="pre">None</span></code>，如果文件名未知，或者 <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>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.DocTest.lineno">
|
||
<code class="sig-name descname">lineno</code><a class="headerlink" href="#doctest.DocTest.lineno" title="永久链接至目标">¶</a></dt>
|
||
<dd><p><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> 中的行号，这个 <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> 开始的地方，或者行号不可用时为 <code class="docutils literal notranslate"><span class="pre">None</span></code>。 这个行号相对于文件的开头来说是零的。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.DocTest.docstring">
|
||
<code class="sig-name descname">docstring</code><a class="headerlink" href="#doctest.DocTest.docstring" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>从测试中提取的字符串，或者如果字符串不可用，或者为 <code class="docutils literal notranslate"><span class="pre">None</span></code> ，如果测试没有从字符串中提取。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="example-objects">
|
||
<span id="doctest-example"></span><h3>Example 对象<a class="headerlink" href="#example-objects" title="永久链接至标题">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="doctest.Example">
|
||
<em class="property">class </em><code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">Example</code><span class="sig-paren">(</span><em class="sig-param">source</em>, <em class="sig-param">want</em>, <em class="sig-param">exc_msg=None</em>, <em class="sig-param">lineno=0</em>, <em class="sig-param">indent=0</em>, <em class="sig-param">options=None</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.Example" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>单个交互式用例，由一个 Python 语句及其预期输出组成。 构造函数参数被用来初始化相同名称的属性。</p>
|
||
<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> 定义了以下属性。 它们由构造函数初始化，不应该被直接修改。</p>
|
||
<dl class="attribute">
|
||
<dt id="doctest.Example.source">
|
||
<code class="sig-name descname">source</code><a class="headerlink" href="#doctest.Example.source" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个包含该用例源码的字符串。 源码由一个 Python 语句组成，并且总是以换行结束；构造函数在必要时添加一个换行。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.Example.want">
|
||
<code class="sig-name descname">want</code><a class="headerlink" href="#doctest.Example.want" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>运行这个用例的源码的预期输出（可以是 stdout ，也可以是异常情况下的回溯）。 <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> 以一个换行符结束，除非没有预期的输出，在这种情况下它是一个空字符串。 构造函数在必要时添加一个换行。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.Example.exc_msg">
|
||
<code class="sig-name descname">exc_msg</code><a class="headerlink" href="#doctest.Example.exc_msg" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用例产生的异常信息，如果这个例子被期望产生一个异常；或者为 <code class="docutils literal notranslate"><span class="pre">None</span></code> ，如果它不被期望产生一个异常。 这个异常信息与 <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> 以换行结束，除非是 <code class="docutils literal notranslate"><span class="pre">None</span></code> 。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.Example.lineno">
|
||
<code class="sig-name descname">lineno</code><a class="headerlink" href="#doctest.Example.lineno" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>包含本例的字符串中的行号，即本例的开始。 这个行号相对于包含字符串的开头来说是以零开始的。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.Example.indent">
|
||
<code class="sig-name descname">indent</code><a class="headerlink" href="#doctest.Example.indent" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用例在包含字符串中的缩进，即在用例的第一个提示前有多少个空格字符。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.Example.options">
|
||
<code class="sig-name descname">options</code><a class="headerlink" href="#doctest.Example.options" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个从选项标志到 <code class="docutils literal notranslate"><span class="pre">True</span></code> 或 <code class="docutils literal notranslate"><span class="pre">False</span></code> 的字典映射，用于覆盖这个例子的默认选项。 任何不包含在这个字典中的选项标志都被保留为默认值（由 <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> 的 <code class="xref py py-attr docutils literal notranslate"><span class="pre">optionflags</span></code> 指定）。默认情况下，没有选项被设置。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="doctestfinder-objects">
|
||
<span id="doctest-doctestfinder"></span><h3>DocTestFinder 对象<a class="headerlink" href="#doctestfinder-objects" title="永久链接至标题">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="doctest.DocTestFinder">
|
||
<em class="property">class </em><code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">DocTestFinder</code><span class="sig-paren">(</span><em class="sig-param">verbose=False</em>, <em class="sig-param">parser=DocTestParser()</em>, <em class="sig-param">recurse=True</em>, <em class="sig-param">exclude_empty=True</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestFinder" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个处理类，用于从一个给定的对象的 docstring 和其包含的对象的 docstring 中提取与之相关的 <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 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>
|
||
<p>可选的参数 <em>verbose</em> 可以用来显示查找器搜索到的对象。 它的默认值是 <code class="docutils literal notranslate"><span class="pre">False</span></code> （无输出）。</p>
|
||
<p>可选的参数 <em>parser</em> 指定了 <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> 对象（或一个可替换的对象），用于从文档串中提取 doctest 。</p>
|
||
<p>如果可选的参数 <em>recurse</em> 是 False ，那么 <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> 将只检查给定的对象，而不是任何包含的对象。</p>
|
||
<p>如果可选参数 <em>exclude_empty</em> 为 False ，那么 <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> 将包括对文档字符串为空的对象的测试。</p>
|
||
<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> 定义了以下方法：</p>
|
||
<dl class="method">
|
||
<dt id="doctest.DocTestFinder.find">
|
||
<code class="sig-name descname">find</code><span class="sig-paren">(</span><em class="sig-param">obj[, name][, module][, globs][, extraglobs]</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestFinder.find" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 的列表，该列表由 <em>obj</em> 的文档串或其包含的任何对象的文档串定义。</p>
|
||
<p>可选参数 <em>name</em> 指定了对象的名称；这个名称将被用来为返回的 <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> 构建名称。 如果没有指定 <em>name</em> ，则使用 <code class="docutils literal notranslate"><span class="pre">obj.__name__</span></code> 。</p>
|
||
<p>可选参数 <em>module</em> 是包含给定对象的模块。如果没有指定模块或者是 <code class="docutils literal notranslate"><span class="pre">None</span></code> ，那么测试查找器将试图自动确定正确的模块。 该对象被使用的模块：</p>
|
||
<ul class="simple">
|
||
<li><p>作为一个默认的命名空间，如果没有指定 <em>globs</em> 。</p></li>
|
||
<li><p>为了防止 DocTestFinder 从其他模块导入的对象中提取 DocTest 。 (包含有除 <em>module</em> 以外的模块的对象会被忽略)。</p></li>
|
||
<li><p>找到包含该对象的文件名。</p></li>
|
||
<li><p>找到该对象在其文件中的行号。</p></li>
|
||
</ul>
|
||
<p>如果 <em>module</em> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code> ，将不会试图找到这个模块。 这是不明确的，主要用于测试 doctest 本身：如果 <em>module</em> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code> ，或者是 <code class="docutils literal notranslate"><span class="pre">None</span></code> 但不能自动找到，那么所有对象都被认为属于（不存在的）模块，所以所有包含的对象将（递归地）被搜索到 doctest 。</p>
|
||
<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> 的 globals 是由 <em>globs</em> 和 <em>extraglobs</em> 组合而成的（ <em>extraglobs</em> 的绑定覆盖 <em>globs</em> 的绑定）。 为每个 <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> 创建一个新的 globals 字典的浅层拷贝。如果没有指定 <em>globs</em> ，那么它默认为模块的 <em>__dict__</em> ，如果指定了或者为 <code class="docutils literal notranslate"><span class="pre">{}</span></code> ，则除外。 如果没有指定 <em>extraglobs</em> ，那么它默认为 <code class="docutils literal notranslate"><span class="pre">{}</span></code> 。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="doctestparser-objects">
|
||
<span id="doctest-doctestparser"></span><h3>DocTestParser 对象<a class="headerlink" href="#doctestparser-objects" title="永久链接至标题">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="doctest.DocTestParser">
|
||
<em class="property">class </em><code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">DocTestParser</code><a class="headerlink" href="#doctest.DocTestParser" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 对象。</p>
|
||
<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> 定义了以下方法：</p>
|
||
<dl class="method">
|
||
<dt id="doctest.DocTestParser.get_doctest">
|
||
<code class="sig-name descname">get_doctest</code><span class="sig-paren">(</span><em class="sig-param">string</em>, <em class="sig-param">globs</em>, <em class="sig-param">name</em>, <em class="sig-param">filename</em>, <em class="sig-param">lineno</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestParser.get_doctest" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 对象中。</p>
|
||
<p><em>globs</em> 、 <em>name</em> 、 <em>filename</em> 和 <em>lineno</em> 是新的 <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 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>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="doctest.DocTestParser.get_examples">
|
||
<code class="sig-name descname">get_examples</code><span class="sig-paren">(</span><em class="sig-param">string</em>, <em class="sig-param">name='<string>'</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestParser.get_examples" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 对象列表的形式返回。 行数以 0 为基数。 可选参数 <em>name</em> 用于识别这个字符串的名称，只用于错误信息。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="doctest.DocTestParser.parse">
|
||
<code class="sig-name descname">parse</code><span class="sig-paren">(</span><em class="sig-param">string</em>, <em class="sig-param">name='<string>'</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestParser.parse" title="永久链接至目标">¶</a></dt>
|
||
<dd><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 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> 的行号以 0 为基数。 可选参数 <em>name</em> 用于识别这个字符串的名称，只用于错误信息。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="doctestrunner-objects">
|
||
<span id="doctest-doctestrunner"></span><h3>DocTestRunner 对象<a class="headerlink" href="#doctestrunner-objects" title="永久链接至标题">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="doctest.DocTestRunner">
|
||
<em class="property">class </em><code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">DocTestRunner</code><span class="sig-paren">(</span><em class="sig-param">checker=None</em>, <em class="sig-param">verbose=None</em>, <em class="sig-param">optionflags=0</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 中的交互式用例。</p>
|
||
<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> 完成的。 这种比较可以用一些选项标志来定制；更多信息请看 <a class="reference internal" href="#doctest-options"><span class="std std-ref">选项标记</span></a> 部分。 如果选项标志不够，那么也可以通过向构造函数传递 <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> 的子类来定制比较。</p>
|
||
<p>测试运行器的显示输出可以通过两种方式控制。首先，一个输出函数可以被传递给 <code class="xref py py-meth docutils literal notranslate"><span class="pre">TestRunner.run()</span></code> ；这个函数将被调用，并显示出应该显示的字符串。 它的默认值是 <code class="docutils literal notranslate"><span class="pre">sys.stdout.write</span></code> 。 如果捕获输出是不够的，那么也可以通过子类化 DocTestRunner 来定制显示输出，并重写 <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> , <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> 和 <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>
|
||
<p>可选的关键字参数 <em>checker</em> 指定了 <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> 对象（或其相似替换），它应该被用来比较预期输出和 doctest 用例的实际输出。</p>
|
||
<p>可选的关键字参数 <em>verbose</em> 控制 <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> 的详细程度。 如果 <em>verbose</em> 是 <code class="docutils literal notranslate"><span class="pre">True</span></code> ，那么每个用例的信息都会被打印出来，当它正在运行时。 如果 <em>verbose</em> 是 <code class="docutils literal notranslate"><span class="pre">False</span></code> ，则只打印失败的信息。 当 <em>verbose</em> 没有指定，或者为 <code class="docutils literal notranslate"><span class="pre">None</span></code> ，如果使用了命令行开关 <code class="docutils literal notranslate"><span class="pre">-v</span></code> ，则使用verbose输出。</p>
|
||
<p>可选的关键字参数 <em>optionflags</em> 可以用来控制测试运行器如何比较预期输出和实际输出，以及如何显示失败。更多信息，请参见章节 <a class="reference internal" href="#doctest-options"><span class="std std-ref">选项标记</span></a> 。</p>
|
||
<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> 定义了以下方法：</p>
|
||
<dl class="method">
|
||
<dt id="doctest.DocTestRunner.report_start">
|
||
<code class="sig-name descname">report_start</code><span class="sig-paren">(</span><em class="sig-param">out</em>, <em class="sig-param">test</em>, <em class="sig-param">example</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.report_start" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 的子类能够定制他们的输出；它不应该被直接调用。</p>
|
||
<p><em>example</em> 是即将被处理的用。 <em>test</em> 是 <em>包含用例</em> 的测试。 <em>out</em> 是传递给 <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>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="doctest.DocTestRunner.report_success">
|
||
<code class="sig-name descname">report_success</code><span class="sig-paren">(</span><em class="sig-param">out</em>, <em class="sig-param">test</em>, <em class="sig-param">example</em>, <em class="sig-param">got</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.report_success" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 的子类能够定制他们的输出；它不应该被直接调用。</p>
|
||
<p><em>example</em> 是即将被处理的用例。 <em>got</em> 是这个例子的实际输出。 <em>test</em> 是包含 <em>example</em> 的测试。 <em>out</em> 是传递给 <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>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="doctest.DocTestRunner.report_failure">
|
||
<code class="sig-name descname">report_failure</code><span class="sig-paren">(</span><em class="sig-param">out</em>, <em class="sig-param">test</em>, <em class="sig-param">example</em>, <em class="sig-param">got</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.report_failure" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 的子类能够定制他们的输出；它不应该被直接调用。</p>
|
||
<p><em>example</em> 是即将被处理的用例。 <em>got</em> 是这个例子的实际输出。 <em>test</em> 是包含 <em>example</em> 的测试。 <em>out</em> 是传递给 <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>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="doctest.DocTestRunner.report_unexpected_exception">
|
||
<code class="sig-name descname">report_unexpected_exception</code><span class="sig-paren">(</span><em class="sig-param">out</em>, <em class="sig-param">test</em>, <em class="sig-param">example</em>, <em class="sig-param">exc_info</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.report_unexpected_exception" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 的子类能够定制他们的输出；它不应该被直接调用。</p>
|
||
<p><em>example</em> 是将要被处理的用例。 <em>exc_info</em> 是一个元组，包含关于异常的信息（如由 <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> 是包含 <em>example</em> 的测试。 <em>out</em> 是传递给 <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>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="doctest.DocTestRunner.run">
|
||
<code class="sig-name descname">run</code><span class="sig-paren">(</span><em class="sig-param">test</em>, <em class="sig-param">compileflags=None</em>, <em class="sig-param">out=None</em>, <em class="sig-param">clear_globs=True</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.run" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在 <em>test</em> （一个 <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> 对象）中运行这些用例，并使用写入函数 <em>out</em> 显示结果。</p>
|
||
<p>这些用例都是在命名空间 <code class="docutils literal notranslate"><span class="pre">test.globs</span></code> 中运行的。 如果 <em>clear_globs</em> 为 True （默认），那么这个命名空间将在测试运行后被清除，以帮助进行垃圾回收。如果你想在测试完成后检查命名空间，那么使用 <em>clear_globs=False</em> 。</p>
|
||
<p><em>compileflags</em> 给出了 Python 编译器在运行例子时应该使用的标志集。如果没有指定，那么它将默认为适用于 <em>globs</em> 的 future-import 标志集。</p>
|
||
<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> 的输出检查器进行检查，结果由 <code class="xref py py-meth docutils literal notranslate"><span class="pre">DocTestRunner.report_*()</span></code> 方法进行格式化。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="doctest.DocTestRunner.summarize">
|
||
<code class="sig-name descname">summarize</code><span class="sig-paren">(</span><em class="sig-param">verbose=None</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestRunner.summarize" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>打印这个 DocTestRunner 运行过的所有测试用例的摘要，并返回一个 <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>
|
||
<p>可选的 <em>verbose</em> 参数控制摘要的详细程度。 如果没有指定 verbose ，那么将使用 <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> 的 verbose 。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="outputchecker-objects">
|
||
<span id="doctest-outputchecker"></span><h3>OutputChecker 对象<a class="headerlink" href="#outputchecker-objects" title="永久链接至标题">¶</a></h3>
|
||
<dl class="class">
|
||
<dt id="doctest.OutputChecker">
|
||
<em class="property">class </em><code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">OutputChecker</code><a class="headerlink" href="#doctest.OutputChecker" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 定义了两个方法： <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> ，比较给定的一对输出，如果它们匹配则返回 <code class="docutils literal notranslate"><span class="pre">True</span></code> ； <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> ，返回一个描述两个输出之间差异的字符串。</p>
|
||
<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> 定义了以下方法：</p>
|
||
<dl class="method">
|
||
<dt id="doctest.OutputChecker.check_output">
|
||
<code class="sig-name descname">check_output</code><span class="sig-paren">(</span><em class="sig-param">want</em>, <em class="sig-param">got</em>, <em class="sig-param">optionflags</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.OutputChecker.check_output" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>如果一个用例的实际输出（ <em>got</em> ）与预期输出（ <em>want</em> ）匹配，则返回 <code class="docutils literal notranslate"><span class="pre">True</span></code> 。 如果这些字符串是相同的，总是被认为是匹配的；但是根据测试运行器使用的选项标志，也可能有几种非精确的匹配类型。 参见章节 <a class="reference internal" href="#doctest-options"><span class="std std-ref">选项标记</span></a> 了解更多关于选项标志的信息。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="method">
|
||
<dt id="doctest.OutputChecker.output_difference">
|
||
<code class="sig-name descname">output_difference</code><span class="sig-paren">(</span><em class="sig-param">example</em>, <em class="sig-param">got</em>, <em class="sig-param">optionflags</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.OutputChecker.output_difference" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>返回一个字符串，描述给定用例（ <em>example</em> ）的预期输出和实际输出（ <em>got</em> ）之间的差异。 <em>optionflags</em> 是用于比较 <em>want</em> 和 <em>got</em> 的选项标志集。</p>
|
||
</dd></dl>
|
||
|
||
</dd></dl>
|
||
|
||
</section>
|
||
</section>
|
||
<section id="debugging">
|
||
<span id="doctest-debugging"></span><h2>调试<a class="headerlink" href="#debugging" title="永久链接至标题">¶</a></h2>
|
||
<p>Doctest 提供了几种调试 doctest 用例的机制：</p>
|
||
<ul>
|
||
<li><p>有几个函数将测试转换为可执行的 Python 程序，这些程序可以在 Python 调试器， <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>
|
||
<li><p><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> 类是 <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> 的一个子类，它为第一个失败的用例触发一个异常，包含关于这个用例的信息。这些信息可以用来对这个用例进行事后调试。</p></li>
|
||
<li><p>由 <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> 生成的 <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> 用例支持由 <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> 定义的 <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> 方法，。</p></li>
|
||
<li><p>你可以在 doctest 的用例中加入对 <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> 的调用，当这一行被执行时，你会进入 Python 调试器。 然后你可以检查变量的当前值，等等。 例如，假设 <code class="file docutils literal notranslate"><span class="pre">a.py</span></code> 只包含这个模块 docstring</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="sd">"""</span>
|
||
<span class="sd">>>> def f(x):</span>
|
||
<span class="sd">... g(x*2)</span>
|
||
<span class="sd">>>> def g(x):</span>
|
||
<span class="sd">... print(x+3)</span>
|
||
<span class="sd">... import pdb; pdb.set_trace()</span>
|
||
<span class="sd">>>> f(3)</span>
|
||
<span class="sd">9</span>
|
||
<span class="sd">"""</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>那么一个交互式Python会话可能是这样的:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">import</span> <span class="nn">a</span><span class="o">,</span> <span class="nn">doctest</span>
|
||
<span class="gp">>>> </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>
|
||
<span class="go">--Return--</span>
|
||
<span class="go">> <doctest a[1]>(3)g()->None</span>
|
||
<span class="go">-> import pdb; pdb.set_trace()</span>
|
||
<span class="go">(Pdb) list</span>
|
||
<span class="go"> 1 def g(x):</span>
|
||
<span class="go"> 2 print(x+3)</span>
|
||
<span class="go"> 3 -> import pdb; pdb.set_trace()</span>
|
||
<span class="go">[EOF]</span>
|
||
<span class="go">(Pdb) p x</span>
|
||
<span class="go">6</span>
|
||
<span class="go">(Pdb) step</span>
|
||
<span class="go">--Return--</span>
|
||
<span class="go">> <doctest a[0]>(2)f()->None</span>
|
||
<span class="go">-> g(x*2)</span>
|
||
<span class="go">(Pdb) list</span>
|
||
<span class="go"> 1 def f(x):</span>
|
||
<span class="go"> 2 -> g(x*2)</span>
|
||
<span class="go">[EOF]</span>
|
||
<span class="go">(Pdb) p x</span>
|
||
<span class="go">3</span>
|
||
<span class="go">(Pdb) step</span>
|
||
<span class="go">--Return--</span>
|
||
<span class="go">> <doctest a[2]>(1)?()->None</span>
|
||
<span class="go">-> f(3)</span>
|
||
<span class="go">(Pdb) cont</span>
|
||
<span class="go">(0, 3)</span>
|
||
<span class="gp">>>></span>
|
||
</pre></div>
|
||
</div>
|
||
</li>
|
||
</ul>
|
||
<p>将测试转换为 Python 代码的函数，并可能在调试器下运行合成的代码:</p>
|
||
<dl class="function">
|
||
<dt id="doctest.script_from_examples">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">script_from_examples</code><span class="sig-paren">(</span><em class="sig-param">s</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.script_from_examples" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将带有用例的文本转换为脚本。</p>
|
||
<p>参数 <em>s</em> 是一个包含测试用例的字符串。 该字符串被转换为 Python 脚本，其中 <em>s</em> 中的 doctest 用例被转换为常规代码，其他的都被转换为 Python 注释。 生成的脚本将以字符串的形式返回。例如，</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="kn">import</span> <span class="nn">doctest</span>
|
||
<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">"""</span>
|
||
<span class="s2"> Set x and y to 1 and 2.</span>
|
||
<span class="s2"> >>> x, y = 1, 2</span>
|
||
|
||
<span class="s2"> Print their sum:</span>
|
||
<span class="s2"> >>> print(x+y)</span>
|
||
<span class="s2"> 3</span>
|
||
<span class="s2">"""</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>显示:</p>
|
||
<div class="highlight-python3 notranslate"><div class="highlight"><pre><span></span><span class="c1"># Set x and y to 1 and 2.</span>
|
||
<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>
|
||
<span class="c1">#</span>
|
||
<span class="c1"># Print their sum:</span>
|
||
<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>
|
||
<span class="c1"># Expected:</span>
|
||
<span class="c1">## 3</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>这个函数在内部被其他函数使用（见下文），但当你想把一个交互式 Python 会话转化为 Python 脚本时，也会很有用。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="doctest.testsource">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">testsource</code><span class="sig-paren">(</span><em class="sig-param">module</em>, <em class="sig-param">name</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.testsource" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>将一个对象的 doctest 转换为一个脚本。</p>
|
||
<p>参数 <em>module</em> 是一个模块对象，或者一个模块带点的名称，包含对其 doctest 感兴趣的对象。 参数 <em>name</em> 是具有感兴趣的测试的对象的名称（在模块中）。 结果是一个字符串，包含该对象的文本串转换为 Python 脚本，如上面 <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> 所述。 例如，如果模块 <code class="file docutils literal notranslate"><span class="pre">a.py</span></code> 包含一个顶级函数 <code class="xref py py-func docutils literal notranslate"><span class="pre">f()</span></code> ，那么</p>
|
||
<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>
|
||
<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">"a.f"</span><span class="p">))</span>
|
||
</pre></div>
|
||
</div>
|
||
<p>打印函数 <code class="xref py py-func docutils literal notranslate"><span class="pre">f()</span></code> 的文档串的脚本版本，将测试转换为代码，其余部分放在注释中。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="doctest.debug">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">debug</code><span class="sig-paren">(</span><em class="sig-param">module</em>, <em class="sig-param">name</em>, <em class="sig-param">pm=False</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.debug" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>对一个对象的 doctest 进行调试。</p>
|
||
<p><em>module</em> 和 <em>name</em> 参数与上面函数 <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> 的参数相同。 被命名对象的文本串的合成 Python 脚本被写入一个临时文件，然后该文件在 Python 调试器 <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>
|
||
<p><code class="docutils literal notranslate"><span class="pre">module.__dict__</span></code> 的一个浅层拷贝被用于本地和全局的执行环境。</p>
|
||
<p>可选参数 <em>pm</em> 控制是否使用事后调试。 如果 <em>pm</em> 为 True ，则直接运行脚本文件，只有当脚本通过引发一个未处理的异常而终止时，调试器才会介入。如果是这样，就会通过 <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> 调用事后调试，并传递未处理异常的跟踪对象。如果没有指定 <em>pm</em> ，或者是 False ，脚本将从一开始就在调试器下运行，通过传递一个适当的 <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> 调用给 <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>
|
||
</dd></dl>
|
||
|
||
<dl class="function">
|
||
<dt id="doctest.debug_src">
|
||
<code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">debug_src</code><span class="sig-paren">(</span><em class="sig-param">src</em>, <em class="sig-param">pm=False</em>, <em class="sig-param">globs=None</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.debug_src" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>在一个字符串中调试 doctest 。</p>
|
||
<p>这就像上面的函数 <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> ，只是通过 <em>src</em> 参数，直接指定一个包含测试用例的字符串。</p>
|
||
<p>可选参数 <em>pm</em> 的含义与上述函数 <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> 的含义相同。</p>
|
||
<p>可选的参数 <em>globs</em> 给出了一个字典，作为本地和全局的执行环境。 如果没有指定，或者为 <code class="docutils literal notranslate"><span class="pre">None</span></code> ，则使用一个空的字典。如果指定，则使用字典的浅层拷贝。</p>
|
||
</dd></dl>
|
||
|
||
<p><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> 类，以及它可能触发的特殊异常，是测试框架作者最感兴趣的，在此仅作简要介绍。请看源代码，特别是 <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> 的文档串（这是一个测试！）以了解更多细节。</p>
|
||
<dl class="class">
|
||
<dt id="doctest.DebugRunner">
|
||
<em class="property">class </em><code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">DebugRunner</code><span class="sig-paren">(</span><em class="sig-param">checker=None</em>, <em class="sig-param">verbose=None</em>, <em class="sig-param">optionflags=0</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DebugRunner" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 的一个子类，一旦遇到失败，就会触发一个异常。 如果一个意外的异常发生，就会引发一个 <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> 异常，包含测试、用例和原始异常。 如果输出不匹配，那么就会引发一个 <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> 异常，包含测试、用例和实际输出。</p>
|
||
<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> 部分的文档 <a class="reference internal" href="#doctest-advanced-api"><span class="std std-ref">高级 API</span></a> 。</p>
|
||
</dd></dl>
|
||
|
||
<p><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> 实例可能会触发两种异常。</p>
|
||
<dl class="exception">
|
||
<dt id="doctest.DocTestFailure">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">DocTestFailure</code><span class="sig-paren">(</span><em class="sig-param">test</em>, <em class="sig-param">example</em>, <em class="sig-param">got</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.DocTestFailure" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 触发的异常，表示一个 doctest 用例的实际输出与预期输出不一致。构造函数参数被用来初始化相同名称的属性。</p>
|
||
</dd></dl>
|
||
|
||
<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> 定义了以下属性:</p>
|
||
<dl class="attribute">
|
||
<dt id="doctest.DocTestFailure.test">
|
||
<code class="sig-prename descclassname">DocTestFailure.</code><code class="sig-name descname">test</code><a class="headerlink" href="#doctest.DocTestFailure.test" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 对象。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.DocTestFailure.example">
|
||
<code class="sig-prename descclassname">DocTestFailure.</code><code class="sig-name descname">example</code><a class="headerlink" href="#doctest.DocTestFailure.example" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.DocTestFailure.got">
|
||
<code class="sig-prename descclassname">DocTestFailure.</code><code class="sig-name descname">got</code><a class="headerlink" href="#doctest.DocTestFailure.got" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>用例的实际输出。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="exception">
|
||
<dt id="doctest.UnexpectedException">
|
||
<em class="property">exception </em><code class="sig-prename descclassname">doctest.</code><code class="sig-name descname">UnexpectedException</code><span class="sig-paren">(</span><em class="sig-param">test</em>, <em class="sig-param">example</em>, <em class="sig-param">exc_info</em><span class="sig-paren">)</span><a class="headerlink" href="#doctest.UnexpectedException" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 触发的异常，以提示一个 doctest 用例引发了一个意外的异常。 构造函数参数被用来初始化相同名称的属性。</p>
|
||
</dd></dl>
|
||
|
||
<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> 定义了以下属性:</p>
|
||
<dl class="attribute">
|
||
<dt id="doctest.UnexpectedException.test">
|
||
<code class="sig-prename descclassname">UnexpectedException.</code><code class="sig-name descname">test</code><a class="headerlink" href="#doctest.UnexpectedException.test" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 对象。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.UnexpectedException.example">
|
||
<code class="sig-prename descclassname">UnexpectedException.</code><code class="sig-name descname">example</code><a class="headerlink" href="#doctest.UnexpectedException.example" title="永久链接至目标">¶</a></dt>
|
||
<dd><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> 。</p>
|
||
</dd></dl>
|
||
|
||
<dl class="attribute">
|
||
<dt id="doctest.UnexpectedException.exc_info">
|
||
<code class="sig-prename descclassname">UnexpectedException.</code><code class="sig-name descname">exc_info</code><a class="headerlink" href="#doctest.UnexpectedException.exc_info" title="永久链接至目标">¶</a></dt>
|
||
<dd><p>一个包含意外异常信息的元组，由 <code class="xref py py-func docutils literal notranslate"><span class="pre">sys.ex_info()</span></code> 返回。</p>
|
||
</dd></dl>
|
||
|
||
</section>
|
||
<section id="soapbox">
|
||
<span id="doctest-soapbox"></span><h2>肥皂盒<a class="headerlink" href="#soapbox" title="永久链接至标题">¶</a></h2>
|
||
<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> 已经发展到有三个主要用途:</p>
|
||
<ol class="arabic simple">
|
||
<li><p>检查 docstring 中的用例。</p></li>
|
||
<li><p>回归测试。</p></li>
|
||
<li><p>可执行的文档/文字测试。</p></li>
|
||
</ol>
|
||
<p>这些用途有不同的要求，区分它们是很重要的。特别是，用晦涩难懂的测试用例来填充你的文档字符串会使文档变得很糟糕。</p>
|
||
<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> 用例在一个“无害”的变化后停止工作。</p>
|
||
<p>Doctest 也是回归测试的一个很好的工具，特别是如果你不吝啬解释的文字。 通过交错的文本和用例，可以更容易地跟踪真正的测试，以及为什么。当测试失败时，好的文本可以使你更容易弄清问题所在，以及如何解决。 的确，你可以在基于代码的测试中写大量的注释，但很少有程序员这样做。许多人发现，使用 doctest 方法反而能使测试更加清晰。 也许这只是因为 doctest 使写散文比写代码容易一些，而在代码中写注释则有点困难。 我认为它比这更深入：当写一个基于 doctest 的测试时，自然的态度是你想解释你的软件的细微之处，并用例子来说明它们。这反过来又自然地导致了测试文件从最简单的功能开始，然后逻辑地发展到复杂和边缘案例。 一个连贯的叙述是结果，而不是一个孤立的函数集合，似乎是随机的测试孤立的功能位。 这是一种不同的态度，产生不同的结果，模糊了测试和解释之间的区别。</p>
|
||
<p>回归测试最好限制在专用对象或文件中。 有几种组织测试的选择：</p>
|
||
<ul class="simple">
|
||
<li><p>编写包含测试案例的文本文件作为交互式例子，并使用 <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> 或 <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> 来测试这些文件。 建议这样做，尽管对于新的项目来说是最容易做到的，从一开始就设计成使用 doctest 。</p></li>
|
||
<li><p>定义命名为 <code class="docutils literal notranslate"><span class="pre">_regrtest_topic</span></code> 的函数，由单个文档串组成，包含命名主题的测试用例。 这些函数可以包含在与模块相同的文件中，或分离出来成为一个单独的测试文件。</p></li>
|
||
<li><p>定义一个从回归测试主题到包含测试用例的文档串的 <code class="docutils literal notranslate"><span class="pre">__test__</span></code> 字典映射。</p></li>
|
||
</ul>
|
||
<p>当你把你的测试放在一个模块中时，这个模块本身就可以成为测试运行器。 当一个测试失败时，你可以安排你的测试运行器只重新运行失败的测试，同时调试问题。 下面是这样一个测试运行器的最小例子:</p>
|
||
<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">'__main__'</span><span class="p">:</span>
|
||
<span class="kn">import</span> <span class="nn">doctest</span>
|
||
<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>
|
||
<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">></span> <span class="mi">1</span><span class="p">:</span>
|
||
<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>
|
||
<span class="k">if</span> <span class="n">name</span> <span class="ow">in</span> <span class="nb">globals</span><span class="p">():</span>
|
||
<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>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<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>
|
||
<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>
|
||
<span class="n">optionflags</span><span class="o">=</span><span class="n">flags</span><span class="p">)</span>
|
||
<span class="k">else</span><span class="p">:</span>
|
||
<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>
|
||
<span class="nb">print</span><span class="p">(</span><span class="s2">"</span><span class="si">{}</span><span class="s2"> failures out of </span><span class="si">{}</span><span class="s2"> tests"</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>
|
||
</pre></div>
|
||
</div>
|
||
<p class="rubric">备注</p>
|
||
<dl class="footnote brackets">
|
||
<dt class="label" id="id2"><span class="brackets"><a class="fn-backref" href="#id1">1</a></span></dt>
|
||
<dd><p>不支持同时包含预期输出和异常的用例。试图猜测一个在哪里结束，另一个在哪里开始，太容易出错了，而且这也会使测试变得混乱。</p>
|
||
</dd>
|
||
</dl>
|
||
</section>
|
||
</section>
|
||
|
||
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
|
||
<div class="sphinxsidebarwrapper">
|
||
<h3><a href="../contents.html">目录</a></h3>
|
||
<ul>
|
||
<li><a class="reference internal" href="#"><code class="xref py py-mod docutils literal notranslate"><span class="pre">doctest</span></code> --- 测试交互式的 Python 示例</a><ul>
|
||
<li><a class="reference internal" href="#simple-usage-checking-examples-in-docstrings">简单用法：检查Docstrings中的示例</a></li>
|
||
<li><a class="reference internal" href="#simple-usage-checking-examples-in-a-text-file">简单的用法：检查文本文件中的例子</a></li>
|
||
<li><a class="reference internal" href="#how-it-works">它是如何工作的</a><ul>
|
||
<li><a class="reference internal" href="#which-docstrings-are-examined">哪些文件串被检查了？</a></li>
|
||
<li><a class="reference internal" href="#how-are-docstring-examples-recognized">文档串的例子是如何被识别的？</a></li>
|
||
<li><a class="reference internal" href="#what-s-the-execution-context">什么是执行上下文？</a></li>
|
||
<li><a class="reference internal" href="#what-about-exceptions">异常如何处理？</a></li>
|
||
<li><a class="reference internal" href="#option-flags">选项标记</a></li>
|
||
<li><a class="reference internal" href="#directives">指令</a></li>
|
||
<li><a class="reference internal" href="#warnings">警告</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#basic-api">基本API</a></li>
|
||
<li><a class="reference internal" href="#unittest-api">Unittest API</a></li>
|
||
<li><a class="reference internal" href="#advanced-api">高级 API</a><ul>
|
||
<li><a class="reference internal" href="#doctest-objects">DocTest 对象</a></li>
|
||
<li><a class="reference internal" href="#example-objects">Example 对象</a></li>
|
||
<li><a class="reference internal" href="#doctestfinder-objects">DocTestFinder 对象</a></li>
|
||
<li><a class="reference internal" href="#doctestparser-objects">DocTestParser 对象</a></li>
|
||
<li><a class="reference internal" href="#doctestrunner-objects">DocTestRunner 对象</a></li>
|
||
<li><a class="reference internal" href="#outputchecker-objects">OutputChecker 对象</a></li>
|
||
</ul>
|
||
</li>
|
||
<li><a class="reference internal" href="#debugging">调试</a></li>
|
||
<li><a class="reference internal" href="#soapbox">肥皂盒</a></li>
|
||
</ul>
|
||
</li>
|
||
</ul>
|
||
|
||
<h4>上一个主题</h4>
|
||
<p class="topless"><a href="pydoc.html"
|
||
title="上一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">pydoc</span></code> --- 文档生成器和在线帮助系统</a></p>
|
||
<h4>下一个主题</h4>
|
||
<p class="topless"><a href="unittest.html"
|
||
title="下一章"><code class="xref py py-mod docutils literal notranslate"><span class="pre">unittest</span></code> --- 单元测试框架</a></p>
|
||
<div role="note" aria-label="source link">
|
||
<h3>本页</h3>
|
||
<ul class="this-page-menu">
|
||
<li><a href="../bugs.html">报告 Bug</a></li>
|
||
<li>
|
||
<a href="https://github.com/python/cpython/blob/3.8/Doc/library/doctest.rst"
|
||
rel="nofollow">显示源代码
|
||
</a>
|
||
</li>
|
||
</ul>
|
||
</div>
|
||
</div>
|
||
</div>
|
||
<div class="clearer"></div>
|
||
</div>
|
||
<div class="related" role="navigation" aria-label="related navigation">
|
||
<h3>导航</h3>
|
||
<ul>
|
||
<li class="right" style="margin-right: 10px">
|
||
<a href="../genindex.html" title="总目录"
|
||
>索引</a></li>
|
||
<li class="right" >
|
||
<a href="../py-modindex.html" title="Python 模块索引"
|
||
>模块</a> |</li>
|
||
<li class="right" >
|
||
<a href="unittest.html" title="unittest --- 单元测试框架"
|
||
>下一页</a> |</li>
|
||
<li class="right" >
|
||
<a href="pydoc.html" title="pydoc --- 文档生成器和在线帮助系统"
|
||
>上一页</a> |</li>
|
||
|
||
<li><img src="../_static/py.svg" alt="python logo" style="vertical-align: middle; margin-top: -1px"/></li>
|
||
<li><a href="https://www.python.org/">Python</a> »</li>
|
||
<li class="switchers">
|
||
<div class="language_switcher_placeholder"></div>
|
||
<div class="version_switcher_placeholder"></div>
|
||
</li>
|
||
<li>
|
||
|
||
</li>
|
||
<li id="cpython-language-and-version">
|
||
<a href="../index.html">3.8.20 Documentation</a> »
|
||
</li>
|
||
|
||
<li class="nav-item nav-item-1"><a href="index.html" >Python 标准库</a> »</li>
|
||
<li class="nav-item nav-item-2"><a href="development.html" >开发工具</a> »</li>
|
||
<li class="right">
|
||
|
||
|
||
<div class="inline-search" role="search">
|
||
<form class="inline-search" action="../search.html" method="get">
|
||
<input placeholder="快速搜索" aria-label="快速搜索" type="text" name="q" />
|
||
<input type="submit" value="转向" />
|
||
<input type="hidden" name="check_keywords" value="yes" />
|
||
<input type="hidden" name="area" value="default" />
|
||
</form>
|
||
</div>
|
||
|
|
||
</li>
|
||
|
||
</ul>
|
||
</div>
|
||
<div class="footer">
|
||
© <a href="../copyright.html">版权所有</a> 2001-2024, Python Software Foundation.
|
||
<br />
|
||
This page is licensed under the Python Software Foundation License Version 2.
|
||
<br />
|
||
Examples, recipes, and other code in the documentation are additionally licensed under the Zero Clause BSD License.
|
||
<br />
|
||
|
||
<br />
|
||
|
||
The Python Software Foundation is a non-profit corporation.
|
||
<a href="https://www.python.org/psf/donations/">Please donate.</a>
|
||
<br />
|
||
<br />
|
||
|
||
最后更新于 12月 09, 2024.
|
||
<a href="https://docs.python.org/3/bugs.html">Found a bug</a>?
|
||
<br />
|
||
|
||
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 2.4.4.
|
||
</div>
|
||
|
||
</body>
|
||
</html> |