怎么在Python中快速查询库函数用法：help()与dir()技巧

一、分工与定位：dir() 与 help() 的协作机制

在没有网络或需要迅速确认函数签名的场景下，开发者面对一个陌生的模块或对象，最直接的问题通常分为两步：第一步是“这个对象里面到底有哪些东西可以用”，第二步是“选中的具体函数到底该怎么传参和调用”。Python 针对这两个阶段分别设计了专职的内置函数。

dir() 本质上是一个属性与名称的探测器。当向它传递一个模块、类或实例对象时，它会返回一个包含该对象所有有效属性和方法名称的字符串列表。它的作用是建立全貌，帮助开发者快速确定函数名称的拼写是否正确、特定方法是否存在。

help() 则是内置的手册阅读器。它调用 Python 内置的帮助系统，依托对象定义中的 __doc__（文档字符串）以及解释器能解析出的参数列表，格式化输出详细的接口说明、参数类型提示、默认值以及使用示例。

二、使用 dir() 快速探测与高效降噪技巧

在直接对大型模块（如 os、sys、requests）执行 dir() 时，输出往往包含上百个条目，其中夹杂着大量的双下划线内置属性（通常称为 dunder 方法）。如果不进行筛选，肉眼查找非常耗时。掌握列表推导式配合条件判断，是发挥 dir() 威力的关键。

1. 剔除私有与内置特殊属性

在大多数日常使用中，开发者只需要查询对外暴露的常规方法或属性。通过判断字符串前缀是否以下划线 _ 开头，可以快速滤除类库底层的私有成员和魔术方法：

import math

# 过滤掉所有以下划线开头的属性
public_funcs = [item for item in dir(math) if not item.startswith('_')]
print("公开函数数量:", len(public_funcs))
print("前五个函数示例:", public_funcs[:5])

2. 关键字模糊搜索与模式匹配

当只记得函数名的一部分（例如记得字符串处理中有一个与“查找”或“大小写”相关的方法）时，可以在列表推导式中加入关键字包含判断：

# 在内置字符串对象中查找包含 'is' 的校验类方法
is_methods = [method for method in dir(str) if 'is' in method and not method.startswith('_')]
print(is_methods)

3. 筛选可调用对象（过滤变量，保留纯函数）

模块中往往既定义了函数，也定义了常量或配置变量（例如 math.pi、math.e）。若只想保留可以调用的函数，可以使用 callable() 函数结合 getattr() 动态提取属性：

import math

# 仅保留可以加括号执行的函数
callable_funcs = [
    name for name in dir(math) 
    if not name.startswith('_') and callable(getattr(math, name))
]
print("纯可调用函数总数:", len(callable_funcs))

三、使用 help() 精准获取函数签名与文档说明

一旦通过 dir() 锁定了候选函数名，下一步就是了解这个函数需要传入什么参数、有哪些可选参数以及返回值是什么。此时便由 help() 出场。

1. 正确的传参形式：对象引用 vs 函数调用

初学者在使用 help() 时最常犯的错误，是在传入函数名时不自觉地加上了圆括号。必须明确：

• 正确写法：help(math.sqrt) —— 传递的是函数对象本身，帮助系统将读取并打印该函数的文档说明。
• 错误写法：help(math.sqrt(4)) —— 这样会先计算 math.sqrt(4) 得到浮点数 2.0，然后实际执行的是 help(2.0)，显示的是 float 类型的帮助信息；若函数没有默认参数而直接加括号（如 help(math.sqrt())），还会直接触发 TypeError: math.sqrt() takes exactly one argument (0 given) 异常。

import math

# 正确：传入函数名称本身（不带括号）
help(math.pow)

2. 解读函数签名中的特殊标记：斜杠 (/) 与星号 (*)

在 Python 3.8 及之后版本的 help() 输出中，经常会在参数列表中看到 / 或 *：

• 位置限定标记 /：位于 / 左侧的形参必须作为仅限位置参数（Positional-only）传递，不能使用形如 pow(x=2, y=3) 的关键字形式。上例中 pow(x, y, /) 表明 x 和 y 只能按位置传入，如 math.pow(2, 3)。
• 关键字限定标记 *：位于 * 右侧的形参必须作为仅限关键字参数（Keyword-only）传递。例如 sorted(iterable, /, *, key=None, reverse=False) 表明 key 和 reverse 如果要指定，必须显式写出参数名。

3. 终端交互控制：分页器（Pager）退出技巧

当查询一个较大对象（例如 help(str) 或 help(os)）时，内容超出一屏，终端会自动调用类似 less 的分页器工具。控制台会出现冒号 : 或底部提示，此时键盘输入普通的退出命令可能无效：

• 向下滚动一行：按 Enter 键或向下方向键。
• 向下翻滚一页：按 空格键（Space）。
• 退出帮助回到 Python 提示符：直接按键盘上的字母 q。
• 若误进入了无参数的交互式帮助环境 help()（提示符变成了 help>），只需输入 quit 并回车，或者直接按 q 回车即可返回。

四、实战演练：在 datetime 模块中定位时间转换函数

为了让这套技巧更具操作感，我们以标准库中高频使用的 datetime 模块为例。假设开发者需要将当前时间格式化为形如 "2026-10-26" 的字符串，但一时记不清具体的方法名。

步骤一：导入模块并使用 dir() 观察顶层类型

import datetime

# 查看 datetime 模块顶层包含的成员
members = [m for m in dir(datetime) if not m.startswith('_')]
print("顶层成员:", members)

步骤二：深入具体类进行关键字搜索

通过顶层名称可知核心操作类为 datetime.datetime。接下来在此类中搜索与格式化（format 或 str）相关的函数：

# 在 datetime.datetime 类中检索包含 'str' 或 'format' 的方法
dt_methods = [
    m for m in dir(datetime.datetime) 
    if not m.startswith('_') and any(k in m.lower() for k in ['str', 'format'])
]
print("匹配到的候选方法:", dt_methods)

步骤三：利用 help() 查阅候选函数的签名与用法

候选结果清晰明了：strftime（String Format Time）用于将时间对象转为字符串，而 strptime（String Parse Time）用于从字符串反向解析为时间对象。我们针对 strftime 查看文档：

help(datetime.datetime.strftime)

步骤四：验证与编写业务代码

阅读文档后明确了参数名和返回值，直接在交互环境中完成测试：

now = datetime.datetime.now()
formatted_str = now.strftime("%Y-%m-%d %H:%M:%S")
print("格式化结果:", formatted_str)

五、深层机制：__doc__ 与 help() 的区别与底层原理

在 Python 中，函数和类的文档本质上是对象的一个特殊属性：__doc__。理解这一机制有助于在编写自定义函数时提供规范的帮助文档。

编写自定义库或模块时，只需在函数声明下方写上三引号注释，help() 即可自动读取并向使用者呈现：

def calculate_discount(price: float, discount: float = 0.9) -> float:
    """计算商品折扣后的最终价格。
    
    参数:
        price: 商品原价 (正浮点数)
        discount: 折扣率，默认为 0.9 (九折)
        
    返回:
        float: 计算后的折后价
    """
    return price * discount

# 此时调用 help 即可看到规范排版的接口手册
help(calculate_discount)

六、总结与核心注意清单

在日常开发与排错中，熟练应用 dir() 和 help() 能够大幅减少在浏览器与代码编辑器之间频繁切换的认知损耗。总结其实操要领如下：

1. 先排查名录，后查阅细节：不要在一开始就盲目对整个大型模块使用 help()。先通过 dir() 结合列表推导式排除魔术属性并筛选关键词，精准定位具体函数名。
2. 传对象引用，不传函数调用：调用 help() 时，入参必须是函数名本身。添加圆括号会导致解释器提前执行函数，产生非预期报错或输出错误类型的帮助。
3. 掌握终端分页快捷键：遇到大量文档输出时，不要强行按 Ctrl+C 中断整个 Python 会话，单按一个英文字母 q 即可无损退出分页器并保留当前交互上下文。