Параметры

Различия

Аргументы могут делать меньше, чем опции. Следующие функции доступны только для опций:

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

С другой стороны, аргументы, в отличие от опций, могут принимать произвольное количество аргументов. Опции могут строго принимать только фиксированное количество аргументов (по умолчанию 1) или могут быть указаны несколько раз, используя Множественные опции.

Типы параметров

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

str / click.STRING:

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

int / click.INT:

Параметр, который принимает только целые числа.

float / click.FLOAT:

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

bool / click.BOOL:

Параметр, который принимает булевы значения. Он автоматически используется для флагов boolean. Строковые значения “1”, “true”, “t”, “yes”, “y” и “on” преобразуются в True. “0”, “false”, “f”, “no”, “n” и “off” преобразуются в False.

click.UUID:

Параметр, который принимает значения UUID. Он не определяется автоматически, но представлен как uuid.UUID.

classclick.File(mode='r', encoding=None, errors='strict', lazy=None, atomic=False)

Объявляет параметр как файл для чтения или записи. Файл автоматически закрывается после завершения контекста (после завершения работы команды).

Файлы могут быть открыты для чтения или записи. Специальное значение - указывает на стандартный ввод или стандартный вывод в зависимости от режима.

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

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

Начиная с Click 2.0, файлы также можно открывать атомарно, в этом случае все записи записываются в отдельный файл в той же папке, а по завершении файл будет перемещен в исходное расположение. Это полезно, если файл, регулярно читаемый другими пользователями, изменяется.

См. Аргументы файлов для получения дополнительной информации.

Параметры:

• mode (str) –
• encoding (str | None) –
• errors (str | None) –
• lazy (bool | None) –
• atomic (bool) –

classclick.Path(exists=False, file_okay=True, dir_okay=True, writable=False, readable=True, resolve_path=False, allow_dash=False, path_type=None, executable=False)

Тип Path похож на тип File, но возвращает имя файла вместо открытого файла. Можно включить различные проверки для проверки типа файла и разрешений.

Параметры:

• exists (bool) – Файл или директория должны существовать для валидного значения. Если это не установлено в True, а файл не существует, то все дальнейшие проверки будут пропущены.
• file_okay (bool) – Разрешить файл в качестве значения.
• dir_okay (bool) – Разрешить директорию в качестве значения.
• readable (bool) – Если True, выполняется проверка на читаемость.
• writable (bool) – Если True, выполняется проверка на возможность записи.
• executable (bool) – Если True, выполняется проверка на исполняемость.
• resolve_path (bool) – Сделать значение абсолютным и разрешить все символические ссылки. ~ не расширяется, поскольку это должно выполняться только оболочкой.
• allow_dash (bool) – Разрешить одиночный тире в качестве значения, что указывает на стандартный поток (но не открывает его). Используйте open_file() для обработки открытия этого значения.
• path_type (Type[Any] | None) – Преобразовать входное значение пути к этому типу. Если None, сохранять значение по умолчанию Python, которое является str. Полезно для преобразования в pathlib.Path.

Изменено в версии 8.1: Добавлен параметр executable.

Журнал изменений

Изменено в версии 8.0: Разрешено передавать path_type=pathlib.Path.

Изменено в версии 6.0: Добавлен параметр allow_dash.

classclick.Choice(choices, case_sensitive=True)

Тип выбора позволяет проверять значение по фиксированному набору допустимых значений. Все эти значения должны быть строками.

Вы должны передавать только список или кортеж вариантов. Другие итерируемые объекты (например, генераторы) могут привести к неожиданным результатам.

Полученное значение всегда будет одним из исходных переданных вариантов независимо от case_sensitive или любых ctx.token_normalize_func.

См. Параметры выбора для примера.

Параметры:

• case_sensitive (bool) – Установите в значение False, чтобы сделать выбор нечувствительным к регистру. По умолчанию True.
• choices (Sequence[str]) –

классclick.IntRange(min=None, max=None, min_open=False, max_open=False, clamp=False)

Ограничить значение click.INT диапазоном допустимых значений. См. Параметры Диапазона.

Если min или max не переданы, в этом направлении принимается любое значение. Если min_open или max_open включены, соответствующая граница не включается в диапазон.

Если clamp включено, значение, выходящее за пределы диапазона, прижимается к границе вместо отказа.

Журнал изменений

Изменено в версии 8.0: Добавлены параметры min_open и max_open.

Параметры:

• min (float | None) –
• max (float | None) –
• min_open (bool) –
• max_open (bool) –
• clamp (bool) –

классclick.FloatRange(min=None, max=None, min_open=False, max_open=False, clamp=False)

Ограничить значение click.FLOAT диапазоном допустимых значений. См. Параметры Диапазона.

Если min или max не переданы, в этом направлении принимается любое значение. Если min_open или max_open включены, соответствующая граница не включается в диапазон.

Если clamp включено, значение, выходящее за пределы диапазона, прижимается к границе вместо отказа. Это не поддерживается, если любая из границ помечена open.

Журнал изменений

Изменено в версии 8.0: Добавлены параметры min_open и max_open.

Параметры:

• min (float | None) –
• max (float | None) –
• min_open (bool) –
• max_open (bool) –
• clamp (bool) –

классclick.DateTime(formats=None)

Тип DateTime преобразует строковые даты в объекты datetime.

Проверяемые форматы даты настраиваются, но по умолчанию используют некоторые распространённые форматы ISO 8601 (без учёта часовых поясов).

При указании форматов DateTime, вы должны передавать только список или кортеж. Другие итерируемые объекты, такие как генераторы, могут привести к неожиданным результатам.

Строки форматов обрабатываются с помощью datetime.strptime, что определяет допустимые форматы дат.

Попытка парсинга происходит для каждой из форматов в заданном порядке, и используется первый формат, который успешно произвёл парсинг.

Параметры:

formats (Sequence[str] | None) – Список или кортеж строк форматов дат, в порядке, в котором они должны быть проверены. По умолчанию '%Y-%m-%d', '%Y-%m-%dT%H:%M:%S', '%Y-%m-%d %H:%M:%S'.

Пользовательские типы параметров могут быть реализованы путём наследования от click.ParamType. Для простых случаев поддерживается передача функции Python, которая завершается с ошибкой ValueError, хотя это не рекомендуется.

Имена Параметров

Параметры (как опции, так и аргументы) имеют имя, которое будет использовано в качестве имени аргумента Python при вызове декорированной функции со значениями.

Аргументы принимают только одно позиционное имя. Чтобы предоставить другое имя для использования в тексте справки, см. Усечение текстов справки.

Опции могут иметь несколько имён, которые могут быть префиксом из одной или двух тире. Имена с одним тире интерпретируются как короткие опции, имена с двумя тире — как длинные опции. Если имя не имеет префикса, оно используется как имя аргумента Python и не интерпретируется как имя опции. В противном случае, первое имя с префиксом из двух тире используется, или первое с префиксом из одного тире, если их нет с двумя. Префикс удаляется, а тире заменяются на подчёркивания для получения имени аргумента Python.

Реализация пользовательских типов

Для реализации пользовательского типа необходимо унаследовать от ParamType класса. Переопределите метод convert() для преобразования значения из строки в соответствующий тип.

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

import click

class BasedIntParamType(click.ParamType):
    name = "integer"

    def convert(self, value, param, ctx):
        if isinstance(value, int):
            return value

        try:
            if value[:2].lower() == "0x":
                return int(value[2:], 16)
            elif value[:1] == "0":
                return int(value, 8)
            return int(value, 10)
        except ValueError:
            self.fail(f"{value!r} is not a valid integer", param, ctx)

BASED_INT = BasedIntParamType()

Атрибут name необязателен и используется для документации. Вызывайте fail(), если преобразование не удалось. Аргументы param и ctx могут быть None в некоторых случаях, таких как запросы.

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