Flag

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

См. также

Документация по PossibleValues — перечисление, определяющее типы допустимых значений.

Документация по InputFlag — объект обработанного флага, введённого пользователем.

Общая информация о флагах и их использовании в Argenta

Инициализация

1__init__(
2    self, name: str, *,
3    prefix: Literal["-", "--", "---"] = "--",
4    possible_values: list[str] | Pattern[str] | PossibleValues = PossibleValues.ALL,
5) -> None

Создаёт новый флаг для регистрации в команде.

  • name: Имя флага (обязательный параметр).

  • prefix: Префикс флага (-, --, ---). По умолчанию --.

  • possible_values: Правила валидации значения. Может быть списком строк, регулярным выражением или значением из PossibleValues. По умолчанию PossibleValues.ALL, то есть любое значение допустимо.

Атрибуты:

name

Имя флага в виде строки.

prefix

Префикс флага. Один из: "-", "--", "---".

possible_values

Допустимые значения для флага.

Пример использования:

 1import re
 2from argenta.command import Flag, PossibleValues
 3
 4# Simple flag with any values
 5verbose_flag = Flag(name="verbose")
 6
 7# Flag with short prefix
 8short_flag = Flag(name="v", prefix="-")
 9
10# Flag that does not take a value
11help_flag = Flag(name="help", possible_values=PossibleValues.NEITHER)
12
13# Flag with list of possible values
14format_flag = Flag(name="format", possible_values=["json", "xml", "csv"])
15
16# Flag with regexp for validation input value
17email_flag = Flag(
18    name="email",
19    possible_values=re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"),
20)

Свойства

string_entity

1@property
2string_entity(self) -> str

Возвращает строковое представление флага в формате prefix + name.

return:

Строковое представление флага

Это свойство объединяет префикс и имя в единую строку, которая представляет флаг так, как он выглядел бы в командной строке.

Магические методы

__str__

1__str__(self) -> str

Возвращает строковое представление флага (аналогично string_entity).

return:

Строковое представление флага

Пример использования:

1from argenta.command import Flag
2
3help_flag = Flag(name="help")
4version_flag = Flag(name="V", prefix="-")
5
6print(help_flag)  # --help
7
8message = f"Use {help_flag} to see help"
9print(message)  # Use --help to see help

__repr__

1__repr__(self) -> str

Возвращает отладочное представление объекта.

return:

Строка в формате Flag<prefix=..., name=...>.

Пример использования:

 1from argenta.command import Flag
 2
 3verbose_flag = Flag(name="verbose", prefix="--")
 4short_flag = Flag(name="v", prefix="-")
 5
 6# Debug presentation
 7print(repr(verbose_flag))  # Flag<prefix=--, name=verbose>
 8print(repr(short_flag))  # Flag<prefix=-, name=v>
 9
10# In an interactive console or debugger
11# >>> verbose_flag
12# Flag<prefix=--, name=verbose>

__eq__

1__eq__(self, other: object) -> bool

Сравнивает два флага на равенство по их строковому представлению (string_entity).

param other:

Объект для сравнения

return:

True, если флаги равны, иначе False

Два флага считаются равными, если их string_entity идентичны.

Пример использования:

 1from argenta.command import Flag, PossibleValues
 2
 3# Creating two flags with the same name and prefix
 4flag1 = Flag(name="verbose", prefix="--")
 5flag2 = Flag(name="verbose", prefix="--")
 6
 7# Flag comparison
 8print(flag1 == flag2)  # True
 9
10# Flags with different prefixes are not equal
11flag3 = Flag(name="verbose", prefix="-")
12print(flag1 == flag3)  # False
13
14# Flags with different names are not equal
15flag4 = Flag(name="help", prefix="--")
16print(flag1 == flag4)  # False
17
18# Different possible_values do not affect equality
19flag5 = Flag(name="verbose", prefix="--", possible_values=PossibleValues.NEITHER)
20flag6 = Flag(name="verbose", prefix="--", possible_values=["value1", "value2"])
21print(flag5 == flag6)

PredefinedFlags

argenta.command.PredefinedFlags

Класс PredefinedFlags предоставляет набор готовых флагов для использования в приложениях без их ручного создания. Эти флаги покрывают распространённые сценарии.

Все предопределённые флаги являются атрибутами класса и представляют собой готовые экземпляры Flag.

Информационные флаги

PredefinedFlags.HELP

Флаг для отображения справки: --help

  • name: "help"

  • prefix: "--" (по умолчанию)

  • possible_values: PossibleValues.NEITHER

PredefinedFlags.SHORT_HELP

Короткая версия флага справки: -H

  • name: "H"

  • prefix: "-"

  • possible_values: PossibleValues.NEITHER

PredefinedFlags.INFO

Флаг для отображения информации: --info

  • name: "info"

  • prefix: "--" (по умолчанию)

  • possible_values: PossibleValues.NEITHER

PredefinedFlags.SHORT_INFO

Короткая версия флага информации: -I

  • name: "I"

  • prefix: "-"

  • possible_values: PossibleValues.NEITHER

Флаги выбора

PredefinedFlags.ALL

Флаг для выбора всех элементов: --all

  • name: "all"

  • prefix: "--"

  • possible_values: PossibleValues.NEITHER

PredefinedFlags.SHORT_ALL

Короткая версия флага выбора всех элементов: -A

  • name: "A"

  • prefix: "-"

  • possible_values: PossibleValues.NEITHER

Сетевые флаги

PredefinedFlags.HOST

Флаг для указания IP-адреса хоста: --host

  • name: "host"

  • prefix: "--" (по умолчанию)

  • possible_values: Регулярное выражение для валидации IPv4: r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"

PredefinedFlags.SHORT_HOST

Короткая версия флага хоста: -H

  • name: "H"

  • prefix: "-"

  • possible_values: Регулярное выражение для валидации IPv4: r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"

PredefinedFlags.PORT

Флаг для указания порта: --port

  • name: "port"

  • prefix: "--" (по умолчанию)

  • possible_values: Регулярное выражение для валидации порта: r"^\d{1,5}$"

PredefinedFlags.SHORT_PORT

Короткая версия флага порта: -P

  • name: "P"

  • prefix: "-"

  • possible_values: Регулярное выражение для валидации порта: r"^\d{1,5}$"

Пример использования:

 1from argenta.command import Flags, PredefinedFlags
 2
 3# Using predefined flags when creating a command
 4command_flags = Flags(
 5    [
 6        PredefinedFlags.HELP,
 7        PredefinedFlags.SHORT_HELP,
 8        PredefinedFlags.INFO,
 9    ]
10)
11
12# Using Network Flags
13network_flags = Flags(
14    [
15        PredefinedFlags.HOST,
16        PredefinedFlags.PORT,
17    ]
18)
19
20# Validating the values of predefined flags
21print(PredefinedFlags.HOST.validate_input_flag_value("192.168.1.1"))  # True
22print(PredefinedFlags.HOST.validate_input_flag_value("invalid"))  # False
23
24print(PredefinedFlags.PORT.validate_input_flag_value("8080"))  # True
25print(PredefinedFlags.PORT.validate_input_flag_value("99999"))  # True
26print(PredefinedFlags.PORT.validate_input_flag_value("abc"))  # False
27
28# Flags without values
29print(PredefinedFlags.HELP.validate_input_flag_value(None))  # True
30print(PredefinedFlags.HELP.validate_input_flag_value("something"))  # False
31
32# Checking string representations
33print(PredefinedFlags.HELP.string_entity)  # --help
34print(PredefinedFlags.SHORT_HELP.string_entity)  # -H
35print(PredefinedFlags.HOST.string_entity)  # --host
36print(PredefinedFlags.SHORT_PORT.string_entity)  # -P