插件#

从 22.11.0 版本开始，conda 支持用户插件，可以扩展或修改某些功能。

快速入门#

这是一个定义新子命令的最小工作 conda 插件示例

example_plugin.py#

import conda.plugins
from conda.base.context import context


def command(arguments: list[str]):
    print("Conda subcommand!")


@conda.plugins.hookimpl
def conda_subcommands():
    yield conda.plugins.CondaSubcommand(
        name="example",
        action=command,
        summary="Example of a conda subcommand",
    )

让我们逐步分解这里发生了什么

首先，我们创建函数 command 作为我们的子命令。此函数传递一个参数列表，该参数列表等于 sys.argv[2:]。
接下来，我们使用 conda_subcommands 插件钩子注册此子命令。为此，我们创建一个名为 conda_subcommands 的函数，然后用 conda.plugins.hookimpl 装饰它。
我们从此函数返回的对象是 conda.plugins.CondaSubcommand，它执行以下几个操作
1. name 是我们通过命令行调用此子命令时使用的名称（即“conda example”）。
2. action 是在调用“conda example”时将调用的函数。
3. summary 是子命令的描述，在用户调用“conda --help”时显示。

为了实际使用 conda 插件，它们必须打包为 Python 包。此外，我们还需要利用称为 Python 包入口点的功能。我们可以通过使用 pyproject.toml 文件（推荐）或 setup.py（遗留）为我们的项目定义 Python 包和入口点。

pyproject.toml#

[build-system]
requires = ["setuptools", "setuptools-scm"]
build-backend = "setuptools.build_meta"

[project]
name = "conda-example-plugin"
version = "1.0.0"
description = "Example conda plugin"
requires-python = ">=3.8"
dependencies = ["conda"]

[project.entry-points."conda"]
conda-example-plugin = "example_plugin"

setup.py#

from setuptools import setup

setup(
    name="conda-example-plugin",
    install_requires="conda",
    entry_points={"conda": ["conda-example-plugin = example_plugin"]},
    py_modules=["example_plugin"],
)

在上面显示的两个示例中，我们都为 conda 定义了一个入口点。确保入口点是为“conda”的，并且它指向插件包中的正确模块。我们的包只包含一个名为 example_plugin 的 Python 模块。如果你有一个大型项目，请务必始终将入口点指向包含插件钩子声明的模块（即使用 conda.plugins.hookimpl 的位置）。我们建议在这种情况下使用 plugin 子模块，例如 large_project.plugin（在 large_project/plugin.py 中）。

使用其他插件钩子#

有关如何使用其他插件钩子的示例，请阅读它们各自的文档页面。

有关插件工作原理的更多信息#

conda 中的插件是使用 Pluggy 实现的，Pluggy 是一个 Python 框架，由其他项目使用，例如 pytest、tox 和 devpi。pluggy 提供了通过函数钩子扩展和修改 conda 行为的能力，这会导致插件系统可以使用 Python 包入口点发现。

有关其工作原理的更多信息，我们建议你访问他们的文档。

API#

有关我们插件系统的更详细的信息，请参阅插件 API 部分。

错误处理#

中的错误 conda 通过 conda.exception_handler.ExceptionHandler 进行路由，当发现意外异常时，它可以打印有关 conda 安装的更多信息。这些自动报告可能非常冗长，并可能妨碍沟通预期错误。请参阅 conda-build 中的此问题作为示例。

为了将异常标记为预期，插件应引发 conda.CondaError 或其子类。请参阅 conda_auth.exceptions 以获取示例。

关于许可的说明#

有关为您的自定义插件使用哪种许可证的更多信息，请参考 "选择开源许可证" 网站。如果您需要帮助确定究竟使用哪种许可证，我们建议您与合格的法律专业人士沟通。

插件#