docs

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

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:
 
-   # Эта команда сработает
+.. seealso:: API и более подробное описание в разделах :ref:`ArgParser <root_api_orchestrator_argparser>` и :ref:`Arguments <root_api_orchestrator_arguments>`.
-   export --format json
+
+**Флаги** — это параметры командных операций, доступные в рамках интерактивной сессии при вводе каждой новой команды. Они позволяют модифицировать поведение конкретной команды без перезагрузки приложения.
+
+.. seealso:: API и более подробное описание в разделе :ref:`Flag <root_api_command_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`` — для команды тестирования
+
+Один пользователь может выполнить разные команды с разными флагами в одной сессии приложения, без необходимости перезапуска с новыми аргументами.

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`` или использовать только латинские символы.

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()