前言标题里的「之类」表述比较含糊本文把它读作怎么读 Python 官方文档里的基础语法部分。这是一项比背语法更值的技能——语言在演进教程会过期但官方文档永远与解释器同步而且它给出的是定义不是某某人的理解。常见的三个误解先澄清。第一「官方文档太学术初学者看不懂」。其实文档是按读者分层的教程Tutorial面向入门库参考Library reference面向查 API语言参考Language reference面向查语义定义三者难度和用途完全不同看错版块才会觉得难。第二「文档没有例子」。语言参考确实例子少但教程与 HOWTO 里有大量可运行片段。第三「只要会搜索就行」。搜索能找到页面但读不懂页面上的记号约定找到了也没用——比如签名里的斜杠与星号、方括号、版本标注这些都是有严格定义的符号不是排版装饰。本文以 Python 3 的官方文档为对象讲清四个问题文档分成哪些版块、函数签名怎么读、页面上的固定惯例是什么意思、以及遇到 3.8 前后有变化的语法时该去哪里确认。必须说明本机没有 Python 解释器本文没有运行任何代码所有关于文档结构与记号的说法都以官方文档页面本身为准。一、先建立版块地图官方文档首页列出的版块不是随便排的每一个都对应一种问题。搞清「我要解决什么问题 → 该翻哪一块」能省掉大量时间。版块回答什么问题什么时候看教程 Tutorial语言怎么上手、基本概念是什么第一次学某个主题内置对象参考 Built-ins referenceint、str、list这些内置类型与方法查内置类型的行为库参考 Library reference标准库每个模块的 API查os、re、json怎么用语言参考 Language reference语法与语义的正式定义想知道「为什么会这样」Python 安装与使用 Setup and usage命令行、环境变量、环境搭建配置解释器与运行方式HOWTO针对具体任务的实操文档学一类做法比如日志、排序安装 Python 模块 Installing modulespip、虚拟环境、包安装装第三方包扩展与嵌入 Extending and embedding写 C 扩展、嵌入解释器需要 C 层面的能力常见问题 FAQs高频疑问与反直觉行为踩坑后找解释术语表 Glossary术语的官方定义遇到不认识的词弃用 Deprecations哪些东西将被移除升级版本前的排查版本变更 Whats new每个版本新增/变更/移除确认某个特性从哪版开始有通用索引 / 搜索页 / 完整目录定位具体页面不记得页面在哪时其中最容易被忽略、也最有用的两块是术语表与版本变更。术语表把「迭代器」「可迭代对象」「描述符」这类容易混的词用一句话定义清楚版本变更文档则是判断「这个写法在我的版本上有没有」的唯一权威来源。库参考与语言参考的分工同一个概念常常在两个版块都有页面这不是重复而是分工不同语言参考回答「语法长什么样、语义是什么」。比如循环、函数定义、赋值语句、表达式求值的规则。它写得像规范会明确说「这是语法错误」还是「这是实现细节」。库参考回答「这个模块接口怎么用」。它给出每个函数与类的签名、参数含义、返回值、异常、以及平台可用性。查某个方法的行为返回值是新对象还是原地修改、参数默认值是什么去看库参考查「为什么这段代码的语义是这样」去看语言参考。把两者混着看就会出现「在语言参考里找一个函数的参数列表」这种徒劳。二、函数签名怎么读这是本文最该记住的一节。库参考里每个函数都配一行签名下面是它用到的记号记号含义例子斜杠/它之前的参数只能按位置传不能当关键字传f(a, b, /, c)中a、b只能按位置传星号*它之后的参数只能按关键字传f(a, *, b)中b必须写b...方括号[...]里面的内容是可选的可以不写split(sepNone, maxsplit-1)里的默认值参数名带该参数有默认值open(file, moder, encoding...)省略号...参数含义需看下方说明不是语法符号某些接受多种类型的参数关于斜杠记号要特别说明它是 Python 3.8 才引入的语言特性PEP 570标题为 Python Positional-Only Parameters。所以你在 3.8 之前的文档或教程里不会看到它而在较新的文档里到处都有。它的意义是让库作者能对外声明「这个名字只是内部实现你不要用关键字传」从而保留以后改名的自由。读签名时看到/不要以为它是个参数。方括号还有一个容易误读的地方它表示「可以省略」不表示「这是列表」。比如sorted(iterable, keyNone, reverseFalse)里没有方括号就说明这三个参数位置固定、名字固定而str.split(sepNone, maxsplit-1)的None与-1是默认值不是取值范围。三、页面上的固定惯例官方文档有一套用了很多年的排版惯例认识了就能快速抓住重点标题末尾的¶是一个锚点链接。它看起来像段落符号其实是「点一下就能拿到这一节的永久链接」的按钮。分享或引用某一节时用它比复制浏览器地址栏更可靠。版本标注Added in version X.Y表示某特性从哪个版本开始有Changed in version X.Y表示行为在哪个版本变了Deprecated since version X.Y表示已弃用将来会移除常带removed in version X.Y。看到这三类标注就要警觉它们正是不同版本行为差异的官方记录。例如文档会写明某个脚本已在 3.6 弃用、3.8 移除。可用性标注以Availability:开头的说明表示平台限制或依赖条件比如某些功能只在 Windows 上可用。跨平台代码必须看这一行。术语会自动链接到术语表。页面上出现的「可迭代对象」「迭代器」「映射」等词常常是链接点进去是官方定义——这比自己猜要快得多。交互式示例用与...开头后面跟输出。...既可能是续行提示符也可能出现在示例里表示省略要结合上下文分辨。See also段落通常指向相关模块、HOWTO 或规范是顺着一条线学下去的最好入口。四、怎么把页面找出来并确认版本支持不记得页面路径时按这个顺序找命中率最高完整目录Complete table of contents给出全站层级结构适合「我知道大概在哪一块但不知道具体页」。通用索引General index按符号与方法名排列适合「我知道函数名想找它在哪一页」。搜索页输入关键词适合知道要做什么、不知道叫什么。术语表知道概念、不知道对应模块时从术语反查。版本变更文档只想知道「这个特性从哪版开始有」时直接看版本变更比翻页面更快。语言参考内部还有一个专门的记法说明章节定义了语法描述用的符号比如::表示规则定义、竖线表示「或」、方括号表示可选、星号表示重复。读语法定义之前先扫一遍那一节能避免把「语法描述里的方括号」和「函数签名里的方括号」混为一谈。把页面找到只是第一步接下来还要确认「我的版本到底支不支持」这是读书型学习者最容易吃亏的地方。看到一篇教程用了某个写法先别抄按三步确认看当前解释器版本。不同机器上装的版本可能完全不同。在库参考或语言参考里找到对应页面看Added in version标注。拿不准就去版本变更文档里搜那里有每个版本的完整变更列表。举个典型例子仅位置参数/是 3.8 才有的所以在 3.8 之前的代码里写/会直接语法错误而反过来3.8 的文档里到处都是/如果你把它当成必须写的语法抄进旧版本项目也会报错。类似的还有f-string 从 3.6 开始有、str.removeprefix从 3.9 开始有、异常组语法从 3.11 开始有、类型参数语法从 3.12 开始有。这些都不靠记忆靠文档上的版本标注。# 适用于 Python 3.8# 用标准库查版本信息比凭印象判断可靠import sysprint(sys.version_info[:3]) # 例如 (3, 8, 10)print(sys.version_info (3, 8)) # 元组可以直接比较用于分支if sys.version_info (3, 9):print(可以用 str.removeprefix / removesuffix)else:print(需要自己用 startswith 切片实现)在 3.8 上运行这段代码没有任何问题它本身就是「读文档之后该做的事」——把文档里的版本标注变成代码里的版本判断。常见坑点❌ 在库参考里找「函数为什么这样设计」在语言参考里找「函数有哪些参数」。 ✅ 库参考查 API 用法与签名语言参考查语法与语义定义两者分工不同。❌ 把函数签名里的/当成一个参数或分隔符照抄进代码。 ✅/是「仅位置参数」的标记是 Python 3.8 起PEP 570引入的语言特性不是参数。❌ 把签名里的方括号[...]理解成列表或数组。 ✅ 方括号表示「这一部分可以省略」与列表语法无关。❌ 看到教程里的写法就直接抄不确认自己解释器的版本。 ✅ 先在文档里找Added in version标注再用sys.version_info在代码里做判断。❌ 忽略页面上的Deprecated since version标注继续用在生产代码里。 ✅ 已经弃用的接口要按标注给出替代方案升级版本前尤其要排查一遍。❌ 忽略Availability:那一行写出只在某个操作系统上能跑的代码。 ✅ 平台相关的接口先看可用性标注再决定是否要写分支或换方案。❌ 只在搜索页里跳来跳去不知道完整目录与通用索引的存在。 ✅ 按「不知道叫什么用搜索、知道名字用通用索引、只知道大概位置用完整目录」来选工具。❌ 把与...当成代码的一部分抄下来。 ✅ 它们是交互式解释器的提示符真正要抄的是提示符之后的表达式。总结你要做的事该翻哪一块第一次学某个主题教程查某个函数的参数与返回库参考查语法/语义的正式定义语言参考确认特性从哪版开始有版本变更文档查一个词的确切含义术语表不知道页面在哪完整目录 / 通用索引 / 搜索页读官方文档的核心只有一句话先把「版块地图」和「记号约定」这两张底图记住剩下的都是查。签名里的斜杠、星号、方括号以及Added in version这类版本标注是文档里信息密度最高的几个符号看到它们不要跳过它们恰好回答了「这么写对不对、我的版本支不支持」这两个最实际的问题。
