Pybi 特定的核心元数据

在给出完整细节之前，以下是一个新的 METADATA 字段的示例

Pybi-Environment-Marker-Variables: {"implementation_name": "cpython", "implementation_version": "3.10.8", "os_name": "posix", "platform_machine": "x86_64", "platform_system": "Linux", "python_full_version": "3.10.8", "platform_python_implementation": "CPython", "python_version": "3.10", "sys_platform": "linux"}
Pybi-Paths: {"stdlib": "lib/python3.10", "platstdlib": "lib/python3.10", "purelib": "lib/python3.10/site-packages", "platlib": "lib/python3.10/site-packages", "include": "include/python3.10", "platinclude": "include/python3.10", "scripts": "bin", "data": "."}
Pybi-Wheel-Tag: cp310-cp310-PLATFORM
Pybi-Wheel-Tag: cp310-abi3-PLATFORM
Pybi-Wheel-Tag: cp310-none-PLATFORM
Pybi-Wheel-Tag: cp39-abi3-PLATFORM
Pybi-Wheel-Tag: cp38-abi3-PLATFORM
Pybi-Wheel-Tag: cp37-abi3-PLATFORM
Pybi-Wheel-Tag: cp36-abi3-PLATFORM
Pybi-Wheel-Tag: cp35-abi3-PLATFORM
Pybi-Wheel-Tag: cp34-abi3-PLATFORM
Pybi-Wheel-Tag: cp33-abi3-PLATFORM
Pybi-Wheel-Tag: cp32-abi3-PLATFORM
Pybi-Wheel-Tag: py310-none-PLATFORM
Pybi-Wheel-Tag: py3-none-PLATFORM
Pybi-Wheel-Tag: py39-none-PLATFORM
Pybi-Wheel-Tag: py38-none-PLATFORM
Pybi-Wheel-Tag: py37-none-PLATFORM
Pybi-Wheel-Tag: py36-none-PLATFORM
Pybi-Wheel-Tag: py35-none-PLATFORM
Pybi-Wheel-Tag: py34-none-PLATFORM
Pybi-Wheel-Tag: py33-none-PLATFORM
Pybi-Wheel-Tag: py32-none-PLATFORM
Pybi-Wheel-Tag: py31-none-PLATFORM
Pybi-Wheel-Tag: py30-none-PLATFORM
Pybi-Wheel-Tag: py310-none-any
Pybi-Wheel-Tag: py3-none-any
Pybi-Wheel-Tag: py39-none-any
Pybi-Wheel-Tag: py38-none-any
Pybi-Wheel-Tag: py37-none-any
Pybi-Wheel-Tag: py36-none-any
Pybi-Wheel-Tag: py35-none-any
Pybi-Wheel-Tag: py34-none-any
Pybi-Wheel-Tag: py33-none-any
Pybi-Wheel-Tag: py32-none-any
Pybi-Wheel-Tag: py31-none-any
Pybi-Wheel-Tag: py30-none-any

规范

• Pybi-Environment-Marker-Variables：所有在安装此 Pybi 时保持静态的 PEP 508 环境标记变量的值，以 JSON 字典形式表示。例如
  • python_version 将始终存在，因为 Python 3.10 包始终具有 python_version == "3.10"。
  • platform_version 通常不会存在，因为它提供了有关 Python 运行所在操作系统的详细信息，例如

    #60-Ubuntu SMP Thu May 6 07:46:32 UTC 2021
    

    platform_release 存在类似问题。

  • platform_machine 通常会存在，但 macOS universal2 pybi 除外：这些 pybi 可以在 x86-64 或 arm64 模式下运行，我们只有在实际调用解释器时才知道哪个模式，因此我们无法在静态元数据中记录它。

  **理由：**在许多情况下，这应该允许在 Linux 上运行的解析器计算 Windows 上 Python 环境的包固定，反之亦然，只要解析器可以访问目标平台的 .pybi 文件。（请注意，可以使用 python_full_version 值检查 Requires-Python 约束。）虽然我们有时必须省略一些键，但它们要么相当无用（platform_version、platform_release），要么可以由解析器重建（platform_machine）。

  标记通常也是有用的信息。例如，如果您有一个 pypy3-7.3.2 pybi，并且您想知道它支持哪个版本的 Python 语言，那么该信息记录在 python_version 标记中。

  （注意：我们可能希望弃用/删除 platform_version 和 platform_release？它们存在问题，我无法找到任何它们有用的情况。但这不在本 PEP 的范围内。）

• Pybi-Paths：安装 wheel 所需的安装路径（与 sysconfig.get_paths() 中的键相同），以从 zip 文件根目录开始的相对路径形式表示，以 JSON 字典形式表示。

  这些路径**必须**以 Unix 格式编写，使用正斜杠作为分隔符，而不是反斜杠。

  必须能够通过运行 {paths["scripts"]}/python 来调用 Python 解释器。如果有其他解释器入口点（例如 Windows GUI 应用程序的 pythonw），那么它们也应该位于该目录下，使用其常规名称，并且不附加版本号。（如果需要，您也可以拥有一个 python3.11 符号链接；没有规则禁止这样做。只是 python 必须存在并工作。）

  **理由：**Pybi-Paths 和 Pybi-Wheel-Tag（见下文）一起足以让安装程序选择 wheel 并将其安装到解压的 pybi 环境中，而无需调用 Python。此外，我们需要在某处写下解释器的位置，所以一举两得。

• Pybi-Wheel-Tag：此解释器支持的 wheel 标签，按优先级排序（最优先的排在最前面，最不优先的排在最后），但特殊平台标签 PLATFORM 应该替换任何依赖于最终安装系统的平台标签。

  **讨论：**如果安装程序能够提前计算 pybi 的对应 wheel 标签，那将非常棒™，这样它们就可以将 wheel 安装到解压的 pybi 中，而无需实际调用 Python 解释器来查询其标签——这既是为了效率，也为了允许更奇特的用例，例如从 Linux 主机设置 Windows 环境。

  但不幸的是，无法提前计算 Python 安装支持的完整平台标签集，因为它们可能依赖于最终系统

  • 标记为 manylinux_2_12_x86_64 的 pybi 始终可以使用标记为 manylinux_2_12_x86_64 的 wheel。它也**可能**能够使用标记为 manylinux_2_17_x86_64 的 wheel，但前提是最终安装系统具有 glibc 2.17+。
  • 标记为 macosx_11_0_universal2（= 在同一个二进制文件中支持 x86-64 和 arm64）的 pybi 可能能够使用标记为 macosx_11_0_arm64 的 wheel，但前提是它安装在“Apple Silicon”机器上并在 arm64 模式下运行。

  在这两种情况下，安装工具仍然可以通过计算本地平台标签、从 Pybi-Wheel-Tag 获取 wheel 标签模板以及将实际支持的平台替换为魔术字符串 PLATFORM 来计算合适的 wheel 标签集。

  但是，还有其他更复杂的情况

  • 您可以在（通常）在 64 位 Windows 上运行 32 位和 64 位应用程序。因此，pybi

    安装程序可能会将当前平台上允许的 pybi 标签集计算为 [win32、win_amd64]。但是，您不能只获取该集合并将其替换到 pybi 的 wheel 标签模板中，否则会得到无意义的结果

    [
      "cp39-cp39-win32",
      "cp39-cp39-win_amd64",
      "cp39-abi3-win32",
      "cp39-abi3-win_amd64",
      ...
    ]
    

    为了处理这个问题，安装程序需要以某种方式理解，只要 manylinux_2_12_x86_64 和 manylinux_2_17_x86_64 在当前机器上都是有效的标签，manylinux_2_12_x86_64 pybi 就可以使用 manylinux_2_17_x86_64 wheel，但是 win32 pybi**不能**使用 win_amd64 wheel，即使它们在当前机器上都是有效的标签。

  • 一个标记为 macosx_11_0_universal2 的 pybi 或许能够使用标记为 macosx_11_0_x86_64 的 wheel，但前提是它安装在 x86-64 机器上 *或者* 安装在 ARM 机器上 *并且* 解释器使用特殊的咒语来告诉 macOS 以 x86-64 模式运行二进制文件。因此，安装程序计划如何调用 pybi 也很重要！

  所以，实际上使用 Pybi-Wheel-Tag 值并没有看起来那么简单，它们可能只在相当复杂的工具中才有用。但是，智能的 pybi 安装程序已经需要理解很多这些平台兼容性问题才能选择一个可用的 pybi，并且对于跨平台固定/环境构建的情况，用户可以提供任何必要的信息来明确他们目标的平台。因此，将其包含在 PyBI 元数据中仍然很有用——不认为它有用的工具可以简单地忽略它。

您可能可以通过在构建的解释器上运行此脚本生成这些元数据值

import packaging.markers
import packaging.tags
import sysconfig
import os.path
import json
import sys

marker_vars = packaging.markers.default_environment()
# Delete any keys that depend on the final installation
del marker_vars["platform_release"]
del marker_vars["platform_version"]
# Darwin binaries are often multi-arch, so play it safe and
# delete the architecture marker. (Better would be to only
# do this if the pybi actually is multi-arch.)
if marker_vars["sys_platform"] == "darwin":
    del marker_vars["platform_machine"]

# Copied and tweaked version of packaging.tags.sys_tags
tags = []
interp_name = packaging.tags.interpreter_name()
if interp_name == "cp":
    tags += list(packaging.tags.cpython_tags(platforms=["xyzzy"]))
else:
    tags += list(packaging.tags.generic_tags(platforms=["xyzzy"]))

tags += list(packaging.tags.compatible_tags(platforms=["xyzzy"]))

# Gross hack: packaging.tags normalizes platforms by lowercasing them,
# so we generate the tags with a unique string and then replace it
# with our special uppercase placeholder.
str_tags = [str(t).replace("xyzzy", "PLATFORM") for t in tags]

(base_path,) = sysconfig.get_config_vars("installed_base")
# For some reason, macOS framework builds report their
# installed_base as a directory deep inside the framework.
while "Python.framework" in base_path:
    base_path = os.path.dirname(base_path)
paths = {key: os.path.relpath(path, base_path).replace("\\", "/") for (key, path) in sysconfig.get_paths().items()}

json.dump({"marker_vars": marker_vars, "tags": str_tags, "paths": paths}, sys.stdout)

这会在标准输出上输出一个 JSON 字典，其中包含每个 pybi 特定标签集的单独条目。

在 zip 文件中表示符号链接

在 zip 文件中表示符号链接的事实标准是 Info-Zip 符号链接扩展，其工作原理如下

• 符号链接的目标路径被存储为文件内容。
• Unix 权限字段的前 4 位设置为 0xa，即：permissions & 0xf000 == 0xa000
• Unix 权限字段反过来存储为“外部属性”字段的前 16 位。

因此，如果使用 Python 的 zipfile 模块，您可以通过执行以下操作来检查 ZipInfo 是否表示符号链接

(zip_info.external_attr >> 16) & 0xf000 == 0xa000

或者如果使用 Rust 的 zip crate，则等效检查为

fn is_symlink(zip_file: &zip::ZipFile) -> bool {
    match zip_file.unix_mode() {
        Some(mode) => mode & 0xf000 == 0xa000,
        None => false,
    }
}

如果您在 Unix 上，您的 zip 和 unzip 命令可能已经理解了此格式。

在 RECORD 文件中表示符号链接

通常，RECORD 文件列出每个文件 + 其哈希值 + 其长度

my/favorite/file,sha256=...,12345

对于符号链接，我们改为写入

name/of/symlink,symlink=path/to/symlink/target,

也就是说：我们使用一个名为 symlink 的特殊“哈希函数”，然后将实际的符号链接目标存储为“哈希值”。长度留空。

理由：我们已经承诺 RECORD 文件包含对主存档中所有内容的冗余检查，因此对于符号链接，我们至少需要存储某种哈希值，以及某种标志来指示这是一个符号链接。鉴于符号链接目标字符串的大小与哈希值大致相同，我们不妨直接存储它们。这还使符号链接信息更容易被不理解 Info-Zip 符号链接扩展的工具访问，并使在 Windows 系统上无损解包和重新打包 Unix pybi 成为可能，这在某些时候可能会派上用场。

在 pybi 文件中存储符号链接

当 pybi 创建者存储符号链接时，他们 *必须* 使用上面定义的两种机制：使用 Info-Zip 表示法直接将其存储在 zip 存档中，以及在 RECORD 文件中记录它。

Pybi 使用者 *应该* 验证存档和 RECORD 文件中的符号链接是否一致。

我们还考虑过 *只* 使用 RECORD 文件来存储符号链接，但随后普通的 unzip 工具将无法解包它们，这将使从 shell 脚本安装 pybi 变得困难。

限制

符号链接带来了许多潜在的混乱。为了控制局势，我们施加以下限制

• 符号链接 *不得* 用于针对 Windows 或其他缺少一流符号链接支持的平台的 .pybi 中。
• 符号链接 *不得* 用于 pybi-info 目录内。（理由：没有必要，并且它简化了需要从 pybi-info 中提取信息而无需解压缩整个存档的解析器。）
• 符号链接目标 *必须* 是相对路径，并且 *必须* 在 pybi 目录内。
• 如果 A/B/... 在存档中被记录为符号链接，则存档中 *不得* 有任何其他条目命名为 A/B/.../C。

  例如，如果一个存档有一个符号链接 foo -> bar，然后在存档的后面有一个名为 foo/blah.py 的普通文件，那么一个简单的解包器可能会最终写入一个名为 bar/blah.py 的文件。不要天真。

解包器 *必须* 验证是否遵循这些规则，因为如果没有这些规则，攻击者可以创建像 foo -> /etc/passwd 或 foo -> ../../../../../etc + foo/passwd -> ... 这样的恶意符号链接并造成破坏。