diff --git a/docs/root/api/orchestrator/arguments.rst b/docs/root/api/orchestrator/arguments.rst index 6940983..da13ff3 100644 --- a/docs/root/api/orchestrator/arguments.rst +++ b/docs/root/api/orchestrator/arguments.rst @@ -137,7 +137,7 @@ BooleanArgument python app.py --verbose python app.py --debug --no-cache - python app.py # без флагов + python app.py # без аргументов ----- @@ -163,7 +163,7 @@ InputArgument Создаёт экземпляр обработанного входного аргумента. :param name: Имя аргумента -:param value: Значение аргумента. Для `BooleanArgument` — `True`, если флаг передан; для `ValueArgument` — строка со значением +:param value: Значение аргумента. Для `BooleanArgument` — `True`, если аргумент передан; для `ValueArgument` — строка со значением :param founder_class: Класс-родитель, из которого был создан аргумент (`BooleanArgument` или `ValueArgument`) **Атрибуты:** @@ -177,7 +177,7 @@ InputArgument Значение аргумента. Тип зависит от исходного класса: -* Для `BooleanArgument`: `True`, если флаг был передан. +* Для `BooleanArgument`: `True`, если аргумент был передан. * Для `ValueArgument`: строка с переданным значением или значением по умолчанию .. py:attribute:: founder_class diff --git a/docs/root/flags.rst b/docs/root/flags.rst index f2c2d68..e0c92d1 100644 --- a/docs/root/flags.rst +++ b/docs/root/flags.rst @@ -3,7 +3,45 @@ Флаги вводимых команд ===================== -Флаги (или параметры) — это специальные аргументы, которые пользователь может добавлять к командам для управления их поведением. +Флаги — это специальные параметры, которые пользователь может добавлять к командам для управления их поведением. + +Зачем нужны флаги в командах +---------------------------- + +Управление поведением команды +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Основная цель флагов — предоставить способ изменить логику работы команды без её переработки. Команда может работать в нескольких режимах: стандартном, подробном, отладочном или упрощённом. Флаги переключают эти режимы по требованию пользователя, оставляя основную функциональность неизменной. + +Опциональность и удобство +~~~~~~~~~~~~~~~~~~~~~~~~~ + +Флаги решают проблему обязательности параметров. Если все параметры команды сделать обязательными, это затруднит использование команды. Флаги же позволяют задать значения только необходимые в конкретной ситуации, остальные используют значения по умолчанию. + +Когда могут понадобиться флаги +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +**Переключение режимов работы** + Команда выполняет развёртывание приложения обычно, но нужен режим без фактического развёртывания (dry-run) для проверки. Флаг ``--dry-run`` переключит режим работы. + +**Настройка уровня детальности** + При отладке или анализе требуется больше информации о процессе выполнения команды. Флаги ``--verbose`` или ``--debug`` предоставляют подробный вывод. + +**Управление поведением при ошибках** + По умолчанию команда может прерваться при первой ошибке. Флаг ``--force`` позволит продолжить работу, пропуская некритичные ошибки. + +**Форматирование вывода** + Команда выводит данные текстом, но в некоторых сценариях нужен JSON или CSV. Флаг ``--format=json`` переключит формат вывода. + +**Комбинирование опций** + Часто нужна комбинация нескольких изменений: подробный вывод, dry-run режим и JSON формат. Несколько флагов решают эту задачу одновременно. + +Практическое значение +~~~~~~~~~~~~~~~~~~~~~ + +Флаги делают команды более предсказуемыми и контролируемыми. Пользователь может начать с простого использования, а затем добавлять флаги по мере необходимости. Это особенно важно при автоматизации задач в скриптах, где гибкость интерфейса критична. + +Флаги также облегчают интеграцию команд в различные системы, так как дополнительное поведение достигается без изменения структуры команды, а только через передачу опциональных параметров. ----- @@ -32,38 +70,55 @@ ----- -Ограничение по списку возможных значений ----------------------------------------- +Флаги против аргументов +----------------------- -Вы можете заранее определить список допустимых значений для флага. +В контексте Argenta флаги и аргументы относятся к разным уровням взаимодействия с приложением и имеют принципиально разные сферы действия. -Предположим, у вас есть флаг ``--format``, который может принимать только значения ``json`` или ``xml``. +Определение и назначение +~~~~~~~~~~~~~~~~~~~~~~~~ -.. code-block:: bash - :linenos: +**Аргументы** — это параметры, передаваемые при запуске приложения один раз при инициализации. Они определяют глобальное состояние и конфигурацию приложения на протяжении всей его работы, например адрес базы данных, уровень логирования или режим работы. - # Эта команда сработает - export --format json +.. seealso:: API и более подробное описание в разделах :ref:`ArgParser ` и :ref:`Arguments `. + +**Флаги** — это параметры командных операций, доступные в рамках интерактивной сессии при вводе каждой новой команды. Они позволяют модифицировать поведение конкретной команды без перезагрузки приложения. + +.. seealso:: API и более подробное описание в разделе :ref:`Flag `. - # А эта команда не пройдёт валидацию, так как значение "csv" не входит в список разрешённых - export --format csv - ----- -Проверка с помощью регулярных выражений ------------------------------------------ +Ключевые различия +~~~~~~~~~~~~~~~~~ -Для более сложных проверок можно использовать регулярные выражения. Это полезно, когда значение должно соответствовать определённому формату (например, email-адрес, дата или номер телефона). +**Время жизни и область действия** + Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы(скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**. -Допустим, флаг ``--email`` должен принимать только корректные email-адреса. +**Частота изменения** + Для изменения аргументов необходимо перезапустить приложение. Флаги можно менять между каждым вводом команды без остановки приложения. -.. code-block:: bash - :linenos: +**Уровень конфигурации** + Аргументы управляют глобальной конфигурацией приложения и его окружением. Флаги управляют поведением отдельных команд и операций пользователя. - # Эта команда выполнится, так как значение соответствует формату email - send --email "user@example.com" +**Использование** + Аргументы задают начальное состояние системы: что подключить, как работать. Флаги управляют тактикой выполнения команд: как её выполнить, с какими изменениями. - # Эта команда не пройдёт валидацию, так как "user_example.com" — некорректный email - send --email "user_example.com" +----- + +Практические примеры в Argenta +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Встроенная валидация избавляет от необходимости писать проверки вручную и делает код более декларативным. +При запуске приложения Argenta передаются аргументы: + +- Адрес подключения к базе данных +- Режим работы (production, development, testing) +- Уровень логирования +- Путь к конфигурационным файлам + +В интерактивной сессии для каждой команды указываются флаги: + +- ``deploy --verbose --dry-run`` — для текущей команды развёртывания +- ``backup --compress --encrypted`` — для команды резервного копирования +- ``test --parallel --coverage`` — для команды тестирования + +Один пользователь может выполнить разные команды с разными флагами в одной сессии приложения, без необходимости перезапуска с новыми аргументами. diff --git a/docs/root/overriding_formatting.rst b/docs/root/overriding_formatting.rst index b51c397..13a9c14 100644 --- a/docs/root/overriding_formatting.rst +++ b/docs/root/overriding_formatting.rst @@ -5,8 +5,6 @@ По умолчанию ``Argenta`` использует библиотеку ``rich`` для вывода текста с расширенным форматированием. Она позволяет применять цвета и стили, создавать таблицы, подсвечивать синтаксис и многое другое, что улучшает визуальное восприятие информации. -Системные сообщения выводятся с помощью метода ``print`` объекта ``rich.console.Console``, который имеет интерфейс, совместимый со встроенной функцией ``print``. - ------ Управление стандартным форматированием @@ -21,7 +19,7 @@ Приветственное и прощальное сообщения -------------------------------------- -Приветственное (``initial_message``) и прощальное (``farewell_message``) сообщения по умолчанию выводятся в виде ASCII-графики с помощью библиотеки ``art`` (а именно, функции ``text2art``). +Приветственное (``initial_message``) и прощальное (``farewell_message``) сообщения по умолчанию выводятся в виде ASCII-графики. .. warning:: Библиотека ``art`` ориентирована на работу с ASCII-символами и **не поддерживает кириллицу**. Это приводит к искажению символов русского и других кириллических алфавитов. Если ваше сообщение содержит кириллицу, рекомендуется отключить форматирование с помощью ``override_system_messages=True`` или использовать только латинские символы. diff --git a/mock/mock_app/main.py b/mock/mock_app/main.py index b3c52c4..3efab8a 100644 --- a/mock/mock_app/main.py +++ b/mock/mock_app/main.py @@ -2,9 +2,15 @@ from argenta import App, Orchestrator from argenta.app import PredefinedMessages, StaticDividingLine from mock.mock_app.routers import work_router +def print_hello(entity: str): + with open('hello.txt', 'a') as file: + file.write(f'printer called: {entity}\n') + print(entity) app: App = App( dividing_line=StaticDividingLine(), + override_system_messages=True, + print_func=print_hello ) orchestrator: Orchestrator = Orchestrator()