yalpt 1.0.0

什么是文献编程？

文献编程这个术语由Donald Knuth（参见[Wikipedia][1]）提出，用来描述一种编程风格，其中文档和关于代码的信息使用常规语言编写，通常使用某种标记语言，然后与实际代码交织在一起。生成的文件应能够编译成普通程序。在Python的情况下，这意味着应该有办法像普通Python程序一样运行它们。

什么是YALPT？

YALPT是一个用于运行正确格式化的文献Python文件的工具。一个YALPT兼容的文件由常规文本和交互式Python会话组成。这些会话应该可以通过doctest检测（实际上，如果您想的话，可以通过doctest运行YALPT文件）。除此之外，格式由您自己决定。YALPT附带一个格式化器，它将Markdown格式的文本转换为使用ANSI转义码显示的文本，以便使加粗文本显示为加粗等。但是，这并不是必需的。

由于 YALPT 基于 Python 标准库中的 doctest 和 code 模块，其行为与您已知的工具非常相似。事实上，YALPT 将检查每段代码的结果，如果与您在文件中编写的内容不同，则会向您发出警告。

为什么选择 YALPT？

此时，您可能想知道为什么应该使用 YALPT 而不是其他一些有文档的 Python 工具，比如 [IPython 笔记本](https://ipython.pythonlang.cn/notebook.html) 或 [python-literate](https://github.com/stdbrouw/python-literate)。

与 python-literate 等工具相比，YALPT 的不同之处在于它设计用于在交互会话中直接运行代码，而不是之后运行代码并生成输出。

与 IPython 笔记本相比，YALPT 的格式非常宽松。IPython 笔记本以 JSON 格式存储，这对于人类来说不太容易快速阅读或写入。YALPT 的一个目标是使文件成为独立的文件，并且在没有 YALPT 的情况下也非常有用。这意味着它们应该能够被人类阅读和编写。此外，还很容易编写既符合 YALPT 又符合您选择的标记语言的 YALPT 文件。例如，Markdown 风格的 YALPT 文件可以被传递到 Markdown 解析器，这样您也可以在不依赖于 YALPT 知道如何读取和输出您选择的标记和输出格式的情况下生成静态页面。

如何运行 YALPT？

YALPT 的基本调用方式如下

$ run-lit.py my-file.txt

如果您的文件是 Markdown 格式，可以使用 Markdown 格式化工具

$ run-lit.py -f markdown my-file.md

默认情况下，YALPT 在每个代码块后都会进入交互会话，这样您可以在继续之前实验该块的结果。要继续，只需在交互会话中输入两个空白行（按两次 Enter）。如果您希望禁用此功能，并且只想在最后显示交互会话，可以传递 –no-interactive 标志

$ run-lit.py my-file.txt –no-interactive

这将简单地在每个代码块后暂停。您可以按 Enter 继续操作。如果您甚至不想暂停，可以使用 –no-pause 标志运行 YALPT

$ run-lit.py my-file.txt –no-pause

默认情况下，YALPT 将启用 readline 支持以实现自动完成和历史记录。自动完成通过 Control-space 触发，历史记录存储在您的家目录中，文件名为 .literate-python-history。您可以使用 –no-readline 标志禁用此功能

$ run-lit.py my-file.txt –no-readline

最后，默认情况下 YALPT 将使用 ANSI 转义代码为代码着色并格式化错误消息。您可以使用 –no-ansi 标志禁用此功能

$ run-lit.py my-file.txt –no-ansi

这就全部了！

我没有阅读上面的描述，我该如何编写 YALPT 文件？

任何看起来像 doctest 兼容的交互式 Python 会话，并且穿插在其他文本“内容”之间的文件都是 YALPT 兼容的文件。只要 doctest 能够找到代码块，YALPT 也能够找到，因为 YALPT 是利用 doctest 的。您还可以自由地使用您选择的标记语言来编写文本部分，甚至可以不使用任何标记。

然而，如上所述，YALPT 确实知道如何格式化一些 Markdown，但使用 Markdown 并非必要。如果您想为其他语言编写格式化程序，可以使用 Markdown 格式化程序作为指南，并在 [GitHub](https://github.com/directxman12/yalpt) 上提交拉取请求。

我可以在没有 doctest 代码块的文件上使用它吗？

现在，YALPT 从技术上讲支持在 Markdown 代码块中运行任何代码。任何缩进的代码块，以及未指定类型的围栏代码块和标记为 Python 的围栏代码块都将被解释为 Python 代码块并执行。

然而，这个功能并没有像doctest解析器那样经过广泛的测试，也不像doctest格式那样“自我说明”，因为它不包含每行输出的内容。

如果您希望使用不同的解析器，可以通过调用YALPT的-p标志来实现。

$ run-lit.py -p markdown my-file.md

我的YALPT文件需要很多设置，这会分散主要内容的注意力！

虽然通常最好将基本设置作为文献Python文件的一部分提供，但当需要太多的样板代码时，这可能会变得繁琐且分散注意力。在这种情况下，可以指定“环境驱动程序”。环境驱动程序执行一些设置和拆除操作，并且还可以提供文献Python文件可以使用的对象。

要使用环境驱动程序运行YALPT，请使用-e标志。

$ run-lit.py -e gssapi basic-tutorial.md

一个提供环境驱动程序的包示例是[GSSAPI控制台](https://pypi.python.org/pypi/gssapi_console)。此环境驱动程序为涉及GSSAPI的文献Python文件设置了一个自包含的MIT Krb5环境。

重用/扩展YALPT

YALPT的核心功能存在于类yalpt.core.LiterateInterpreter中。可以通过继承此类来修改功能。

它的工作方式与标准库中的code.InteractiveConsole非常相似，它从其中继承。

自定义格式化程序应实现一个格式化方法，该方法接受一个字符串并返回一个格式化后的字符串。

此外，YALPT现在有多个setuptools入口点用于扩展。

• yalpt.formatters可用于引入自定义格式化程序以格式化文件的代码部分。有关更多信息，请参阅yalpt.formatters。

• yalpt.parsers可用于引入自定义解析器以将代码与非代码分离。有关更多信息，请参阅yalpt.parsers。

• yalpt.env_drivers可用于引入环境驱动程序以提供文献Python文件的样板设置。环境驱动程序类应实现一个setup()方法（该方法返回一个包含在环境中的局部变量字典），一个teardown()方法，并具有DRIVER_NAME和banner属性/字段。

[1]: http://en.wikipedia.org/wiki/Literate_programming