风格指南

本页介绍了我们文档的语言风格指南。有关 reST 文件中的标记详细信息，请参阅 reStructuredText 标记。

脚注

通常不建议使用脚注，但当它们是呈现特定信息的最优方式时，可以使用脚注。当在句末添加脚注引用时，它应遵循句末标点符号。reST 标记应类似于以下内容

This sentence has a footnote reference. [#]_ This is the next sentence.

脚注应收集在文件末尾，或者如果文件很长，则收集在节末。docutils 将自动创建指向脚注引用的反向链接。

脚注可以适当地出现在句子的中间。

大写

在 Python 文档中，首选在章节标题中使用句子大小写，但一个单元内的连贯性比遵循此规则更重要。如果您向大多数章节都使用标题大小写的章节添加一个章节，则可以将所有标题转换为句子大小写，或在新章节标题中使用主要样式。

应避免使用以特定规则要求小写字母开头的单词开头的句子。

注意

描述库模块的章节通常具有“模块名称——模块的简短描述”形式的标题。在这种情况下，描述应大写为独立句子。

Python 文档中使用了许多特殊名称，包括操作系统、编程语言、标准机构等名称。大多数这些实体未分配任何特殊标记，但此处给出了首选拼写，以帮助作者保持 Python 文档中呈现的一致性。

其他术语和单词也值得特别提及；应使用这些约定以确保整个文档的一致性

C API

Python 的 API 由 C 程序员用于编写扩展模块。全部大写且不连字符。

CPU

中央处理器。无需拼写出来。

POSIX

分配给特定标准组的名称。这始终是大写。

Python

我们最喜欢的编程语言的名称始终大写。

reST

对于“reStructuredText”，一种易于阅读的纯文本标记语法，用于生成 Python 文档。拼写出来时，它始终是一个单词，并且两种形式都以小写“r”开头。

Unicode

字符编码系统的名称。这始终大写。

Unix

20 世纪 70 年代初 AT&T 贝尔实验室开发的操作系统的名称。

Diátaxis

Python 的文档力求遵循 Diátaxis 框架。这意味着根据正在编写的文档的性质调整写作风格。该框架将文档分为四种不同的类型：教程、操作指南、参考和说明。

  • Python 教程 应明确无误，避免对读者的知识做出假设。教程的目标是让用户尽可能快地使用清晰的逻辑步骤编写 Python 代码。应避免解释和抽象概念。请查阅 Diátaxis 指南，了解 教程 的更多详细信息。

  • Python 操作指南 旨在指导用户解决问题领域。教程和操作指南都是指导性的，而不是解释性的，并且应提供如何完成任务的逻辑步骤。但是，操作指南对用户的知识做出了更多假设，并专注于用户找到解决其自身特定问题的最佳方法。

  • Python 语言参考 应真实且简洁。参考文档的目的是描述而不是解释。准确性和一致性是关键，因为这种类型的文档应被视为权威来源。 代码示例 可能是实现这些目标的有用方法。

  • Python 说明提供了更深层次的理解，并且自然更具讨论性。它们旨在加深读者的理解并回答“为什么”的问题。它们应提供上下文，在主题之间建立联系并讨论替代观点。没有专门用于说明的章节，但可以在整个 Python 文档中找到它们，例如 Unicode 操作指南。

请查阅 Diátaxis 指南，了解更多详细信息。

肯定语调

文档重点肯定地说明语言的作用以及如何有效地使用它。

除了某些安全或段错误风险外，文档应避免使用“功能 x 很危险”或“仅限专家”之类的措辞。这些类型的价值判断属于外部博客和 wiki，不属于核心文档。

不好的示例（在读者心中制造担忧）

警告：未能显式关闭文件可能会导致数据丢失或过度消耗资源。切勿依赖引用计数来自动关闭文件。

好的示例（建立对语言有效使用的信心）

使用文件的最佳实践是在使用文件后使用 try/finally 对来显式关闭文件。或者，使用 with 语句可以达到相同的效果。这确保文件被刷新，并且文件描述符资源被及时释放。

表达经济

更多的文档不一定就是更好的文档。尽量简洁。

不幸的是，使文档更长可能会阻碍理解，并可能导致更多错误解读或误解文本的方法。充满极端情况和注意事项的冗长描述会给人一种印象，即函数比实际情况更复杂或更难使用。

安全注意事项（和其他注意事项）

Python 提供的某些模块本质上会暴露于安全问题（例如，由于模块的用途而导致的 shell 注入漏洞（例如，ssl）。在这些模块的文档中散布红色警告框，指出由于手头任务而不是 Python 对该任务的支持而导致的问题，并不能带来良好的阅读体验。

相反，这些安全问题应汇总到模块文档中的专门的“安全注意事项”部分，并从受影响接口的文档中交叉引用，并附上类似于 "请 参阅 :security-considerations` 部分 以 获取 有关 如何 避免 常见 错误 的重要 信息 。" 的注释。

类似地，如果模块中的许多接口都存在一个常见错误（例如，OS 级管道缓冲区已满并导致子进程停滞），则可以将这些错误记录在“常见错误”部分中并进行交叉引用，而不是针对每个受影响的接口重复这些错误。

代码示例

简短的代码示例有助于理解。读者通常可以比理解散文形式的正式描述更快地掌握一个简单的示例。

人们通过与典型用例的背景相匹配的具体、激励性的示例学习得更快。例如，str.rpartition()方法最好通过一个从 URL 中拆分域名的示例来演示，而不是通过一个从一行 Monty Python 对话中删除最后一个单词的示例来演示。

用于sys.ps2辅助解释器提示符的省略号只应谨慎使用，在必须明确区分输入行和输出行时使用。除了增加视觉混乱之外，它还使读者难以剪切和粘贴示例，以便他们可以尝试不同的变体。

代码等效项

提供纯 Python 代码等效项（或近似等效项）可以作为散文描述的有用补充。文档编写者应仔细权衡代码等效项是否增加了价值。

一个很好的例子是all()的代码等效项。简短的 4 行代码等效项很容易理解；它重新强调了早期退出行为；并且它阐明了可迭代对象为空时的处理方式。此外，它还为希望实现一种常见请求的替代方案的人们提供了一个模型，其中all()将在函数提前终止时返回评估为 False 的特定对象。

一个更有争议的例子是itertools.groupby()的代码。它的代码等效项过于复杂，无法快速理解。尽管很复杂，但保留了代码等效项，因为它可以作为替代实现的模型，并且“分组器”的操作在代码中比在英语散文中的展示更容易。

不使用代码等效项的一个示例是oct()函数。将数字转换为八进制的确切步骤对试图了解函数功能的用户没有价值。

受众

教程（和所有文档）的语气需要尊重读者的智力。不要以为读者很愚蠢。列出相关信息，展示激励性的用例，提供词汇表链接，并尽力连接点，但不要贬低他们或浪费他们的时间。

本教程面向新手，其中许多人将使用本教程来评估整个语言。体验需要是积极的，并且不会让读者担心如果他们失足会发生不好的事情。本教程作为对聪明和好奇的读者的指南，将详细信息留给操作指南和其他来源。

小心接受来自罕见但直言不讳的读者类别的文档更改请求，他们正在为他们的一个编程错误寻找辩护（“我犯了一个错误，因此文档一定是错的……”）。通常，在错误发生后才会查阅文档。不幸的是，通常没有文档编辑可以拯救用户免于对语言做出错误的假设（“我感到惊讶的是……”）。