docs

2026-06-10 10:05:28 +03:00 · 2025-11-01 11:54:46 +03:00
parent e4a5c6d398
commit 9b28ef17ff
18 changed files with 916 additions and 2 deletions
@@ -1,4 +1,254 @@
 .. _root_api_command_input_flags:

 InputFlags
-===========
+==========
+
+Объект ``InputFlags`` представляет собой коллекцию введённых флагов команды в приложении ``Argenta``. Его основная задача — группировать и управлять набором флагов, которые были введены пользователем вместе с командой. ``InputFlags`` служит контейнером, который позволяет удобно извлекать, итерировать и проверять наличие введённых флагов, а также работать с их значениями и статусами валидации.
+
+``InputFlags`` наследуется от базового класса ``BaseFlags`` и специализируется для работы с объектами типа ``InputFlag``. Этот класс автоматически создаётся системой при парсинге пользовательского ввода и передаётся в обработчики команд через объект ``Response``.
+
+.. seealso::
+
+   Документация по отдельным флагам (:ref:`Flag <root_api_command_flag>`, :ref:`InputFlag <root_api_command_input_flag>`)
+   
+   Документация по :ref:`Flags <root_api_command_flags>` — коллекции зарегистрированных флагов команды
+   
+   Документация по :ref:`Response <root_api_response>` — объект ответа, содержащий ``InputFlags``
+   
+   :ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``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
@@ -1,4 +1,212 @@
 .. _root_api_response:

 Response
-****************
+========
+
+Объект ``Response`` представляет собой сущность ответа пользовательского ввода, передаваемого в обработчик команды. Он создаётся автоматически при парсинге пользовательского ввода и содержит информацию о статусе валидации флагов, введённые флаги, а также предоставляет механизм для передачи данных между обработчиками команд через глобальное хранилище данных.
+
+``Response`` наследуется от ``DataBridge``, который предоставляет методы для работы с глобальным хранилищем данных, позволяющим обмениваться данными между различными обработчиками команд в контексте приложения.
+
+.. seealso::
+
+   Документация по :ref:`InputFlags <root_api_command_input_flags>` — коллекция введённых флагов команды.
+
+   Документация по :ref:`ResponseStatus <root_api_response_status>` — статусы валидации флагов команды.
+
+   Документация по :ref:`InputFlag <root_api_command_input_flag>` — отдельный введённый флаг.
+
+-----
+
+Инициализация
+-------------
+
+.. 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'
+
+Указывает, что среди введённых флагов одновременно присутствуют и незарегистрированные флаги, и флаги с невалидными значениями.