diff --git a/docs/code_snippets/input_flags/snippet1.py b/docs/code_snippets/input_flags/snippet1.py new file mode 100644 index 0000000..4a79340 --- /dev/null +++ b/docs/code_snippets/input_flags/snippet1.py @@ -0,0 +1,23 @@ +from argenta import Router, Command, Response +from argenta.command import Flag, Flags + +router = Router(title="Example") + +@router.command(Command( + "example", + description="Example command with flags", + flags=Flags([ + Flag("name"), + Flag("age") + ]) +)) +def example_handler(response: Response): + # response.input_flags содержит коллекцию InputFlags + input_flags = response.input_flags + + # Проверяем наличие флагов + if input_flags: + print(f"Received {len(input_flags.flags)} flag(s)") + else: + print("No flags provided") + diff --git a/docs/code_snippets/input_flags/snippet10.py b/docs/code_snippets/input_flags/snippet10.py new file mode 100644 index 0000000..0942644 --- /dev/null +++ b/docs/code_snippets/input_flags/snippet10.py @@ -0,0 +1,48 @@ +from argenta import Router, Command, Response +from argenta.command import Flag, Flags +from argenta.command.flag import ValidationStatus + +router = Router(title="Comprehensive Example") + +@router.command(Command( + "validate", + description="Validate all flags", + flags=Flags([ + Flag("format", possible_values=["json", "xml"]), + Flag("output"), + Flag("force") + ]) +)) +def validate_handler(response: Response): + input_flags = response.input_flags + + # Итерируемся по всем флагам и проверяем их статусы + print("Flag validation results:") + + valid_flags = [] + invalid_flags = [] + undefined_flags = [] + + for flag in input_flags: + if flag.status == ValidationStatus.VALID: + valid_flags.append(flag) + print(f" ✓ {flag.string_entity}: {flag.input_value} (VALID)") + elif flag.status == ValidationStatus.INVALID: + invalid_flags.append(flag) + print(f" ✗ {flag.string_entity}: {flag.input_value} (INVALID)") + elif flag.status == ValidationStatus.UNDEFINED: + undefined_flags.append(flag) + print(f" ? {flag.string_entity}: {flag.input_value} (UNDEFINED)") + + # Выводим сводку + print(f"\nSummary:") + print(f" Valid flags: {len(valid_flags)}") + print(f" Invalid flags: {len(invalid_flags)}") + print(f" Undefined flags: {len(undefined_flags)}") + + # Обрабатываем только валидные флаги + if valid_flags: + print("\nProcessing valid flags:") + for flag in valid_flags: + print(f" Processing {flag.name} = {flag.input_value}") + diff --git a/docs/code_snippets/input_flags/snippet2.py b/docs/code_snippets/input_flags/snippet2.py new file mode 100644 index 0000000..d711943 --- /dev/null +++ b/docs/code_snippets/input_flags/snippet2.py @@ -0,0 +1,36 @@ +from argenta import Router, Command, Response +from argenta.command import Flag, Flags + +router = Router(title="Get Flag Example") + +@router.command(Command( + "config", + description="Configure settings", + flags=Flags([ + Flag("host"), + Flag("port"), + Flag("debug") + ]) +)) +def config_handler(response: Response): + input_flags = response.input_flags + + # Получаем флаг по имени + host_flag = input_flags.get_flag_by_name("host") + port_flag = input_flags.get_flag_by_name("port") + debug_flag = input_flags.get_flag_by_name("debug") + + if host_flag: + print(f"Host: {host_flag.input_value}") + + if port_flag: + print(f"Port: {port_flag.input_value}") + + if debug_flag: + print("Debug mode enabled") + + # Если флаг не найден, get_flag_by_name вернёт None + missing_flag = input_flags.get_flag_by_name("nonexistent") + if missing_flag is None: + print("Flag 'nonexistent' not found") + diff --git a/docs/code_snippets/input_flags/snippet3.py b/docs/code_snippets/input_flags/snippet3.py new file mode 100644 index 0000000..5c69149 --- /dev/null +++ b/docs/code_snippets/input_flags/snippet3.py @@ -0,0 +1,22 @@ +from argenta import Router, Command, Response +from argenta.command.flag import InputFlag, ValidationStatus, InputFlags + +router = Router(title="Add Flag Example") + +@router.command(Command("test", description="Test command")) +def test_handler(response: Response): + # Создаём новую коллекцию InputFlags + new_flags = InputFlags() + + # Добавляем один флаг + test_flag = InputFlag( + name="test", + prefix="--", + input_value="value", + status=ValidationStatus.VALID + ) + new_flags.add_flag(test_flag) + + print(f"Flags count: {len(new_flags.flags)}") + print(f"First flag: {new_flags.flags[0].name}") + diff --git a/docs/code_snippets/input_flags/snippet4.py b/docs/code_snippets/input_flags/snippet4.py new file mode 100644 index 0000000..eaebbc6 --- /dev/null +++ b/docs/code_snippets/input_flags/snippet4.py @@ -0,0 +1,34 @@ +from argenta.command.flag import InputFlag, ValidationStatus, InputFlags + +# Создаём коллекцию InputFlags +flags = InputFlags() + +# Создаём несколько флагов +flag1 = InputFlag( + name="option1", + prefix="--", + input_value="value1", + status=ValidationStatus.VALID +) + +flag2 = InputFlag( + name="option2", + prefix="--", + input_value="value2", + status=ValidationStatus.VALID +) + +flag3 = InputFlag( + name="option3", + prefix="---", + input_value="value3", + status=ValidationStatus.VALID +) + +# Добавляем все флаги одним вызовом +flags.add_flags([flag1, flag2, flag3]) + +print(f"Total flags: {len(flags.flags)}") +for flag in flags: + print(f" - {flag.string_entity}: {flag.input_value}") + diff --git a/docs/code_snippets/input_flags/snippet5.py b/docs/code_snippets/input_flags/snippet5.py new file mode 100644 index 0000000..2572dec --- /dev/null +++ b/docs/code_snippets/input_flags/snippet5.py @@ -0,0 +1,28 @@ +from argenta import Router, Command, Response +from argenta.command import Flag, Flags + +router = Router(title="Iterate Example") + +@router.command(Command( + "process", + description="Process with multiple flags", + flags=Flags([ + Flag("file"), + Flag("format"), + Flag("output") + ]) +)) +def process_handler(response: Response): + input_flags = response.input_flags + + # Итерируемся по всем введённым флагам + print("All flags:") + for flag in input_flags: + status_str = flag.status.name if flag.status else "None" + print(f" {flag.string_entity}: {flag.input_value} (status: {status_str})") + + # Также можно использовать enumerate для получения индексов + print("\nFlags with indices:") + for index, flag in enumerate(input_flags): + print(f" [{index}] {flag.name}: {flag.input_value}") + diff --git a/docs/code_snippets/input_flags/snippet6.py b/docs/code_snippets/input_flags/snippet6.py new file mode 100644 index 0000000..ddc93d8 --- /dev/null +++ b/docs/code_snippets/input_flags/snippet6.py @@ -0,0 +1,31 @@ +from argenta import Router, Command, Response +from argenta.command import Flag, Flags + +router = Router(title="Index Access Example") + +@router.command(Command( + "example", + description="Example with indexed access", + flags=Flags([ + Flag("first"), + Flag("second"), + Flag("third") + ]) +)) +def example_handler(response: Response): + input_flags = response.input_flags + + # Получаем флаги по индексу + if len(input_flags.flags) > 0: + first_flag = input_flags[0] + print(f"First flag: {first_flag.name} = {first_flag.input_value}") + + if len(input_flags.flags) > 1: + second_flag = input_flags[1] + print(f"Second flag: {second_flag.name} = {second_flag.input_value}") + + # Можно использовать срез для получения нескольких флагов + if len(input_flags.flags) >= 2: + first_two = input_flags.flags[:2] + print(f"First two flags: {[f.name for f in first_two]}") + diff --git a/docs/code_snippets/input_flags/snippet7.py b/docs/code_snippets/input_flags/snippet7.py new file mode 100644 index 0000000..5833513 --- /dev/null +++ b/docs/code_snippets/input_flags/snippet7.py @@ -0,0 +1,28 @@ +from argenta import Router, Command, Response +from argenta.command import Flag, Flags + +router = Router(title="Bool Check Example") + +@router.command(Command( + "action", + description="Action with optional flags", + flags=Flags([ + Flag("option1"), + Flag("option2") + ]) +)) +def action_handler(response: Response): + input_flags = response.input_flags + + # Проверяем наличие флагов + if input_flags: + print("Flags were provided:") + for flag in input_flags: + print(f" - {flag.name}: {flag.input_value}") + else: + print("No flags provided, using defaults") + + # Альтернативный способ проверки + has_flags = bool(input_flags) + print(f"\nHas flags: {has_flags}") + diff --git a/docs/code_snippets/input_flags/snippet8.py b/docs/code_snippets/input_flags/snippet8.py new file mode 100644 index 0000000..79e6aa0 --- /dev/null +++ b/docs/code_snippets/input_flags/snippet8.py @@ -0,0 +1,30 @@ +from argenta.command.flag.flags.models import InputFlags +from argenta.command.flag import InputFlag, ValidationStatus + +# Создаём первую коллекцию +flags1 = InputFlags([ + InputFlag(name="flag1", input_value="value1", status=ValidationStatus.VALID), + InputFlag(name="flag2", input_value="value2", status=ValidationStatus.VALID) +]) + +# Создаём вторую коллекцию с теми же флагами +flags2 = InputFlags([ + InputFlag(name="flag1", input_value="value1", status=ValidationStatus.VALID), + InputFlag(name="flag2", input_value="value2", status=ValidationStatus.VALID) +]) + +# Создаём третью коллекцию с другими флагами +flags3 = InputFlags([ + InputFlag(name="flag1", input_value="different", status=ValidationStatus.VALID), + InputFlag(name="flag2", input_value="value2", status=ValidationStatus.VALID) +]) + +print(f"flags1 == flags2: {flags1 == flags2}") # True (одинаковые имена) +print(f"flags1 == flags3: {flags1 == flags3}") # True (имена одинаковые, значения не учитываются) + +# Разные коллекции +flags4 = InputFlags([ + InputFlag(name="flag3", input_value="value3", status=ValidationStatus.VALID) +]) +print(f"flags1 == flags4: {flags1 == flags4}") # False (разные флаги) + diff --git a/docs/code_snippets/input_flags/snippet9.py b/docs/code_snippets/input_flags/snippet9.py new file mode 100644 index 0000000..db74241 --- /dev/null +++ b/docs/code_snippets/input_flags/snippet9.py @@ -0,0 +1,40 @@ +from argenta import Router, Command, Response +from argenta.command import Flag, Flags +from argenta.command.flag import InputFlag, ValidationStatus + +router = Router(title="Contains Example") + +@router.command(Command( + "check", + description="Check flags", + flags=Flags([ + Flag("verbose"), + Flag("debug"), + Flag("quiet") + ]) +)) +def check_handler(response: Response): + input_flags = response.input_flags + + # Проверяем наличие конкретного флага + verbose_flag = input_flags.get_flag_by_name("verbose") + debug_flag = input_flags.get_flag_by_name("debug") + + # Используем оператор in для проверки + if verbose_flag and verbose_flag in input_flags: + print("Verbose flag is present") + + if debug_flag and debug_flag in input_flags: + print("Debug flag is present") + + # Можно создать флаг для проверки (сравнение идёт по имени) + test_flag = InputFlag( + name="verbose", + prefix="--", + input_value="any", + status=None + ) + + if test_flag in input_flags: + print("Verbose flag found using 'in' operator") + diff --git a/docs/code_snippets/response/snippet1.py b/docs/code_snippets/response/snippet1.py new file mode 100644 index 0000000..7030edd --- /dev/null +++ b/docs/code_snippets/response/snippet1.py @@ -0,0 +1,16 @@ +from argenta import Router, Command, Response +from argenta.response import ResponseStatus + +router = Router(title="Example") + +@router.command(Command("greet", description="Greet the user")) +def greet_handler(response: Response): + # response автоматически передаётся в обработчик + # response.status содержит статус валидации флагов + # response.input_flags содержит все введённые флаги + + if response.status == ResponseStatus.ALL_FLAGS_VALID: + print("Hello! All flags are valid.") + else: + print("Warning: Some flags have issues.") + diff --git a/docs/code_snippets/response/snippet2.py b/docs/code_snippets/response/snippet2.py new file mode 100644 index 0000000..f59c815 --- /dev/null +++ b/docs/code_snippets/response/snippet2.py @@ -0,0 +1,22 @@ +from argenta import Router, Command, Response + +router = Router(title="Data Example") + +@router.command(Command("set", description="Set data")) +def set_handler(response: Response): + # Обновляем глобальное хранилище данных + response.update_data({ + "user_name": "John", + "timestamp": "2024-01-01", + "settings": {"theme": "dark", "language": "ru"} + }) + print("Data updated successfully") + +@router.command(Command("show", description="Show data")) +def show_handler(response: Response): + # Получаем данные из глобального хранилища + data = response.get_data() + if "user_name" in data: + print(f"User: {data['user_name']}") + print(f"Settings: {data.get('settings', {})}") + diff --git a/docs/code_snippets/response/snippet3.py b/docs/code_snippets/response/snippet3.py new file mode 100644 index 0000000..c7a6d09 --- /dev/null +++ b/docs/code_snippets/response/snippet3.py @@ -0,0 +1,16 @@ +from argenta import Router, Command, Response + +router = Router(title="Get Data Example") + +@router.command(Command("info", description="Show all stored data")) +def info_handler(response: Response): + # Получаем все данные из глобального хранилища + all_data = response.get_data() + + if all_data: + print("Stored data:") + for key, value in all_data.items(): + print(f" {key}: {value}") + else: + print("No data stored") + diff --git a/docs/code_snippets/response/snippet4.py b/docs/code_snippets/response/snippet4.py new file mode 100644 index 0000000..52a735f --- /dev/null +++ b/docs/code_snippets/response/snippet4.py @@ -0,0 +1,18 @@ +from argenta import Router, Command, Response + +router = Router(title="Clear Data Example") + +@router.command(Command("clear", description="Clear all stored data")) +def clear_handler(response: Response): + # Очищаем всё хранилище данных + response.clear_data() + print("All data cleared") + +@router.command(Command("check", description="Check if data exists")) +def check_handler(response: Response): + data = response.get_data() + if data: + print(f"Storage contains {len(data)} item(s)") + else: + print("Storage is empty") + diff --git a/docs/code_snippets/response/snippet5.py b/docs/code_snippets/response/snippet5.py new file mode 100644 index 0000000..db09bb8 --- /dev/null +++ b/docs/code_snippets/response/snippet5.py @@ -0,0 +1,26 @@ +from argenta import Router, Command, Response + +router = Router(title="Delete Data Example") + +@router.command(Command("store", description="Store data")) +def store_handler(response: Response): + response.update_data({ + "temp_key": "temporary value", + "important_key": "important value", + "another_key": "another value" + }) + print("Data stored") + +@router.command(Command("remove", description="Remove specific key")) +def remove_handler(response: Response): + # Удаляем конкретный ключ из хранилища + try: + response.delete_from_data("temp_key") + print("Key 'temp_key' deleted") + + # Проверяем, что осталось + remaining = response.get_data() + print(f"Remaining keys: {list(remaining.keys())}") + except KeyError: + print("Key not found") + diff --git a/docs/code_snippets/response/snippet6.py b/docs/code_snippets/response/snippet6.py new file mode 100644 index 0000000..f09ab36 --- /dev/null +++ b/docs/code_snippets/response/snippet6.py @@ -0,0 +1,38 @@ +from argenta import Router, Command, Response +from argenta.command import Flag, Flags +from argenta.response import ResponseStatus + +router = Router(title="Flags Example") + +@router.command(Command( + "process", + description="Process with flags", + flags=Flags([ + Flag("format", possible_values=["json", "xml"]), + Flag("verbose") + ]) +)) +def process_handler(response: Response): + # Проверяем статус валидации флагов + print(f"Status: {response.status.value}") + + # Работаем с флагами + format_flag = response.input_flags.get_flag_by_name("format") + verbose_flag = response.input_flags.get_flag_by_name("verbose") + + if format_flag: + format_value = format_flag.input_value + print(f"Format: {format_value}") + + if verbose_flag: + print("Verbose mode enabled") + + # Проверяем валидность флагов + if response.status == ResponseStatus.ALL_FLAGS_VALID: + print("All flags are valid, proceeding...") + elif response.status == ResponseStatus.INVALID_VALUE_FLAGS: + print("Warning: Some flags have invalid values") + for flag in response.input_flags: + if flag.status and flag.status.name == "INVALID": + print(f" Invalid flag: {flag.string_entity} = {flag.input_value}") + diff --git a/docs/root/api/command/input_flags.rst b/docs/root/api/command/input_flags.rst index 7bf60cb..6d25c29 100644 --- a/docs/root/api/command/input_flags.rst +++ b/docs/root/api/command/input_flags.rst @@ -1,4 +1,254 @@ .. _root_api_command_input_flags: InputFlags -=========== \ No newline at end of file +========== + +Объект ``InputFlags`` представляет собой коллекцию введённых флагов команды в приложении ``Argenta``. Его основная задача — группировать и управлять набором флагов, которые были введены пользователем вместе с командой. ``InputFlags`` служит контейнером, который позволяет удобно извлекать, итерировать и проверять наличие введённых флагов, а также работать с их значениями и статусами валидации. + +``InputFlags`` наследуется от базового класса ``BaseFlags`` и специализируется для работы с объектами типа ``InputFlag``. Этот класс автоматически создаётся системой при парсинге пользовательского ввода и передаётся в обработчики команд через объект ``Response``. + +.. seealso:: + + Документация по отдельным флагам (:ref:`Flag `, :ref:`InputFlag `) + + Документация по :ref:`Flags ` — коллекции зарегистрированных флагов команды + + Документация по :ref:`Response ` — объект ответа, содержащий ``InputFlags`` + + :ref:`Общая информация ` о флагах и их использовании в приложении ``Argenta`` + +----- + +Инициализация +------------- + +.. code-block:: python + :linenos: + + __init__(self, flags: list[InputFlag] | None = None) -> None + +Создает новую коллекцию введённых флагов. + +* ``flags`` : Необязательный список введённых флагов типа ``InputFlag`` для инициализации коллекции. Если не указан, создается пустая коллекция. + +.. warning :: + Экземпляры класса обычно не создаются напрямую. Они автоматически формируются системой при парсинге пользовательского ввода и доступны через атрибут ``input_flags`` объекта ``Response`` в обработчиках команд. + +**Атрибуты:** + +.. py:attribute:: flags + + Список всех введённых флагов типа ``InputFlag``. Пустой список, если флаги не были переданы при инициализации или пользователь не ввёл флагов с командой. + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/input_flags/snippet1.py + :linenos: + :language: python + +----- + +Методы +------ + +get_flag_by_name +~~~~~~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + get_flag_by_name(self, name: str) -> InputFlag | None + +Получает введённый флаг по его имени. + +:param name: Имя искомого флага (без префикса) +:return: Объект ``InputFlag`` с указанным именем или ``None``, если флаг не найден + +Метод выполняет поиск по списку ``flags`` и возвращает первый флаг с соответствующим именем. Поиск происходит по атрибуту ``name`` объекта ``InputFlag``, сравнивая только имена флагов, без учёта префикса. + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/input_flags/snippet2.py + :linenos: + :language: python + +----- + +add_flag +~~~~~~~~ + +.. code-block:: python + :linenos: + + add_flag(self, flag: InputFlag) -> None + +Добавляет один введённый флаг в коллекцию. + +:param flag: Флаг типа ``InputFlag`` для добавления в коллекцию +:return: None + +Метод добавляет переданный флаг в конец списка ``flags``. Используется для динамического расширения набора флагов после создания коллекции. + +.. note:: + Этот метод используется редко, так как ``InputFlags`` обычно создаётся автоматически системой при парсинге пользовательского ввода. Однако он может быть полезен для тестирования или ручного создания коллекций флагов. + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/input_flags/snippet3.py + :linenos: + :language: python + +----- + +add_flags +~~~~~~~~~ + +.. code-block:: python + :linenos: + + add_flags(self, flags: list[InputFlag]) -> None + +Добавляет список введённых флагов в коллекцию. + +:param flags: Список флагов типа ``InputFlag`` для добавления +:return: None + +Метод расширяет текущую коллекцию, добавляя все флаги из переданного списка. Эффективен для пакетного добавления множества флагов. + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/input_flags/snippet4.py + :linenos: + :language: python + +----- + +Магические методы +----------------- + +__iter__ +~~~~~~~~ + +.. code-block:: python + :linenos: + + __iter__(self) -> Iterator[InputFlag] + +Делает коллекцию итерируемой, позволяя использовать её в циклах. + +:return: Итератор по списку введённых флагов + +Позволяет перебирать все введённые флаги команды, что особенно полезно для проверки статусов валидации или обработки всех флагов. + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/input_flags/snippet5.py + :linenos: + :language: python + +----- + +__getitem__ +~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + __getitem__(self, flag_index: int) -> InputFlag + +Позволяет получать введённые флаги по индексу. + +:param flag_index: Индекс флага в списке +:return: Флаг с указанным индексом + +Позволяет обращаться к флагам по их позиции в списке, что может быть полезно для обработки флагов в определённом порядке. + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/input_flags/snippet6.py + :linenos: + :language: python + +----- + +__bool__ +~~~~~~~~ + +.. code-block:: python + :linenos: + + __bool__(self) -> bool + +Определяет, содержит ли коллекция какие-либо флаги. + +:return: ``True``, если в коллекции есть хотя бы один флаг, иначе ``False`` + +Позволяет проверять наличие флагов в команде, что удобно для условной логики. + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/input_flags/snippet7.py + :linenos: + :language: python + +----- + +__eq__ +~~~~~~ + +.. code-block:: python + :linenos: + + __eq__(self, other: object) -> bool + +Сравнивает две коллекции введённых флагов на равенство. + +:param other: Объект для сравнения +:return: ``True``, если коллекции равны, иначе ``False`` +:raises NotImplementedError: Если ``other`` не является экземпляром ``InputFlags`` + +Две коллекции считаются равными, если они содержат одинаковое количество флагов и все соответствующие флаги равны (сравнение происходит по правилам ``InputFlag.__eq__``, то есть по имени). + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/input_flags/snippet8.py + :linenos: + :language: python + +----- + +__contains__ +~~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + __contains__(self, ingressable_item: object) -> bool + +Проверяет, содержится ли указанный введённый флаг в коллекции. + +:param ingressable_item: Объект ``InputFlag`` для проверки +:return: ``True``, если флаг найден в коллекции, иначе ``False`` +:raises TypeError: Если ``ingressable_item`` не является экземпляром ``InputFlag`` + +Позволяет использовать оператор ``in`` для проверки наличия флага в коллекции. + +**Пример использования:** + +.. literalinclude:: ../../../code_snippets/input_flags/snippet9.py + :linenos: + :language: python + +----- + +Практические примеры +-------------------- + +Обработка всех флагов с проверкой статусов +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Пример демонстрирует, как итерироваться по всем введённым флагам и проверять их статусы валидации: + +.. literalinclude:: ../../../code_snippets/input_flags/snippet10.py + :linenos: + :language: python diff --git a/docs/root/api/response.rst b/docs/root/api/response.rst index 75ba620..9468c1e 100644 --- a/docs/root/api/response.rst +++ b/docs/root/api/response.rst @@ -1,4 +1,212 @@ .. _root_api_response: Response -**************** +======== + +Объект ``Response`` представляет собой сущность ответа пользовательского ввода, передаваемого в обработчик команды. Он создаётся автоматически при парсинге пользовательского ввода и содержит информацию о статусе валидации флагов, введённые флаги, а также предоставляет механизм для передачи данных между обработчиками команд через глобальное хранилище данных. + +``Response`` наследуется от ``DataBridge``, который предоставляет методы для работы с глобальным хранилищем данных, позволяющим обмениваться данными между различными обработчиками команд в контексте приложения. + +.. seealso:: + + Документация по :ref:`InputFlags ` — коллекция введённых флагов команды. + + Документация по :ref:`ResponseStatus ` — статусы валидации флагов команды. + + Документация по :ref:`InputFlag ` — отдельный введённый флаг. + +----- + +Инициализация +------------- + +.. code-block:: python + :linenos: + + __init__( + self, + status: ResponseStatus, + input_flags: InputFlags = EMPTY_INPUT_FLAGS, + ) + +Создаёт новый объект ответа на пользовательский ввод. + +* ``status`` : Статус валидации флагов команды из перечисления ``ResponseStatus`` +* ``input_flags`` : Коллекция введённых флагов команды. По умолчанию используется пустая коллекция ``EMPTY_INPUT_FLAGS`` + +.. warning :: + Экземпляры класса не предназначены для их прямого создания. Они автоматически создаются системой при обработке пользовательского ввода и передаются в обработчики команд в качестве обязательного первого аргумента. + +**Атрибуты:** + +.. py:attribute:: status + + Статус валидации всех флагов команды типа ``ResponseStatus``. Указывает, были ли среди введённых флагов невалидные или незарегистрированные. + +.. py:attribute:: input_flags + + Коллекция всех флагов, переданных с командой, типа ``InputFlags``. Содержит все распарсенные флаги команды с их значениями и статусами валидации. + +**Пример использования:** + +.. literalinclude:: ../../code_snippets/response/snippet1.py + :linenos: + :language: python + +----- + +Методы DataBridge + +``Response`` наследует от ``DataBridge`` методы для работы с глобальным хранилищем данных, которое позволяет передавать информацию между различными обработчиками команд в рамках одного сеанса работы приложения. + +update_data +~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + @classmethod + update_data(cls, data: dict[str, Any]) -> None + +Обновляет глобальное хранилище данных, добавляя или обновляя значения из переданного словаря. + +:param data: Словарь с данными для обновления хранилища +:return: None + +Метод объединяет переданные данные с существующими данными в хранилище. Если ключ уже существует, его значение будет обновлено. + +**Пример использования:** + +.. literalinclude:: ../../code_snippets/response/snippet2.py + :linenos: + :language: python + +----- + +get_data +~~~~~~~~ + +.. code-block:: python + :linenos: + + @classmethod + get_data(cls) -> dict[str, Any] + +Получает все данные из глобального хранилища. + +:return: Словарь со всеми данными из хранилища + +**Пример использования:** + +.. literalinclude:: ../../code_snippets/response/snippet3.py + :linenos: + :language: python + +----- + +clear_data +~~~~~~~~~~ + +.. code-block:: python + :linenos: + + @classmethod + clear_data(cls) -> None + +Очищает все данные из глобального хранилища. + +:return: None + +**Пример использования:** + +.. literalinclude:: ../../code_snippets/response/snippet4.py + :linenos: + :language: python + +----- + +delete_from_data +~~~~~~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + @classmethod + delete_from_data(cls, key: str) -> None + +Удаляет конкретный ключ и его значение из глобального хранилища данных. + +:param key: Ключ, который необходимо удалить из хранилища +:return: None +:raises KeyError: Если указанный ключ не существует в хранилище + +**Пример использования:** + +.. literalinclude:: ../../code_snippets/response/snippet5.py + :linenos: + :language: python + +----- + +Работа с флагами +---------------- + +``Response`` предоставляет доступ к введённым флагам команды через атрибут ``input_flags``. Вы можете проверять наличие флагов, получать их значения и статусы валидации. + +**Пример работы с флагами:** + +.. literalinclude:: ../../code_snippets/response/snippet6.py + :linenos: + :language: python + +----- + +.. _root_api_response_status: + +ResponseStatus +-------------- + +Enum ``ResponseStatus`` представляет собой перечисление, определяющее общий статус валидации всех флагов команды. Используется в атрибуте ``status`` объекта ``Response`` для информирования о результате проверки всех введённых флагов. + +Значения enum +~~~~~~~~~~~~~ + +ALL_FLAGS_VALID +~~~~~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + ResponseStatus.ALL_FLAGS_VALID = 'ALL_FLAGS_VALID' + +Указывает, что все введённые флаги команды прошли валидацию успешно. Нет ни невалидных, ни незарегистрированных флагов. + +UNDEFINED_FLAGS +~~~~~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + ResponseStatus.UNDEFINED_FLAGS = 'UNDEFINED_FLAGS' + +Указывает, что среди введённых флагов присутствуют незарегистрированные флаги, но нет флагов с невалидными значениями. + +INVALID_VALUE_FLAGS +~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + ResponseStatus.INVALID_VALUE_FLAGS = 'INVALID_VALUE_FLAGS' + +Указывает, что среди введённых флагов присутствуют флаги с невалидными значениями, но нет незарегистрированных флагов. + +UNDEFINED_AND_INVALID_FLAGS +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +.. code-block:: python + :linenos: + + ResponseStatus.UNDEFINED_AND_INVALID_FLAGS = 'UNDEFINED_AND_INVALID_FLAGS' + +Указывает, что среди введённых флагов одновременно присутствуют и незарегистрированные флаги, и флаги с невалидными значениями.