摘要

本文档描述了对构建后端和前端通信的扩展（如PEP 517中介绍的那样），以允许通过引入虚拟轮包来以可编辑模式安装项目。

动机

在开发过程中，许多 Python 用户更喜欢安装他们的库，以便对底层源代码和资源的更改会自动反映在后续的解释器调用中，而无需额外的安装步骤。此模式通常称为“开发模式”或“可编辑安装”。目前，没有标准化的方法来实现这一点，因为它在PEP 517中被明确排除在外，因为实际观察到的行为的复杂性。

目前，用户要获得此行为，可以执行以下操作之一

• 对于仅包含 Python 代码的情况，可以通过将相关的源目录添加到sys.path（可以通过PYTHONPATH环境变量从命令行界面配置）来实现。请注意，在这种情况下，用户必须自己安装项目依赖项，并且不会生成入口点或项目元数据。
• setuptools 提供了setup.py develop 机制：它安装一个pth文件，该文件在解释器启动时将项目根目录注入到sys.path中，生成项目元数据，并安装项目依赖项。pip 通过pip install -e命令行界面公开了调用此机制的方法。
• flit 提供了flit install –symlink 命令，该命令将项目文件符号链接到解释器的purelib文件夹中，生成项目元数据，并安装依赖项。请注意，这还允许支持资源文件。

正如这些示例所示，可编辑安装可以通过多种方式实现，目前还没有标准的方法。此外，目前尚不清楚谁应该负责实现和定义可编辑安装的含义

1. 允许构建后端定义和实现它，
2. 允许构建前端定义和实现它，
3. 明确定义和标准化可能选项中的一个方法。

本 PEP 的作者认为这里没有一刀切的解决方案，每种实现可编辑效果的方法都有其优缺点。因此，本 PEP 拒绝了选项三，因为社区不太可能就一个解决方案达成一致。此外，问题仍然存在于前端还是构建后端应该承担此责任。 PEP 660 提出由构建后端负责，而本 PEP 则主要提出由前端负责，但如果后端希望这样做，它仍然允许后端接管控制权。

基本原理

PEP 517 推迟了“可编辑安装”，因为这会延迟其进一步采用，并且当时还没有就如何实现可编辑安装达成一致。由于setuptools和pip项目的普及，现状得以保留，后端可以通过提供setup.py develop实现来实现可编辑模式，用户可以通过pip install -e触发。通过定义构建后端和前端之间的可编辑接口，我们可以消除setup.py文件及其当前的通信方法。

术语和目标

本 PEP 的目标是明确界定前端和后端的角色，并赋予每个开发人员最大能力为其用户提供有价值的功能。在本提案中，后端的角色是为可编辑安装准备项目，然后向前端提供足够的信息，以便前端能够实现和执行可编辑安装。

后端提供给前端的信息是一个符合PEP 427中现有规范的轮包。关于归档本身的轮包元数据（{distribution}-{version}.dist-info/WHEEL）还必须包含键Editable，其值为true。

但是，它不应在轮包中提供项目文件，而应提供一个editable.json文件（位于轮包的根级别），该文件定义了前端要公开的文件。此文件的内容被表述为源代码树绝对路径到方案映射中解释器目标路径的相对路径的映射。

满足前两段描述的轮包即为虚拟轮包。前端的角色是获取虚拟轮包并以可编辑模式安装项目。它实现此目标的方式完全取决于前端，并被视为实现细节。

可编辑安装模式意味着要安装的项目的源代码在本地目录中可用。一旦项目以可编辑模式安装，对本地源代码树中项目代码的一些更改将无需新的安装步骤即可生效。至少，对安装时存在的非生成文件的文本的更改应该在随后导入包时反映出来。

某些类型的更改，例如添加或修改入口点或新的依赖项，需要新的安装步骤才能生效。这些更改通常在构建后端配置文件（例如pyproject.toml）中进行。此要求与用户普遍期望一致，即此类修改仅在重新安装后才会生效。

虽然用户期望可编辑安装的行为与标准安装相同，但这并不总是可能的，并且可能与其他用户期望相冲突。根据前端实现可编辑模式的方式，可能会出现一些差异，例如在源代码树或解释器的安装路径中存在其他文件（与典型安装相比）。

前端应尽量减少可编辑安装和标准安装行为之间的差异，并记录已知的差异。

作为参考，非可编辑安装的工作原理如下

1. **开发者**正在使用一个工具，我们在这里将其称为**前端**，来驱动项目开发（例如，pip）。当用户想要触发项目的包构建和安装时，他们将与**前端**通信。
2. 前端使用**构建前端**来触发轮包的构建（例如，build）。构建前端使用PEP 517与**构建后端**（例如setuptools）通信 - 构建后端安装在PEP 518环境中。一旦被调用，后端将返回一个轮包。
3. 前端获取轮包并将其提供给**安装程序**（例如，installer），以将轮包安装到目标 Python 解释器中。

机制

本 PEP 向PEP 517后端接口添加了两个可选钩子。其中一个钩子用于指定可编辑安装的构建依赖项。另一个钩子通过构建前端返回前端创建可编辑安装所需的信息。

def get_requires_for_build_editable(config_settings=None):
    ...

def prepare_metadata_for_build_editable(metadata_directory, config_settings=None):
    ...

def build_editable(self, wheel_directory, config_settings=None,
                    metadata_directory=None):
    ...

{
  "$schema": "https://json-schema.fullstack.org.cn/draft-07/schema",
  "$id": "http://pypa.io/editables.json",
  "type": "object",
  "title": "Virtual wheel editable schema.",
  "required": ["version", "scheme"],
  "properties": {
    "version": {
      "$id": "#/properties/version",
      "type": "integer",
      "minimum": 1,
      "maximum": 1,
      "title": "The version of the schema."
    },
    "scheme": {
      "$id": "#/properties/scheme",
      "type": "object",
      "title": "Files to expose.",
      "required": ["purelib", "platlib", "data", "headers", "scripts"],
      "properties": {
        "purelib": { "$ref": "#/$defs/mapping" },
        "platlib": { "$ref": "#/$defs/mapping" },
        "data": { "$ref": "#/$defs/mapping" },
        "headers": { "$ref": "#/$defs/mapping" },
        "scripts": { "$ref": "#/$defs/mapping" }
      },
      "additionalProperties": true
    }
  },
  "additionalProperties": true,
  "$defs": {
    "mapping": {
      "type": "object",
      "description": "A mapping of source to target paths. The source is absolute path, the destination is relative path.",
      "additionalProperties": true
    }
  }
}

{
   "version": 1,
   "scheme": {
      "purelib": {"/src/tree/a.py": "tree/a.py"},
      "platlib": {},
      "data": {"/src/tree/py.typed": "tree/py.typed"},
      "headers": {},
      "scripts": {}
   }
}

{
  {"version": 1, "scheme": {"purelib": {"<project dir>": "<project dir>"}}}
}

{
   "version": 1,
   "scheme": {
      "purelib": {
        "<project dir>/.editable/_register_importer.pth": "<project dir>/_register_importer.pth".
        "<project dir>/.editable/_editable_importer.py": "<project dir>/_editable_importer.py"
      }
    }
  }
}

被拒绝的想法

此 PEP 与PEP 660存在竞争关系，并拒绝该提案，因为我们认为实现可编辑安装的机制应该在前端而不是构建后端中。此外，此方法允许生态系统使用替代方法来实现可编辑安装效果（例如，在sys.path上插入路径或符号链接，而不仅仅是暗示该 PEP 所描述的后端中的松散轮子模式）。

最重要的是，PEP 660不允许使用符号链接来公开代码和数据文件，而不扩展轮子文件标准以支持符号链接。目前尚不清楚如何扩展轮子格式以支持引用非轮子本身内的文件，而是仅在本地磁盘上可用的文件。需要注意的是，后端本身（或后端生成的代码）不得生成这些符号链接（例如，在解释器启动时），因为这会与前端对需要卸载的文件的记录冲突。

最后，PEP 660仅添加了对purelib和platlib文件的支持。它有意避免支持轮子格式支持的其他类型的信息：include、data和scripts。通过此路径，前端可以通过符号链接机制以尽力而为的方式支持这些文件（尽管此功能并非普遍可用——在 Windows 上需要启用）。我们认为，添加对这些文件类型的尽力而为的支持，而不是完全排除支持它们的可能性，是有益的。

版权

本文档置于公共领域或根据 CC0-1.0-Universal 许可证，以更具许可性的为准。