docs

2026-06-10 10:05:28 +03:00 · 2025-11-07 17:00:34 +03:00
parent 4da876b774
commit 16e7cc21fb
4 changed files with 88 additions and 29 deletions
@@ -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
@@ -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 <root_api_orchestrator_argparser>` и :ref:`Arguments <root_api_orchestrator_arguments>`.
+
+**Флаги** — это параметры командных операций, доступные в рамках интерактивной сессии при вводе каждой новой команды. Они позволяют модифицировать поведение конкретной команды без перезагрузки приложения.
+
+.. 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`` — для команды тестирования
+
+Один пользователь может выполнить разные команды с разными флагами в одной сессии приложения, без необходимости перезапуска с новыми аргументами.
@@ -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`` или использовать только латинские символы.