anaconda-cli-base

使用Typer支持Anaconda CLI插件的基CLI入口。

注册插件

要在第三方包中开发子命令，首先创建一个包含一个或多个命令的typer.Typer()应用程序。请参阅此示例。您包中定义的命令将带有您在注册插件时定义的子命令作为前缀。

在您的pyproject.toml中可以按以下方式注册子命令

# In pyproject.toml

[project.entry-points."anaconda_cli.subcommand"]
auth = "anaconda_cloud_auth.cli:app"

在上面的示例中

• "anaconda_cloud_cli.subcommand"是用于注册的必需字符串。引号很重要。
• auth是新子命令的名称，即anaconda auth
  • 您包中定义的所有typer.Typer命令都可以通过注册的子命令访问
  • 即anaconda auth <command>。
• anaconda_cloud_auth.cli:app表示anaconda_cloud_auth.cli模块中名为app的对象是子命令的入口点。

错误处理

默认情况下，在您的注册插件中执行CLI时引发的任何异常都将被捕获，并且只会向用户显示最小消息。

您可以为可能从您的子命令抛出的个别异常定义自定义回调。您可以注册标准库异常或自定义定义的异常的处理程序。最好使用自定义异常以避免对其他插件产生意外后果。

要注册回调，请使用装饰器装饰一个接受异常作为输入的函数，并返回一个整数错误代码。错误代码将通过CLI发送回，并且您的子命令将以该错误代码退出。

from typing import Type
from anaconda_cli_base.exceptions import register_error_handler

@register_error_handler(MyCustomException)
def better_exception_handling(e: Type[Exception]) -> int:
    # do something or print useful information
    return 1

@register_error_handler(AnotherException)
def just_ignore_it(e: Type[Exception])
    # ignore the error and let the CLI exit successfully
    return 0


@register_error_handler(YetAnotherException)
def fix_the_error_and_try_again(e: Type[Exception]) -> int:
    # do something and retry the CLI command
    return -1

在第二个示例中，处理程序返回-1。这意味着处理程序已尝试纠正错误，CLI子命令应该重新尝试。处理程序可以在再次尝试CLI子命令之前调用另一个交互式命令，如登录操作。

请参阅anaconda-cloud-auth插件以获取自定义处理程序的示例。

配置文件

如果您的插件想使用Anaconda配置文件（默认位置~/.anaconda/config.toml），以读取从anaconda_cli_base.config.AnacondaBaseSettings派生的配置参数，您可以在配置文件中为您的插件添加一个部分。每个AnacondaBaseSettings的子类定义了部分标题。基类被配置为允许从以下优先级从低到高读取子类中定义的参数。

1. AnacondaBaseSettings子类的默认值
2. 全局配置文件位于~/.anaconda/config.toml
3. 工作目录中.env文件中定义的ANACONDA_<PLUGIN-NAME>_<FIELD>变量
4. 在您的shell或命令调用中设置的ANACONDA_<PLUGIN-NAME>_<FIELD>环境变量
5. 直接使用配置子类时传递的kwarg值

注意

• AnacondaBaseSettings是来自pydantic-settings的BaseSettings的子类。
• 还支持嵌套pydantic模型。

以下是一个示例子类

from anaconda_cli_base.config import AnacondaBaseSettings

class MyPluginConfig(AnacondaBaseSettings, plugin_name="my_plugin"):
    foo: str = "bar"

根据上述优先级在您的插件中读取配置值

config = MyPluginConfig()
assert config.foo == "bar"

由于配置文件中没有foo的值，它假设来自子类定义的默认值。

现在可以将foo的值写入配置文件中的my_plugin部分

# ~/.anaconda/config.toml
[plugin.my_plugin]
foo = "baz"

配置文件已写入后，从config.toml文件读取foo的值

config = MyPluginConfig()
assert config.foo == "baz"

有关更多示例，请参阅测试。

开发设置

确保您已安装conda。然后运行

make setup

运行单元测试

make test

使用tox运行跨隔离环境的单元测试

make tox