kolo/Argenta
1
0
Fork 0
mirror of https://github.com/koloideal/Argenta.git synced 2026-06-10 18:15:28 +03:00
Code Issues Packages Projects Releases Wiki Activity

docs

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