2.1 代码自动补全与提示

2.1 代码自动补全与提示

本节摘要：SOURCE 2.1 把 Tab 补全、点号后成员列表、括号内参数提示和 Shift+Tab docstring 列为编码提速四件套。本节按交互顺序演示 pandas 场景下的补全路径，并说明 JupyterLab 与经典 Notebook 在 LSP 上的差异。

先说结论

阅读完本节，你应当能够：

1. 在编辑模式下用 Tab 补全变量名、函数名与模块成员
2. 输入 . 后浏览对象可用属性与方法列表
3. 输入 ( 后查看函数签名与参数说明
4. 用 Shift+Tab 展开/收起 docstring，多次按键看更完整文档

一、Tab 键：最省时间的补全

SOURCE 举例：输入 pd. 后按 Tab，Jupyter 弹出 pandas 全部公开函数与属性——read_csv、DataFrame、merge 等。比翻官网或靠记忆拼写快一个数量级。

同样适用于：

• 已定义变量名前缀（如 train_ + Tab）
• import 后的模块名（from sklearn. + Tab）
• 字符串路径（部分环境支持路径补全）

⚠️ 常见坑：命令模式（蓝框）下按 Tab 无效——必须先 Enter 进入编辑模式（绿框）。

二、点号与括号：上下文提示

SOURCE 强调两类自动提示：

Modern JupyterLab 若启用 Language Server（Python LSP），括号内会浮层显示参数名与类型；经典 Notebook 依赖 IPython 的 ?/?? 与 Shift+Tab 作为补充。

三、Shift+Tab：docstring 深度阅读

SOURCE：光标置于函数名上，Shift+Tab 显示文档字符串——参数、返回值、示例。再按可展开更多信息；Esc 关闭。

等价于在 IPython 里输入 pd.read_csv?（单问号摘要）或 pd.read_csv??（双问号含源码）。Notebook 里我们更喜欢 Shift+Tab，因为手不用离开键盘。

示例工作流：

import pandas as pd
# 光标放在 read_csv 上 → Shift+Tab
# 看到 sep, encoding, parse_dates 等参数说明
df = pd.read_csv("data.csv")
​

四、代码片段与第三方扩展

SOURCE 指出：Notebook 本体没有内置「片段库」，但可通过 nbextensions 或 JupyterLab 扩展加载常用模板（如 sklearn 训练骨架）。团队可维护一份 .py 或 Markdown cheat sheet，用第 2.2 节 %load 拉进单元格。

JupyterLab 4 的 Advanced Code Completion 支持更长上下文；若补全突然失效，先检查内核是否 Running（右上角）以及是否装在同一环境。

💡 关键直觉：补全质量 = 内核里实际安装了什么包——pd. 能列出 read_csv 的前提是 pandas 已装进当前内核对应的环境（回顾 1.1 的 sys.executable）。

重点提炼

• Tab：变量/模块/成员补全，须在编辑模式
• . 与 (：成员列表与参数提示
• Shift+Tab：docstring，可多次展开
• ? / ??：IPython 等价查询
• 补全依赖内核环境：ImportError 时先查内核，再怪 Tab

下一节 2.2 魔法命令 用 %timeit 量化「循环 vs 向量化」谁更快——补全帮你写对函数名，Magic 帮你量对不对。

用 ? 与 ?? 深入对象

Shift+Tab 之外，IPython 的 ? 与 ?? 是两条被低估的快速通道。在任意单元格执行 pd.read_csv?，会打印签名与摘要；pd.read_csv?? 还会附带源码。对自定义模块同样有效：my_module.my_func?。写代码时如果对某个参数拿不准，把 ? 加在函数名后运行，比翻文档快得多。

补全失效的排查顺序

• 内核是否 Running：右上角圆点灰了，先启动内核。
• 补全依赖的环境：pandas 装在哪套环境，补全就在哪套环境生效。
• 是否在编辑模式：命令模式（蓝框）下 Tab 无响应，先 Enter。
• JupyterLab 是否启用 LSP：扩展未启用时括号参数提示会缺失。

# 补全环境自检：确认 pandas 属于当前内核
import sys, pandas as pd
print(sys.executable)
print(pd.__version__)
​

养成"先打点，再看列表"的习惯

熟练用户不会背 API，而是靠 df. 回车弹列表来回忆方法。看列表时关注两点：方法名是否带括号（可调用），是否有 _ 前缀（私有）。这两点能帮你快速排除"看起来像但调不出来"的误用。配合 Shift+Tab 看签名，十次里有八次不用离开编辑器。

自定义对象的补全支持

自写模块的函数若写了完整 docstring（Args / Returns 分节），Shift+Tab 同样能展示。团队约定 docstring 模板后，成员的补全体验会明显提升——这也是 2.4 节代码风格的一部分。

def normalize_price(price: float, rate: float = 1.0) -> float:
    """统一价格口径。

    Args:
        price: 原始价格。
        rate: 汇率或倍率，默认 1.0。

    Returns:
        折算后的价格。
    """
    return price * rate
​

补全与代码正确性的关系

补全减少的是"拼错"和"记错参数名"两类错误，不保证逻辑正确。写完仍然要跑、要断言。把补全当成打字工具而不是思维替代品：先想清楚这一格要回答什么问题，再靠补全加速实现。

练习与检查

请在实际 Notebook 中完成以下动作，检验本节是否吃透：输入 df. 后回车看成员列表；把光标放在任意函数名上连按两次 Shift+Tab，观察 docstring 展开层级；对自写函数补一段带 Args/Returns 的 docstring，确认补全浮层能读到它。

完成后回答：pandas 装在哪个环境，补全才会对 pd. 生效？如果 pd. 弹不出 read_csv，第一步该检查什么？两个问题都答得上，说明你对"补全依赖内核环境"这条主线已经掌握。