Справочник Ansible: утилиты модулей

ArgumentSpecValidator

class ansible.module_utils.common.arg_spec.ArgumentSpecValidator(argument_spec, mutually_exclusive=None, required_together=None, required_one_of=None, required_if=None, required_by=None)

Класс для проверки спецификации аргументов

Создаёт средство проверки на основе argument_spec, которое можно использовать для проверки ряда параметров с помощью метода validate().

Параметры:

• argument_spec (dict[str, dict]) – Спецификация допустимых параметров и их типов. Может содержать вложенные спецификации аргументов.
• mutually_exclusive (list[str] or list[list[str]]) – Список или список списков терминов, которые нельзя указывать вместе.
• required_together (list[list[str]]) – Список списков терминов, которые требуются одновременно.
• required_one_of (list[list[str]]) – Список списков терминов, в каждом из которых требуется указать хотя бы один термин.
• required_if (list) – Список списков [parameter, value, [parameters]], где один из [parameters] требуется, если parameter == value.
• required_by (dict[str, list[str]]) – Словарь имён параметров, значения которого содержат список параметров, требуемых для каждого ключа словаря.

validate(parameters, *args, **kwargs)

Проверяет parameters на соответствие спецификации аргументов.

Сообщения об ошибках в ValidationResult могут содержать значения no_log, поэтому перед записью в журнал или отображением их необходимо обработать с помощью sanitize_keys().

Параметры:

parameters (dict[str, dict]) – Параметры для проверки на соответствие спецификации аргументов

Возвращает:

ValidationResult, содержащий проверенные параметры.

Простой пример:

argument_spec = {
    'name': {'type': 'str'},
    'age': {'type': 'int'},
}

parameters = {
    'name': 'bo',
    'age': '42',
}

validator = ArgumentSpecValidator(argument_spec)
result = validator.validate(parameters)

if result.error_messages:
    sys.exit("Validation failed: {0}".format(", ".join(result.error_messages))

valid_params = result.validated_parameters

ValidationResult

class ansible.module_utils.common.arg_spec.ValidationResult(parameters)

Результат проверки спецификации аргументов.

Этот объект возвращается методом ArgumentSpecValidator.validate() и содержит проверенные параметры и все ошибки.

Параметры:

parameters (dict) – Термины для проверки и приведения к правильному типу.

errors

AnsibleValidationErrorMultiple, содержащий все объекты AnsibleValidationError, если при проверке произошли ошибки.

property validated_parameters

Проверенные параметры, приведённые к нужным типам.

property unsupported_parameters

set имён неподдерживаемых параметров.

property error_messages

list всех сообщений об ошибках из каждого исключения в errors.

Параметры

ansible.module_utils.common.parameters.DEFAULT_TYPE_VALIDATORS

dict имён типов, например 'str', и используемой по умолчанию функции для проверки соответствующего типа — в данном случае check_type_str().

ansible.module_utils.common.parameters.env_fallback(*args, **kwargs)

Загружает значение из переменной окружения

ansible.module_utils.common.parameters.remove_values(value, no_log_strings)

Удаляет строки из no_log_strings в значении.

Если значение является контейнером, удаляется гораздо больше.

Используется deferred_removals, а не чисто рекурсивное решение, поскольку при обработке больших объёмов данных можно достичь максимальной глубины рекурсии (см. проблему #24560).

ansible.module_utils.common.parameters.sanitize_keys(obj, no_log_strings, ignore_keys=frozenset({}))

Очищает ключи объекта-контейнера, удаляя значения no_log из имён ключей.

Эта функция дополняет функцию remove_values(). Как и в той функции, здесь используется deferred_removals, чтобы избежать достижения максимальной глубины рекурсии при обработке больших структур данных.

Параметры:

• obj – Объект-контейнер для очистки. Объекты, не являющиеся контейнерами, возвращаются без изменений.
• no_log_strings – Множество строковых значений, которые не следует записывать в журнал.
• ignore_keys – Множество строковых значений ключей, которые не следует очищать.

Возвращает:

Объект с очищенными ключами.

Проверка

Автономные функции для проверки различных типов параметров.

ansible.module_utils.common.validation.check_missing_parameters(parameters, required_parameters=None)

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

Вызывает TypeError, если отсутствуют какие-либо обязательные параметры.

Параметры:

• parameters – Словарь параметров
• required_parameters – Список параметров, наличие которых нужно проверить среди переданных параметров.

Возвращает:

Пустой список или вызывает TypeError, если проверка не пройдена.

ansible.module_utils.common.validation.check_mutually_exclusive(terms, parameters, options_context=None)

Проверяет взаимоисключающие термины в параметрах аргументов

Принимает один список или список списков — группы терминов, которые являются взаимоисключающими.

Параметры:

• terms – Список взаимоисключающих параметров
• parameters – Словарь параметров
• options_context – Список строк с именами родительских ключей, если terms находятся во вложенной спецификации.

Возвращает:

Пустой список или вызывает TypeError, если проверка не пройдена.

ansible.module_utils.common.validation.check_required_arguments(argument_spec, parameters, options_context=None)

Проверяет все параметры в argument_spec и возвращает список обязательных параметров, отсутствующих в parameters.

Вызывает TypeError, если проверка не пройдена.

Параметры:

• argument_spec – Словарь спецификации аргументов со всеми параметрами и их описаниями
• parameters – Словарь параметров
• options_context – Список строк с именами родительских ключей, если argument_spec находятся во вложенной спецификации.

Возвращает:

Пустой список или вызывает TypeError, если проверка не пройдена.

ansible.module_utils.common.validation.check_required_by(requirements, parameters, options_context=None)

Для каждого ключа в requirements проверяет, присутствуют ли соответствующие значения в parameters.

Для каждого ключа принимает строку или список значений.

Параметры:

• requirements – Словарь требований
• parameters – Словарь параметров
• options_context – Список строк с именами родительских ключей, если requirements находятся во вложенной спецификации.

Возвращает:

Пустой словарь или вызывает TypeError, если проверка не пройдена.

ansible.module_utils.common.validation.check_required_if(requirements, parameters, options_context=None)

Проверяет условно обязательные параметры

Вызывает TypeError, если проверка не пройдена.

Параметры:

requirements – Список списков, задающих параметр, его значение, параметры, обязательные при указанном значении параметра, и, при необходимости, логическое значение, указывающее, обязательны ли некоторые или все параметры.

Пример:

required_if=[
    ['state', 'present', ('path',), True],
    ['someint', 99, ('bool_param', 'string_param')],
]

Параметры:

• parameters – Словарь параметров
• options_context – Список строк с именами родительских ключей, если requirements находятся во вложенной спецификации.

Возвращает:

Пустой список или вызывает TypeError, если проверка не пройдена. Атрибут results исключения содержит список словарей. Каждый словарь представляет собой результат проверки одного элемента из requirements. Каждый возвращаемый словарь содержит следующие ключи:

отсутствующие ключи:

Список обязательных, но отсутствующих параметров

требует ключ:

’any’ или ‘all’

параметр ключа:

Имя параметра, для которого задано требование

значение ключа:

Исходное значение параметра

требования ключа:

Исходные обязательные параметры

Пример:

[
    {
        'parameter': 'someint',
        'value': 99
        'requirements': ('bool_param', 'string_param'),
        'missing': ['string_param'],
        'requires': 'all',
    }
]

ansible.module_utils.common.validation.check_required_one_of(terms, parameters, options_context=None)

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

Принимает список списков или кортежей

Параметры:

• terms – Список списков терминов для проверки. В каждом списке терминов требуется указать хотя бы один.
• parameters – Словарь параметров
• options_context – Список строк с именами родительских ключей, если terms находятся во вложенной спецификации.

Возвращает:

Пустой список или вызывает TypeError, если проверка не пройдена.

ansible.module_utils.common.validation.check_required_together(terms, parameters, options_context=None)

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

Принимает список списков или кортежей.

Параметры:

• terms – Список списков терминов для проверки. Каждый список должен содержать параметры, которые требуются все вместе, если в parameters указан хотя бы один из них.
• parameters – Словарь параметров
• options_context – Список строк с именами родительских ключей, если terms находятся во вложенной спецификации.

Возвращает:

Пустой список или вызывает TypeError, если проверка не пройдена.

ansible.module_utils.common.validation.check_type_bits(value)

Преобразует понятное человеку строковое значение битов в целое число битов.

Пример: check_type_bits('1Mb') возвращает целое число 1048576.

Вызывает TypeError, если преобразовать значение не удалось.

ansible.module_utils.common.validation.check_type_bool(value)

Проверяет, является ли значение типом bool, или преобразует его к типу bool и возвращает результат.

Вызывает TypeError, если преобразовать значение к типу bool не удалось.

Параметры:

value – Строка, целое число или число с плавающей точкой для преобразования к типу bool. Допустимые логические значения: ‘1’, ‘on’, 1, ‘0’, 0, ‘n’, ‘f’, ‘false’, ‘true’, ‘y’, ‘t’, ‘yes’, ‘no’, ‘off’

Возвращает:

Логическое значение True или False

ansible.module_utils.common.validation.check_type_bytes(value)

Преобразует понятное человеку строковое значение в байты

Вызывает TypeError, если преобразовать значение не удалось.

ansible.module_utils.common.validation.check_type_dict(value)

Проверяет, является ли значение словарём, или преобразует его в словарь и возвращает результат.

Вызывает TypeError, если преобразовать значение в словарь не удалось.

Параметры:

value – Словарь или строка для преобразования в словарь. Принимает k1=v2, k2=v2 или k1=v2 k2=v2.

Возвращает:

Значение, преобразованное в словарь

ansible.module_utils.common.validation.check_type_float(value)

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

Вызывает TypeError, если преобразовать значение к типу float не удалось.

Параметры:

value – Число с плавающей точкой, целое число, строка или байты для проверки или преобразования.

Возвращает:

Число с плавающей точкой, полученное из заданного значения.

ansible.module_utils.common.validation.check_type_int(value)

Проверяет, является ли значение целым числом, и возвращает его, либо преобразует значение в целое число и возвращает его.

Вызывает TypeError, если преобразовать значение к типу int не удалось.

Параметры:

value – Строка или целое число для проверки или преобразования

Возвращает:

Целое число, полученное из заданного значения

ansible.module_utils.common.validation.check_type_jsonarg(value)

Сериализует dict/list/tuple в JSON, удаляет пробелы из str и bytes. Ранее требовалось в случаях, когда этап литерального вычисления в классическом режиме Ansible/Jinja мог непреднамеренно десериализовать объекты.

ansible.module_utils.common.validation.check_type_list(value)

Проверяет, является ли значение списком, или преобразует его в список

Строка, разделённая запятыми, будет разбита на элементы списка. Если преобразовать значение в список не удалось, вызывается исключение TypeError.

Параметры:

value – Значение для проверки или преобразования в список

Возвращает:

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

ansible.module_utils.common.validation.check_type_path(value)

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

ansible.module_utils.common.validation.check_type_raw(value)

Возвращает исходное значение

ansible.module_utils.common.validation.check_type_str(value, allow_conversion=True, param=None, prefix='')

Проверяет, является ли значение строкой, или преобразует его в строку.

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

Параметры:

• value – Значение для проверки или преобразования в строку
• allow_conversion – Следует ли преобразовать значение в строку и вернуть его или вызвать TypeError

Возвращает:

Исходное значение, если оно является строкой; преобразованное в строку значение, если allow_conversion=True; или вызывает TypeError, если allow_conversion=False.

ansible.module_utils.common.validation.count_terms(terms, parameters)

Подсчитывает количество вхождений ключа в заданном словаре

Параметры:

• terms – Строка или итерируемый объект со значениями для проверки
• parameters – Словарь параметров

Возвращает:

Целое число — количество вхождений значений terms в заданный словарь.