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 и возвращение списка параметров, которые являются обязательными, но отсутствуют в параметрах.

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

Параметры:

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

Возвращает:

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

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

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

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

Параметры:

• 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 исключения содержит список словарей. Каждый словарь — результат оценки каждого элемента в требованиях. Каждый возвращаемый словарь содержит следующие ключи:

key missing:

Список параметров, которые необходимы, но отсутствуют

key requires:

’any’ или ‘all’

key parameter:

Имя параметра, у которого есть требование

key value:

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

key requirements:

Исходные необходимые параметры

Пример:

[
    {
        '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 – Словарь параметров
• 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)

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

Вызывает TypeError, если преобразование в булевое невозможно

Параметры:

value – Строка, целое число или число с плавающей точкой для преобразования в булевое. Допустимые булевы значения: ‘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, если преобразование в словарь невозможно.

Параметры:

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

Возвращает:

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

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

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

Вызывает TypeError, если преобразование в число с плавающей точкой невозможно.

Параметры:

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

Возвращает:

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

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

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

Вызывает TypeError, если преобразование в целое число невозможно.

Параметры:

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

Возвращает:

целое число заданного значения.

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

Возвращает закодированную в формате JSON строку. Иногда контроллер преобразует строку JSON в словарь/список, поэтому здесь она преобразуется обратно в JSON.

Вызывает TypeError, если преобразование значения невозможно.

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

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

Строка, разделенная запятыми, будет разделена на список. Вызывает TypeError, если преобразование в список невозможно.

Параметры:

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

Возвращает:

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

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, если значение не является строкой и должно быть преобразовано.

Параметры:

• значение – значение для проверки или преобразования в строку
• разрешить_преобразование – следует ли преобразовывать строку и возвращать её или поднимать TypeError

Возвращает:

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

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

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

Параметры:

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

Возвращает:

Целое число, представляющее количество вхождений значений терминов в предоставленном словаре.