导入

Ansible 允许对某些库进行未检查的导入，这些库来自特定的目录。导入任何其他 Python 库都需要处理导入错误。这支持健全性测试（如 validate-modules）并为用户提供更好的错误消息。

重要

有关解决此测试报告的常见问题解答，请参阅常见问题解答。

处理导入错误

Ansible 在许多主机上执行，并且可以同时使用多个 Python 解释器，这些解释器甚至可能具有不同的版本。为了确保用户获得可操作且易于理解的错误，我们尝试确保模块/插件中的任何非核心导入都受到保护，以避免出现跟踪回溯，大多数用户无法理解，更不用说用来解决问题了。

Ansible 这样做还有另一个原因是导入代码以进行检查。这使 Ansible 可以轻松地测试、记录、配置等代码，而无需在所有地方都安装所有需求，尤其是在执行代码的环境并非如此的情况下。

以下代码显示了如何避免导入错误，然后使用提供的 missing_required_lib 来确保用户知道哪个库丢失、在哪个主机上丢失以及哪个特定解释器需要它。

在模块中

不要使用 import another_library

import traceback

from ansible.module_utils.basic import missing_required_lib

try:
    import another_library
except ImportError:
    HAS_ANOTHER_LIBRARY = False
    ANOTHER_LIBRARY_IMPORT_ERROR = traceback.format_exc()
else:
    HAS_ANOTHER_LIBRARY = True
    ANOTHER_LIBRARY_IMPORT_ERROR = None

注意

上面的 missing_required_lib 导入将在下面使用。

然后在模块代码中，通常在 main 方法内

module = AnsibleModule(...)

if not HAS_ANOTHER_LIBRARY:
    module.fail_json(
        msg=missing_required_lib('another_library'),
        exception=ANOTHER_LIBRARY_IMPORT_ERROR)

在插件中

不要使用 import another_library

try:
    import another_library
except ImportError as imp_exc:
    ANOTHER_LIBRARY_IMPORT_ERROR = imp_exc
else:
    ANOTHER_LIBRARY_IMPORT_ERROR = None

然后在插件代码中，例如在插件的 run 方法中（某些插件没有 run 方法，而需要在 __init__ 方法中进行）

if ANOTHER_LIBRARY_IMPORT_ERROR:
    raise AnsibleError('another_library must be installed to use this plugin') from ANOTHER_LIBRARY_IMPORT_ERROR

用作基类时

重要

此解决方案建立在前面两个示例的基础上。在继续使用此解决方案之前，请确保选择合适的一个。

有时，导入是在基类中使用的，例如

from another_library import UsefulThing

class CustomThing(UsefulThing):
    pass

一种选择是使整个类定义成为条件

if not ANOTHER_LIBRARY_IMPORT_ERROR:
    class CustomThing(UsefulThing):
        pass

另一种选择是通过修改异常处理程序来定义一个替代基类

try:
    from another_library import UsefulThing
except ImportError:
    class UsefulThing:
        pass
    ...

允许的未检查导入

Ansible 允许从以下特定目录进行未检查的导入

ansible-core
- 对于 lib/ansible/modules/ 和 lib/ansible/module_utils/，仅允许从 Python 标准库进行未检查的导入；
- 对于 lib/ansible/plugins/，仅允许从 Python 标准库、ansible-core 的公共依赖项以及 ansible-core 本身进行未检查的导入；
集合
- 对于 plugins/modules/ 和 plugins/module_utils/，仅允许从 Python 标准库进行未检查的导入；
- 对于 plugins/ 中的其他目录（有关列表，请参阅社区集合要求），仅允许从 Python 标准库、ansible-core 的公共依赖项以及 ansible-core 本身进行未检查的导入。

ansible-core 的公共依赖项为

Jinja2

PyYAML

MarkupSafe（作为 Jinja2 的依赖项）

常见问题解答（FAQ）

为什么我在模块或插件工作时会收到 `ImportError` 错误？

import 健全性测试与其他测试非常不同。根据设计，它只能看到 Python 标准库中的模块。这意味着您的模块或插件可以在您的剧本、集成测试和单元测试中运行，而不会通过 import 健全性测试。