ansible argspec gen

Генератор спецификации аргумента

Этот пакет содержит код для программы спецификации аргументов Ansible. Его основная аудитория - это Ansible Module Savingers, которые хотели бы уменьшить дублирование в своих модулях, генерируя спецификацию аргумента непосредственно из пользовательской документации модуля.

QuickStart

Экстрактор документации опубликован на PYPI, и мы можем установить его с помощью pip :

 $ pip установить ansible-argspec-gen [base] # Это установит ansible-base
$ pip установить ansible-argspec-gen [ansible] # это установит ansible
$ pip установить Ansible-argspec-Gen # нам нужно установить Ansible или
                                            # сами база

Если предыдущая команда не удалась, мы готовы начать обновлять наши модули. Когда мы используем генератор в первый раз, нам нужно выполнить следующие три шага:

1. Добавьте два комментария к источнику модуля, который будет отмечать местоположение для сгенерированного кода. По умолчанию генератор искал комментарий # AUTOMATIC MODULE ARGUMENTS , но это можно изменить с помощью параметра командной строки- --marker .
2. Запустите генератор, возможно, сначала в режиме сухого и Diff, чтобы выяснить любые проблемы.
3. Удалите любые ручные остатки, которые больше не нужны.

Например, давайте предположим, что первые несколько строк основной функции нашего модуля выглядят при этом перед запуском генератора:

 def main ():
    # Аргументы автоматического модуля
    # Аргументы автоматического модуля

    module = ansiblemodule (

Если мы запустим генератор сейчас в контрольном режиме с переключением различий, мы вернем что -то вроде этого:

 $ ansible-argspec-gen-diff-Dry-Run Plugins/Modules/Route.py
--- ../Ansible_collections/steampunk/nginx_unit/plugins/modules/route.py.old
+++ ../ansible_collections/steampunk/nginx_unit/plugins/modules/route.py.new
@@ -359,6 +359,52 @@

 def main ():
     # Аргументы автоматического модуля
+ argys_spec = {
+ "global": {"default": false, "type": "bool"},
+ "имя": {"type": "str"},
+ "сокет": {"type": "path"},
+ "состояние": {
+ «выбор»: [«настоящий», «отсутствует»],
+ "по умолчанию": "настоящий",
+ "type": "str",
+},
+}
+ required_if = [("global", false, ("name",), ("state", "present", ("Steps",))]]]
     # Аргументы автоматического модуля

     module = ansiblemodule (

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

 $ ansible-argspec-Gen плагины/модули/route.py

Если мы обновим документацию модуля, мы можем просто повторно затронуть предыдущую команду, и генератор примет или обновит спецификацию. Обратите внимание, что генератор будет перезаписать содержание между маркерами, поэтому убедитесь, что вы не измените эту часть файла вручную, или вы потеряете изменения в следующем обновлении.

Документация по написанию модуля

Создание спецификации аргумента для класса AnsibleModule должно работать над любым модулем, который имеет документацию. Но привлечение генератора для создания других параметров, таких как условные требования, требует небольшой работы.

Чтобы сгенерировать спецификацию required_if , наши параметры должны иметь предложение в своем описании, которое соответствует необходимому шаблону, если i ({param_name}) является c ({param_value}) . Следующий пример:

 параметры:
  имя:
    описание:
      - Имя ресурса. Требуется, если я (состояние) является c (присутствует).

Создаст следующую спецификацию:

 required_if = [("state", "present", ("name",))]]

Еще одна вещь, которую генератор знает, как создавать, - это mutually_exclusive Specification. Образец, который генератор ищет в этом случае, является взаимоисключающим с i ({param1}), i ({param2}) и i ({param3}) , где количество параметров, которые мы можем указать, не ограничено. Пример:

 параметры:
  процессы:
    описание:
      - Динамические пределы процесса.
      - взаимно эксклюзивный с i (no_processes).
  no_processes:
    описание:
      - Статический предел процесса.
      - взаимно эксклюзив с i (процессы).

Это будет производить:

 mutuly_exclusive = [("no_processes", "процессы")]]]

Настройка разработки

Получение среды развития и запуск относительно просто, если у нас установлен pipenv :

 $ pipenv обновление

Чтобы проверить экстрактор, мы можем запустить:

 $ pipenv run ansible-argspec-gen