《学习 Python》第 5 版

第 15 章 文献插曲

本作品已使用人工智能进行翻译。欢迎您提供反馈和意见：[e-mail]

本书的这一部分最后介绍了用于记录 Python 代码的技术和工具。尽管 Python 代码被设计为可读的，但一些位置恰当、易于理解的注释也能帮助他人理解程序的工作原理。正如我们将看到的，Python 包含了语法和工具来简化文档。特别是这里介绍的PyDoc系统，它可以在 shell 中将模块的内部文档显示为纯文本，或者在 web 浏览器中显示为 HTML。

虽然这是一个与工具相关的概念，但在这里介绍这个主题的部分原因是它涉及 Python 的语法模型，部分原因是作为读者在理解 Python 工具集时的参考资料。出于后一个目的，我还将在这里扩展第 4 章中首次给出的文档指针。与往常一样，由于本章是本部分的结尾，因此除了本章小测验之外，本章还附有一些关于常见陷阱的警告和本部分的练习。

Python 文档资源

在这本书中，您可能已经开始意识到 Python 提供了大量的预置功能--内置函数和异常、预定义对象属性和方法、标准库模块，等等。而我们只是触及了这些类别的表面。

困惑的初学者经常问的第一个问题是：我如何找到所有内置工具的信息？本节提供了 Python 中可用的各种文档来源的提示。它还介绍了文档字符串(docstrings) 和使用它们的PyDoc系统。这些主题对于核心语言本身来说有些无关紧要，但当您的代码达到本书这一部分的示例和练习的水平时，它们就会成为必不可少的知识。

如表 15-1 所示，有各种各样的地方可以查找有关 Python 的信息，这些地方的信息量一般都在增加。由于文档是实际编程中的重要工具，我们将在下面的章节中逐一探讨。

表 15-1. Python 文档来源

形式	角色
# 评论	文件内 文档
dir 功能	对象中可用的属性列表
文件串：__doc__	文件内 附加到对象上的文件
PyDoc：help 函数	交互式对象帮助
PyDoc：HTML 报告	模块浏览器文档
斯芬克斯第三方工具	为大型项目提供更丰富的文档
标准手册集	官方语言和图书馆说明
网络资源	在线教程、示例等
出版书籍	经过商业打磨的参考文献

# 评论

我们已经了解到， 哈希标记注释是记录代码的最基本方法。Python 会简单地忽略# 后面的所有文本（只要它不在字符串字面量之内），因此您可以在这个字符后面加上任何对程序员有意义的词语和描述。不过这些注释只能在源文件中访问；要编写更广泛的注释，您需要使用 docstrings。

事实上，目前的最佳实践通常规定，文档说明最好用于较大的功能文档（例如，"我的文件是这样做的"），而# 注释最好限于较小的代码文档（例如，"这个奇怪的表达式是这样做的"），并且最好限于脚本或函数中的一条语句或一小组语句。稍后将详细介绍 docstrings；首先，让我们来看看如何探索对象。

dir 功能

正如我们已经看到的，内置的dir 函数是获取对象内部所有可用属性（即对象的方法和更简单的数据项）列表的简便方法。调用该函数时可以不带参数，以列出调用者作用域中的变量。更有用的是，它还可以在任何有属性的对象上调用，包括导入模块和内置类型，以及数据类型的名称。例如，要查找标准库sys 中的可用模块，可以导入该模块并将其传递给dir ：

>>> import sys
>>> dir(sys)
['__displayhook__', ...more names omitted..., 'winver']

这些结果来自 Python 3.3，我省略了大部分返回的名称，因为它们在其他地方略有不同；请自行运行以获得更好的效果。事实上，目前 ...