不稳定 C API 层

Python C-API 目前分为三个稳定性层级

• 有限 API，具有高度兼容性预期
• 公共 API，遵循向后兼容性策略，在更改前需要弃用警告
• 内部（私有）API，可随时更改。

需要访问 CPython 内部工具（例如高级调试器和 JIT 编译器）的工具通常是为 CPython 的次要系列版本构建的，并假设所使用的 C-API 内部在补丁版本中不会改变。为了支持这些工具，我们需要在公共和私有 C-API 之间设置一个层级，保证在整个次要系列版本中的稳定性：即拟议的不稳定层级。

一些函数，例如 PyCode_New()，被文档化为不稳定（“直接调用[它]可能会使您绑定到精确的 Python 版本”），并且在实践中也经常发生变化。不稳定层级应该使其状态显而易见，即使对于那些不仔细阅读文档的人来说也是如此，从而使它们难以意外使用。

为私有 API 保留前导下划线

目前，CPython 开发者对 API 名称中前导下划线的确切含义存在分歧。它被用来表示两种不同的事物

• 在次要版本之间可能更改的 API，如这里提出的不稳定层级（例如，PEP 523 中引入的函数）。
• 私有 API，完全不应在 CPython 之外使用（例如，因为它可能在不通知的情况下更改，或者它依赖于非 CPython 代码无法保证的未文档化假设）。

不明确的含义使得下划线不如它应有的有用。如果它只标记私有 API，CPython 开发者可以更改带下划线的函数，或删除未使用的函数，而无需研究它们在 CPython 之外如何文档化或使用。

随着专用不稳定层级的引入，我们可以阐明前导下划线的含义。它应该只标记私有 API。

避免不必要地破坏代码

本 PEP 规定不稳定层级中的 API 应具有特殊的名称前缀。这意味着函数（宏等）将需要重命名。重命名后，旧名称应继续可用，直到发生不兼容的更改（即，直到调用站点无论如何都需要更新）。换句话说，仅仅更改函数的层级不应破坏用户的代码。

前导下划线

带有前导下划线的 C API，以及仅在 Py_BUILD_CORE 可用时才可用的 API，将被视为内部。这意味着

• 它可能在次要版本（3.x.0，包括 3.x.0 的 Alpha 和 Beta 版本）中未经通知而改变或删除。补丁版本或发布候选版本中的 API 更改应仅在绝对必要时进行。
• 它应仅在源代码注释或开发指南中记录，而不应在公共文档中记录。
• 在 Python 3.12 之前引入的已文档化或在外部广泛使用的 API 应如上所述移动到不稳定层级。

  这可能在本 PEP 被接受后很久才发生。因此，在未来几年中，核心开发者在更改带下划线的 API 之前应进行一些研究，特别是如果它不需要 Py_BUILD_CORE。

鼓励 C API 用户在其代码库中搜索 _Py 和 _PY 标识符前缀，并将任何命中视为最终需要修复的问题 – 或者通过切换到现有替代方案，或者通过打开 CPython 问题来请求为其用例公开公共 API，并最终切换到该 API。

初始不稳定 API

以下 API 将在初始实现中移至不稳定层级，作为概念验证。

代码对象构造函数

• PyUnstable_Code_New() (从 PyCode_New 重命名)
• PyUnstable_Code_NewWithPosOnlyArgs() (从 PyCode_NewWithPosOnlyArgs 重命名)

代码额外信息 (PEP 523)

• PyUnstable_Eval_RequestCodeExtraIndex() (从 _PyEval_RequestCodeExtraIndex 重命名)
• PyUnstable_Code_GetExtra() (从 _PyCode_GetExtra 重命名)
• PyUnstable_Code_SetExtra() (从 _PyCode_SetExtra 重命名)

预计在 Python 3.12 中会有更多，无需另一个 PEP。

无特殊前缀

在本 PEP 的初始版本中，不稳定 API 没有 PyUnstable 前缀。相反，定义 Py_USING_UNSTABLE_API 会使 API 在给定的源文件中可用，表明承认该文件作为一个整体可能需要针对每个 Python 版本进行重新审视。

然而，后来决定不稳定性质需要通过单独的名称来公开。

下划线前缀

可以同时用前导下划线标记私有和不稳定 API。然而，这会稀释 _Py 前缀的含义。将前缀仅保留给内部 API，使其搜索变得轻而易举。

新的头文件目录

其他 API 层级有专门的头文件目录（Include/cpython/, Include/internal/）。

由于不稳定层级使用非常明显的命名约定，并且名称始终可用，因此像 Include/unstable/ 这样的目录是不必要的。

Python API

在 Python（而非 C）API 中添加类似的层级可能很好，例如对于 types.CodeType。然而，实现机制需要不同。这超出了本 PEP 的范围。