mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
docs
This commit is contained in:
@@ -1,4 +1,269 @@
|
||||
.. _root_api_command_flag:
|
||||
|
||||
Flag
|
||||
=====
|
||||
=====
|
||||
|
||||
Объект ``Flag`` представляет собой сущность флага, регистрируемого для последующей обработки в приложении ``Argenta``. Его основная задача — определить параметры флага команды, включая имя, префикс и допустимые значения. ``Flag`` используется при создании команд с флагами и предоставляет механизм валидации входящих значений от пользователя.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Документация по :ref:`PossibleValues <root_api_command_possible_values>` — сущность, определяющая допустимые значения флага.
|
||||
|
||||
Документация по :ref:`InputFlag <root_api_command_input_flag>` — объект распаршенного введённого флага.
|
||||
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``
|
||||
|
||||
-----
|
||||
|
||||
Инициализация
|
||||
-------------
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__init__(
|
||||
self, name: str, *,
|
||||
prefix: Literal["-", "--", "---"] = "--",
|
||||
possible_values: list[str] | Pattern[str] | PossibleValues = PossibleValues.ALL,
|
||||
) -> None
|
||||
|
||||
Создает новый флаг для регистрации в команде.
|
||||
|
||||
* ``name`` : Имя флага (обязательный параметр)
|
||||
* ``prefix`` : Префикс флага. По умолчанию ``"--"``. Возможные значения: ``"-"``, ``"--"``, ``"---"``
|
||||
* ``possible_values`` : Допустимые значения флага. По умолчанию ``PossibleValues.ALL``. Может быть списком строк, регулярным выражением или значением из enum ``PossibleValues``
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: name
|
||||
|
||||
Имя флага в виде строки.
|
||||
|
||||
.. py:attribute:: prefix
|
||||
|
||||
Префикс флага. Один из: ``"-"``, ``"--"``, ``"---"``.
|
||||
|
||||
.. py:attribute:: possible_values
|
||||
|
||||
Определяет допустимые значения для флага. Может быть:
|
||||
|
||||
* Списком строк — флаг принимает только значения из этого списка
|
||||
* Регулярным выражением (``Pattern[str]``) — значение проверяется на соответствие паттерну
|
||||
* Значением ``PossibleValues.ALL`` — флаг принимает любое значение
|
||||
* Значением ``PossibleValues.NEITHER`` — флаг не должен иметь значения
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag_snippet.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Свойства
|
||||
--------
|
||||
|
||||
string_entity
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
@property
|
||||
string_entity(self) -> str
|
||||
|
||||
Возвращает строковое представление флага в формате ``prefix + name``.
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
Это свойство объединяет префикс и имя флага в единую строку, которая представляет, как флаг будет выглядеть в командной строке.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag_snippet3.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Магические методы
|
||||
-----------------
|
||||
|
||||
__str__
|
||||
~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__str__(self) -> str
|
||||
|
||||
Возвращает строковое представление флага (аналогично ``string_entity``).
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag_snippet4.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
__repr__
|
||||
~~~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__repr__(self) -> str
|
||||
|
||||
Возвращает отладочное представление объекта флага.
|
||||
|
||||
:return: Строка в формате ``Flag<prefix=..., name=...>``
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag_snippet5.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
__eq__
|
||||
~~~~~~
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__eq__(self, other: object) -> bool
|
||||
|
||||
Сравнивает два флага на равенство по их строковому представлению.
|
||||
|
||||
:param other: Объект для сравнения
|
||||
:return: ``True``, если флаги равны, иначе ``False``
|
||||
:raises NotImplementedError: Если ``other`` не является экземпляром ``Flag``
|
||||
|
||||
Два флага считаются равными, если их ``string_entity`` идентичны.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag_snippet6.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
PredefinedFlags
|
||||
---------------
|
||||
|
||||
``argenta.command.flag.defaults.PredefinedFlags``
|
||||
|
||||
Класс ``PredefinedFlags`` предоставляет набор предопределенных флагов, которые можно использовать в приложениях без необходимости их ручного создания. Эти флаги покрывают наиболее распространенные сценарии использования и следуют общепринятым соглашениям командной строки.
|
||||
|
||||
Все предопределенные флаги являются атрибутами класса и представляют собой готовые экземпляры ``Flag``.
|
||||
|
||||
-----
|
||||
|
||||
Доступные флаги
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
Информационные флаги
|
||||
|
||||
|
||||
.. py:attribute:: PredefinedFlags.HELP
|
||||
|
||||
Флаг для отображения справки: ``--help``
|
||||
|
||||
* ``name``: ``"help"``
|
||||
* ``prefix``: ``"--"`` (по умолчанию)
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.SHORT_HELP
|
||||
|
||||
Короткая версия флага справки: ``-H``
|
||||
|
||||
* ``name``: ``"H"``
|
||||
* ``prefix``: ``"-"``
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.INFO
|
||||
|
||||
Флаг для отображения информации: ``--info``
|
||||
|
||||
* ``name``: ``"info"``
|
||||
* ``prefix``: ``"--"`` (по умолчанию)
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.SHORT_INFO
|
||||
|
||||
Короткая версия флага информации: ``-I``
|
||||
|
||||
* ``name``: ``"I"``
|
||||
* ``prefix``: ``"-"``
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
-----
|
||||
|
||||
Флаги выбора
|
||||
~~~~~~~~~~~~
|
||||
|
||||
.. py:attribute:: PredefinedFlags.ALL
|
||||
|
||||
Флаг для выбора всех элементов: ``--all``
|
||||
|
||||
* ``name``: ``"all"``
|
||||
* ``prefix``: ``"--"``
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.SHORT_ALL
|
||||
|
||||
Короткая версия флага выбора всех элементов: ``-A``
|
||||
|
||||
* ``name``: ``"A"``
|
||||
* ``prefix``: ``"-"``
|
||||
* ``possible_values``: ``PossibleValues.NEITHER``
|
||||
|
||||
-----
|
||||
|
||||
Сетевые флаги
|
||||
~~~~~~~~~~~~~
|
||||
|
||||
.. py:attribute:: PredefinedFlags.HOST
|
||||
|
||||
Флаг для указания IP-адреса хоста: ``--host``
|
||||
|
||||
* ``name``: ``"host"``
|
||||
* ``prefix``: ``"--"`` (по умолчанию)
|
||||
* ``possible_values``: Регулярное выражение для валидации IPv4: ``r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.SHORT_HOST
|
||||
|
||||
Короткая версия флага хоста: ``-H``
|
||||
|
||||
* ``name``: ``"H"``
|
||||
* ``prefix``: ``"-"``
|
||||
* ``possible_values``: Регулярное выражение для валидации IPv4: ``r"^\d{1,3}\.\d{1,3}\.\d{1,3}\.\d{1,3}$"``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.PORT
|
||||
|
||||
Флаг для указания порта: ``--port``
|
||||
|
||||
* ``name``: ``"port"``
|
||||
* ``prefix``: ``"--"`` (по умолчанию)
|
||||
* ``possible_values``: Регулярное выражение для валидации порта: ``r"^\d{1,5}$"``
|
||||
|
||||
.. py:attribute:: PredefinedFlags.SHORT_PORT
|
||||
|
||||
Короткая версия флага порта: ``-P``
|
||||
|
||||
* ``name``: ``"P"``
|
||||
* ``prefix``: ``"-"``
|
||||
* ``possible_values``: Регулярное выражение для валидации порта: ``r"^\d{1,5}$"``
|
||||
|
||||
-----
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/predefined_flags_snippet.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
Reference in New Issue
Block a user