PYTHON-UTILS-R1.ECLASS

章节: eclass-manpages (5)
更新: 2024年11月
索引返回主内容

名称

python-utils-r1.eclass - 用于包含 Python 部分的软件包的实用程序函数。

描述

一个实用程序 eclass，提供查询 Python 实现、安装 Python 模块和脚本的函数。

此 eclass 不会设置任何元数据变量，也不会导出任何阶段函数。它可以安全地继承。

有关更多信息，请参阅 Python 指南：https://projects.gentoo.org/python/guide/

支持的 EAPIS

7 8

函数

python_get_stdlib [<impl>]

获取并打印给定实现的“stdlib”路径。如果未提供实现，则将使用 ${EPYTHON}。

python_get_sitedir [<impl>]

获取并打印给定实现的“site-packages”路径。如果未提供实现，则将使用 ${EPYTHON}。

python_get_includedir [<impl>]

获取并打印给定实现的包含路径。如果未提供实现，则将使用 ${EPYTHON}。

python_get_library_path [<impl>]

获取并打印给定实现的 Python 库路径。如果未提供实现，则将使用 ${EPYTHON}。

请注意，此函数只能与 CPython 一起使用。在其他实现中使用会导致致命错误。

python_get_CFLAGS [<impl>]

获取并打印针对给定实现的 Python 构建的编译器标志。如果未提供实现，则将使用 ${EPYTHON}。

请注意，此函数只能与 CPython 一起使用。它需要安装 Python 和 pkg-config，因此需要在 ebuild 中添加适当的构建时依赖项。

python_get_LIBS [<impl>]

获取并打印针对给定实现的 Python 链接的编译器标志。如果未提供实现，则将使用 ${EPYTHON}。

请注意，此函数只能与 CPython 一起使用。它需要安装 Python 和 pkg-config，因此需要在 ebuild 中添加适当的构建时依赖项。

python_get_PYTHON_CONFIG [<impl>]

获取并打印给定实现的 PYTHON_CONFIG 位置。如果未提供实现，则将使用 ${EPYTHON}。

请注意，此函数只能与 CPython 一起使用。它需要安装 Python，因此需要在 ebuild 中添加适当的构建时依赖项。

python_get_scriptdir [<impl>]

获取并打印给定实现的脚本安装路径。如果未提供实现，则将使用 ${EPYTHON}。

python_optimize [<directory>...]

编译并优化指定目录（绝对路径）中的 Python 模块。如果未提供目录，则使用默认系统路径（以 ${D} 为前缀）。

python_scriptinto <new-path>

设置传递给 python_doexe()、python_doscript()、python_newexe() 和 python_newscript() 的文件将要安装到的目录。新值需要相对于安装根目录 (${ED})。

如果未显式设置，则目录默认为 /usr/bin。

示例

src_install() {
  python_scriptinto /usr/sbin
  python_foreach_impl python_doscript foo
}

python_doexe <files>...

将给定的可执行文件安装到可执行文件安装目录中，用于当前 Python 实现 (${EPYTHON})。

可执行文件将针对 Python 实现进行正确包装，但不会执行 shebang 转换。

python_newexe <path> <new-name>

将给定的可执行文件安装到可执行文件安装目录中，用于当前 Python 实现 (${EPYTHON})。

可执行文件将针对 Python 实现进行正确包装，但不会执行 shebang 转换。它将重命名为 <new-name>。

python_doscript <files>...

将给定的脚本安装到可执行文件安装目录中，用于当前 Python 实现 (${EPYTHON})。

所有指定的文件必须以“python”shebang 开头。shebang 将被转换，并且文件将针对 Python 实现进行正确包装。

示例

src_install() {
  python_foreach_impl python_doscript ${PN}
}

python_newscript <path> <new-name>

将给定的脚本安装到当前 Python 实现 (${EPYTHON}) 的可执行文件安装目录中，并将其命名为 <new-name>。

该文件必须以“python”shebang 开头。shebang 将被转换，并且文件将针对 Python 实现进行正确包装。它将重命名为 <new-name>。

示例

src_install() {
  python_foreach_impl python_newscript foo.py foo
}

python_moduleinto <new-path>

为 python_domodule() 设置 Python 模块安装目录。<new-path> 可以是绝对的目标系统路径（在这种情况下，它需要以斜杠开头，并且 ${ED} 将被附加到它前面）或相对于实现的 site-packages 目录（然后它不能以斜杠开头）。可以使用 Python 包表示法（用点分隔）或目录表示法（使用斜杠）指定相对路径。

如果未显式设置，则模块安装到顶级 site-packages 目录。

在相对情况下，确切的路径由每个 python_domodule 调用直接确定。因此，可以在建立 Python 解释器之前安全地调用 python_moduleinto，或者可以使用单个调用为多个实现正确设置路径，如下例所示。

示例

src_install() {
  python_moduleinto bar
  # installs ${PYTHON_SITEDIR}/bar/baz.py
  python_foreach_impl python_domodule baz.py
}

python_domodule <files>...

将给定的模块（或包）安装到当前 Python 模块安装目录中。该列表可以同时提及模块（文件）和包（目录）。所有列出的文件都将为所有启用的实现安装，并在之后编译。

在 src_install() 阶段运行时，文件安装到 ${D} 中。否则，它们将安装到 ${BUILD_DIR}/install 位置，该位置适合在 PEP517 模式下由 distutils-r1 获取。

示例

src_install() {
  # (${PN} being a directory)
  python_foreach_impl python_domodule ${PN}
}

python_doheader <files>...

将给定的头文件安装到特定于实现的包含目录中。此函数是无条件递归的，即您可以传递目录而不是文件。

示例

src_install() {
  python_foreach_impl python_doheader foo.h bar.h
}

python_fix_shebang [-f|--force] [-q|--quiet] <path>...

将 Python 脚本中的 shebang 替换为当前 Python 实现（PYTHON，包括 EPREFIX）的完整路径。如果传递了目录，则递归地处理在目录树中找到的所有 Python 脚本。

只有具有 Python shebang（任何已知 Python 解释器的路径，前面可以选择性地加上 env(1) 调用）的文件才会被处理。具有任何其他 shebang 的文件将被静默跳过（如果传递了目录），或者对于任何未明确指定 Python shebang 的文件将报告错误。

与当前 Python 版本兼容的 Shebang 将被无条件转换。不兼容的 shebang 将导致致命错误，除非指定了 --force。

--force 使函数替换与不兼容的 Python 版本的 shebang（但不替换非 Python shebang）。--quiet 使函数不详细列出已修改的文件。

python_export_utf8_locale

尝试在 LC_CTYPE 变量中导出可用的 UTF-8 区域设置。如果定义了 LC_ALL，或者当前区域设置使用 UTF-8 字符集，则不执行任何操作。这可用于解决 python3 的古怪 open() 行为。

返回值：成功时为 0，失败时为 1。

build_sphinx <directory>

在指定的 <directory> 中使用 dev-python/sphinx 构建 HTML 文档。负责禁用 Intersphinx 并附加到 HTML_DOCS。

如果 <directory> 相对于当前目录，则需要小心地从同一目录（通常是 ${S}）运行 einstalldocs。

EPYTEST_DESELECT

指定要通过 pytest 的 --deselect 参数取消选择的测试数组，在调用 epytest 时。该列表可以包含文件路径、特定的测试函数或参数化测试调用。

请注意，列出的文件仍将受到收集，即在全局范围内导入的模块需要可用。如果不需要，则可以使用 EPYTEST_IGNORE 代替。

EPYTEST_IGNORE

指定要通过 pytest 的 --ignore 参数忽略的路径数组，在调用 epytest 时。列出的文件将完全跳过测试收集。

epytest [<args>...]

运行 pytest，传递标准的 pytest 选项集，然后根据 EPYTEST_DESELECT 和 EPYTEST_IGNORE 传递 --deselect 和 --ignore 选项，然后是用户指定的选项。

此命令在失败时退出并尊重 nonfatal。

eunittest [<args>...]

使用 dev-python/unittest-or-fail 运行单元测试，传递标准选项集，然后是用户指定的选项。

此命令在失败时退出并尊重 nonfatal。

python_has_version [-b|-d|-r] <atom>...

一个用于 has_version() 的便利包装器，具有详细输出和更好的默认值，用于在 python_check_deps() 中使用。

包装器接受 -b/-d/-r 选项以指示执行查找的根目录。与 has_version 不同，默认值为 -b。

包装器接受多个包规范。为了使检查成功，*所有*指定的原子都必须匹配。

ECLASS 变量

PYTHON

当前 Python 解释器的绝对路径。

此变量在以下上下文中自动设置

python-r1：在 python_foreach_impl() 调用的函数中或调用 python_setup() 后设置。

python-single-r1：在调用 python-single-r1_pkg_setup() 后设置。

distutils-r1：在任何 python 子阶段函数中设置。

示例值

/usr/bin/python2.7

EPYTHON

当前 Python 解释器的可执行文件名。

此变量在以下上下文中自动设置

python-r1：在 python_foreach_impl() 调用的函数中或调用 python_setup() 后设置。

python-single-r1：在调用 python-single-r1_pkg_setup() 后设置。

distutils-r1：在任何 python 子阶段函数中设置。

示例值

python2.7

EPYTEST_TIMEOUT

如果设置为非空值，则启用 pytest-timeout 插件并将测试超时设置为指定值。此变量可以在已知挂起的 ebuild 中设置，或者由用户设置以防止在自动测试环境中挂起。如果在 distutils-r1 中调用 distutils_enable_tests 之前设置了此变量，则会自动添加对 dev-python/pytest-timeout 的测试依赖项。

EPYTEST_XDIST

如果设置为非空值，则通过 pytest-xdist 插件启用并行运行测试。如果在 distutils-r1 中调用 distutils_enable_tests 之前设置了此变量，则会自动添加对 dev-python/pytest-xdist 的测试依赖项。

EPYTEST_JOBS (用户变量)

指定并行 (pytest-xdist) 测试运行的作业数。如果未设置，则默认为 MAKEOPTS 中的 -j，或当前的 nproc。

EPYTEST_FLAGS (用户变量)

要传递给 pytest 的其他标志。这旨在在调试软件包时在环境中设置（此处 -x 或 -s 等选项很有用），而不是全局设置。它不能在 ebuild 中设置。