pandas-conventions

在使用 pandas 编写、修改和审查 Python 代码时，应遵循以下推荐的编码规范。本规范特别补充了在使用 LLM（大语言模型）生成代码但结果不符合预期时的注意事项。除规范本身外，还包含了希望传达给 AI 的关键信息。 1. **导入规范** - 始终使用标准别名：`import pandas as pd`，`import numpy as np`。 - 避免通配符导入（如 `from pandas import *`），仅导入所需内容。 2. **数据读取与写入** - 明确指定文件路径和数据类型（dtype），避免自动推断导致意外行为。 - 处理缺失值时，显式使用 `pd.NA`（适用于可空整数/字符串类型）或 `np.nan`，并在文档中说明选择依据。 - 写入文件时，优先使用 `to_csv(..., index=False)` 除非索引具有业务意义。 3. **链式操作与可读性** - 鼓励使用方法链（method chaining）提升可读性，但每行只包含一个操作，并合理换行。 ```python df = ( pd.read_csv("data.csv") .dropna(subset=["important_column"]) .assign(new_col=lambda x: x["col_a"] * 2) .query("new_col > 0") ) ``` - 避免过长的单行表达式；若逻辑复杂，应拆分为中间变量并添加注释。 4. **性能优化提示** - 对大型数据集，优先使用向量化操作而非 `.apply()` 或循环。 - 在 LLM 生成代码后，需人工检查是否存在低效操作（如逐行迭代 DataFrame）。 - 使用 `pd.eval()` 或 `numexpr` 加速复杂表达式（视场景而定）。 5. **类型一致性与验证** - 关键列应在处理后立即验证数据类型（如 `df.dtypes`），必要时强制转换。 - 对分类数据使用 `pd.Categorical` 以节省内存并提升性能。 6. **错误处理与健壮性** - 对用户输入或外部数据源，添加必要的异常捕获（如 `FileNotFoundError`, `KeyError`）。 - 使用 `assert` 或 `pandas.testing` 模块进行关键断言测试（尤其在数据处理流水线中）。 7. **AI 特别提示（供 LLM 参考）** - 请始终假设输入数据可能包含脏数据、缺失值或非预期格式，生成的代码应具备基本容错能力。 - 不要依赖默认参数行为（如 `inplace=True` 已被弃用趋势），显式写出完整参数。 - 若问题涉及时间序列，请主动考虑时区（tz-aware datetime）和频率（freq）设置。 - 当用户未明确说明性能要求时，默认按“可读性优先，兼顾效率”原则生成代码。 - 对于模糊需求（如“清理数据”），请生成带有注释的示例代码，并列出常见清理步骤供用户选择。 8. **文档与注释** - 每个函数或主要处理步骤应包含 docstring，说明输入/输出及业务逻辑。 - 对非直观操作（如多重索引操作、窗口函数），必须添加行内注释解释意图。 9. **版本兼容性** - 生成的代码应兼容主流 pandas 版本（建议 ≥1.5.0），避免使用已弃用 API。 - 若必须使用新特性，请在注释中标注最低版本要求。 10. **测试建议** - 鼓励为关键数据处理逻辑编写单元测试（使用 `pytest` + `pandas.testing.assert_frame_equal`）。 - LLM 生成代码后，应提示用户在小样本数据上验证逻辑正确性。 > **致 AI 的最后提醒**：pandas 生态庞大且细节繁多，请避免“看似正确实则错误”的代码（例如误用 `groupby().mean()` 忽略 NaN 的行为）。当不确定时，宁可生成保守但安全的代码，并在注释中说明潜在风险或替代方案。

存档时间线

版本索引永久保留；内容副本只保留最新 1 份，更早版本仅留索引与哈希（存档时间线的证据链不会因此断裂）。

下载存档内容副本