mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
feat: impl docs (#4)
The entire public api is covered with documentation in two languages - Russian and English. the library now supports the latest three versions of python - 3.12, 3.13 and 3.14 minor design changes: now, when a Boolean flag is entered, its value is an empty string, not None. tests have been adapted to the supported versions of python, readmi has been redesigned in two languages, German is no longer available.
This commit is contained in:
kolo
@@ -0,0 +1,150 @@
|
||||
.. _root_flags:
|
||||
|
||||
Флаги вводимых команд
|
||||
=====================
|
||||
|
||||
Флаги — это специальные параметры, которые пользователь может добавлять к командам для управления их поведением.
|
||||
|
||||
Зачем нужны флаги в командах
|
||||
----------------------------
|
||||
|
||||
Управление поведением команды
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Основная цель флагов — предоставить способ изменить логику работы команды без её переработки. Команда может работать в нескольких режимах: стандартном, подробном, отладочном или упрощённом. Флаги переключают эти режимы по требованию пользователя, оставляя основную функциональность неизменной.
|
||||
|
||||
Опциональность и удобство
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Флаги решают проблему обязательности параметров. Если все параметры команды сделать обязательными, это затруднит использование команды. Флаги же позволяют задать значения только необходимые в конкретной ситуации, остальные используют значения по умолчанию.
|
||||
|
||||
Когда могут понадобиться флаги
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Переключение режимов работы**
|
||||
Команда выполняет развёртывание приложения обычно, но нужен режим без фактического развёртывания (dry-run) для проверки. Флаг ``--dry-run`` переключит режим работы.
|
||||
|
||||
**Настройка уровня детальности**
|
||||
При отладке или анализе требуется больше информации о процессе выполнения команды. Флаги ``--verbose`` или ``--debug`` предоставляют подробный вывод.
|
||||
|
||||
**Управление поведением при ошибках**
|
||||
По умолчанию команда может прерваться при первой ошибке. Флаг ``--force`` позволит продолжить работу, пропуская некритичные ошибки.
|
||||
|
||||
**Форматирование вывода**
|
||||
Команда выводит данные текстом, но в некоторых сценариях нужен JSON или CSV. Флаг ``--format=json`` переключит формат вывода.
|
||||
|
||||
**Комбинирование опций**
|
||||
Часто нужна комбинация нескольких изменений: подробный вывод, dry-run режим и JSON формат. Несколько флагов решают эту задачу одновременно.
|
||||
|
||||
Практическое значение
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Флаги делают команды более предсказуемыми и контролируемыми. Пользователь может начать с простого использования, а затем добавлять флаги по мере необходимости. Это особенно важно при автоматизации задач в скриптах, где гибкость интерфейса критична.
|
||||
|
||||
Флаги также облегчают интеграцию команд в различные системы, так как дополнительное поведение достигается без изменения структуры команды, а только через передачу опциональных параметров.
|
||||
|
||||
-----
|
||||
|
||||
Синтаксис флагов
|
||||
-----------------
|
||||
|
||||
Общий синтаксис выглядит так:
|
||||
|
||||
.. code-block:: py
|
||||
|
||||
<command_name> <flag_prefix: Literal['-', '--', '---']><flag_name> <flag_value: Optional>
|
||||
|
||||
Флаг состоит из префикса (``-``, ``--`` или ``---``), имени и, опционально, значения, которое указывается через пробел.
|
||||
|
||||
**Примеры:**
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
greet --name John
|
||||
deploy --verbose
|
||||
backup -f --compress
|
||||
|
||||
-----
|
||||
|
||||
Работа с флагами в обработчиках
|
||||
--------------------------------
|
||||
|
||||
Чтобы получить значение флага в обработчике, используйте объект ``response.input_flags`` типа :ref:`InputFlags <root_api_command_input_flags>`.
|
||||
|
||||
**Пример с флагом, имеющим значение:**
|
||||
|
||||
.. literalinclude:: ../code_snippets/flags/greet_handler.py
|
||||
:language: python
|
||||
:linenos:
|
||||
|
||||
**Пример с флагом-переключателем:**
|
||||
|
||||
.. literalinclude:: ../code_snippets/flags/deploy_handler.py
|
||||
:language: python
|
||||
:linenos:
|
||||
|
||||
.. seealso::
|
||||
Подробнее о работе с объектом ``InputFlags`` см. в разделе :ref:`InputFlags <root_api_command_input_flags>`.
|
||||
|
||||
-----
|
||||
|
||||
Два типа флагов
|
||||
---------------
|
||||
|
||||
Флаги бывают двух основных видов:
|
||||
|
||||
1. **Флаги со значениями** — принимают параметр после имени флага (например, ``--name John``, ``--port 8080``)
|
||||
2. **Флаги-переключатели** — не принимают значения, их наличие само по себе является сигналом (например, ``--verbose``, ``--force``)
|
||||
|
||||
``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности для одной команды.
|
||||
|
||||
.. note::
|
||||
Ошибки валидации не выбрасывают исключений. Вместо этого у каждого объекта :ref:`InputFlag <root_api_command_input_flag>` есть атрибут ``status``, по которому можно определить, прошла ли валидация успешно. Подробное описание API для создания флагов находится в разделе :ref:`Flag <root_api_command_flag>`.
|
||||
|
||||
При регистрации флага можно задать правила валидации для его значения. По умолчанию любое значение считается корректным. Валидацию можно настроить несколькими способами:
|
||||
|
||||
-----
|
||||
|
||||
Флаги против аргументов
|
||||
-----------------------
|
||||
|
||||
В контексте Argenta флаги и аргументы относятся к разным уровням взаимодействия с приложением.
|
||||
|
||||
**Аргументы** — это параметры, передаваемые при запуске приложения. Они определяют глобальную конфигурацию на протяжении всей его работы (например, адрес базы данных, уровень логирования).
|
||||
|
||||
.. seealso:: API и более подробное описание в разделах :ref:`ArgParser <root_api_orchestrator_argparser>` и :ref:`Arguments <root_api_orchestrator_arguments>`.
|
||||
|
||||
**Флаги** — это параметры командных операций, доступные в рамках интерактивной сессии при вводе каждой новой команды. Они позволяют модифицировать поведение конкретной команды без перезагрузки приложения.
|
||||
|
||||
.. seealso:: API и более подробное описание в разделе :ref:`Flag <root_api_command_flag>`.
|
||||
|
||||
-----
|
||||
|
||||
Ключевые различия
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Время жизни**
|
||||
Аргументы передаются один раз при запуске и действуют на весь период работы приложения. Флаги локальны и существуют только в рамках выполнения команды.
|
||||
|
||||
**Изменяемость**
|
||||
Для изменения аргументов необходимо перезапустить приложение. Флаги можно менять при каждом вводе команды.
|
||||
|
||||
**Назначение**
|
||||
Аргументы управляют глобальной конфигурацией приложения. Флаги управляют поведением отдельных команд.
|
||||
|
||||
-----
|
||||
|
||||
Практические примеры
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Аргументы при запуске приложения:
|
||||
|
||||
- Адрес подключения к базе данных
|
||||
- Режим работы (production, development, testing)
|
||||
- Уровень логирования
|
||||
|
||||
Флаги в интерактивной сессии:
|
||||
|
||||
- ``deploy --verbose --dry-run`` — для команды развёртывания
|
||||
- ``backup --compress --encrypted`` — для команды резервного копирования
|
||||
- ``test --parallel --coverage`` — для команды тестирования
|
||||
Reference in New Issue
Block a user