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：作为 JSON 字典，包含此 Pybi 在所有安装中保持静态的所有 PEP 508 环境标记变量的值。例如：
  • 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 除外：它们可能在 x86-64 或 arm64 模式下运行，我们直到实际调用解释器才知道是哪种模式，因此我们无法将其记录在静态元数据中。

  原理：在许多情况下，只要解析器能够访问目标平台的 .pybi 文件，它就应该能够让在 Linux 上运行的解析器计算 Windows 上的 Python 环境的包依赖项，反之亦然。（请注意，可以通过使用 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：安装 wheels 所需的安装路径（与 sysconfig.get_paths() 相同的键），作为从 zip 文件根目录开始的相对路径，以 JSON 字典形式。

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

  必须可以通过运行 {paths["scripts"]}/python 来调用 Python 解释器。如果存在其他解释器入口点（例如用于 Windows GUI 应用程序的 pythonw），那么它们也应该在该目录中，使用其传统名称，不带版本号。（如果需要，您也可以有一个 python3.11 符号链接；对此没有限制。只是 python 必须存在并能工作。）

  原理： Pybi-Paths 和 Pybi-Wheel-Tags（见下文）共同足以让安装程序选择 wheels 并将其安装到解压后的 pybi 环境中，而无需调用 Python。此外，我们需要在某个地方记录解释器位置，这样一石二鸟。

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

  讨论：如果安装程序能够预先计算 pybi 对应的 wheel 标签，以便它们可以将 wheels 安装到未打包的 pybi 中，而无需实际调用 python 解释器来查询其标签，那将是极好的™——既提高了效率，又允许更奇特的用例，例如从 Linux 主机设置 Windows 环境。

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

  • 标记为 manylinux_2_12_x86_64 的 pybi 始终可以使用标记为 manylinux_2_12_x86_64 的 wheels。它也可能能够使用标记为 manylinux_2_17_x86_64 的 wheels，但前提是最终安装系统具有 glibc 2.17+。
  • 标记为 macosx_11_0_universal2 (= x86-64 + arm64 支持在同一二进制文件中) 的 pybi 可能能够使用标记为 macosx_11_0_arm64 的 wheels，但前提是它安装在“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 pybi 可以使用 manylinux_2_17_x86_64 wheel，只要这些都是当前机器上有效的标签，但是 win32 pybi **不能** 使用 win_amd64 wheel，即使这些都是当前机器上有效的标签。

  • 标记为 macosx_11_0_universal2 的 pybi 可能能够使用标记为 macosx_11_0_x86_64 的 wheels，但前提是它安装在 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)

这会在 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 -> ...，造成混乱。