Python要求¶
介绍¶
python_requires
功能是共享不同食谱之间文件和代码的便捷方式。Python要求是一种特殊的食谱,它不创建包,只用于被其他食谱重用。
我们想要重用的一个非常简单的食谱可能是
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要求也可以使用版本范围,如果这些 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/conanfile.py
来使用 test_package
测试 python_require
from conan import ConanFile
def mynumber():
return 42
class PyReq(ConanFile):
name = "pyreq"
version = "1.0"
package_type = "python-require"
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 的修订版的补丁版本所做的更改不会影响包 ID。因此,依赖于
"pyreq/1.2.3"
或"pyreq/1.2.4"
将导致相同的包 ID(两者都将在哈希计算中映射到"pyreq/1.2.Z"
)。如果您想更改您的公共代码,但又不想影响消费者或触发依赖项的重新构建,请增加补丁版本。对次要版本的更改将产生不同的包 ID。因此,如果您依赖
"pyreq/1.2.3"
,并且您将版本提升到"pyreq/1.3.0"
,那么,您将需要构建使用该新 python-require 的新二进制文件。如果您想确保需要此 python-require 的包将使用代码中的这些更改进行构建,请增加次要或主要版本。
在大多数情况下,使用版本范围 python_requires = "pyreq/[>=1.0 <2.0]"
是正确的方法,因为这意味着不包含主要版本升级,因为它们将需要消费者自身的更改。然后可以发布 pyreq/2.0
的新主要版本,并让消费者逐渐将其要求更改为 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 require 食谱只被解释器加载一次,并且它们对所有消费者都是通用的。不要在
python_requires
食谱中使用任何全局状态。Python require 对消费者是私有的。它们不是传递性的。不同的消费者可以要求同一
python-require
的不同版本。由于是私有的,它们不能以任何方式从下游被覆盖。python_requires
本身不能使用常规的requires
或tool_requires
。拥有requirements()
(及类似)方法以供食谱继承是可能的和允许的,但python_requires
类本身不能使用它们。python_requires
不能被“别名”。python_requires
可以使用本地 pythonimport
导入其他 python 文件,只要这些文件与食谱一起导出。python_requires
也可以用作可编辑包。python_requires
在 lockfiles 中被锁定,以保证可重现性,就像其他requires
和tool_requires
被锁定一样。
注意
最佳实践
即使
python-requires
可以传递性地python_requires
其他python-requires
食谱,这也是不鼓励的。多级继承和重用会变得相当复杂且难以管理,建议保持层次结构扁平。不要尝试将 Python 继承与
python_requires_extend
继承机制混合使用,它们不兼容且可能导致中断。不要对
python-requires
使用多重继承