怎么在Python中使用help()和dir()查看命令帮助文档
全面讲解在Python中如何使用内置函数dir()与help()查看命令帮助文档,涵盖属性探测、文档查阅、分页器导航、二者核心差异及排查实践。
在编写 Python 代码或调试程序时,经常会遇到记不清函数参数顺序、不确定模块包含哪些可用接口,或是需要了解某个对象具体能力的情况。在没有网络或者不愿频繁切换浏览器查找官方手册时,Python 内置的 dir() 与 help() 是最直接高效的两个本地探索工具。简而言之,dir() 负责“列出清单”,告诉你对象内部有哪些属性和方法;help() 则负责“翻开手册”,展示函数签名、参数规则及详细说明。理解并组合使用这两个函数,能够让你在终端与交互环境中快速完成自我排查与探索。
一、使用 dir() 探测对象的成员与结构
dir() 是 Python 的内置函数,其作用是返回一个包含有效属性名称的列表。当你在编写代码时突然想不起字符串有哪些关于大小写的处理方法,或者面对一个新安装的第三方库对象不清楚暴露了哪些接口时,dir() 可以在几毫秒内给出答案。
1. 无参调用:查看当前局部作用域
在交互式终端或脚本中直接执行 dir()(不传任何参数),它会返回当前作用域中已经定义的所有变量名、导入的模块名和内置名称:
>>> dir()
['__annotations__', '__builtins__', '__doc__', '__loader__', '__name__', '__package__', '__spec__']
>>> x = 10
>>> import math
>>> dir()
['__annotations__', '__builtins__', '__doc__', '__loader__', '__name__', '__package__', '__spec__', 'math', 'x']
可以看到,新赋值的变量 x 和导入的 math 模块立刻出现在了列表末尾。这在排查命名冲突或检查某个模块是否成功导入时十分有用。
2. 传参调用:探查模块、类型与实例
把任何对象作为参数传给 dir(obj),Python 会调用该对象的 __dir__() 方法,收集其所有属性、方法和内置魔术名称:
>>> import math
>>> dir(math)
['__doc__', '__loader__', '__name__', '__package__', '__spec__', 'acos', 'acosh', 'asin', 'asinh', 'atan', 'atan2', 'atanh', 'ceil', 'comb', 'copysign', 'cos', 'cosh', 'degrees', 'dist', 'e', 'erf', 'erfc', 'exp', 'expm1', 'fabs', 'factorial', 'floor', 'fmod', 'frexp', 'fsum', 'gamma', 'gcd', 'hypot', 'inf', 'isclose', 'isfinite', 'isinf', 'isnan', 'isqrt', 'lcm', 'ldexp', 'lgamma', 'log', 'log10', 'log1p', 'log2', 'modf', 'nan', 'nextafter', 'perm', 'pi', 'pow', 'prod', 'radians', 'remainder', 'sin', 'sinh', 'sqrt', 'tan', 'tanh', 'tau', 'trunc', 'ulp']
3. 实操技巧:利用列表推导式过滤下划线成员
大多数 Python 对象的 dir() 结果开头都充斥着大量形如 __init__、__repr__ 的双下划线特殊成员(通常称为魔术方法)。在日常开发中,我们通常只关心常规的公共方法。使用一行列表推导式即可完成清洗:
>>> # 过滤掉所有以下划线开头的私有或特殊方法
>>> [item for item in dir(str) if not item.startswith('_')]
['capitalize', 'casefold', 'center', 'count', 'encode', 'endswith', 'expandtabs', 'find', 'format', 'format_map', 'index', 'isalnum', 'isalpha', 'isascii', 'isdecimal', 'isdigit', 'isidentifier', 'islower', 'isnumeric', 'isprintable', 'isspace', 'istitle', 'isupper', 'join', 'ljust', 'lower', 'lstrip', 'maketrans', 'partition', 'removeprefix', 'removesuffix', 'replace', 'rfind', 'rindex', 'rjust', 'rpartition', 'rsplit', 'rstrip', 'split', 'splitlines', 'startswith', 'strip', 'swapcase', 'title', 'translate', 'upper', 'zfill']
如果想按关键词检索,例如查看列表中所有关于“查找”或“计数”的方法,可以这样写:
>>> [item for item in dir(str) if 'find' in item or 'count' in item]
['count', 'find', 'rfind']
二、使用 help() 查阅详细使用手册与参数文档
通过 dir() 锁定了方法名称后,接下来就需要了解该方法到底接收哪些参数、各参数的默认值是什么、返回值是什么类型。这就是 help() 的职责所在。help() 是 Python 基于内置模块 pydoc 构建的交互式帮助系统,能把代码中的函数签名、类型提示和文档字符串(Docstrings)格式化后呈现在终端中。
1. 对象直接查阅:help(obj)
最直接的做法是将函数、类或模块对象作为实参直接传入 help():
>>> help(str.split)
Help on method_descriptor:
split(self, /, sep=None, maxsplit=-1)
Return a list of the substrings in the string, using sep as the delimiter string.
sep
The delimiter according to which to split the string.
None (the default value) means split according to any whitespace,
and discard empty strings from the result.
maxsplit
Maximum number of splits to do.
-1 (the default value) means no limit.
从输出中可以清晰读出:sep 默认值为 None(代表按空白字符切分),maxsplit 默认是 -1(代表不限制切分次数)。这就无需猜测参数名是 delimiter 还是 sep。
查阅文档时应传入函数对象本身
help(str.split),而不是 help(str.split())。如果加上了括号,Python 会先执行该函数,然后把该函数的返回值传给 help()。如果该函数执行耗时很长或具有删除数据的副作用,这将引发预期之外的操作。
2. 字符串名称查阅:无需导入即可查询模块
如果还没有在代码中执行 import,也可以直接以字符串形式将模块名、关键字或内置主题传给 help():
>>> # 无需先执行 import math,直接传入字符串
>>> help("math.sqrt")
Help on built-in function sqrt in math:
math.sqrt = sqrt(x, /)
Return the square root of x.
此外,还可以通过字符串查阅 Python 语言级别的关键字和特殊语法说明:
help("keywords"):列出 Python 所有的保留关键字(如def、class、with、yield等)。help("for"):查看for循环语法的官方语法规范与说明。help("symbols"):列出 Python 中所有符号操作符(如+、**、@等)。help("modules"):扫描当前 Python 环境下所有可导入的模块列表(扫描耗时可能稍长)。
3. 交互式帮助控制台:无参调用 help()
在 Python 终端中单独输入 help() 并按回车,将启动专门的交互式帮助控制台:
>>> help()
Welcome to Python 3.11's help utility!
If this is your first time using Python, you should definitely check out
the tutorial on the internet at https://docs.python.org/3.11/tutorial/.
Enter the name of any module, keyword, or topic to get help on writing
Python programs and using Python modules. To quit this help utility and
return to the interpreter, just type "quit".
help> math
# ... 此时会直接进入 math 模块的详细说明 ...
help> quit
You are now leaving help and returning to the interpreter.
>>>
在 help> 提示符下,可以直接输入任意模块名、关键字或函数名,而无需额外加引号或括号;连续查询完成后,输入 quit 即可退回原本的 Python 提示符 >>>。
4. 终端分页器(Pager)的操作导航
当查阅的内容超过一屏时(例如 help(sys) 或 help(list)),Python 会自动调用系统的分页器(在 macOS 与 Linux 上通常是 less,在 Windows 上通常是 more)。初学者常在此处感到困惑,不知道如何退出或继续阅读。记住以下四个关键按键即可自如控制:
三、dir() 与 help() 的关键差异与协同决策
许多刚接触 Python 的开发者容易混淆两者的边界,或者在需要简要信息时调用了 help() 导致终端被大量文本淹没,又或者在需要函数参数时仅调用 dir() 面对一堆名字无从下手。理解两者的根本差异,是提升开发排查效率的核心。
| 对比维度 | dir(obj) | help(obj) | 差异对开发的影响 |
|---|---|---|---|
| 数据源头 | 调用 __dir__() 或抓取 __dict__ 的键名 |
读取 __doc__(文档字符串)并结合函数签名解析 |
即使作者没写任何注释,dir() 依然能完整列出属性;而没有文档的函数在 help() 中只有签名。 |
| 返回类型 | Python 原生列表(list) |
无返回值(返回 None),内容直接打印至标准输出或分页器 |
dir() 的结果可以在代码中被变量接收、循环遍历、筛选;help() 纯粹服务于人类阅读。 |
| 信息密度 | 极简(仅有标识符字符串) | 极高(包含参数、默认值、说明、异常及示例) | 当屏幕空间有限或只想确认拼写时,dir() 极其清爽;深入学习接口行为必须用 help()。 |
| 参数类型支持 | 必须传入具体的 Python 对象或表达式 | 可传对象,也可传主题字符串(如 "modules") |
help() 能作为全功能的离线手册检索工具,dir() 则聚焦于运行时的对象自省。 |
为什么区分这种差异很重要?
在日常编码实践中,二者并不是竞争关系,而是典型的“漏斗型”配合。如果一开始就对整个模块执行 help(),往往需要滚动几十页才能找到目标;反之,如果只依赖 dir(),你只能猜测函数的调用参数。最高效的工作流始终是:先广度探测,再深度研读。
四、常见问题与注意事项
1. 为什么有的自定义对象 dir() 出来的属性无法在 help() 里查到说明?
这是因为 dir() 只需要标识符存在于实例或类的命名空间即可,而 help() 的说明文字完全依赖于代码中的 Docstrings(文档字符串)。如果自定义类或第三方库没有在函数下方编写三引号注释 """...""",help() 只能回退显示函数签名,无法提供更多文字描述。因此,在开发自己的模块时,规范编写 Docstrings 能够大幅提升其他人使用 help() 查阅时的体验。
2. 如何只查阅模块中函数的 Docstring 而不触发长篇分页?
如果只想快速查看某函数的原生文档说明,不想进入 help() 的全屏分页器,可以直接打印该对象的 __doc__ 属性:
>>> print(str.lower.__doc__)
Return a copy of the string converted to lowercase.
这种方式输出简洁,不会打断当前的控制台交互流程。
总结
掌握 dir() 和 help() 是深入掌握 Python 自省机制(Introspection)的基础。在日常编码与交互调试中,善用 dir() 配合列表推导式快速探测未知对象结构,利用 help() 精确掌握函数签名与参数细节,配合分页器快捷键流转导航,可以极大摆脱对外部浏览器的依赖,让代码编写与排错过程更加流畅自如。
本站声明
本文内容仅供参考,不代表本站观点。转载或引用请注明出处。如发现内容问题,请通过联系我们页面反馈。













