From 2a96dfcabe40c5f06d8ee3f79c8e3e02c47ae5d4 Mon Sep 17 00:00:00 2001 From: kolo Date: Sat, 29 Nov 2025 11:51:59 +0300 Subject: [PATCH] docs --- docs/code_snippets/command/snippet.py | 13 +++-- docs/code_snippets/command/snippet2.py | 2 +- docs/code_snippets/command/snippet3.py | 6 +-- docs/code_snippets/command/snippet5.py | 11 +++++ docs/code_snippets/flag/predefined_flags.py | 10 ++-- docs/code_snippets/flag/snippet.py | 11 ++--- docs/code_snippets/flag/snippet3.py | 11 ----- docs/code_snippets/flag/snippet4.py | 5 +- docs/code_snippets/flag/snippet5.py | 4 +- docs/code_snippets/flag/snippet6.py | 12 ++--- docs/code_snippets/input_flag/snippet1.py | 11 ----- docs/code_snippets/input_flag/snippet2.py | 8 --- docs/code_snippets/input_flag/snippet3.py | 2 +- docs/code_snippets/input_flag/snippet4.py | 2 +- docs/code_snippets/input_flag/snippet5.py | 13 ----- docs/code_snippets/possible_values/all.py | 10 +--- .../code_snippets/possible_values/combined.py | 9 ++-- docs/code_snippets/possible_values/neither.py | 6 +-- .../possible_values/predefined.py | 10 ---- docs/root/api/command/flag.rst | 34 +++++-------- docs/root/api/command/index.rst | 35 ++++--------- docs/root/api/command/input_flag.rst | 49 ++----------------- docs/root/api/command/possible_values.rst | 42 +++++----------- docs/root/contributing.rst | 1 - docs/root/error_handling.rst | 2 + mock/mock_app/main.py | 6 +-- mock/mock_app/routers.py | 11 ++++- src/argenta/command/models.py | 9 ++-- 28 files changed, 103 insertions(+), 242 deletions(-) create mode 100644 docs/code_snippets/command/snippet5.py delete mode 100644 docs/code_snippets/flag/snippet3.py delete mode 100644 docs/code_snippets/input_flag/snippet1.py delete mode 100644 docs/code_snippets/input_flag/snippet2.py delete mode 100644 docs/code_snippets/input_flag/snippet5.py delete mode 100644 docs/code_snippets/possible_values/predefined.py diff --git a/docs/code_snippets/command/snippet.py b/docs/code_snippets/command/snippet.py index ab082ca..4ff62df 100644 --- a/docs/code_snippets/command/snippet.py +++ b/docs/code_snippets/command/snippet.py @@ -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"], diff --git a/docs/code_snippets/command/snippet2.py b/docs/code_snippets/command/snippet2.py index 1a32810..b2bbaef 100644 --- a/docs/code_snippets/command/snippet2.py +++ b/docs/code_snippets/command/snippet2.py @@ -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...") diff --git a/docs/code_snippets/command/snippet3.py b/docs/code_snippets/command/snippet3.py index e4e21bd..ff5b9c8 100644 --- a/docs/code_snippets/command/snippet3.py +++ b/docs/code_snippets/command/snippet3.py @@ -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"], diff --git a/docs/code_snippets/command/snippet5.py b/docs/code_snippets/command/snippet5.py new file mode 100644 index 0000000..4939f95 --- /dev/null +++ b/docs/code_snippets/command/snippet5.py @@ -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...") \ No newline at end of file diff --git a/docs/code_snippets/flag/predefined_flags.py b/docs/code_snippets/flag/predefined_flags.py index 8c8ac8a..e2176c6 100644 --- a/docs/code_snippets/flag/predefined_flags.py +++ b/docs/code_snippets/flag/predefined_flags.py @@ -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 diff --git a/docs/code_snippets/flag/snippet.py b/docs/code_snippets/flag/snippet.py index a2c24e9..a46b1a5 100644 --- a/docs/code_snippets/flag/snippet.py +++ b/docs/code_snippets/flag/snippet.py @@ -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,}$"), diff --git a/docs/code_snippets/flag/snippet3.py b/docs/code_snippets/flag/snippet3.py deleted file mode 100644 index 6d42692..0000000 --- a/docs/code_snippets/flag/snippet3.py +++ /dev/null @@ -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 diff --git a/docs/code_snippets/flag/snippet4.py b/docs/code_snippets/flag/snippet4.py index 3f7f589..ccae89f 100644 --- a/docs/code_snippets/flag/snippet4.py +++ b/docs/code_snippets/flag/snippet4.py @@ -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 diff --git a/docs/code_snippets/flag/snippet5.py b/docs/code_snippets/flag/snippet5.py index 7f91b5f..7200566 100644 --- a/docs/code_snippets/flag/snippet5.py +++ b/docs/code_snippets/flag/snippet5.py @@ -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 print(repr(short_flag)) # Flag -# В интерактивной консоли или отладчике +# In an interactive console or debugger # >>> verbose_flag # Flag diff --git a/docs/code_snippets/flag/snippet6.py b/docs/code_snippets/flag/snippet6.py index b6d7866..0ac23e1 100644 --- a/docs/code_snippets/flag/snippet6.py +++ b/docs/code_snippets/flag/snippet6.py @@ -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) diff --git a/docs/code_snippets/input_flag/snippet1.py b/docs/code_snippets/input_flag/snippet1.py deleted file mode 100644 index 875897e..0000000 --- a/docs/code_snippets/input_flag/snippet1.py +++ /dev/null @@ -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 -) diff --git a/docs/code_snippets/input_flag/snippet2.py b/docs/code_snippets/input_flag/snippet2.py deleted file mode 100644 index 01df300..0000000 --- a/docs/code_snippets/input_flag/snippet2.py +++ /dev/null @@ -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 diff --git a/docs/code_snippets/input_flag/snippet3.py b/docs/code_snippets/input_flag/snippet3.py index 17e83ef..0ac07d6 100644 --- a/docs/code_snippets/input_flag/snippet3.py +++ b/docs/code_snippets/input_flag/snippet3.py @@ -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 diff --git a/docs/code_snippets/input_flag/snippet4.py b/docs/code_snippets/input_flag/snippet4.py index 71b16f8..3e96e08 100644 --- a/docs/code_snippets/input_flag/snippet4.py +++ b/docs/code_snippets/input_flag/snippet4.py @@ -7,6 +7,6 @@ flag = InputFlag( status=ValidationStatus.VALID, ) -# Отладочное представление объекта +# Debug representation of the object print(repr(flag)) # InputFlag diff --git a/docs/code_snippets/input_flag/snippet5.py b/docs/code_snippets/input_flag/snippet5.py deleted file mode 100644 index a19a815..0000000 --- a/docs/code_snippets/input_flag/snippet5.py +++ /dev/null @@ -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("Флаги имеют одинаковое имя") # Выведется diff --git a/docs/code_snippets/possible_values/all.py b/docs/code_snippets/possible_values/all.py index 7a1ebe5..9be6044 100644 --- a/docs/code_snippets/possible_values/all.py +++ b/docs/code_snippets/possible_values/all.py @@ -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 diff --git a/docs/code_snippets/possible_values/combined.py b/docs/code_snippets/possible_values/combined.py index 62159ee..d9167a4 100644 --- a/docs/code_snippets/possible_values/combined.py +++ b/docs/code_snippets/possible_values/combined.py @@ -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+$")) diff --git a/docs/code_snippets/possible_values/neither.py b/docs/code_snippets/possible_values/neither.py index 572bca0..de7d57f 100644 --- a/docs/code_snippets/possible_values/neither.py +++ b/docs/code_snippets/possible_values/neither.py @@ -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 diff --git a/docs/code_snippets/possible_values/predefined.py b/docs/code_snippets/possible_values/predefined.py deleted file mode 100644 index 66010e1..0000000 --- a/docs/code_snippets/possible_values/predefined.py +++ /dev/null @@ -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 для валидации порта diff --git a/docs/root/api/command/flag.rst b/docs/root/api/command/flag.rst index 92eb8a7..7fa886e 100644 --- a/docs/root/api/command/flag.rst +++ b/docs/root/api/command/flag.rst @@ -3,7 +3,7 @@ Flag ===== -``Flag`` — это сущность, описывающая флаг команды. Её основная задача — определить параметры флага, включая его имя, префикс и правила валидации. `Flag` используется при создании команд и предоставляет механизм для проверки значений, введённых пользователем. +``Flag`` — это сущность, описывающая флаг команды. Её основная задача — определить параметры флага, включая его имя, префикс и правила валидации. .. seealso:: @@ -11,7 +11,7 @@ Flag Документация по :ref:`InputFlag ` — объект обработанного флага, введённого пользователем. - :ref:`Общая информация ` о флагах и их использовании в приложении ``Argenta`` + :ref:`Общая информация ` о флагах и их использовании в ``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`. +:return: Строка в формате ``Flag``. **Пример использования:** @@ -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``. ----- diff --git a/docs/root/api/command/index.rst b/docs/root/api/command/index.rst index 4931776..0f44996 100644 --- a/docs/root/api/command/index.rst +++ b/docs/root/api/command/index.rst @@ -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:`здесь `. - -Создаёт экземпляр обработанной команды. - -:param trigger: Триггер команды, извлечённый из пользовательского ввода. -:param input_flags: Флаги, переданные пользователем. + Подробнее о пользовательских обработчиках исключений см. :ref:`здесь `. **Атрибуты:** @@ -132,7 +115,7 @@ InputCommand .. py:attribute:: input_flags :no-index: - Объект `InputFlags`, содержащий все переданные с командой флаги. Автоматически конвертируется из одиночного `InputFlag` в коллекцию. + Объект ``InputFlags``, содержащий все введённые и распаршенные флаги. .. toctree :: :hidden: diff --git a/docs/root/api/command/input_flag.rst b/docs/root/api/command/input_flag.rst index 7391893..27e8df5 100644 --- a/docs/root/api/command/input_flag.rst +++ b/docs/root/api/command/input_flag.rst @@ -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 `. @@ -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`. +:return: Строка в формате ``InputFlag``. **Пример использования:** @@ -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 diff --git a/docs/root/api/command/possible_values.rst b/docs/root/api/command/possible_values.rst index 4340a67..9d7ae23 100644 --- a/docs/root/api/command/possible_values.rst +++ b/docs/root/api/command/possible_values.rst @@ -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:`здесь `. + Результат валидации доступен через атрибут ``status`` у экземпляра ``InputFlag``. Подробнее см. :ref:`здесь `. .. seealso:: - Документация по :ref:`Flag ` — класс флага, использующий `PossibleValues`. + Документация по :ref:`Flag ` — класс флага, использующий ``PossibleValues``. - Документация по :ref:`PredefinedFlags ` — готовые флаги с примерами использования `PossibleValues`. + Документация по :ref:`ValidationStatus ` — результат валидации ввёденного флага. :ref:`Общая информация ` о флагах и их использовании в приложении ``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 - diff --git a/docs/root/contributing.rst b/docs/root/contributing.rst index 54f6cb0..2089c05 100644 --- a/docs/root/contributing.rst +++ b/docs/root/contributing.rst @@ -31,7 +31,6 @@ * `Ваш первый вклад в код`_ * `Улучшение документации`_ * `Руководства по стилю`_ -* `Сообщения коммитов`_ * `Присоединяйтесь к команде проекта`_ .. _Кодекс поведения: diff --git a/docs/root/error_handling.rst b/docs/root/error_handling.rst index 1d94932..496d384 100644 --- a/docs/root/error_handling.rst +++ b/docs/root/error_handling.rst @@ -90,6 +90,8 @@ Argenta выбрасывает исключения в пограничных с --------------- +.. _root_error_handling_unknown_command: + Обработка неизвестной команды ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ diff --git a/mock/mock_app/main.py b/mock/mock_app/main.py index 13e115c..0e07271 100644 --- a/mock/mock_app/main.py +++ b/mock/mock_app/main.py @@ -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) \ No newline at end of file diff --git a/mock/mock_app/routers.py b/mock/mock_app/routers.py index 2edc8d6..735476f 100644 --- a/mock/mock_app/routers.py +++ b/mock/mock_app/routers.py @@ -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}!") diff --git a/src/argenta/command/models.py b/src/argenta/command/models.py index f19e085..71ea99b 100644 --- a/src/argenta/command/models.py +++ b/src/argenta/command/models.py @@ -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: """