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
|
||||
|
||||
@@ -63,20 +63,9 @@ add_flag
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. code-block:: python
|
||||
.. literalinclude:: ../../../code_snippets/flags_snippet2.py
|
||||
:linenos:
|
||||
|
||||
from argenta import Flags, ValueFlag, BooleanFlag
|
||||
|
||||
# Создание коллекции
|
||||
flags = Flags()
|
||||
|
||||
# Динамическое добавление флагов
|
||||
flags.add_flag(ValueFlag("config", help="Config file path"))
|
||||
flags.add_flag(BooleanFlag("debug", help="Debug mode"))
|
||||
flags.add_flag(ValueFlag("log-level", possible_values=["INFO", "DEBUG", "ERROR"]))
|
||||
|
||||
print(len(flags.flags)) # 3
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
@@ -97,28 +86,9 @@ add_flags
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. code-block:: python
|
||||
.. literalinclude:: ../../../code_snippets/flags_snippet3.py
|
||||
:linenos:
|
||||
|
||||
from argenta import Flags, ValueFlag, BooleanFlag
|
||||
|
||||
# Начальная коллекция
|
||||
flags = Flags([
|
||||
ValueFlag("host", default="localhost")
|
||||
])
|
||||
|
||||
# Дополнительные флаги
|
||||
additional_flags = [
|
||||
ValueFlag("port", default="8080"),
|
||||
ValueFlag("database", help="Database name"),
|
||||
BooleanFlag("ssl", help="Use SSL"),
|
||||
BooleanFlag("verbose", help="Verbose output")
|
||||
]
|
||||
|
||||
# Добавление списка флагов
|
||||
flags.add_flags(additional_flags)
|
||||
|
||||
print(len(flags.flags)) # 5
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
@@ -139,27 +109,9 @@ get_flag_by_name
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. code-block:: python
|
||||
.. literalinclude:: ../../../code_snippets/flags_snippet4.py
|
||||
:linenos:
|
||||
|
||||
from argenta import Flags, ValueFlag, BooleanFlag
|
||||
|
||||
flags = Flags([
|
||||
ValueFlag("host", default="localhost"),
|
||||
ValueFlag("port", default="8080"),
|
||||
BooleanFlag("verbose")
|
||||
])
|
||||
|
||||
# Получение флага по имени
|
||||
host_flag = flags.get_flag_by_name("host")
|
||||
if host_flag:
|
||||
print(f"Found flag: {host_flag.name}")
|
||||
print(f"Default value: {host_flag.default}")
|
||||
|
||||
# Поиск несуществующего флага
|
||||
unknown_flag = flags.get_flag_by_name("nonexistent")
|
||||
if unknown_flag is None:
|
||||
print("Flag not found")
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
@@ -180,24 +132,9 @@ __iter__
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. code-block:: python
|
||||
.. literalinclude:: ../../../code_snippets/flags_snippet5.py
|
||||
:linenos:
|
||||
|
||||
from argenta import Flags, ValueFlag, BooleanFlag
|
||||
|
||||
flags = Flags([
|
||||
ValueFlag("host", default="localhost"),
|
||||
ValueFlag("port", default="8080"),
|
||||
BooleanFlag("verbose")
|
||||
])
|
||||
|
||||
# Итерация по всем флагам
|
||||
for flag in flags:
|
||||
print(f"Flag: {flag.name} (type: {type(flag).__name__})")
|
||||
|
||||
# Использование в list comprehension
|
||||
flag_names = [flag.name for flag in flags]
|
||||
print(f"All flags: {flag_names}")
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
@@ -216,12 +153,6 @@ __getitem__
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. code-block:: python
|
||||
.. literalinclude:: ../../../code_snippets/flags_snippet6.py
|
||||
:linenos:
|
||||
|
||||
from argenta import Flags, ValueFlag
|
||||
|
||||
flags = Flags([
|
||||
ValueFlag("first"),
|
||||
ValueFlag("second"),
|
||||
ValueFlag("third")
|
||||
:language: python
|
||||
|
||||
Reference in New Issue
Block a user