PEP 1 – PEP 目的和指南

猫勺猫勺 02-19 162 阅读 1 评论

什么是 PEP

PEP 代表 Python 增强提案。PEP 是一种设计 向 Python 社区提供信息的文档,或描述 Python 或其进程或环境的新功能。PEP的 应提供该功能的简明技术规范和 该功能的基本原理。

我们打算将政治人物作为提出重大新建议的主要机制 功能,用于收集社区对某个问题的意见,以及 记录 Python 中的设计决策。PEP的 作者负责在社区内建立共识,并 记录不同意见。

因为 PEP 在版本化中作为文本文件进行维护 存储库,它们的修订历史是 功能提案。此历史记录可通过普通 git 获得 用于检索旧版本的命令,也可以在 Github 上浏览。

PEP 受众

PEP 的典型主要受众是 CPython 的核心开发人员 参考口译员及其选出的指导委员会,以及开发人员 Python 语言规范的其他实现。

但是,Python 社区的其他部分也可以选择使用该过程 (特别是对于信息性 PEP)来记录预期的 API 约定和 管理需要跨部门协作的复杂设计协调问题 多个项目。

PEP 类型

PEP有三种类型:

标准跟踪 PEP 描述新功能或实现 对于 Python。它还可能描述一个互操作性标准,该标准将 在当前 Python 版本的标准库之外受支持 在后续 PEP 将来添加标准库支持之前 版本。

信息性 PEP 描述 Python 设计问题,或者 向 Python 社区提供一般指南或信息, 但没有提出新功能。信息性 PEP 不会 必须代表 Python 社区的共识,或者 建议,因此用户和实现者可以自由忽略 信息性 PEP 或听从他们的建议。

进程 PEP 描述了围绕 Python 的进程,或者 提议对流程进行更改(或流程中的事件)。过程 PEP 是 与标准跟踪 PEP 一样,但适用于 Python 以外的领域 语言本身。他们可能会提出实施建议,但不能 Python 的代码库;它们通常需要社区共识;与 信息性 PEP,它们不仅仅是建议和用户 通常不能随意忽略它们。示例包括 程序、指南、决策过程的变更,以及 对 Python 开发中使用的工具或环境的更改。 任何元 PEP 也被视为过程 PEP。

PEP 工作流程

Python 的指导委员会

本 PEP 中多次提到“指导委员会”或“委员会”。 这是指所描述的当选指导委员会的现任成员 在 PEP 13 中,他们作为 PEP 是否 PEP 的最终权威 将被接受或拒绝。

Python 的核心开发人员

此 PEP 中有几个对“核心开发人员”的引用。这是指 PEP 13 中描述的当前活跃的 Python 核心团队成员。

Python 的 BDFL

此 PEP 的早期版本使用标题“BDFL-Delegate”作为 PEP 决策 制造商。这是对 Python 之前治理模型的历史参考, 所有设计权威最终都来自 Guido van Rossum, Python 编程语言的原始创建者。相比之下,转向 理事会的设计权来自他们由当前活跃的选举产生 核心开发人员。现在,PEP-Delegate 代替了 BDFL-Delegate 。

PEP 编辑器

PEP 编辑是负责管理行政管理的个人 以及 PEP 工作流程的编辑方面(例如分配 PEP 编号和 更改其状态)。请参阅 PEP 编辑职责和工作流程 详。

PEP编辑是受现任编辑的邀请,他们可以 通过在 GitHub 上提及来联系。所有 PEP 工作流可以通过 GitHub PEP 存储库问题和拉取来执行 请求。@python/pep-editors

从 Python 的想法开始

PEP 过程始于 Python 的新想法。它是高度的 建议单个 PEP 包含单个密钥提案或新的 想法;PEP越专注,它往往就越成功。 大多数增强功能和错误修复不需要 PEP 和 可以直接提交到 Python 问题跟踪器。 PEP 编辑保留 如果 PEP 提案看起来太不集中或太过集中,则有权拒绝这些提案 广泛。如果有疑问,请将您的 PEP 分成几个重点突出的 PEP。

每个 PEP 都必须有一个冠军——使用样式编写 PEP 的人 和下面描述的格式,引导讨论在适当的 论坛,并尝试围绕这个想法建立社区共识。PEP的 冠军(又名作者)应该首先尝试确定这个想法是否是 PEP能力。发布到 Python 话语的 Ideas 类别通常是 最好的方法,除非有更专业的场地是合适的, 例如“打字”类别(用于静态打字创意) 或 Python 话语中的打包类别(用于打包想法)。

在撰写 PEP 之前公开审查一个想法意味着 以节省潜在作者的时间。带来了许多想法 forward 用于更改已被拒绝的各种 Python 原因。首先询问 Python 社区的想法是否是原创的 有助于防止在以下事情上花费太多时间 保证根据先前的讨论被拒绝(搜索 互联网并不总是能解决问题)。它还有助于确保 这个想法适用于整个社区,而不仅仅是作者。 仅仅因为一个想法对作者来说听起来不错,并不意味着 意味着它将适用于大多数使用 Python 领域的大多数人。

一旦冠军询问 Python 社区是否 想法有任何被接受的机会,应该向 PEP 提交草案 上述适当的地点。 这让作者有机会充实草稿 PEP 使格式正确、高质量和解决 对该提案的初步担忧。

提交 PEP

在上述初步讨论之后,工作流程会根据以下因素而有所不同: PEP 的任何合著者都是核心开发人员。如果一个或多个 PEP 合著者是核心开发人员,他们负责遵循该过程 概述如下。否则(即没有一个合著者是核心开发人员), 那么 PEP 作者将需要为 PEP 找到赞助商。

理想情况下,确定核心开发人员发起人,但非核心发起人也可以 经指导委员会批准后选出。GitHub 的成员 “PEP 编辑”团队和打字委员会 (PEP 729) 的成员是 预先批准成为赞助商。赞助商的工作是 为 PEP 作者提供指导,以帮助他们完成 PEP过程(有点像导师)。成为赞助商并不会取消该人以后成为合著者或 PEP 代表的资格(但 不是两者兼而有之)。PEP 的发起人记录在 页眉。

一旦发起人或共同创作 PEP 的核心开发人员认为 PEP 准备提交时,提案应通过 GitHub 拉取请求作为 PEP 草案提交。草稿必须按照所述以 PEP 风格编写 否则将立即无法通过审核(尽管可能会出现小错误 由编辑更正)。

标准的 PEP 工作流程是:

你(PEP 作者)分叉 PEP 存储库,并创建一个名为包含新 PEP 的文件。 应该是下一个 已发布或 PR 中的 PEP 未使用的可用 PEP 编号。pep-NNNN.rstNNNN

在“PEP:”标头字段中,输入与您的文件名匹配的 PEP 编号 作为您的 PEP 编号草案。

在“Type:”标题字段中,输入“Standards Track”, “信息”或“处理”(视情况而定),对于“状态:” 字段输入“草稿”。有关完整详细信息,请参阅 PEP 标头前导码。

更新,以便任何合著者或发起人 对新文件的 PEP 存储库具有写入访问权限。 这可确保将来任何更改文件的拉取请求都将被分配 对他们来说。

将其推送到 GitHub 分支并提交拉取请求。

PEP 编辑会审查您的 PR 的结构、格式和其他 错误。对于 reST 格式的 PEP,PEP 12 作为模板提供。 它还提供了对所使用的 reST 标记的完整介绍 在 PEP 中。批准标准是:

编辑们通常对这个初步审查相当宽容, 期望问题将通过审查过程得到纠正。注意:PEP 的批准并不能保证没有 令人尴尬的错误!正确性是作者的责任 和审稿人,而不是编辑。

如果 PEP 尚未准备好获得批准,编辑会将其发回给 作者进行修改,并附有具体说明。

它是健全和完整的。这些想法必须具有技术意义。这 编辑们不考虑他们是否可能被接受。

标题准确地描述了内容。

PEP 的语言(拼写、语法、句子结构等) 代码样式(示例应与 PEP 7 和 PEP 8 匹配)应该是 正确且符合要求。将自动检查 PEP 文本 提交拉取请求时更正 reStructuredText 格式。 具有无效 reST 标记的 PEP 将不被批准。

一旦获得批准,他们将为您的 PEP 分配一个号码。

一旦审查过程完成,并且 PEP 编辑批准它(请注意 这与接受你的 PEP 不同!),他们会把你的 将请求拉到主节点上。

PEP 编辑不会无理拒绝 PEP 的发布。原因 否认 PEP 身份包括重复工作、技术上不合理、 没有提供适当的动机或解决向后兼容性问题,或者不 与 Python 理念保持一致。可以咨询指导委员会 在批准阶段,并且是草案 PEP 能力的最终仲裁者。

对 PEP 存储库具有写入权限的开发人员可以声明 PEP 通过创建和提交新的 PEP 直接编号。执行此操作时, 开发人员必须处理通常由 PEP编辑(参见下面的PEP编辑职责和工作流程)。这包括 确保初始版本符合提交 PEP。或者,即使是开发人员也应该通过拉取请求提交 PEP。 这样做时,通常需要您自己处理该过程; 如果您需要 PEP 编辑的帮助,请在 GitHub 上提及。@python/pep-editors

由于更新是必要的,PEP 作者可以在以下情况下签入新版本 (或协作开发人员)具有对 PEP 存储库的写入访问权限。 尽早分配 PEP 编号有助于轻松实现 参考,尤其是当 同时。

标准跟踪 PEP 由两部分组成,设计文档和 参考实现。通常建议至少 原型实现应与 PEP 共同开发,作为听起来不错的想法 原则上的好有时在受到 实施测试。

讨论 PEP

一旦分配了 PEP 编号 并且 PEP 草案已提交到 PEP 存储库, 应为 PEP 创建讨论线程 提供一个讨论和审查其内容的中心场所,以及 应更新 PEP,以便标头链接到它。Discussions-To

PEP 作者(或赞助商,如适用)可以选择任何合理的地点 对于讨论,只要满足以下条件:

该论坛适合 PEP 的主题。

该线程在网络上公开提供,以便所有相关方 可以参加。

讨论受 Python 社区行为准则的约束。

PEP 中提供了指向当前讨论线程的直接链接 在标题下。Discussions-To

Python Discourse 的 PEP 类别是大多数新 PEP 的首选, 而从历史上看,Python-Dev 邮件列表是常用的。 一些专业主题有特定的场所,例如 Python 上的“类型”类别和“打包”类别 分别用于打字和包装 PEP 的话语。 如果 PEP 作者不确定最佳地点, PEP 赞助商和 PEP 编辑可以为他们提供相应的建议。

如果 PEP 经历了重大的重写或其他重大的、实质性的 对其建议的规范进行更改时,通常应创建一个新线程 在选定的地点征求其他反馈。如果发生这种情况,则必须更新链接并添加新条目 指向这个新线程。Discussions-ToPost-History

如果未选择它作为讨论地点, 应该在 PEP 类别上发布一个简短的公告帖子,至少要有一个指向呈现的 PEP 和线程的链接 当 PEP 草案提交到存储库时 以及是否进行了足够大的更改以触发新线程。Discussions-To

PEP 作者负责收集社区对 PEP 的反馈 在提交审核之前。但是,为了避免啰嗦和 开放式讨论,诸如征求私人或更多等策略 在早期设计阶段进行狭隘的定制反馈, 与具有 PEP 专业知识的其他社区成员合作 主题,并为 应考虑 PEP 的主题(如果适用)。 PEP 作者应在此处自行决定。

为 PEP 分配编号并提交到 PEP 存储库后, 实质性问题一般应在规范的公众中讨论 线程,而不是专用频道、GitHub 拉取请求评审或 不相关的场所。这确保了每个人都可以关注和贡献, 避免讨论碎片化, 并确保将其作为 PEP 审查过程的一部分得到充分考虑。 对此指定主题的评论、支持、疑虑和其他反馈 是指导委员会或 PEP 代表将要做的事情的关键部分 在审查 PEP 时考虑。

PEP 审查和决议

一旦作者完成了 PEP,他们可以要求对 来自 PEP 编辑器的风格和一致性。 然而,内容审查和对 PEP 的接受最终是 指导委员会的责任,该委员会由以下机构正式发起 一旦作者(和赞助商,如果有的话)打开指导委员会问题 确定 PEP 已准备好进行最终审查和解决。

在选定的情况下加快流程(例如,当变更明确时) 有益并准备被接受,但 PEP 尚未正式提交 供审查),指导委员会也可以首先启动 PEP 审查 通知 PEP 作者并给他们一个进行修改的机会。

PEP 批准的最终机构是指导委员会。但是,每当 提出了一个新的 PEP,任何认为自己合适的核心开发人员 有经验的人可以对 PEP 可能提供作为其服务的最终决定做出最终决定 PEP-代表,通知指导委员会他们的意图。如果指导委员会批准他们的提议, 然后,PEP 代表将有权批准或拒绝该 PEP。 对于与 Python 类型系统相关的 PEP,类型委员会 (PEP 729) 向指导委员会提出建议。要请求这样的 建议,在 Typing Council 问题跟踪器上打开一个问题。

“PEP-Delegate”一词在指导委员会治理模型下使用 对于 PEP 指定的决策者, 谁被记录在 PEP 标头的“PEP-Delegate”字段中。 术语“BDFL-Deregate”是 PEP-Delegate 的已弃用别名,是 Python 由 BDFL 领导的时间。 对“BDFL-Delegate”的任何旧引用都应被视为等同于 “PEP代表”。

提出提名自己为 PEP 代表的个人必须通知 相关作者和(在场时)PEP的申办者,并提交 他们向指导委员会提出的要求 (这可以通过新问题来完成)。 承担这一责任的人可以自由地寻求 指导委员会随时提供额外的指导,预计也会得到指导 考虑其他核心开发人员的建议和观点。

指导委员会通常会默认批准此类自我提名, 但可能会选择拒绝他们。 指导委员会拒绝 自我提名为 PEP 代表包括但不限于对以下方面的看法 潜在的利益冲突(例如,在与 PEP 提交者),或者只是考虑另一个潜在的 PEP 代表 更合适。如果核心开发人员(或其他社区成员)有顾虑 关于 PEP 代表是否适合任何给定的 PEP,他们可能会问 指导委员会审查代表团。

如果没有志愿者挺身而出,那么指导委员会将接近核心 开发人员(以及潜在的其他 Python 社区成员)具有相关的 专业知识,以试图确定愿意担任的候选人 该 PEP 的 PEP 代表。如果找不到合适的候选人,则 PEP 将被标记为“延迟”,直到有可用。

先前任命的 PEP 代表可以选择辞职或被要求辞职 由理事会下属,在这种情况下,将在 与新的 PEP 相同(包括在没有合适的 PEP 的情况下推迟 PEP 可以找到替代品)。如果 PEP 代表被要求介入 下来,这将推翻任何先前对 PEP 的接受或拒绝,并且它 将恢复为草稿状态。

当这种常设代表团到位时,指导委员会将 保留足够的公共记录,以允许随后的理事会,核心 开发人员和更广泛的 Python 社区来了解 目前存在,为什么实施这些措施,以及在什么情况下实施 可能不再需要它们。

要使 PEP 被接受,它必须满足某些最低标准。它 必须清晰完整地描述建议的增强功能。 增强必须代表净改进。建议的 如果适用,实施必须是坚实的,并且不能使复杂化 口译员不恰当地。最后,建议的增强功能必须是 “pythonic”,以便被指导委员会接受。(但是, “pythonic”是一个不精确的术语;它可以被定义为任何可以接受的东西 指导委员会。这个逻辑是有意循环的。有关标准库模块验收标准,请参见 PEP 2。

除非指导委员会另有批准, PEP 决议的声明将发布到 Python 话语的 PEP 类别中。

一旦 PEP 被接受,参考实现必须 完成。当参考实现完成并合并时 进入主源代码仓库,状态将更改为“Final”。

允许在提交之前收集其他设计和接口反馈 语言功能或标准库 API(PEP)的长期稳定性 也可以标记为“临时”。这是“暂时接受”的缩写, 并表示该提案已被接受纳入参考文献 实现,但在完成完整设计之前需要额外的用户反馈 可以被认为是“最终的”。与常规接受的 PEP 不同,暂时接受 即使在相关更改发生后,PEP 仍可能被拒绝或撤回 包含在 Python 版本中。

在可能的情况下,最好缩小提案的范围 以避免依赖“临时”状态的需要(例如,通过推迟一些 功能到以后的 PEP),因为此状态可能会导致版本兼容性 更广泛的 Python 生态系统中的挑战。PEP 411 提供了更多详细信息 关于临时状态的潜在用例。

还可以为 PEP 分配“延迟”状态。PEP 作者或 当没有进展时,编辑者可以为 PEP 分配此状态 在 PEP 上。一旦 PEP 被推迟,PEP 编辑者可以重新分配它 到草稿状态。

PEP 也可以被“拒绝”。也许毕竟已经说完了 这不是一个好主意。对此进行记录仍然很重要 事实。“撤回”状态类似 - 这意味着 PEP 作者 他们自己已经决定 PEP 实际上是一个坏主意,或者已经 接受竞争性提案是更好的选择。

当 PEP 被接受、拒绝或撤回时,PEP 应更新 因此。除了更新“状态”字段外,至少 应使用直接链接添加分辨率标头 到相关职位对 PEP 做出决定。

PEP 也可以被不同的 PEP 取代,呈现原始 过时。这适用于信息性 PEP,其中版本 2 API 可以替换版本 1。

PEP 状态的可能路径如下:

1.png PEP 1 – 目的和指南  Python 教程 第1张

虽然图中未显示,但从技术上讲,“已接受”的 PEP 可能会转移到 即使在接受后仍被“拒绝”或“撤回”。只有在以下情况下才会发生这种情况 实施过程揭示了设计中的根本缺陷,这些缺陷是 在接受 PEP 之前未被注意到。与临时政治人物不同,这些 只有当已接受的提案未被包括在内时,才允许过渡 在 Python 版本中 - 已发布的更改必须通过常规 弃用过程(这可能需要一个新的 PEP 来提供 弃用)。

某些信息和流程 PEP 也可能处于“活动”状态 如果它们永远不会完成。例如 PEP 1(此 PEP)。

PEP维护

一般来说,PEP 在达到 “已接受”、“最终”、“已拒绝”或“已取代”状态。一旦达成决议, PEP 被视为历史文件,而不是活的规范。 预期行为的正式文档应保存在其他地方, 例如核心功能的语言参考、标准库模块的库参考或打包的 PyPA 规范。

如果根据实施经验和用户反馈进行更改,则对 标准跟踪 PEP 在临时或(经 SC 批准)接受时 状态,它们应该在 PEP 中注明,以便 PEP 准确地描述 在标记为 Final 的点处实现。

活动(信息和过程)PEP 可能会随着时间的推移而更新以反映 对开发实践和其他细节的更改。精准工艺 在这些情况下,遵循将取决于 PEP 的性质和目的 有问题。

有时,延期甚至撤回的 PEP 可能会复活 有重大更新,但通常最好只是提出一个新的更新。

什么是成功的 PEP?

每个 PEP 应包含以下部分/部分:

前导码 – RFC 2822 样式标头,其中包含有关 PEP,包括 PEP 编号,一个简短的描述性标题(有限 最多 44 个字符)、名称,以及可选的 每个作者的联系信息等

摘要 – 对技术问题的简短(~200 字)描述 正在解决。

动机 – 动机对于想要 更改 Python 语言、库或生态系统。它应该 清楚地解释为什么现有的语言规范是 不足以解决 PEP 解决的问题。这可以 包括从重要的 PEP 中收集文件支持 Python 生态系统中的项目。PEP 提交没有 足够的动机可能会被拒绝。

基本原理 – 基本原理通过以下方式充实规范 描述做出特定设计决策的原因。它应该 描述考虑的替代设计和相关工作, 例如,该功能在其他语言中是如何支持的。

理由应提供在 社区并讨论提出的重要反对意见或疑虑 在讨论中。

规范 – 技术规范应描述 任何新语言功能的语法和语义。这 规格应足够详细,以允许竞争, 至少当前主要 Python 的可互操作实现 平台(CPython、Jython、IronPython、PyPy)。

向后兼容性 – 所有向后引入的 PEP 不兼容必须包括描述这些的部分 不相容性及其严重性。PEP 必须解释如何 作者建议处理这些不相容性。PEP的 没有足够向后兼容性论文的提交 可能会被直接拒绝。

安全隐患 – 如果存在相关的安全问题 对 PEP 来说,这些担忧应该明确地写出来 当然,PEP 的审稿人知道它们。

如何教这个 – 对于添加新功能或更改的 PEP 语言行为,包括一个关于如何 教新老用户如何将 PEP 应用于他们的 工作。

本部分可能包括要点和推荐的文档 可帮助用户采用新功能或迁移其 代码来使用语言更改。

引用实现 – 引用实现必须是 在任何 PEP 被赋予“最终”状态之前完成,但它不需要 在接受 PEP 之前完成。虽然有优点 就规范达成共识的方法和 编写代码前的基本原理,“粗略共识”原则 和运行代码“在解决许多问题时仍然很有用 讨论 API 详细信息。

最终实现必须包括测试代码和文档 适用于 Python 语言参考或 标准库参考。

被拒绝的想法 – 在 PEP 的整个讨论过程中,各种想法 将被提议,但未被接受。那些被拒绝的想法应该 与被拒绝的原因一起记录下来。 这两者都有助于记录最终版本背后的思考过程 PEP 以及防止人们提出同样的问题 在随后的讨论中再次拒绝了这个想法。

在某种程度上,这部分可以被认为是 基本原理部分,专门针对某些想法的原因 最终没有被追究。

未解决的问题 – 当 PEP 处于草案阶段时,可能会提出以下想法 值得进一步讨论。这些想法应该被记录下来,以便人们 知道他们正在被考虑,但没有具体 分辨率。这有助于确保 PEP 所需的所有问题 准备考虑是完整的,并减少人员重复 事先讨论。

脚注 – PEP 中引用的脚注集合,以及 列出非内联超链接目标的位置。

版权/许可 – 每个新的 PEP 都必须置于双重许可之下 public domain 和 CC0-1.0-Universal(有关示例,请参阅此 PEP)。

PEP 格式和模板

PEP 是使用 reStructuredText 格式的 UTF-8 编码文本文件。 reStructuredText 允许丰富的标记,这仍然很容易 阅读,但也会产生好看且实用的 HTML。PEP 12 包含说明和 PEP 模板。

PEP 文本文件会自动转换为 HTML(通过基于 Sphinx 的构建系统) 以便于在线阅读。

PEP 标头前导码

每个 PEP 都必须以 RFC 2822 样式标头前导码开头。标头 必须按以下顺序显示。标有“*”的标题是 可选,如下所述。所有其他标头都是必需的。

PEP: <pep number>
  Title: <pep title>
  Author: <list of authors' real names and optionally, email addrs>
* Sponsor: <real name of sponsor>
* PEP-Delegate: <PEP delegate's real name>
  Discussions-To: <URL of current canonical discussion thread>
  Status: <Draft | Active | Accepted | Provisional | Deferred | Rejected |
           Withdrawn | Final | Superseded>
  Type: <Standards Track | Informational | Process>
* Topic: <Governance | Packaging | Release | Typing>
* Requires: <pep numbers>
  Created: <date created on, in dd-mmm-yyyy format>
* Python-Version: <version number>
  Post-History: <dates, in dd-mmm-yyyy format,
                 inline-linked to PEP discussion threads>
* Replaces: <pep number>
* Superseded-By: <pep number>
* Resolution: <url>

“作者”标头列出了姓名,并列出了电子邮件地址(可选) PEP 的所有作者/所有者。Author 标头的格式 值必须为:

Random J. User <random@example.com>

如果包含电子邮件地址,并且只是:

Random J. User

如果未提供地址。

如果有多个作者,则每个作者都应该在单独的行上 遵循 RFC 2822 延续行约定。请注意,个人 PEP 中的电子邮件地址将被遮挡,以防止垃圾邮件 收割机。

Sponsor 字段记录哪个开发人员(核心,或以其他方式批准 指导委员会)正在赞助 PEP。如果 PEP 的作者之一是 核心开发人员,则不需要赞助商,因此应该保留此字段 外。

PEP-Delegate 字段用于记录由 指导委员会就是否批准或 拒绝 PEP。

注意:标准跟踪 PEP 需要分辨率标头 只。它包含一个 URL,该 URL 应指向电子邮件或 其他网络资源,其中声明关于 (即批准或拒绝)PEP。

Discussions-To 标头提供指向当前 PEP 的规范讨论线程。 对于电子邮件列表,这应该是指向列表中线程的直接链接 存档,而不仅仅是 mailto: 或指向列表本身的超链接。

Type 标头指定 PEP 的类型:标准跟踪、 信息或过程。

可选的 Topic 标头列出特殊主题(如果有), PEP属于。 有关现有主题,请参阅主题索引。

Created 标头记录了为 PEP 分配 number,而 Post-History 用于记录日期和相应的日期 指向 PEP 的 Discussions-To 线程的 URL,前者为 链接文本,后者作为链接目标。 两组日期都应采用格式,例如 .dd-mmm-yyyy14-Aug-2001

标准跟踪 PEP 通常具有 Python-Version 标头,该标头 指示将随功能一起发布的 Python 版本。 标准跟踪 PEP 没有 Python-Version 标头指示 最初将通过以下方式支持的互操作性标准 外部库和工具,然后可能由以后的 PEP 补充 添加对标准库的支持。信息和流程 PEP 确实如此 不需要 Python-Version 标头。

PEP 可能有一个 Requires 标头,指示 PEP 编号 PEP 取决于。

PEP 也可能有一个 Supersed-By 标头,指示 PEP 具有 被后来的文件弄过时了;该值是 替换当前文档的 PEP。较新的 PEP 必须具有 替换包含它呈现的 PEP 编号的标头 过时。

辅助文件

PEP 可能包括辅助文件,例如图表。此类文件应为 named ,其中“XXXX”是 PEP 编号,“Y”是 序列号(从 1 开始),“ext”替换为实际的 文件扩展名(例如“png”)。pep-XXXX-Y.ext

或者,所有支持文件都可以放在名为 的子目录中,其中“XXXX”是 PEP 编号。使用子目录时,有 对文件中使用的名称没有约束。pep-XXXX

更改现有 PEP

PEP 草案可自由开放讨论和提议修改,网址为 作者的自由裁量权,直到提交给指导委员会或 PEP-代表进行审查和解决。实质性内容修改应 通常首先在其标题中列出的 PEP 讨论线程上提出,而可以提交复制编辑和更正 作为 GitHub 问题或 GitHub 拉取请求。 对 PEP 存储库具有写入访问权限的 PEP 作者可以更新 PEP 自己使用 GitHub PR 提交更改。 有关修改其他 PEP 的指导,请参阅 PEP 维护部分。Discussions-Togit push

有关更多详细信息,请参阅贡献指南,如有疑问, 请先与 PEP 作者和/或 PEP 编辑联系。

转让 PEP 所有权

有时有必要将 PEP 的所有权转让给 新冠军。一般来说,最好保留原作者作为 转移的 PEP 的合著者,但这实际上取决于 原作者。转让所有权的一个很好的理由是因为 原作者不再有时间或兴趣更新它,或者 遵循 PEP 流程,或者已经从脸上掉下来 “网络”(即无法访问或不回复电子邮件)。一个坏的 转让所有权的原因是因为作者不同意 PEP的方向。PEP 过程的一个目标是尝试构建 围绕 PEP 达成共识,但如果这是不可能的,作者总是可以 提交竞争性 PEP。

如果您有兴趣获得 PEP 的所有权,您也可以通过以下方式进行 拉取请求。分叉 PEP 存储库,修改您的所有权, 并提交拉取请求。您应该在拉取请求的评论中提及原作者和原始作者。(如果原件 作者的 GitHub 用户名未知,请使用电子邮件。如果原作者 没有及时回复,PEP编辑会做一个 单方面决定(并不是说这样的决定不能:)推翻。@python/pep-editors

PEP编辑的职责和工作流程

必须将 PEP 编辑器添加到 GitHub 上的组中,并且 必须监视 PEP 存储库。@python/pep-editors

请注意,对 PEP 存储库具有写入权限的开发人员可以 处理通常由 PEP 编辑处理的任务。 或者,即使是开发人员也可以通过以下方式向 PEP 编辑请求帮助 在 GitHub 上提及。@python/pep-editors

对于每个新的 PEP,编辑器会执行以下操作:

确保 PEP 是由核心开发人员共同创作的,并且具有核心 开发商作为赞助商,或有专门批准用于此 PEP 的赞助商 由指导委员会。

阅读 PEP 以检查它是否准备好:声音和完整。想法 必须具有技术意义,即使它们似乎不太可能 接受。

标题应准确描述内容。

文件扩展名正确(即 )。.rst

确保被列为 PEP 的发起人或合著者的每个人都有 对 PEP 存储库的访问权限已添加到 .github/CODEOWNERS。

略读 PEP 以查找语言中的明显缺陷(拼写、语法、 句子结构等)和代码风格(示例应符合 PEP 7 和 PEP 8)。编辑可以自己纠正问题,但 不需要这样做(reStructuredText 语法由存储库的 CI 检查)。

如果一个项目被描述为受益于或支持 PEP,请确保 所包含的项目有一些直接指示来提供支持 清楚。这是为了避免 PEP 意外地将项目描述为支持 一个 PEP,而实际上支持是基于猜想的。

如果 PEP 尚未准备好,编辑会将其发回给作者 修订,并附有具体说明。如果 reST 格式是 问题,请作者使用 PEP 12 作为模板并重新提交。

一旦 PEP 准备好用于存储库,PEP 编辑器将:

检查作者是否选择了有效的 PEP 编号或为其分配一个 数字,如果他们没有(几乎总是下一个可用数字,但是 有时它是一个特殊/笑话数字,例如 666 或 3141)。

请记住,低于 100 的数字是元 PEP。

检查作者是否正确标记了 PEP 的类型 (“标准跟踪”、“信息”或“流程”),并将其标记为 状态为“草稿”。

确保所有 CI 构建和 lint 检查都通过且没有错误, 并且渲染的预览输出中没有明显的问题。

合并新的(或更新的)PEP。

通知作者后续步骤(打开讨论线程并 用它更新 PEP,发布公告等)。

对现有 PEP 的更新应作为 GitHub 拉取请求提交。

许多 PEP 由具有写入权限的开发人员编写和维护 到 Python 代码库。PEP 编辑器监视 PEP 存储库 进行更改,并更正任何结构、语法、拼写或 他们看到的标记错误。

PEP 编辑不会对 PEP 做出判断。他们只是做 行政和编辑部分(这通常是一个小批量的任务)。


版权

本文档被置于公共领域或位于 CC0-1.0-通用许可证,以更宽松的许可证为准。


The End 微信扫一扫

文章声明:以上内容(如有图片或视频在内)除非注明,否则均为腾龙猫勺儿原创文章,转载或复制请以超链接形式并注明出处。

本文作者:猫勺本文链接:https://www.jo6.cn/post/1.html

上一篇 下一篇

相关阅读

发表评论

访客 访客
快捷回复: 表情:
评论列表 (有 1 条评论,162人围观)
网友昵称:猫勺
猫勺 V 博主 Google Chrome 114.0.5735.289 Windows 10 x64 沙发
02-21 回复
醍醐灌顶
取消
微信二维码
微信二维码
支付宝二维码