mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 18:15:28 +03:00
Update documentation and code snippets
This commit is contained in:
@@ -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
|
||||
|
||||
|
||||
Reference in New Issue
Block a user