构建并测试Python示例
exemplar的Python项目详细描述
模范的
一个用于测试文档中Python示例的微型库。在
安装
要安装示例，请使用pip：
pip install exemplary示例性要求Python3.6或更高版本。在
注意：在您的项目中，您可能希望安装示例作为 “开发”依赖关系。它是更新和测试文档的工具。在
示范解决了什么问题？在
示例解决了两个主要问题：
- 它确保文档中的示例能够实际工作。在
- 它呈现示例的输出，以便您的文档显示 你的用户将会看到什么。在
你如何使用模范？在
TLDR:
exemplary.run(pathnames)——运行 降价文件。在exemplary.run(pathnames, render=True)——运行所有Python 示例，还呈现以>>>开头的任何示例的输出。在
（提示：使用glob('**/*.md', recursive=True)在所有
项目中的标记文件。）
或者，要从命令行运行示例：
^{pr2}$用于测试：
在标记文件中放入一些Python部分。在
然后，在你的测试中：
fromglobimportglobimportexemplarydeftest_docs():# Run all the examples in your markdown files:pathnames=glob('**/*.md',recursive=True)exemplary.run(pathnames)
如果您的任何示例失败，则会引发异常。在
用于渲染：
在这种情况下，“呈现”的意思是“举个例子，展示它的样子 就像在Python的交互式解释器中运行它一样。”
假设你有这样的降价：
# How to use deque ```python >>> from collections import deque >>> d = deque([1, 2, 3]) >>> d.popleft() >>> d.pop() ```
在构建脚本中，使用render=True运行示例：
fromglobimportglobimportexemplarydefrender_docs():# Render all the examples in your markdown files:pathnames=glob('**/*.md',recursive=True)exemplary.run(pathnames,render=True)
或从shell脚本运行：
^{pr2}$之后，示例将如下所示：
# How to use deque ```python >>> from collections import deque >>> d = deque([1, 2, 3]) >>> d.popleft() 1 >>> d.pop() 3 ```
当示例性看到以>>>开头的示例时，它将在中运行该示例
Python的itereactive解释器，并将解释器的输出添加到
文档。在
（示例性地在解释器的输出之后添加一个额外的换行符，以改进 可读性。）
如果再次运行examplial，它将再次呈现示例，忽略任何 可能已经出现在示例中的输出。这可以让你成为模范 多次编辑文档。在
注意：因为示例性修改了您的文件，所以请确保它们是 在你渲染它们之前。在
（或者，作为构建的一部分，将标记文件复制到生成目录，然后 然后在副本上运行示例。）
如果在一个降价文件中有多个示例呢？在
示例性在同一个解释器中运行同一文件中的每个示例。 这允许您将示例与文本部分分开。在
例如，如果您有：
# My example ```python x = "hello" ``` Now use x: ```python >>> print(x) ```
当您呈现此示例时，examplial将在末尾添加hello。重点
第二个python节可以看到x，这是在第一个定义的
第节。在
如果需要一个示例在它自己的命名空间中重新开始，可以将一个特殊的 示例前一行的HTML注释：
<!-- fresh example -->
```python
# Exmplary will run this example in a fresh environment.
import foo
foo.bar('baz')
```
当examplial看到“fresh example”注释时，它实际上会重新启动 它用来测试和呈现示例的解释器。在
如何为我的示例隐藏一些测试？在
示例性查找代码部分，甚至在HTML注释中。这让你可以写作 为你的例子做额外的测试（以确保它们真的起作用），没有 把你的文件弄乱了。在
例如：
# Some Example Setup: ```python import something foo = do_something() ``` <!-- ```python assert foo.some_property assert some_other_predicate(foo) ``` -->
examplial将同时运行两个Python部分——注释前面的部分和 一个在评论里。在
这样您可以：
- 彻底测试你的例子。在
- 将示例和测试放在同一个文件中。在
- 隐藏测试，这样它们就不会影响文档。在
极端地说，您可以将所有单元测试视为 文档，并以这种方式组织它们。在
如果我不想示范性地测试一个例子呢？在
将HTML注释<!-- skip example -->放在li上每个上方的ne
你想要示范性忽略的例子。在
# My bad example Exemplary will never know... <!-- skip example --> ```python >>> assert False ```
示例不会尝试测试或呈现此示例，因为它由
<!-- skip example -->注释。在
- 项目
标签：
欢迎加入QQ群-->： 979659372
