Руководство по VarDict

Краткое руководство

Самый простой способ использовать VarDict:

from ansible_collections.community.general.plugins.module_utils.vardict import VarDict

Затем в main() или любой другой вызываемой из неё функции:

vars = VarDict()

# Next 3 statements are equivalent
vars.abc = 123
vars["abc"] = 123
vars.set("abc", 123)

vars.xyz = "bananas"
vars.ghi = False

И перед тем, как модуль завершит работу:

results = vars.output()
module.exit_json(**results)

В результате модуль вернёт:

{
    "abc": 123,
    "xyz": "bananas",
    "ghi": false
}

Метаданные

Для каждой переменной можно задать следующие значения метаданных:

• output: bool — помечает переменную для вывода модуля в качестве возвращаемого значения.
• fact: bool — помечает переменную для вывода модуля в качестве факта Ansible.
• verbosity: int — задаёт минимальный уровень подробности, начиная с которого переменная будет включаться в вывод.
• change: bool — управляет обнаружением изменений значения переменной.
• initial_value: any — при использовании change позволяет принудительно задать переменной начальное значение.
• diff: bool — при использовании вместе с change формирует разницу в стиле Ansible dict.

Подробнее об использовании метаданных см. в разделах ниже.

Основы использования

Как показано выше, к переменным можно обращаться с помощью оператора [], как к объекту dict, а также как к атрибутам объекта, например vars.abc. Форма с использованием метода set() особенная: она позволяет задавать значения метаданных:

vars.set("abc", 123, output=False)
vars.set("abc", 123, output=True, change=True)

Ещё один способ задать метаданные после создания переменных:

vars.set_meta("abc", output=False)
vars.set_meta("abc", output=True, change=True, diff=True)

Для доступа к значению переменной можно использовать оператор или форму атрибута. Другие способы получить доступ к её значению и метаданным:

print("abc value = {0}".format(vars.var("abc")["value"]))        # get the value
print("abc output? {0}".format(vars.get_meta("abc")["output"]))  # get the metadata like this

Имена методов, например set, get_meta, output и других, зарезервированы и не могут использоваться в качестве имён переменных. При попытке использовать зарезервированное имя возникает исключение ValueError с сообщением «Имя <var> зарезервировано».

Формирование вывода

По умолчанию каждая созданная переменная включена в вывод, а минимальный уровень подробности равен нулю. Иными словами, по умолчанию переменные всегда присутствуют в выводе.

Это можно настроить при первом создании переменной или позже в коде:

vars.set("internal", x + 4, output=False)
vars.set_meta("internal", output=False)

Для некоторых переменных можно также задать уровень подробности, например:

vars.set("abc", x + 4)
vars.set("debug_x", x, verbosity=3)

results = vars.output(module._verbosity)
module.exit_json(**results)

Если модуль был запущен с уровнем подробности ниже 3, вывод будет содержать только переменную abc. При запуске с более высоким уровнем подробности, например ansible-playbook -vvv, вывод также будет содержать debug_x.

Формирование фактов очень похоже на формирование обычного вывода, однако по умолчанию переменные не помечаются как факты.

vars.set("modulefact", x + 4, fact=True)
vars.set("debugfact", x, fact=True, verbosity=3)

results = vars.output(module._verbosity)
results["ansible_facts"] = {"module_name": vars.facts(module._verbosity)}
module.exit_json(**results)

Отслеживание изменений

С помощью VarDict можно определить, изменились ли значения переменных.

vars.set("abc", 42, change=True)
vars.abc = 90

results = vars.output()
results["changed"] = vars.has_changed
module.exit_json(**results)

При отслеживании изменений переменных может потребоваться показать разницу между их начальными и конечными значениями. Для этого используйте:

vars.set("abc", 42, change=True, diff=True)
vars.abc = 90

results = vars.output()
results["changed"] = vars.has_changed
results["diff"] = vars.diff()
module.exit_json(**results)