Python requires

介绍

python_requires 特性是一种在不同配方之间共享文件和代码的非常便捷的方式。Python require 是一种特殊的配方,它不创建包,仅用于被其他配方复用。

一个我们想要复用的非常简单的配方可以是

from conan import ConanFile

myvar = 123

def myfunct():
    return 234

class Pkg(ConanFile):
    name = "pyreq"
    version = "0.1"
    package_type = "python-require"

然后我们可以使用 conan create . 命令将其提供给其他包。请注意,python-require 包不创建二进制文件,它仅仅是配方部分。

$ conan create .
# It will only export the recipe, but will NOT create binaries
# python-requires do NOT have binaries

我们可以通过在 python_requires 属性中声明依赖来复用上述配方功能,并且可以使用 self.python_requires["<name>"].module 访问其成员。

from conan import ConanFile

class Pkg(ConanFile):
    name = "pkg"
    version = "0.1"
    python_requires = "pyreq/0.1"

    def build(self):
        v = self.python_requires["pyreq"].module.myvar  # v will be 123
        f = self.python_requires["pyreq"].module.myfunct()  # f will be 234
        self.output.info(f"{v}, {f}")
$ conan create .
...
pkg/0.1: 123, 234

Python requires 也可以使用版本范围,如果这些 python-requires 需要随着时间演进,在许多情况下建议这样做。

from conan import ConanFile

class Pkg(ConanFile):
    python_requires = "pyreq/[>=1.0 <2]"

也可以使用 python_requires = "pyreq/0.1", "other/1.2" 来引用多个 python-requires

扩展基类

一个常见的用例是声明一个基类,其中包含我们希望通过继承在多个配方中复用的方法。我们将在 python-requires 包中编写这个基类:

from conan import ConanFile

class MyBase:
    def source(self):
        self.output.info("My cool source!")
    def build(self):
        self.output.info("My cool build!")
    def package(self):
        self.output.info("My cool package!")
    def package_info(self):
        self.output.info("My cool package_info!")

class PyReq(ConanFile):
    name = "pyreq"
    version = "0.1"
    package_type = "python-require"

并使其可供复用:

$ conan create .

请注意,配方文件中有两个类:

  • MyBase 是用于继承的类,它不扩展 ConanFile

  • PyReq 定义了当前正在导出的包,它是引用 pyreq/0.1 的配方。

一旦我们想要复用的基类包可用,我们就可以在其他配方中使用它来继承该基类的功能。我们需要像之前一样声明 python_requires,并且需要在 python_requires_extend 属性中告知 Conan 要使用的基类。在这里,我们的配方将继承自 MyBase 类。

from conan import ConanFile

class Pkg(ConanFile):
    name = "pkg"
    version = "0.1"
    python_requires = "pyreq/0.1"
    python_requires_extend = "pyreq.MyBase"

由此产生的继承等同于将我们的 Pkg 类声明为 class Pkg(pyreq.MyBase, ConanFile)。因此,创建包时,我们可以看到基类中的方法是如何被复用的。

$ conan create .
...
pkg/0.1: My cool source!
pkg/0.1: My cool build!
pkg/0.1: My cool package!
pkg/0.1: My cool package_info!
...

一般来说,基类属性不会被继承,应尽可能避免使用。对于其中一些属性,例如 export()set_version(),有方法替代方案。对于特殊情况,请参阅 init() 方法文档,了解有关扩展继承属性的更多信息。

可以使用 Python 的 super() 语法重新实现基类中的一些方法,也可以显式调用基类方法。

from conan import ConanFile

class Pkg(ConanFile):
    name = "pkg"
    version = "0.1"
    python_requires = "pyreq/0.1"
    python_requires_extend = "pyreq.MyBase"

    def source(self):
        super().source()  # call the base class method
        self.output.info("MY OWN SOURCE") # Your own implementation

不强制调用基类方法,不调用 super() 进行完全覆盖是可行的。此外,调用顺序也可以更改,先调用自己的代码再调用 super() 也是可行的。

复用文件

可以访问与 python_requires 一起使用的配方导出的文件。我们可以有这个配方,以及一个包含“Hello”文本的 myfile.txt 文件。

from conan import ConanFile

class PyReq(ConanFile):
    name = "pyreq"
    version = "1.0"
    package_type = "python-require"
    exports = "*"
$ echo "Hello" > myfile.txt
$ conan create .

一旦 python-require 被创建,我们就可以使用 path 属性访问其路径(即 myfile.txt 所在的位置)。

import os

from conan import ConanFile
from conan.tools.files import load

class Pkg(ConanFile):
    python_requires = "pyreq/0.1"

    def build(self):
        pyreq_path = self.python_requires["pyreq"].path
        myfile_path = os.path.join(pyreq_path, "myfile.txt")
        content = load(self, myfile_path)  # content = "Hello"
        self.output.info(content)
        # we could also copy the file, instead of reading it

请注意,只有 exports 适用于这种情况,而 exports_sources 不适用。

测试 python-requires

可以通过在 test_package 中添加 test_package/conanfile.py 来测试 python_require

conanfile.py
from conan import ConanFile

def mynumber():
    return 42

class PyReq(ConanFile):
    name = "pyreq"
    version = "1.0"
    package_type = "python-require"
test_package/conanfile.py
from conan import ConanFile

class Tool(ConanFile):

    # Literal "tested_reference_str", Conan will dynamically replace it
    python_requires = "tested_reference_str"

    def test(self):
        pyreq = self.python_requires["pyreq"].module
        mynumber = pyreq.mynumber()
        self.output.info("{}!!!".format(mynumber))

从 Conan 2.1 开始,python_requires = "tested_reference_str" 是强制性的。没有此声明的 python_requires 自动注入已被弃用,并将在未来版本中移除。

请注意,test_package/conanfile.py 不需要任何类型的 python_requires 声明,这是自动隐式完成的。我们现在可以使用以下命令创建并测试它:

$ conan create .
...
pyreq/0.1 (test package): 42!!!

对 package_id 的影响

python_requires 将影响使用这些依赖项的消费包package_id。默认情况下,策略是 minor_mode,这意味着:

  • Python require 的修订版patch 版本更改不会影响包 ID。因此,依赖于 "pyreq/1.2.3""pyreq/1.2.4" 将导致相同的包 ID(两者在哈希计算中都将映射到 "pyreq/1.2.Z")。如果您想更改您的公共代码,但又不想影响消费者或触发依赖项的重新构建,请提升 patch 版本。

  • minor 版本的更改将产生不同的包 ID。因此,如果您依赖 "pyreq/1.2.3",并且将版本提升到 "pyreq/1.3.0",那么您将需要构建使用该新 python-require 的新二进制文件。如果您想确保要求此 python-require 的包将使用代码中的这些更改进行构建,请提升 minor 或 major 版本。

在大多数情况下,使用版本范围 python_requires = "pyreq/[>=1.0 <2.0]" 是正确的方法,因为这意味着不包括 major 版本提升,因为它们需要消费者自身进行更改。这样就可以发布 pyreq/2.0 的新 major 版本,并让消费者逐步将其要求更改为 python_requires = "pyreq/[>=2.0 <3.0]",修复配方,然后继续前进,而不会破坏整个项目。

与常规的 requires 一样,此默认设置可以通过 core.package_id:default_python_mode 配置进行自定义。

也可以使用 package_id() 方法按包自定义 python_requires 的影响。

from conan import ConanFile

class Pkg(ConanFile):
    python_requires ="pyreq/[>=1.0]"
    def package_id(self):
        self.info.python_requires.patch_mode()

python_requires 的解析

使用 python_requires 时,有几点重要事项需要考虑:

  • Python requires 配方仅由解释器加载一次,并且对所有消费者通用。请勿在 python_requires 配方中使用任何全局状态。

  • Python requires 对消费者是私有的。它们不可传递。不同的消费者可以要求相同 python-require 的不同版本。由于是私有的,它们无法从下游以任何方式被覆盖。

  • python_requires 本身不能使用常规的 requirestool_requires。配方可以继承 requirements()(及类似)方法是可能且允许的,但 python_requires 类本身不能使用它们。

  • python_requires 不能被“别名化”。

  • python_requires 可以使用原生 Python 的 import 导入其他 Python 文件,只要这些文件与配方一起导出。

  • python_requires 也可以用作可编辑包。

  • python_requires 在 lockfile 中被锁定,以保证可复现性,就像其他 requirestool_requires 被锁定一样。

注意

最佳实践

  • 即使 python-requires 可以传递地 python_requires 其他 python-requires 配方,但这是不建议的。多级继承和复用会变得相当复杂且难以管理,建议保持层级扁平化。

  • 不要尝试将 Python 继承与 python_requires_extend 继承机制混合使用,它们不兼容并且可能导致错误。

  • 不要对 python-requires 使用多重继承