mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
Update documentation and code snippets
This commit is contained in:
@@ -3,18 +3,20 @@
|
||||
DataBridge
|
||||
==========
|
||||
|
||||
`DataBridge` — это сущность, предоставляющая временное хранилище данных, которое существует в рамках одной сессии приложения (от запуска до выхода). Она предназначена для обмена данными между вызовами разных команд.
|
||||
``DataBridge`` — это сущность, предоставляющая временное хранилище данных, которое существует в рамках одной сессии приложения (от запуска до выхода). Она предназначена для обмена данными между обработчиками.
|
||||
|
||||
Основной способ получения доступа к `DataBridge` — через систему внедрения зависимостей (DI).
|
||||
Основной способ получения доступа к ``DataBridge`` — через ``di``.
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
from argenta.di import FromDishka
|
||||
from argenta import DataBridge, Response
|
||||
|
||||
# ... setting up router and other
|
||||
|
||||
def my_handler(response: Response, data_bridge: FromDishka[DataBridge]):
|
||||
# ... ваш код
|
||||
# ... your code
|
||||
|
||||
**Практический пример: Аутентификация**
|
||||
|
||||
@@ -26,9 +28,9 @@ DataBridge
|
||||
|
||||
**Как это работает:**
|
||||
|
||||
1. При вызове обработчика `dishka` автоматически внедряет экземпляр `DataBridge`.
|
||||
2. Команда ``login --username <имя>`` вызывает `login_handler`, который через внедрённый `data_bridge` сохраняет токен.
|
||||
3. Команда `get-profile` вызывает `get_profile_handler`, который так же получает `data_bridge` и извлекает из него токен.
|
||||
1. При вызове обработчика ``dishka`` автоматически внедряет экземпляр ``DataBridge``.
|
||||
2. Команда ``login --username <имя>`` вызывает ``login_handler``, который через внедрённый ``data_bridge`` сохраняет токен.
|
||||
3. Команда ``get-profile`` вызывает ``get_profile_handler``, который так же получает ``data_bridge`` и извлекает из него токен.
|
||||
|
||||
API класса
|
||||
-----------
|
||||
@@ -37,7 +39,7 @@ API класса
|
||||
|
||||
.. py:method:: __init__(self, initial_data: dict | None = None)
|
||||
|
||||
Инициализирует хранилище. При использовании через DI вызывается автоматически.
|
||||
Инициализирует хранилище. При использовании через ``di`` вызывается автоматически.
|
||||
|
||||
.. py:method:: update(self, data: dict) -> None
|
||||
|
||||
@@ -49,11 +51,11 @@ API класса
|
||||
|
||||
.. py:method:: get_by_key(self, key: str) -> Any
|
||||
|
||||
Возвращает значение по ключу или `None`, если ключ не найден.
|
||||
Возвращает значение по ключу или ``None``, если ключ не найден.
|
||||
|
||||
.. py:method:: delete_by_key(self, key: str) -> None
|
||||
|
||||
Удаляет значение по ключу. Вызывает `KeyError`, если ключ не найден.
|
||||
Удаляет значение по ключу. Вызывает ``KeyError``, если ключ не найден.
|
||||
|
||||
.. py:method:: clear_all(self) -> None
|
||||
|
||||
|
||||
@@ -3,9 +3,7 @@
|
||||
Flags
|
||||
======
|
||||
|
||||
`Flags` — это коллекция флагов команды. Её основная задача — группировать и управлять набором флагов, зарегистрированных для конкретной команды. `Flags` служит контейнером, который позволяет удобно добавлять, извлекать, итерировать флаги и проверять их наличие.
|
||||
|
||||
`Flags` наследуется от базового класса `BaseFlags` и специализируется на работе с объектами типа `Flag`. Этот класс используется при создании команд с несколькими флагами и предоставляет интерфейс для управления ими.
|
||||
``Flags`` — это коллекция флагов команды. Её основная задача — группировать и управлять набором флагов, зарегистрированных для конкретной команды. ``Flags`` служит контейнером, который позволяет удобно добавлять, извлекать, итерировать флаги и проверять их наличие.
|
||||
|
||||
.. seealso::
|
||||
|
||||
@@ -27,14 +25,14 @@ Flags
|
||||
|
||||
Создаёт новую коллекцию флагов.
|
||||
|
||||
* ``flags``: Необязательный список флагов типа `Flag` для инициализации коллекции. Если не указан, создаётся пустая коллекция.
|
||||
* ``flags``: Необязательный список флагов типа ``Flag`` для инициализации коллекции. Если не указан, создаётся пустая коллекция.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: flags
|
||||
:no-index:
|
||||
|
||||
Список всех зарегистрированных флагов типа `Flag`. Пуст, если флаги не были переданы при инициализации.
|
||||
Список всех зарегистрированных флагов типа ``Flag``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -57,10 +55,10 @@ add_flag
|
||||
|
||||
Добавляет флаг в коллекцию.
|
||||
|
||||
:param flag: Флаг типа `Flag` для добавления.
|
||||
:param flag: Флаг типа ``Flag`` для добавления.
|
||||
:return: None.
|
||||
|
||||
Метод добавляет флаг в конец списка `flags`. Используется для динамического расширения набора флагов.
|
||||
Используется для динамического расширения набора флагов.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -80,7 +78,7 @@ add_flags
|
||||
|
||||
Добавляет в коллекцию список флагов.
|
||||
|
||||
:param flags: Список флагов типа `Flag` для добавления.
|
||||
:param flags: Список флагов типа ``Flag`` для добавления.
|
||||
:return: None.
|
||||
|
||||
Метод расширяет коллекцию, добавляя в неё все флаги из переданного списка. Эффективен для пакетного добавления.
|
||||
@@ -104,56 +102,12 @@ get_flag_by_name
|
||||
Возвращает флаг по имени.
|
||||
|
||||
:param name: Имя искомого флага.
|
||||
:return: Объект `Flag` или `None`, если флаг не найден.
|
||||
:return: Объект ``Flag`` или ``None``, если флаг не найден.
|
||||
|
||||
Метод выполняет поиск по списку `flags` и возвращает первый флаг с соответствующим именем. Если флаг не найден, возвращается `None`.
|
||||
Метод возвращает флаг с соответствующим именем. Если флаг не найден, возвращается ``None``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flags/snippet4.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Магические методы
|
||||
-----------------
|
||||
|
||||
__iter__
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__iter__(self) -> Iterator[Flag]
|
||||
|
||||
Делает коллекцию итерируемой для использования в циклах.
|
||||
|
||||
:return: Итератор по списку флагов.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flags/snippet5.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
__getitem__
|
||||
~~~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__getitem__(self, flag_index: int) -> Flag
|
||||
|
||||
Позволяет получать флаг по индексу.
|
||||
|
||||
:param flag_index: Индекс флага в списке.
|
||||
:return: Флаг по указанному индексу.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flags/snippet6.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
@@ -3,9 +3,7 @@
|
||||
InputFlags
|
||||
==========
|
||||
|
||||
`InputFlags` — это коллекция флагов, введённых пользователем. Её основная задача — группировать и управлять набором флагов, переданных вместе с командой. `InputFlags` служит контейнером, который позволяет удобно извлекать, итерировать и проверять наличие флагов, а также работать с их значениями и статусами валидации.
|
||||
|
||||
`InputFlags` наследуется от `BaseFlags` и специализируется на работе с объектами типа `InputFlag`. Этот класс создаётся автоматически при обработке пользовательского ввода и передаётся в обработчики команд через объект `Response`.
|
||||
``InputFlags`` — это коллекция флагов, введённых пользователем. Её основная задача — группировать и управлять набором флагов, переданных вместе с командой. ``InputFlags`` служит контейнером, который позволяет удобно извлекать, итерировать и проверять наличие флагов, а также работать с их значениями и статусами валидации.
|
||||
|
||||
.. seealso::
|
||||
|
||||
@@ -29,17 +27,17 @@ InputFlags
|
||||
|
||||
Создаёт новую коллекцию введённых флагов.
|
||||
|
||||
* ``flags``: Необязательный список флагов типа `InputFlag` для инициализации коллекции. Если не указан, создаётся пустая коллекция.
|
||||
* ``flags``: Необязательный список флагов типа ``InputFlag`` для инициализации коллекции. Если не указан, создаётся пустая коллекция.
|
||||
|
||||
.. warning ::
|
||||
Экземпляры этого класса обычно не создаются напрямую. Они автоматически формируются системой при обработке пользовательского ввода и доступны через атрибут `input_flags` объекта `Response`.
|
||||
Экземпляры этого класса обычно не создаются напрямую. Они автоматически формируются системой при обработке пользовательского ввода и доступны через атрибут ``input_flags`` объекта ``Response``.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: flags
|
||||
:no-index:
|
||||
|
||||
Список всех введённых флагов типа `InputFlag`. Пуст, если флаги не были переданы при инициализации или пользователь не ввёл их с командой.
|
||||
Список всех введённых флагов типа ``InputFlag``. Пуст, если флаги не были переданы при инициализации или пользователь не ввёл их с командой.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -60,12 +58,12 @@ get_flag_by_name
|
||||
|
||||
get_flag_by_name(self, name: str) -> InputFlag | None
|
||||
|
||||
Возвращает введённый флаг по имени.
|
||||
Возвращает флаг по имени.
|
||||
|
||||
:param name: Имя искомого флага (без префикса).
|
||||
:return: Объект `InputFlag` или `None`, если флаг не найден.
|
||||
:return: Объект ``InputFlag`` или ``None``, если флаг не найден.
|
||||
|
||||
Метод выполняет поиск по списку `flags` и возвращает первый флаг с соответствующим именем (без учёта префикса).
|
||||
Метод возвращает первый флаг с соответствующим именем (без учёта префикса).
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -124,124 +122,6 @@ add_flags
|
||||
|
||||
-----
|
||||
|
||||
Магические методы
|
||||
-----------------
|
||||
|
||||
__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
|
||||
|
||||
-----
|
||||
|
||||
Практические примеры
|
||||
--------------------
|
||||
|
||||
|
||||
@@ -3,17 +3,17 @@
|
||||
ValidationStatus
|
||||
================
|
||||
|
||||
`ValidationStatus` — это перечисление (`Enum`), которое определяет состояние валидации флага. Его задача — предоставить стандартные константы для отображения результата проверки. `ValidationStatus` используется в атрибуте `status` класса `InputFlag`, чтобы сообщить, прошла ли валидация успешно.
|
||||
``ValidationStatus`` — это перечисление, которое определяет состояние валидации флага. Его задача — предоставить стандартные константы для отображения результата проверки. ``ValidationStatus`` используется в атрибуте ``status`` класса ``InputFlag``.
|
||||
|
||||
`ValidationStatus` наследуется от `Enum` и содержит три значения: `VALID` (корректный флаг), `INVALID` (некорректный) и `UNDEFINED` (незарегистрированный).
|
||||
``ValidationStatus`` содержит три значения: **VALID** (корректный флаг), **INVALID** (некорректный) и **UNDEFINED** (незарегистрированный).
|
||||
|
||||
.. note::
|
||||
|
||||
Статус валидации устанавливается автоматически при создании экземпляра `InputFlag` на основе правил, заданных в соответствующем `Flag`.
|
||||
Статус валидации устанавливается автоматически при создании экземпляра ``InputFlag`` на основе правил, заданных в соответствующем ``Flag``.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Документация по :ref:`InputFlag <root_api_command_input_flag>` — класс введённого флага, использующий `ValidationStatus`.
|
||||
Документация по :ref:`InputFlag <root_api_command_input_flag>` — класс введённого флага, использующий ``ValidationStatus``.
|
||||
|
||||
Документация по :ref:`Flag <root_api_command_flag>` — класс флага с правилами валидации.
|
||||
|
||||
@@ -21,9 +21,6 @@ ValidationStatus
|
||||
|
||||
-----
|
||||
|
||||
Значения enum
|
||||
-------------
|
||||
|
||||
VALID
|
||||
~~~~~
|
||||
|
||||
@@ -34,21 +31,15 @@ VALID
|
||||
|
||||
Указывает, что флаг и его значение **прошли** валидацию.
|
||||
|
||||
Флаги с этим статусом соответствуют правилам, заданным в `possible_values` соответствующего `Flag`. Их можно безопасно использовать в логике приложения без дополнительных проверок.
|
||||
Флаги с этим статусом соответствуют правилам, заданным в ``possible_values`` соответствующего ``Flag``. Их можно безопасно использовать в логике приложения без дополнительных проверок.
|
||||
|
||||
**Условия получения статуса** ``VALID``:
|
||||
|
||||
* Флаг с `PossibleValues.NEITHER` передан без значения.
|
||||
* Флаг с `PossibleValues.ALL` передан с любым значением или без него.
|
||||
* Флаг с ``PossibleValues.NEITHER`` передан без значения.
|
||||
* Флаг с ``PossibleValues.ALL`` передан с любым значением или без него.
|
||||
* Значение флага входит в список разрешённых.
|
||||
* Значение флага соответствует регулярному выражению.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/validation_status/valid.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
INVALID
|
||||
@@ -61,21 +52,15 @@ INVALID
|
||||
|
||||
Указывает, что флаг или его значение **не прошли** валидацию.
|
||||
|
||||
Флаги с этим статусом нарушают правила, заданные в `possible_values` соответствующего `Flag`. Их следует обрабатывать как ошибочные.
|
||||
Флаги с этим статусом нарушают правила, заданные в ``possible_values`` соответствующего ``Flag``. Их следует обрабатывать как ошибочные.
|
||||
|
||||
**Условия получения статуса** ``INVALID``:
|
||||
|
||||
* Флаг с `PossibleValues.NEITHER` передан со значением.
|
||||
* Флаг с ``PossibleValues.NEITHER`` передан со значением.
|
||||
* Значение флага не входит в список разрешённых.
|
||||
* Значение флага не соответствует регулярному выражению.
|
||||
* Флаг требует значение, но передан без него.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/validation_status/invalid.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
UNDEFINED
|
||||
@@ -91,19 +76,3 @@ UNDEFINED
|
||||
**Условия получения статуса** ``UNDEFINED``:
|
||||
|
||||
* Введённый флаг не найден среди зарегистрированных для данной команды.
|
||||
|
||||
-----
|
||||
|
||||
|
||||
Практические примеры
|
||||
--------------------
|
||||
|
||||
Комплексный пример валидации
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Пример демонстрирует использование всех статусов в реальном сценарии.
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/validation_status/comprehensive.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Response
|
||||
========
|
||||
|
||||
`Response` — это объект, который передаётся в обработчик команды. Он создаётся автоматически при обработке пользовательского ввода и содержит статус валидации, введённые флаги.
|
||||
``Response`` — это объект, который передаётся в обработчик команды. Он создаётся автоматически при обработке пользовательского ввода и содержит статус валидации, введённые флаги.
|
||||
|
||||
|
||||
.. seealso::
|
||||
@@ -23,15 +23,14 @@ Response
|
||||
:linenos:
|
||||
|
||||
__init__(
|
||||
self,
|
||||
status: ResponseStatus,
|
||||
self, status: ResponseStatus,
|
||||
input_flags: InputFlags = EMPTY_INPUT_FLAGS,
|
||||
)
|
||||
|
||||
Создаёт новый объект ответа.
|
||||
|
||||
* ``status``: Общий статус валидации флагов из перечисления `ResponseStatus`.
|
||||
* ``input_flags``: Коллекция введённых флагов (`InputFlags`). По умолчанию — пустая.
|
||||
* ``status``: Общий статус валидации флагов из перечисления ``ResponseStatus``.
|
||||
* ``input_flags``: Коллекция введённых флагов (``InputFlags``). По умолчанию — пустая.
|
||||
|
||||
.. warning ::
|
||||
Экземпляры этого класса не предназначены для прямого создания. Они автоматически формируются системой и передаются в обработчик команды в качестве первого обязательного аргумента.
|
||||
@@ -41,12 +40,12 @@ Response
|
||||
.. py:attribute:: status
|
||||
:no-index:
|
||||
|
||||
Общий статус валидации всех флагов команды (`ResponseStatus`). Указывает, были ли среди введённых флагов некорректные или незарегистрированные.
|
||||
Общий статус валидации всех флагов команды (``ResponseStatus``). Указывает, были ли среди введённых флагов некорректные или незарегистрированные.
|
||||
|
||||
.. py:attribute:: input_flags
|
||||
:no-index:
|
||||
|
||||
Коллекция всех флагов, переданных с командой (`InputFlags`). Содержит все обработанные флаги с их значениями и статусами валидации.
|
||||
Коллекция всех флагов, переданных с командой (``InputFlags``). Содержит все обработанные флаги с их значениями и статусами валидации.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -59,7 +58,7 @@ Response
|
||||
Работа с флагами
|
||||
----------------
|
||||
|
||||
`Response` предоставляет доступ к введённым флагам через атрибут `input_flags`. Вы можете проверять их наличие, получать значения и статусы валидации.
|
||||
``Response`` предоставляет доступ к введённым флагам через атрибут ``input_flags``. Вы можете проверять их наличие, получать значения и статусы валидации.
|
||||
|
||||
**Пример работы с флагами:**
|
||||
|
||||
@@ -74,10 +73,7 @@ Response
|
||||
ResponseStatus
|
||||
--------------
|
||||
|
||||
`ResponseStatus` — это перечисление (`Enum`), которое определяет общий статус валидации всех флагов команды. Используется в атрибуте `status` объекта `Response`.
|
||||
|
||||
Значения enum
|
||||
~~~~~~~~~~~~~
|
||||
``ResponseStatus`` — это перечисление, которое определяет общий статус валидации всех флагов команды. Используется в атрибуте ``status`` объекта ``Response``.
|
||||
|
||||
ALL_FLAGS_VALID
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Reference in New Issue
Block a user