PDEP-1: 目的和指南
- 创建日期: 2022 年 8 月 3 日
- 状态: 已接受
- 讨论: #47444, #51417
- 作者: Marc Garcia, Noa Tamir
- 修订版本: 2
PDEP 定义、目的和范围
PDEP(pandas 增强提案)是对 pandas 中 **重大** 更改的提案,类似于 Python 的 PEP 或 NumPy 的 NEP。
错误修复和概念上较小的更改(例如,向函数添加参数)不在 PDEP 的范围内。PDEP 应该用于非立即且非显而易见的更改,当 pandas 社区中的每个人都需要意识到即将发生的更改的可能性时。此类更改需要在实施之前进行详细的文档记录,并且经常会导致社区内进行重大讨论。
PDEP 适用于面向用户的更改、内部更改和重大讨论。值得进行 PDEP 的主题示例包括实质性的 API 更改、破坏性行为更改、将模块从 pandas 移动到单独的存储库或 pandas 块管理器重构。并非总是很容易知道哪个问题有足够的范围来需要完整的 PDEP 流程。一些简单的 API 更改在核心团队中达成了一致,并且对社区的影响最小。另一方面,如果一个问题变得有争议,即它引发了重大讨论,则可以建议打开一个 PDEP 来正式化和记录讨论,使更广泛的社区更容易参与。有关上下文,请参阅 可能成为 PDEP 的问题列表。
PDEP 指南
目标受众
PDEP 是一份公开文件,任何人都可以访问,但在撰写 PDEP 时需要考虑的主要利益相关者是
- 核心开发团队,他们将最终决定是否批准 PDEP
- pandas 及其他相关项目的贡献者,以及经验丰富的用户。他们的反馈意见非常鼓励和赞赏,以确保所有观点都被考虑在内
- 更广泛的 pandas 社区,尤其是用户,他们可能对提案有或没有反馈,但应该了解并能够理解项目的未来方向
PDEP 作者
任何人都可以提出 PDEP,但核心成员应该参与,为非核心贡献者提出的提案提供建议。要作为社区成员提交 PDEP,请在 问题 上提出 PDEP 概念,并找到 pandas 团队成员进行合作。他们可以就 PDEP 流程提供建议,并在 PDEP 提交到 PDEP 存储库时被列为顾问。
工作流程
PDEP 可能处于以下状态
- 正在讨论
- 已接受
- 已实施
- 已拒绝
接下来将描述 PDEP 可以遵循的工作流程。
提交 PDEP
提出 PDEP 是通过创建一个 PR 来完成的,该 PR 将一个新文件添加到 web/pdeps/
中。该文件是一个 markdown 文件,您可以使用 web/pdeps/0001.md
作为预期格式的参考。
PDEP 的初始状态将为 Status: Under discussion
。当 PDEP 准备就绪并获得核心团队的批准时,这将更改为 Status: Accepted
。
已接受的 PDEP
只有核心开发团队才能接受 PDEP,如果该提案被认为值得实施。决策将基于 pandas 治理文档 中详细说明的流程。一般来说,在 PR 合并之前需要多个批准。合并时不应该有任何 Request changes
审查。
一旦 PDEP 被接受,就可以对 PDEP 的实施做出任何贡献,并具有开放式的完成时间线。pandas 的开发很难理解和预测,因为 pandas 的贡献者是来自不同来源、具有不同优先级的志愿者和开发人员的混合体。对于有兴趣看到 PDEP 被实施的公司、机构或个人,或者一般来说希望看到 pandas 路线图的进展,请查看 贡献页面 中如何提供帮助。
已实现 PDEP
一旦 PDEP 在 pandas 的主分支中实现并可用,其状态将更改为 Status: Implemented
,以便能够直观地看到该 PDEP 不再属于路线图和未来计划,而是一项已经完成的更改。PDEP 实现可用的第一个 pandas 版本也将包含在 PDEP 标题中,例如 Implemented: v2.0.0
。
被拒绝的 PDEP
当最终决定不实施 PDEP 对项目最有利时,可以拒绝该 PDEP。被拒绝的 PDEP 与被接受的 PDEP 一样有用,因为它们包含了值得讨论的内容,以及关于 pandas 更改的决策。它们将被合并为 Status: Rejected
,以便能够直观地了解讨论的内容以及讨论的结果。PDEP 可能会因各种原因被拒绝,例如,一些好主意可能不向后兼容,而这些破坏性更改被认为不值得实施。
无效的 PDEP
对于提交的 PDEP,如果它们不包含适当的文档,超出范围,或因其他任何原因对社区没有用处,则在与作者讨论后,将关闭 PR,而不是将其合并为拒绝。这样做是为了避免在被拒绝的 PDEP 列表中添加噪音,该列表应该包含与被接受的 PDEP 一样好的文档,但最终决定不实施这些更改。
PDEP 的演变
大多数 PDEP 在被接受后预计不会发生变化。一旦对更改达成一致,并实施了这些更改,PDEP 将仅用于了解开发的原因以及讨论的细节。
但在某些情况下,可以更新 PDEP。例如,定义过程或策略的 PDEP,例如本 PDEP (PDEP-1)。或者,在尝试实施后,获得的新知识使原始 PDEP 过时,需要进行更改。当需要对原始 PDEP 进行特定更改时,将对其进行编辑,其 Revision: X
标签将增加 1,并且将在 PDEP-N history
部分添加注释。这将使读者了解 PDEP 发生了变化,并避免混淆。
可能作为 PDEP 的问题列表,以供参考
潜在 PDEP 的清晰示例
- 向许多现有方法添加新参数,或在许多地方弃用参数。例如
numeric_only
弃用 (GH-28900) 影响了许多方法,本可以成为一个 PDEP。- 添加新的数据类型会影响需要处理该数据类型的各种地方。这种广泛的影响需要一个 PDEP。例如
Categorical
(GH-7217, GH-8074),StringDtype
(GH-8640),ArrowDtype
- 对现有行为的重大(破坏性)更改。例如
- 复制/视图更改 (GH-36195)
- 支持具有广泛影响的新 Python 特性。例如
- 在 pandas 中支持类型化与创建
pandas-stubs
(GH-43197, GH-45253) - 新的必需依赖项。
- 从项目中删除模块或将其拆分到单独的存储库中
- 将很少使用的 I/O 连接器移到单独的存储库中 GH-28409
- 对贡献者流程的重大更改不会影响用户,但它们确实受益于贡献者之间的结构化讨论。例如
- 将构建系统更改为 meson (GH-49115)
边界示例
对核心功能(如 DataFrame
和 Series
)的小更改应始终被视为 PDEP 候选,因为它很可能对用户产生重大影响。但其他功能中的相同类型更改将不是好的 PDEP 候选。也就是说,任何讨论,无论更改有多小,只要变得有争议,都是 PDEP 候选。考虑是否需要更多关注和/或正式的决策过程。以下是一些我们希望可以帮助澄清我们在此含义的示例
- API 更改或其讨论可能是 PDEP。例如
value_counts
结果重命名 (GH-49497)。范围最初不值得 PDEP,但后来关于是否应将其作为破坏性更改或使用弃用执行的讨论出现,这可能会从 PDEP 过程中受益。- 向现有方法添加新方法或参数通常不需要为非核心功能创建 PDEP。例如
dropna(percentage)
(GH-35299) 和Timestamp.normalize()
(GH-8794) 都不需要 PDEP。- 另一方面,
DataFrame.assign()
可能需要。虽然它是一个没有向后兼容性问题的方法,但它也是一个核心功能,讨论应该高度可见。 - 在大多数情况下,弃用或删除单个方法不需要 PDEP。
- 也就是说,
DataFrame.append
(GH-35407)是核心功能弃用示例,非常适合作为 PDEP。 - 更改核心 pandas 方法中参数的默认值是另一个边缘情况。例如
DataFrame.groupby
和Series.groupby
中dropna
的此类更改可以作为 PDEP。- 新的顶级模块和/或公开内部类。例如
- 添加
pandas.api.typing
(GH-48577)相对较小,不一定需要 PDEP。