mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
docs
This commit is contained in:
@@ -1,20 +1,19 @@
|
||||
from argenta import Command
|
||||
from argenta.command import Flag, Flags
|
||||
from argenta.command import Flag, Flags, Command
|
||||
|
||||
# Простая команда без флагов
|
||||
# Simple command without flags
|
||||
hello_cmd = Command("hello", description="Greet the user")
|
||||
|
||||
# Команда с описанием и псевдонимами
|
||||
# Command with description and aliases
|
||||
quit_cmd = Command("quit", description="Exit the application", aliases=["exit", "q"])
|
||||
|
||||
# Команда с флагами
|
||||
# Command with flags
|
||||
deploy_cmd = Command(
|
||||
"deploy",
|
||||
description="Deploy application to server",
|
||||
flags=Flags(
|
||||
[
|
||||
Flag("env", help="Environment name", possible_values=["dev", "prod"]),
|
||||
Flag("force", help="Force deployment"),
|
||||
Flag("env", possible_values=["dev", "prod"]),
|
||||
Flag("force"),
|
||||
]
|
||||
),
|
||||
aliases=["dep"],
|
||||
|
||||
@@ -4,7 +4,7 @@ router = Router(title="User Management")
|
||||
|
||||
|
||||
@router.command(Command("create-user", description="Create a new user account"))
|
||||
def handle_create_user(response):
|
||||
def handle_create_user(response: Response):
|
||||
print("Creating new user...")
|
||||
|
||||
|
||||
|
||||
@@ -10,9 +10,9 @@ router = Router(title="Server Management")
|
||||
description="Start the server",
|
||||
flags=Flags(
|
||||
[
|
||||
Flag("port", help="Server port", default="8080"),
|
||||
Flag("host", help="Server host", default="localhost"),
|
||||
Flag("debug", help="Enable debug mode"),
|
||||
Flag("port"),
|
||||
Flag("host"),
|
||||
Flag("debug"),
|
||||
]
|
||||
),
|
||||
aliases=["run"],
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
from argenta import Router, Command, Response
|
||||
|
||||
router = Router(title="System")
|
||||
|
||||
@router.command(Command(
|
||||
"shutdown",
|
||||
description="Shutdown the system",
|
||||
aliases=["poweroff", "halt", "stop"]
|
||||
))
|
||||
def handle_shutdown(response: Response):
|
||||
print("Shutting down the system...")
|
||||
@@ -1,6 +1,6 @@
|
||||
from argenta.command import Flags, PredefinedFlags
|
||||
|
||||
# Использование предопределенных флагов при создании команды
|
||||
# Using predefined flags when creating a command
|
||||
command_flags = Flags(
|
||||
[
|
||||
PredefinedFlags.HELP,
|
||||
@@ -9,7 +9,7 @@ command_flags = Flags(
|
||||
]
|
||||
)
|
||||
|
||||
# Использование сетевых флагов
|
||||
# Using Network Flags
|
||||
network_flags = Flags(
|
||||
[
|
||||
PredefinedFlags.HOST,
|
||||
@@ -17,7 +17,7 @@ network_flags = Flags(
|
||||
]
|
||||
)
|
||||
|
||||
# Валидация значений предопределенных флагов
|
||||
# Validating the values of predefined flags
|
||||
print(PredefinedFlags.HOST.validate_input_flag_value("192.168.1.1")) # True
|
||||
print(PredefinedFlags.HOST.validate_input_flag_value("invalid")) # False
|
||||
|
||||
@@ -25,11 +25,11 @@ print(PredefinedFlags.PORT.validate_input_flag_value("8080")) # True
|
||||
print(PredefinedFlags.PORT.validate_input_flag_value("99999")) # True
|
||||
print(PredefinedFlags.PORT.validate_input_flag_value("abc")) # False
|
||||
|
||||
# Флаги без значений
|
||||
# Flags without values
|
||||
print(PredefinedFlags.HELP.validate_input_flag_value(None)) # True
|
||||
print(PredefinedFlags.HELP.validate_input_flag_value("something")) # False
|
||||
|
||||
# Проверка строковых представлений
|
||||
# Checking string representations
|
||||
print(PredefinedFlags.HELP.string_entity) # --help
|
||||
print(PredefinedFlags.SHORT_HELP.string_entity) # -H
|
||||
print(PredefinedFlags.HOST.string_entity) # --host
|
||||
|
||||
@@ -1,20 +1,19 @@
|
||||
import re
|
||||
|
||||
from argenta.command import Flag, PossibleValues
|
||||
|
||||
# Простой флаг с любыми значениями
|
||||
# Simple flag with any values
|
||||
verbose_flag = Flag(name="verbose")
|
||||
|
||||
# Флаг с коротким префиксом
|
||||
# Flag with short prefix
|
||||
short_flag = Flag(name="v", prefix="-")
|
||||
|
||||
# Флаг без значения
|
||||
# Flag that does not take a value
|
||||
help_flag = Flag(name="help", possible_values=PossibleValues.NEITHER)
|
||||
|
||||
# Флаг со списком допустимых значений
|
||||
# Flag with list of possible values
|
||||
format_flag = Flag(name="format", possible_values=["json", "xml", "csv"])
|
||||
|
||||
# Флаг с регулярным выражением для валидации
|
||||
# Flag with regexp for validation input value
|
||||
email_flag = Flag(
|
||||
name="email",
|
||||
possible_values=re.compile(r"^[a-zA-Z0-9._%+-]+@[a-zA-Z0-9.-]+\.[a-zA-Z]{2,}$"),
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
from argenta.command import Flag
|
||||
|
||||
# Создание флагов с разными префиксами
|
||||
verbose_flag = Flag(name="verbose", prefix="--")
|
||||
short_flag = Flag(name="v", prefix="-")
|
||||
triple_flag = Flag(name="debug", prefix="---")
|
||||
|
||||
# Получение строкового представления
|
||||
print(verbose_flag.string_entity) # --verbose
|
||||
print(short_flag.string_entity) # -v
|
||||
print(triple_flag.string_entity) # ---debug
|
||||
@@ -3,10 +3,7 @@ from argenta.command import Flag
|
||||
help_flag = Flag(name="help")
|
||||
version_flag = Flag(name="V", prefix="-")
|
||||
|
||||
# Использование str() или print()
|
||||
print(str(help_flag)) # --help
|
||||
print(version_flag) # -V
|
||||
print(help_flag) # --help
|
||||
|
||||
# Форматирование строк
|
||||
message = f"Use {help_flag} to see help"
|
||||
print(message) # Use --help to see help
|
||||
|
||||
@@ -3,10 +3,10 @@ from argenta.command import Flag
|
||||
verbose_flag = Flag(name="verbose", prefix="--")
|
||||
short_flag = Flag(name="v", prefix="-")
|
||||
|
||||
# Отладочное представление
|
||||
# Debug view
|
||||
print(repr(verbose_flag)) # Flag<prefix=--, name=verbose>
|
||||
print(repr(short_flag)) # Flag<prefix=-, name=v>
|
||||
|
||||
# В интерактивной консоли или отладчике
|
||||
# In an interactive console or debugger
|
||||
# >>> verbose_flag
|
||||
# Flag<prefix=--, name=verbose>
|
||||
|
||||
@@ -1,21 +1,21 @@
|
||||
from argenta.command import Flag, PossibleValues
|
||||
|
||||
# Создание двух флагов с одинаковым именем и префиксом
|
||||
# Creating two flags with the same name and prefix
|
||||
flag1 = Flag(name="verbose", prefix="--")
|
||||
flag2 = Flag(name="verbose", prefix="--")
|
||||
|
||||
# Сравнение флагов
|
||||
# Flag comparison
|
||||
print(flag1 == flag2) # True
|
||||
|
||||
# Флаги с разными префиксами не равны
|
||||
# Flags with different prefixes are not equal
|
||||
flag3 = Flag(name="verbose", prefix="-")
|
||||
print(flag1 == flag3) # False
|
||||
|
||||
# Флаги с разными именами не равны
|
||||
# Flags with different names are not equal
|
||||
flag4 = Flag(name="help", prefix="--")
|
||||
print(flag1 == flag4) # False
|
||||
|
||||
# Разные possible_values не влияют на равенство
|
||||
# Different possible_values do not affect equality
|
||||
flag5 = Flag(name="verbose", prefix="--", possible_values=PossibleValues.NEITHER)
|
||||
flag6 = Flag(name="verbose", prefix="--", possible_values=["value1", "value2"])
|
||||
print(flag5 == flag6) # True (сравнение только по string_entity)
|
||||
print(flag5 == flag6)
|
||||
|
||||
@@ -1,11 +0,0 @@
|
||||
from argenta.command.flag import InputFlag, ValidationStatus
|
||||
|
||||
# Создание InputFlag с полным набором параметров
|
||||
output_flag = InputFlag(
|
||||
name="output", prefix="--", input_value="result.txt", status=ValidationStatus.VALID
|
||||
)
|
||||
|
||||
# Флаг без значения
|
||||
help_flag = InputFlag(
|
||||
name="help", prefix="-", input_value=None, status=ValidationStatus.VALID
|
||||
)
|
||||
@@ -1,8 +0,0 @@
|
||||
from argenta.command.flag import InputFlag, ValidationStatus
|
||||
|
||||
flag = InputFlag(
|
||||
name="verbose", prefix="-", input_value=None, status=ValidationStatus.VALID
|
||||
)
|
||||
|
||||
# Получение строкового представления флага
|
||||
print(flag.string_entity) # -verbose
|
||||
@@ -8,6 +8,6 @@ flag_without_value = InputFlag(
|
||||
name="help", prefix="-", input_value=None, status=ValidationStatus.VALID
|
||||
)
|
||||
|
||||
# Строковое представление включает значение
|
||||
# String representation includes value
|
||||
print(str(flag_with_value)) # --output result.txt
|
||||
print(str(flag_without_value)) # -help None
|
||||
|
||||
@@ -7,6 +7,6 @@ flag = InputFlag(
|
||||
status=ValidationStatus.VALID,
|
||||
)
|
||||
|
||||
# Отладочное представление объекта
|
||||
# Debug representation of the object
|
||||
print(repr(flag))
|
||||
# InputFlag<prefix='--', name='config', value='settings.json', status=ValidationStatus.VALID>
|
||||
|
||||
@@ -1,13 +0,0 @@
|
||||
from argenta.command.flag import InputFlag, ValidationStatus
|
||||
|
||||
flag1 = InputFlag(
|
||||
name="debug", prefix="--", input_value=None, status=ValidationStatus.VALID
|
||||
)
|
||||
|
||||
flag2 = InputFlag(
|
||||
name="debug", prefix="-", input_value="true", status=ValidationStatus.INVALID
|
||||
)
|
||||
|
||||
# Сравнение по имени (префикс и значение не учитываются)
|
||||
if flag1 == flag2:
|
||||
print("Флаги имеют одинаковое имя") # Выведется
|
||||
@@ -1,13 +1,5 @@
|
||||
from argenta.command import Flag, PossibleValues
|
||||
|
||||
# Создание флагов с любыми значениями
|
||||
output_flag = Flag(name="output", possible_values=PossibleValues.ALL)
|
||||
# Creating flags with any values
|
||||
message_flag = Flag(name="message", possible_values=PossibleValues.ALL)
|
||||
name_flag = Flag(name="name", possible_values=PossibleValues.ALL)
|
||||
|
||||
# Можно передать любую строку или ничего
|
||||
# Примеры:
|
||||
# --output result.json
|
||||
# --message "Any text here"
|
||||
# --name "User Name"
|
||||
# --message
|
||||
|
||||
@@ -1,15 +1,14 @@
|
||||
import re
|
||||
|
||||
from argenta.command import Flag, PossibleValues
|
||||
|
||||
# Флаг без значения
|
||||
# Flag without value
|
||||
verbose_flag = Flag(name="verbose", possible_values=PossibleValues.NEITHER)
|
||||
|
||||
# Флаг с любым значением
|
||||
# Flag with any value
|
||||
output_flag = Flag(name="output", possible_values=PossibleValues.ALL)
|
||||
|
||||
# Флаг со списком допустимых значений
|
||||
# Flag with a list of valid values
|
||||
format_flag = Flag(name="format", possible_values=["json", "xml", "csv", "yaml"])
|
||||
|
||||
# Флаг с регулярным выражением
|
||||
# Flag with regular expression
|
||||
email_flag = Flag(name="email", possible_values=re.compile(r"^[\w\.-]+@[\w\.-]+\.\w+$"))
|
||||
|
||||
@@ -1,10 +1,6 @@
|
||||
from argenta.command import Flag, PossibleValues
|
||||
|
||||
# Создание флагов без значений
|
||||
# Creating flags without values
|
||||
help_flag = Flag(name="help", possible_values=PossibleValues.NEITHER)
|
||||
verbose_flag = Flag(name="verbose", possible_values=PossibleValues.NEITHER)
|
||||
force_flag = Flag(name="force", possible_values=PossibleValues.NEITHER)
|
||||
|
||||
# Такие флаги используются как переключатели
|
||||
# Правильно: myapp --help
|
||||
# Неправильно: myapp --help something
|
||||
|
||||
@@ -1,10 +0,0 @@
|
||||
from argenta.command.flag.defaults import PredefinedFlags
|
||||
|
||||
# Проверка типа possible_values в предопределенных флагах
|
||||
print(PredefinedFlags.HELP.possible_values) # PossibleValues.NEITHER
|
||||
print(PredefinedFlags.INFO.possible_values) # PossibleValues.NEITHER
|
||||
print(PredefinedFlags.ALL.possible_values) # PossibleValues.NEITHER
|
||||
|
||||
# Сетевые флаги используют регулярные выражения, а не PossibleValues
|
||||
# PredefinedFlags.HOST использует Pattern для валидации IP
|
||||
# PredefinedFlags.PORT использует Pattern для валидации порта
|
||||
@@ -3,7 +3,7 @@
|
||||
Flag
|
||||
=====
|
||||
|
||||
``Flag`` — это сущность, описывающая флаг команды. Её основная задача — определить параметры флага, включая его имя, префикс и правила валидации. `Flag` используется при создании команд и предоставляет механизм для проверки значений, введённых пользователем.
|
||||
``Flag`` — это сущность, описывающая флаг команды. Её основная задача — определить параметры флага, включая его имя, префикс и правила валидации.
|
||||
|
||||
.. seealso::
|
||||
|
||||
@@ -11,7 +11,7 @@ Flag
|
||||
|
||||
Документация по :ref:`InputFlag <root_api_command_input_flag>` — объект обработанного флага, введённого пользователем.
|
||||
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в ``Argenta``
|
||||
|
||||
-----
|
||||
|
||||
@@ -31,7 +31,7 @@ Flag
|
||||
|
||||
* ``name``: Имя флага (обязательный параметр).
|
||||
* ``prefix``: Префикс флага (``-``, ``--``, ``---``). По умолчанию ``--``.
|
||||
* ``possible_values``: Правила валидации значения. Может быть списком строк, регулярным выражением или значением из `PossibleValues`. По умолчанию `PossibleValues.ALL`.
|
||||
* ``possible_values``: Правила валидации значения. Может быть списком строк, регулярным выражением или значением из ``PossibleValues``. По умолчанию ``PossibleValues.ALL``, то есть любое значение допустимо.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
@@ -45,12 +45,7 @@ Flag
|
||||
|
||||
.. py:attribute:: possible_values
|
||||
|
||||
Определяет допустимые значения для флага:
|
||||
|
||||
* Список строк: флаг принимает только значения из этого списка.
|
||||
* Регулярное выражение (`Pattern[str]`): значение проверяется на соответствие паттерну.
|
||||
* `PossibleValues.ALL`: флаг принимает любое значение.
|
||||
* `PossibleValues.NEITHER`: флаг не должен иметь значения.
|
||||
Допустимые значения для флага.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -78,12 +73,6 @@ string_entity
|
||||
|
||||
Это свойство объединяет префикс и имя в единую строку, которая представляет флаг так, как он выглядел бы в командной строке.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/flag/snippet3.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Магические методы
|
||||
@@ -97,7 +86,7 @@ __str__
|
||||
|
||||
__str__(self) -> str
|
||||
|
||||
Возвращает строковое представление флага (аналогично `string_entity`).
|
||||
Возвращает строковое представление флага (аналогично ``string_entity``).
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
@@ -119,7 +108,7 @@ __repr__
|
||||
|
||||
Возвращает отладочное представление объекта.
|
||||
|
||||
:return: Строка в формате `Flag<prefix=..., name=...>`.
|
||||
:return: Строка в формате ``Flag<prefix=..., name=...>``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -137,13 +126,12 @@ __eq__
|
||||
|
||||
__eq__(self, other: object) -> bool
|
||||
|
||||
Сравнивает два флага на равенство по их строковому представлению (`string_entity`).
|
||||
Сравнивает два флага на равенство по их строковому представлению (``string_entity``).
|
||||
|
||||
:param other: Объект для сравнения
|
||||
:return: ``True``, если флаги равны, иначе ``False``
|
||||
:raises NotImplementedError: Если `other` не является экземпляром `Flag`.
|
||||
:return: **True**, если флаги равны, иначе **False**
|
||||
|
||||
Два флага считаются равными, если их `string_entity` идентичны.
|
||||
Два флага считаются равными, если их ``string_entity`` идентичны.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -160,9 +148,9 @@ PredefinedFlags
|
||||
|
||||
``argenta.command.PredefinedFlags``
|
||||
|
||||
Класс `PredefinedFlags` предоставляет набор готовых флагов для использования в приложениях без их ручного создания. Эти флаги покрывают наиболее распространённые сценарии и следуют общепринятым соглашениям.
|
||||
Класс ``PredefinedFlags`` предоставляет набор готовых флагов для использования в приложениях без их ручного создания. Эти флаги покрывают распространённые сценарии.
|
||||
|
||||
Все предопределённые флаги являются атрибутами класса и представляют собой готовые экземпляры `Flag`.
|
||||
Все предопределённые флаги являются атрибутами класса и представляют собой готовые экземпляры ``Flag``.
|
||||
|
||||
-----
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Command
|
||||
=======
|
||||
|
||||
``Command`` — это основная единица функциональности в приложении. Каждая команда определяет действие, которое пользователь может выполнить, введя соответствующий триггер. Команды регистрируются в роутерах и формируют интерфейс взаимодействия с приложением.
|
||||
``Command`` — это основная единица функциональности в приложении. Каждая команда связывает хэндлер с триггером, введя который он будет вызван для обработки.
|
||||
|
||||
``Command`` инкапсулирует всю информацию о команде: её триггер (ключевое слово для вызова), описание, набор флагов и список псевдонимов.
|
||||
|
||||
@@ -18,13 +18,13 @@ Command
|
||||
__init__(self, trigger: str, *,
|
||||
description: str | None = None,
|
||||
flags: Flag | Flags = DEFAULT_WITHOUT_FLAGS,
|
||||
aliases: list[str] | None = None) -> None
|
||||
aliases: list[str] | list[Never] = DEFAULT_WITHOUT_ALIASES) -> None
|
||||
|
||||
Создаёт новую команду для регистрации в роутере.
|
||||
|
||||
* ``trigger``: Строковый триггер, который пользователь вводит для вызова команды. Является основным идентификатором.
|
||||
* ``description``: Необязательное описание, объясняющее назначение команды. Отображается в справке.
|
||||
* ``flags``: Набор флагов для настройки поведения. Может быть одиночным объектом `Flag` или коллекцией `Flags`.
|
||||
* ``flags``: Набор флагов для настройки поведения. Может быть одиночным объектом ``Flag`` или коллекцией ``Flags``.
|
||||
* ``aliases``: Список строковых псевдонимов для основного триггера.
|
||||
|
||||
**Атрибуты:**
|
||||
@@ -39,7 +39,7 @@ Command
|
||||
|
||||
.. py:attribute:: registered_flags
|
||||
|
||||
Объект `Flags`, содержащий все зарегистрированные флаги. Автоматически конвертируется из одиночного `Flag` в коллекцию при инициализации.
|
||||
Объект ``Flags``, содержащий все зарегистрированные флаги. Если был передан ``Flag``, то автоматически конвертируется из одиночного в коллекцию при инициализации.
|
||||
|
||||
.. py:attribute:: aliases
|
||||
|
||||
@@ -58,7 +58,7 @@ Command
|
||||
Регистрация команд
|
||||
------------------
|
||||
|
||||
Команды регистрируются в роутерах с помощью декоратора ``@router.command()``, после чего становятся доступными для вызова.
|
||||
Команды передаются в качестве аргумента в декоратор ``@router.command()``.
|
||||
|
||||
**Базовый пример:**
|
||||
|
||||
@@ -79,21 +79,9 @@ Command
|
||||
|
||||
**Пример с псевдонимами:**
|
||||
|
||||
.. code-block:: python
|
||||
.. literalinclude:: ../../../code_snippets/command/snippet5.py
|
||||
:linenos:
|
||||
|
||||
from argenta import Router, Command
|
||||
|
||||
router = Router(title="System")
|
||||
|
||||
@router.command(Command(
|
||||
"shutdown",
|
||||
description="Shutdown the system",
|
||||
aliases=["poweroff", "halt", "stop"]
|
||||
))
|
||||
def handle_shutdown(response):
|
||||
response.write("Shutting down the system...")
|
||||
|
||||
Теперь пользователь может вызвать команду любым из способов:
|
||||
|
||||
.. code-block:: bash
|
||||
@@ -103,7 +91,7 @@ Command
|
||||
halt
|
||||
stop
|
||||
|
||||
Все эти варианты выполнят одну и ту же функцию ``handle_shutdown``.
|
||||
Все эти варианты вызовут один и тот же хэндлер ``handle_shutdown``.
|
||||
|
||||
-----
|
||||
|
||||
@@ -115,12 +103,7 @@ InputCommand
|
||||
``InputCommand`` представляет собой обработанную команду, введённую пользователем. Этот внутренний класс создаётся автоматически при обработке пользовательского ввода. Прямая работа с ним возможна при создании пользовательского обработчика для неизвестных команд.
|
||||
|
||||
.. seealso ::
|
||||
Подробнее о пользовательских обработчиках исключений см. :ref:`здесь <root_error_handling>`.
|
||||
|
||||
Создаёт экземпляр обработанной команды.
|
||||
|
||||
:param trigger: Триггер команды, извлечённый из пользовательского ввода.
|
||||
:param input_flags: Флаги, переданные пользователем.
|
||||
Подробнее о пользовательских обработчиках исключений см. :ref:`здесь <root_error_handling_unknown_command>`.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
@@ -132,7 +115,7 @@ InputCommand
|
||||
.. py:attribute:: input_flags
|
||||
:no-index:
|
||||
|
||||
Объект `InputFlags`, содержащий все переданные с командой флаги. Автоматически конвертируется из одиночного `InputFlag` в коллекцию.
|
||||
Объект ``InputFlags``, содержащий все введённые и распаршенные флаги.
|
||||
|
||||
.. toctree ::
|
||||
:hidden:
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
InputFlag
|
||||
=========
|
||||
|
||||
Объект `InputFlag` представляет собой флаг, введённый пользователем. Он создаётся в результате обработки пользовательского ввода и содержит информацию о распознанном флаге: его имя, префикс, значение и статус валидации.
|
||||
Объект ``InputFlag`` представляет собой флаг, введённый пользователем. Он создаётся в результате обработки пользовательского ввода и содержит информацию о распознанном флаге: его имя, префикс, значение и статус валидации.
|
||||
|
||||
.. seealso::
|
||||
|
||||
@@ -13,26 +13,6 @@ InputFlag
|
||||
|
||||
-----
|
||||
|
||||
Инициализация
|
||||
-------------
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__init__(
|
||||
self, name: str, *,
|
||||
prefix: Literal['-', '--', '---'] = '--',
|
||||
input_value: str | None,
|
||||
status: ValidationStatus | None
|
||||
)
|
||||
|
||||
Создаёт новый объект введённого флага.
|
||||
|
||||
* ``name``: Имя введённого флага.
|
||||
* ``prefix``: Префикс флага (``-``, ``--``, ``---``). По умолчанию ``--``.
|
||||
* ``input_value``: Значение, переданное с флагом. Может быть `None`.
|
||||
* ``status``: Статус валидации из перечисления `ValidationStatus`.
|
||||
|
||||
.. warning ::
|
||||
Экземпляры этого класса не предназначены для прямого создания. Они содержатся в объекте :ref:`Response <root_api_response>`.
|
||||
|
||||
@@ -55,13 +35,7 @@ InputFlag
|
||||
.. py:attribute:: status
|
||||
:no-index:
|
||||
|
||||
Статус валидации флага: `ValidationStatus.VALID`, `ValidationStatus.INVALID` или `ValidationStatus.UNDEFINED`.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flag/snippet1.py
|
||||
:linenos:
|
||||
:language: python
|
||||
Статус валидации флага: ``ValidationStatus.VALID``, ``ValidationStatus.INVALID`` или ``ValidationStatus.UNDEFINED``.
|
||||
|
||||
-----
|
||||
|
||||
@@ -81,14 +55,6 @@ string_entity
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
Это свойство объединяет префикс и имя в строку, представляющую флаг так, как он был введён в командной строке.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flag/snippet2.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Магические методы
|
||||
@@ -124,7 +90,7 @@ __repr__
|
||||
|
||||
Возвращает отладочное представление объекта.
|
||||
|
||||
:return: Строка в формате `InputFlag<prefix=..., name=..., value=..., status=...>`.
|
||||
:return: Строка в формате ``InputFlag<prefix=..., name=..., value=..., status=...>``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -145,13 +111,6 @@ __eq__
|
||||
Сравнивает два введённых флага на равенство по имени.
|
||||
|
||||
:param other: Объект для сравнения.
|
||||
:return: `True`, если имена флагов совпадают, иначе `False`.
|
||||
:raises NotImplementedError: Если `other` не является экземпляром `InputFlag`.
|
||||
:return: **True**, если имена флагов совпадают, иначе **False**.
|
||||
|
||||
Два введённых флага считаются равными, если их имена совпадают.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/input_flag/snippet5.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
@@ -4,26 +4,23 @@
|
||||
PossibleValues
|
||||
==============
|
||||
|
||||
`PossibleValues` — это перечисление (`Enum`), которое определяет специальные режимы валидации для значений флагов. Его задача — предоставить стандартные константы для управления поведением флагов. `PossibleValues` используется в параметре `possible_values` класса `Flag`, чтобы указать, может ли флаг принимать значения и какие ограничения на них накладываются.
|
||||
``PossibleValues`` — это перечисление (``Enum``), которое определяет специальные режимы валидации для значений флагов. ``PossibleValues`` используется в параметре ``possible_values`` класса ``Flag``, чтобы указать, может ли флаг принимать значения и какие ограничения на них накладываются.
|
||||
|
||||
`PossibleValues` наследуется от `Enum` и содержит два основных значения: `NEITHER` (для флагов без значений) и `ALL` (для флагов, принимающих любые значения). Это перечисление используется вместе со списками строк и регулярными выражениями для создания гибкой системы валидации.
|
||||
``PossibleValues`` содержит два основных значения: ``NEITHER`` (для флагов, которые не могут принимать значения) и ``ALL`` (для флагов, принимающих любые значения). Это перечисление используется вместе со списками строк и регулярными выражениями для создания гибкой системы валидации.
|
||||
|
||||
.. note::
|
||||
Результат валидации доступен через атрибут `status` у экземпляра `InputFlag`. Подробнее см. :ref:`здесь <root_api_command_input_flag>`.
|
||||
Результат валидации доступен через атрибут ``status`` у экземпляра ``InputFlag``. Подробнее см. :ref:`здесь <root_api_command_input_flag>`.
|
||||
|
||||
.. seealso::
|
||||
|
||||
Документация по :ref:`Flag <root_api_command_flag>` — класс флага, использующий `PossibleValues`.
|
||||
Документация по :ref:`Flag <root_api_command_flag>` — класс флага, использующий ``PossibleValues``.
|
||||
|
||||
Документация по :ref:`PredefinedFlags <root_api_command_flag_predefined_flags>` — готовые флаги с примерами использования `PossibleValues`.
|
||||
Документация по :ref:`ValidationStatus <root_api_command_validation_status>` — результат валидации ввёденного флага.
|
||||
|
||||
:ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``
|
||||
|
||||
-----
|
||||
|
||||
Значения enum
|
||||
-------------
|
||||
|
||||
NEITHER
|
||||
~~~~~~~
|
||||
|
||||
@@ -65,10 +62,8 @@ ALL
|
||||
|
||||
**Примеры флагов с** ``ALL``:
|
||||
|
||||
* ``--output`` — путь к выходному файлу
|
||||
* ``--message`` — произвольное текстовое сообщение
|
||||
* ``--name`` — произвольное имя
|
||||
* ``--data`` — произвольные данные
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -78,35 +73,20 @@ ALL
|
||||
|
||||
-----
|
||||
|
||||
Использование в Flag
|
||||
---------------------
|
||||
|
||||
Параметр possible_values
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
`PossibleValues` используется как один из возможных типов для параметра `possible_values` при создании экземпляра `Flag`.
|
||||
``PossibleValues`` используется как один из возможных типов для параметра ``possible_values`` при создании экземпляра ``Flag``.
|
||||
|
||||
**Доступные типы для** `possible_values`:
|
||||
**Доступные типы для** ``possible_values``:
|
||||
|
||||
1. `PossibleValues.NEITHER`: флаг без значения.
|
||||
2. `PossibleValues.ALL`: флаг с любым значением (по умолчанию).
|
||||
3. `list[str]`: флаг с ограниченным набором значений.
|
||||
4. `Pattern[str]`: флаг со значением, проверяемым по регулярному выражению.
|
||||
1. ``PossibleValues.NEITHER``: флаг без значения.
|
||||
2. ``PossibleValues.ALL``: флаг с любым значением (по умолчанию).
|
||||
3. ``list[str]``: флаг с ограниченным набором значений.
|
||||
4. ``Pattern[str]``: флаг со значением, проверяемым по регулярному выражению.
|
||||
|
||||
**Пример комбинированного использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/possible_values/combined.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
-----
|
||||
|
||||
Использование в PredefinedFlags
|
||||
-------------------------------
|
||||
|
||||
Многие предопределённые флаги используют `PossibleValues.NEITHER`:
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/possible_values/predefined.py
|
||||
:linenos:
|
||||
:language: python
|
||||
|
||||
|
||||
@@ -31,7 +31,6 @@
|
||||
* `Ваш первый вклад в код`_
|
||||
* `Улучшение документации`_
|
||||
* `Руководства по стилю`_
|
||||
* `Сообщения коммитов`_
|
||||
* `Присоединяйтесь к команде проекта`_
|
||||
|
||||
.. _Кодекс поведения:
|
||||
|
||||
@@ -90,6 +90,8 @@ Argenta выбрасывает исключения в пограничных с
|
||||
|
||||
---------------
|
||||
|
||||
.. _root_error_handling_unknown_command:
|
||||
|
||||
Обработка неизвестной команды
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
from argenta import App, Orchestrator
|
||||
from argenta.app import PredefinedMessages
|
||||
from argenta.orchestrator.argparser import ArgParser, BooleanArgument
|
||||
from argenta.app.dividing_line.models import StaticDividingLine, DynamicDividingLine
|
||||
from argenta.app.dividing_line.models import DynamicDividingLine
|
||||
from mock.mock_app.routers import work_router
|
||||
|
||||
app: App = App(
|
||||
@@ -21,6 +21,6 @@ def main():
|
||||
|
||||
orchestrator.start_polling(app)
|
||||
|
||||
|
||||
|
||||
if __name__ == "__main__":
|
||||
orchestrator.start_polling(app)
|
||||
|
||||
@@ -1,9 +1,18 @@
|
||||
from argenta import Router, Response, Command
|
||||
from argenta.command import Flags, Flag
|
||||
|
||||
work_router: Router = Router(title="Base points:", disable_redirect_stdout=True)
|
||||
|
||||
|
||||
@work_router.command(Command('hello', description="Hello, world!"))
|
||||
@work_router.command(Command
|
||||
(
|
||||
'hello',
|
||||
flags=Flags(
|
||||
Flag('test')
|
||||
),
|
||||
description="Hello, world!"
|
||||
)
|
||||
)
|
||||
def command_help(response: Response):
|
||||
c = input("Enter your name: ")
|
||||
print(f"Hello, {c}!")
|
||||
|
||||
@@ -15,6 +15,7 @@ ParseResult = tuple[str, InputFlags]
|
||||
|
||||
MIN_FLAG_PREFIX: str = "-"
|
||||
DEFAULT_WITHOUT_FLAGS: Flags = Flags()
|
||||
DEFAULT_WITHOUT_ALIASES: list[Never] = []
|
||||
|
||||
DEFAULT_WITHOUT_INPUT_FLAGS: InputFlags = InputFlags()
|
||||
|
||||
@@ -24,9 +25,9 @@ class Command:
|
||||
self,
|
||||
trigger: str,
|
||||
*,
|
||||
description: str | None = None,
|
||||
description: str = "Some useful command",
|
||||
flags: Flag | Flags = DEFAULT_WITHOUT_FLAGS,
|
||||
aliases: list[str] | None = None,
|
||||
aliases: list[str] | list[Never] = DEFAULT_WITHOUT_ALIASES,
|
||||
):
|
||||
"""
|
||||
Public. The command that can and should be registered in the Router
|
||||
@@ -37,8 +38,8 @@ class Command:
|
||||
"""
|
||||
self.registered_flags: Flags = flags if isinstance(flags, Flags) else Flags([flags])
|
||||
self.trigger: str = trigger
|
||||
self.description: str = description if description else "Command without description"
|
||||
self.aliases: list[str] = aliases if aliases else []
|
||||
self.description: str = description
|
||||
self.aliases: list[str] = []
|
||||
|
||||
def validate_input_flag(self, flag: InputFlag) -> ValidationStatus:
|
||||
"""
|
||||
|
||||
Reference in New Issue
Block a user