前言初学 Python 时最常见的困惑不是写法是什么而是我怎么知道有哪些可用的东西。答案是不用背——解释器自带了一套文档查询系统入口就是内置的help()。新手对它的两个典型误解一是以为help()只能在交互式解释器里用脚本里用不了其实能用只是输出方式不同二是把help(obj)和print(obj.__doc__)当成一回事前者会整理成员列表和签名后者只吐一段未经排版的原始字符串。本文从零讲清help()的几种用法、怎么看懂它打印出来的签名、配套的dir()与pydoc怎么配合并给出可以直接照着敲的示例。示例基于 Python 3.8。一、help() 的两种形态官方给的签名有两种形式help()help(request)调用形式行为help()进入交互式帮助系统仅在解释器里合适help(名字)按字符串查找模块、函数、类、方法、关键字或文档主题help(对象)为这个对象生成帮助页关键在于help()这个函数是由site模块在解释器启动时加进内置命名空间的。也就是说如果你用python -S启动关闭 site 模块help这个名字根本不存在。平时不用管但遇到我的 Python 里没有 help时先想想是不是被 -S 关掉了。# 适用于 Python 3.8help(keywords) # 打印 Python 关键字列表help(modules) # 打印当前环境可导入的模块清单help(topics) # 打印可用的帮助主题这三条是入门阶段最有用的索引。不过要注意help(modules)会真的去扫描可导入模块输出很长在交互式解释器里更合适。想程序化地拿关键字列表用keyword模块更稳# 适用于 Python 3.9kwlist 与 iskeyword 在 3.8 也有softkwlist 需 3.9import keywordprint(keyword.kwlist)print(keyword.iskeyword(while)) # Trueprint(keyword.iskeyword(match)) # Falsematch 是「软关键字」不在 kwlist 里print(keyword.softkwlist) # [_, case, match, ...]需 3.9二、给对象生成帮助页传入对象是最常用的形式模块、函数、类、实例都可以。# 适用于 Python 3.8help(str) # 字符串类型的所有方法help(str.split) # 只看 split 这一个方法import jsonhelp(json.dumps) # 第三方/标准库模块同理对自定义的类也一样只要写好文档字符串docstringhelp()就能展示出来# 适用于 Python 3.8class Rect:矩形。width 与 height 都是正数。def area(self):返回面积宽乘高。return self.width * self.heighthelp(Rect)help(Rect.area)类、函数、模块的第一条字符串语句会自动成为它们的__doc__属性help()就是把它整理后打印出来。如果某处没有文档字符串help()会提示找不到文档——这不是报错只是说明作者没写。三、怎么看懂 help 打印的签名help()输出里最需要注意的是函数签名中的两个符号斜杠/和星号*。符号含义例子/它前面的参数是仅位置参数positional-onlyhelp(len)显示len(obj, /)*它后面的参数是仅关键字参数keyword-onlyhelp(sorted)显示sorted(iterable, /, *, keyNone, reverseFalse)代入结论就是len()的参数只能按位置传sorted()的第一个参数可以按位置传而key和reverse必须写成关键字。# 适用于 Python 3.8import inspectprint(inspect.signature(sorted))# (iterable, /, *, keyNone, reverseFalse)help()的输出是给人看的格式随版本会变要在程序里稳定地取签名用inspect.signature()。四、配套工具dir、doc 与 pydochelp()只列出比较大的东西dir()则把对象所有名字都列出来速度更快适合快速探索。# 适用于 Python 3.8import jsonnames dir(json)print(names[:10])print([n for n in names if not n.startswith(_)]) # 只看公开名字对照记忆工具作用适合场合help(obj)整理后的文档 成员列表想读懂怎么用dir(obj)全部名字的列表快速看有哪些名字obj.__doc__原始文档字符串程序里读取、测试断言inspect.signature(f)结构化的签名对象程序里做分析pydoc命令行把help能力搬到终端/浏览器不在解释器里时命令行版更灵活不用先进入解释器# 查看某个模块的文档python -m pydoc json# 用关键词搜索所有已安装模块的摘要python -m pydoc -k csv# 起一个本地文档服务器并打开浏览器python -m pydoc -b-k特别适合我记得有个模块能干这件事但想不起叫什么。五、一段可照着敲的入门练习# 适用于 Python 3.8import keywordimport inspectdef show(name, obj):print( * 40)print(f{name}: {type(obj).__name__})try:print(签名:, inspect.signature(obj))except (TypeError, ValueError):print(签名: (无法获取))doc inspect.getdoc(obj)print(首行:, (doc or (无文档)).splitlines()[0])show(len, len)show(sorted, sorted)show(str.split, str.split)show(dict.get, dict.get)print(关键字:, keyword.kwlist)inspect.getdoc()会帮你把文档字符串的缩进处理好比直接读__doc__干净。常见坑点坑 1用变量名把 help 覆盖掉。❌help 查看文档—— 之后help(...)立刻变成字符串不可调用的TypeError。✅ 换个变量名同理别用dir、type、vars、format当变量名。坑 2在脚本里调不带参数的help()。❌ 脚本里写help()—— 它会尝试进入交互式帮助系统在非交互环境下会读到 EOF行为不是你想要的效果。✅ 用help(模块名)或help(对象)这种带参数的形式。坑 3把help()的输出当稳定格式解析。❌ 用正则去抠help(f)里的参数名 —— 输出格式在版本间会变。✅ 程序里要签名就用inspect.signature(f)要文档就用inspect.getdoc(f)。坑 4以为print(obj.__doc__)和help(obj)等价。❌ 只print(json.dumps.__doc__)就以为看全了 —— 你只拿到一段原始字符串看不到整体的成员结构。✅help(obj)看全貌inspect.getdoc(obj)在程序里取干净文本。坑 5以为dir()只列公开名字。❌ 看到dir(...)结果里一堆双下划线就懵了。✅dir()列出全部名字过滤用[n for n in dir(x) if not n.startswith(_)]。坑 6python -S之后找不到 help。❌ 以为解释器坏了 ——-S跳过了site模块而help正是它加进内置命名空间的。✅ 去掉-S或者改用python -m pydoc这种不依赖内置help的方式。坑 7没写文档字符串然后抱怨 help 没用。❌ 自己定义的类不写 docstringhelp(MyClass)只显示Help on class MyClass什么信息都没有。✅ 类、公开函数、模块顶部都写一段一句话摘要 需要的补充说明。坑 8对可选依赖的模块在没装的情况下help(它)。❌help(numpy)在没装 numpy 的环境里报ModuleNotFoundError。✅help(名字)对模块名会尝试导入不确定是否安装时用python -m pydoc 名字或先importlib.util.find_spec(名字)探测。总结你想知道的事用什么有哪些关键字、主题、模块help(keywords)、help(topics)、help(modules)某个对象怎么用help(obj)或help(模块名)有哪些成员dir(obj)配合下划线过滤参数怎么传看help里的签名或inspect.signature(obj)强制文档怎么打「/」之前是仅位置参数「*」之后是仅关键字参数不在解释器里怎么查python -m pydoc 名字、python -m pydoc -k 关键词help()是 Python 送给初学者最好的礼物不懂就问问到的内容直接来自官方文档字符串比任何二手教程都准。入门阶段把它和三件事绑在一起用就够了——dir()看有哪些名字、help()看怎么用、inspect.signature()在程序里拿签名。养成遇到不认识的函数先help一下的习惯比背 API 清单高效得多。Python 2 中print是语句而非函数写print(x)会被当成带括号的表达式Python 3 中print才是函数。Python 2 的raw_input()也已改名为input()。Python 2.7 自 2020 年 1 月 1 日停止维护本文一律使用 Python 3 写法。