docs

2026-06-10 10:05:28 +03:00 · 2025-11-02 00:17:28 +03:00
parent acddb1fbc6
commit df7313912c
26 changed files with 501 additions and 566 deletions
@@ -3,48 +3,48 @@
 AutoCompleter
 =====================

-Объект ``AutoCompleter`` является компонентом ``Argenta``, отвечающим за интерактивное автодополнение команд. Его основная задача — улучшить опыт взаимодействия пользователя с командной строкой, предоставляя подсказки и автоматически завершая ввод на основе ранее введенных команд. Это значительно ускоряет работу и снижает вероятность опечаток.
+``AutoCompleter`` — это компонент, отвечающий за интерактивное автодополнение команд. Он улучшает пользовательский опыт, предлагая подсказки и завершая ввод на основе истории команд, что ускоряет работу и снижает вероятность опечаток.

-``AutoCompleter`` использует ``pyreadline3`` для имплементации ``readline GNU`` на ``Windows`` для управления историей команд и реализации логики автодополнения.
+``AutoCompleter`` использует ``pyreadline3`` для реализации функциональности `GNU readline` в `Windows`, что позволяет управлять историей команд и автодополнением.

 -----

 Инициализация
 -------------

-.. code:: python
+.. code-block:: python

  __init__(self, history_filename: str | None = None, 
           autocomplete_button: str = "tab") -> None

-Создает и настраивает экземпляр ``AutoCompleter``.
+Создаёт и настраивает экземпляр ``AutoCompleter``.

-* ``history_filename``: Имя файла для сохранения и загрузки истории команд. Если указано, история будет персистентной между сессиями приложения. Если **None**, история будет храниться только в памяти текущей сессии.
-* ``autocomplete_button``: Название клавиши, которая активирует автодополнение. По умолчанию используется клавиша **"tab"**.
+* ``history_filename``: Имя файла для сохранения истории команд. Если указано, история будет сохраняться между сессиями. При значении `None` история хранится только в памяти.
+* ``autocomplete_button``: Клавиша, активирующая автодополнение. По умолчанию — **Tab**.

 -----

 Назначение и возможности
 -------------------------

-``AutoCompleter`` обладает следующими возможностями:
+Основные возможности ``AutoCompleter``:

-*   **Автодополнение по истории**: Основная логика автодополнения основана на истории команд, которые пользователь вводил ранее. Когда пользователь начинает вводить команду и нажимает клавишу автодополнения (по умолчанию **Tab**), система ищет в истории все команды, начинающиеся с введенного текста.
+*   **Автодополнение по истории**: При нажатии клавиши автодополнения (по умолчанию **Tab**) система ищет в истории команды, начинающиеся с уже введённого текста.

-*   **Завершение по общему префиксу**: Если найдено несколько команд с общим префиксом, автодокомплитер подставит только общую часть. Например, если в истории есть команды ``show_users`` и ``show_profile``, при вводе ``sho`` и нажатии **Tab** будет подставлено ``show_``.
+*   **Общий префикс**: Если найдено несколько команд с общим префиксом, будет подставлена только общая часть. Например, для команд ``show_users`` и ``show_profile`` при вводе ``sho`` и нажатии **Tab** ввод дополнится до ``show_``.

-*   **Персистентная история**: При указании параметра ``history_filename`` в конструкторе, вся история команд сохраняется в файл при выходе из приложения и загружается при следующем запуске. Это делает автодополнение со временем все более "умным" и персонализированным.
+*   **Постоянная история**: Если указан ``history_filename``, история команд сохраняется в файл при выходе и загружается при следующем запуске. Это делает автодополнение со временем «умнее».

-*   **Очистка истории**: При сохранении истории ``AutoCompleter`` автоматически удаляет дубликаты и команды, которые больше не зарегистрированы в приложении, поддерживая актуальность и чистоту файла истории.
+*   **Очистка истории**: При сохранении ``AutoCompleter`` удаляет дубликаты и более не существующие команды, поддерживая историю в актуальном состоянии.

-*   **Настройка клавиши активации**: Вы можете изменить клавишу, отвечающую за автодополнение, через параметр ``autocomplete_button``.
+*   **Настройка клавиши**: Клавишу автодополнения можно изменить с помощью параметра ``autocomplete_button``.
 
 -----

 Пример использования
 --------------------

-``AutoCompleter`` передается как аргумент при инициализации `App`.
+``AutoCompleter`` передаётся как аргумент при инициализации `App`.

 .. literalinclude:: ../../../code_snippets/autocompleter/snippet.py
    :language: python
@@ -3,15 +3,14 @@
 Dividing Lines
 ==============

-Разделительные линии в ``Argenta`` играют важную роль в визуальном оформлении консольного интерфейса. Они используются для структурирования вывода, отделения блоков информации друг от друга (например, вывода команды от следующего приглашения к вводу).
-Библиотека предлагает два подхода к управлению разделительными линиями: статический и динамический, каждый из которых имеет свои преимущества и сценарии использования.
+Разделительные линии в ``Argenta`` используются для визуального структурирования вывода и отделения блоков информации друг от друга. Библиотека предлагает два типа линий: статическую и динамическую.

 ----

 Класс ``StaticDividingLine``
 -----------------------------

-``StaticDividingLine`` — это класс, который создает разделительную линию **фиксированной** длины. Длина и символ-заполнитель задаются при инициализации объекта. Этот тип линии полезен, когда вам нужен предсказуемый и унифицированный внешний вид интерфейса, независимо от содержимого вывода.
+``StaticDividingLine`` создаёт разделительную линию **фиксированной** длины. Этот тип линии полезен для создания предсказуемого и унифицированного интерфейса.

 .. code-block:: python
   :linenos:
@@ -19,28 +18,28 @@ Dividing Lines
      def __init__(self, unit_part: str = "-", *, 
                   length: int = 25) -> None

-Создает экземпляр статической разделительной линии.
+Создаёт экземпляр статической разделительной линии.

-* ``unit_part``: Символ, который будет использоваться для построения линии. Учитывается только первый символ строки. По умолчанию: ``-``.
-* ``length``: Целое число, определяющее фиксированную длину линии в символах. Является keyword-only аргументом. По умолчанию: ``25``.
+* ``unit_part``: Символ для построения линии (учитывается только первый символ). По умолчанию: ``-``.
+* ``length``: Фиксированная длина линии (keyword-only аргумент). По умолчанию: ``25``.

 -----

 Класс ``DynamicDividingLine``
 ------------------------------

-``DynamicDividingLine`` представляет собой более "умный" подход. Этот класс создает линию, длина которой **динамически** подстраивается под самую длинную строку, выведенную в консоль, в рамках выполнения одной команды. Это достигается за счет механизма перехвата `stdout`. В результате разделительные линии всегда идеально обрамляют выводимый контент, что выглядит очень аккуратно.
+``DynamicDividingLine`` создаёт линию, длина которой **динамически** подстраивается под самую длинную строку в выводе команды. Это требует перехвата `stdout`, в результате чего разделители идеально обрамляют выводимый контент.

 .. code-block:: python
  :linenos:

   __init__(self, unit_part: str = "-") -> None

-Создает экземпляр динамической разделительной линии.
+Создаёт экземпляр динамической разделительной линии.

-* ``unit_part``: Символ, который будет использоваться для построения линии. По умолчанию: ``-``.
+* ``unit_part``: Символ для построения линии. По умолчанию: ``-``.

-Длина для этой линии не задается при инициализации, так как она вычисляется автоматически во время выполнения.
+Длина вычисляется автоматически и не задаётся при инициализации.

 .. warning::
    Обязательно почитайте про нюансы использования динамических линий и перехвата ``stdout`` в :ref:`этом разделе<root_redirect_stdout>`.
@@ -50,20 +49,20 @@ Dividing Lines
 Назначение и использование
 --------------------------

-Выбор между статической и динамической линией зависит от ваших потребностей в конкретном приложении или даже для конкретного ``Router``-а.
+Выбор между статической и динамической линией зависит от ваших задач.

 *   **StaticDividingLine** идеально подходит, если:

-    *   Вам нужен строгий, консистентный дизайн.
-    *   Вы используете роутеры с отключенным перехватом ``stdout`` (``disable_redirect_stdout=True``), так как в этом случае динамическое вычисление длины невозможно.
+    *   Вам нужен строгий и консистентный дизайн.
+    *   Вы используете роутеры с отключённым перехватом ``stdout`` (``disable_redirect_stdout=True``), где динамическое вычисление длины невозможно.

-*   **DynamicDividingLine** (используется по умолчанию) является предпочтительным выбором, если:
+*   **DynamicDividingLine** (поведение по умолчанию) — предпочтительный выбор, если:

-    *   Вы хотите, чтобы интерфейс выглядел аккуратно и адаптивно.
-    *   Вывод ваших команд имеет разную длину, и вы хотите, чтобы рамки всегда соответствовали контенту.
-    *   В ваших хэндлерах нет ожидающих ``io`` операций.
+    *   Вы хотите, чтобы интерфейс был адаптивным.
+    *   Вывод ваших команд имеет разную длину.
+    *   В ваших обработчиках нет интерактивных операций ввода (например, ``input()``).

-Тип разделительной линии для всего приложения задается при инициализации ``App`` через параметр ``dividing_line``.
+Тип разделителя для всего приложения задаётся при инициализации ``App`` через параметр ``dividing_line``.

 -----

@@ -3,14 +3,14 @@
 App
 ===

-Объект ``App`` является центральной сущностью библиотеки ``Argenta``. Он выступает в роли ядра вашего консольного приложения, отвечая за его конфигурацию, управление жизненным циклом, обработку команд и взаимодействие с пользователем. ``App`` координирует работу всех остальных компонентов, таких как роутеры, обработчики команд и системные сообщения.
+Объект ``App`` — это ядро вашего консольного приложения. Он отвечает за конфигурацию, управление жизненным циклом, обработку команд и взаимодействие с пользователем, координируя работу всех компонентов: роутеров, обработчиков и системных сообщений.

 ------

 Инициализация
 -------------

-.. code-block:: rust
+.. code-block:: python
   :linenos:

    AVAILABLE_DIVIDING_LINES: TypeAlias = StaticDividingLine | DynamicDividingLine
@@ -35,19 +35,19 @@ App
                autocompleter: AutoCompleter = DEFAULT_AUTOCOMPLETER, 
                print_func: Printer = DEFAULT_PRINT_FUNC) -> None

-Создает и настраивает экземпляр приложения ``Argenta``.
+Создаёт и настраивает экземпляр приложения.

-    * ``prompt``:  Строка-приглашение, которая отображается перед вводом каждой команды. По умолчанию: **"What do you want to do?\\n\\n"**.
-    * ``initial_message``: Приветственное сообщение, которое выводится при запуске приложения.
-    * ``farewell_message``: Прощальное сообщение при завершении работы приложения.
-    * ``exit_command``: Сущность команды, которая будет маркирована как команда для выхода из приложения.
-    * ``system_router_title``: Заголовок для системного роутера, который содержит команду выхода и другие системные команды.
-    * ``ignore_command_register``: Если **True** (по умолчанию), регистр введенных команд будет игнорироваться при поиске обработчика.
-    * ``dividing_line``: Объект, управляющий стилем разделительной линии. Может быть **StaticDividingLine** или **DynamicDividingLine**.
-    * ``repeat_command_groups``: Если **True** (по умолчанию), описание доступных команд будет выводиться перед каждым вводом.
-    * ``override_system_messages``: Если **True** (по умолчанию), стандартное форматирование системных сообщений (цвета, ASCII-арт) будет отключено.
-    * ``autocompleter``: Объект, отвечающий за логику автодополнения команд.
-    * ``print_func``: Функция, используемая для вывода всех системных сообщений. По умолчанию используется ``rich.console.Console().print``.
+    * ``prompt``: Приглашение к вводу, отображаемое перед каждой командой.
+    * ``initial_message``: Сообщение, выводимое при запуске приложения.
+    * ``farewell_message``: Сообщение, выводимое при выходе из приложения.
+    * ``exit_command``: Команда, используемая для выхода из приложения.
+    * ``system_router_title``: Заголовок для системного роутера (содержит команду выхода).
+    * ``ignore_command_register``: Если ``True``, регистр команд игнорируется при поиске обработчика.
+    * ``dividing_line``: Стиль разделительной линии (``StaticDividingLine`` или ``DynamicDividingLine``).
+    * ``repeat_command_groups``: Если ``True``, список доступных команд выводится перед каждым вводом.
+    * ``override_system_messages``: Если ``True``, стандартное форматирование (цвета, ASCII-арт) отключается.
+    * ``autocompleter``: Объект, отвечающий за автодополнение команд.
+    * ``print_func``: Функция для вывода всех системных сообщений (по умолчанию ``rich.print``).

 -----
    
@@ -56,19 +56,19 @@ App

 - .. py:method:: include_router(self, router: Router) -> None

-    Регистрирует один ``Router`` в приложении. Все команды, определенные в этом роутере, становятся доступными для вызова.
+    Регистрирует роутер в приложении. Все команды из этого роутера становятся доступными для вызова.
    
-    :param router: Объект роутера, который нужно зарегистрировать.
+    :param router: Экземпляр ``Router`` для регистрации.

 - .. py:method:: include_routers(self, *routers: Router) -> None

-    Регистрирует несколько роутеров одновременно. Является удобной оберткой над ``include_router``.
+    Регистрирует несколько роутеров одновременно.
    
-    :param routers: Последовательность объектов ``Router`` для регистрации.
+    :param routers: Последовательность экземпляров ``Router`` для регистрации.

 - .. py:method:: add_message_on_startup(self, message: str) -> None
    
-    Добавляет дополнительное текстовое сообщение, которое будет выведено на экран при запуске приложения, сразу после `initial_message`.
+    Добавляет текстовое сообщение, которое выводится при запуске приложения после `initial_message`.
    
    :param message: Строка с сообщением.
    
@@ -77,70 +77,58 @@ App
 Методы установки обработчиков
 -------------------------------

-``App`` позволяет гибко настраивать реакцию на различные события, такие как ошибки ввода или ввод неизвестной команды.
+``App`` позволяет настраивать реакцию на различные события, такие как ошибки ввода или неизвестные команды.

 .. hint::
   Подробнее о исключениях и их обработке в соответствующем :ref:`разделе документации <root_error_handling>`.
   
 -----

-.. py:method:: set_description_message_pattern(self, handler: DescriptionMessageGenerator) -> None
+.. py:method:: set_description_message_pattern(self, handler: Callable[[str, str], str]) -> None

-   Устанавливает пользовательский шаблон для форматирования строки, описывающей доступную команду (триггер + описание).
+   Устанавливает шаблон для форматирования строки описания команды.
   
-   ``DescriptionMessageGenerator`` -> ``Callable[[str, str], str]``
-   
-   Где первый аргумент - это триггер команды, а второй - ее описание, возвращает строку, которая является форматированной строкой.
+   Обработчик принимает триггер команды (``str``) и её описание (``str``), а возвращает отформатированную строку.
   
 ------

-.. py:method:: set_incorrect_input_syntax_handler(self, handler: NonStandardBehaviorHandler[str]) -> None
+.. py:method:: set_incorrect_input_syntax_handler(self, handler: Callable[[str], None]) -> None

-   Устанавливает обработчик, который вызывается при некорректном синтаксисе флагов в введенной команде.
+   Устанавливает обработчик для некорректного синтаксиса флагов.
   
-   ``NonStandardBehaviorHandler[str]`` -> ``Callable[[str], None]``
-   
-   Где первый и единственный аргумент - это необработанная строка пользовательского ввода.
+   Обработчик принимает строку, введённую пользователем.
   
 ------

-.. py:method:: set_repeated_input_flags_handler(self, handler: NonStandardBehaviorHandler[str]) -> None
+.. py:method:: set_repeated_input_flags_handler(self, handler: Callable[[str], None]) -> None

-   Устанавливает обработчик для ситуации, когда пользователь вводит один и тот же флаг несколько раз.
+   Устанавливает обработчик для повторяющихся флагов в команде.
   
-   ``NonStandardBehaviorHandler[str]`` -> ``Callable[[str], None]``
-   
-   Где первый и единственный аргумент - это необработанная строка пользовательского ввода.
+   Обработчик принимает строку, введённую пользователем.
   
 ------

-.. py:method:: set_unknown_command_handler(self, handler: NonStandardBehaviorHandler[InputCommand]) -> None
+.. py:method:: set_unknown_command_handler(self, handler: Callable[[InputCommand], None]) -> None

-   Устанавливает обработчик, который срабатывает, если введенная команда не была найдена ни в одном из зарегистрированных роутеров.
+   Устанавливает обработчик для неизвестной команды.
   
-   ``NonStandardBehaviorHandler[InputCommand]`` -> ``Callable[[InputCommand], None]``
-   
-   Где первый и единственный аргумент - это распаршенный в объект InputCommand ввод пользователя.
+   Обработчик принимает объект ``InputCommand``.
   
 -----

-.. py:method:: set_empty_command_handler(self, handler: EmptyCommandHandler) -> None
+.. py:method:: set_empty_command_handler(self, handler: Callable[[], None]) -> None

-   Устанавливает обработчик для случая, когда пользователь отправляет пустую строку вместо команды.
+   Устанавливает обработчик для пустого ввода.
   
-   ``EmptyCommandHandler`` -> ``Callable[[], None]``
-   
-   Не принимает и не возвращает ничего.
+   Обработчик не принимает аргументов.
   
 -----

-.. py:method:: set_exit_command_handler(self, handler: NonStandardBehaviorHandler[Response]) -> None
+.. py:method:: set_exit_command_handler(self, handler: Callable[[Response], None]) -> None

-   Позволяет переопределить стандартное поведение при вызове команды выхода. По умолчанию просто выводится ``farewell_message``.
+   Переопределяет стандартное поведение при вызове команды выхода.
   
-   ``NonStandardBehaviorHandler[Response]`` -> ``Callable[[Response], None]``
-   
-   Где первый и единственный аргумент - это объект ответа, ``Response``.
+   Обработчик принимает объект ``Response``.

 .. toctree::
    :hidden:
@@ -3,13 +3,13 @@
 Flag
 =====

-Объект ``Flag`` представляет собой сущность флага, регистрируемого для последующей обработки в приложении ``Argenta``. Его основная задача — определить параметры флага команды, включая имя, префикс и допустимые значения. ``Flag`` используется при создании команд с флагами и предоставляет механизм валидации входящих значений от пользователя.
+``Flag`` — это сущность, описывающая флаг команды. Её основная задача — определить параметры флага, включая его имя, префикс и правила валидации. `Flag` используется при создании команд и предоставляет механизм для проверки значений, введённых пользователем.

 .. seealso::

-   Документация по :ref:`PossibleValues <root_api_command_possible_values>` — сущность, определяющая допустимые значения флага.
+   Документация по :ref:`PossibleValues <root_api_command_possible_values>` — перечисление, определяющее типы допустимых значений.
   
-   Документация по :ref:`InputFlag <root_api_command_input_flag>` — объект распаршенного введённого флага.
+   Документация по :ref:`InputFlag <root_api_command_input_flag>` — объект обработанного флага, введённого пользователем.
   
   :ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``

@@ -27,11 +27,11 @@ Flag
       possible_values: list[str] | Pattern[str] | PossibleValues = PossibleValues.ALL,
   ) -> None

-Создает новый флаг для регистрации в команде.
+Создаёт новый флаг для регистрации в команде.

-* ``name`` : Имя флага (обязательный параметр)
-* ``prefix`` : Префикс флага. По умолчанию ``"--"``. Возможные значения: ``"-"``, ``"--"``, ``"---"``
-* ``possible_values`` : Допустимые значения флага. По умолчанию ``PossibleValues.ALL``. Может быть списком строк, регулярным выражением или значением из enum ``PossibleValues``
+* ``name``: Имя флага (обязательный параметр).
+* ``prefix``: Префикс флага (``-``, ``--``, ``---``). По умолчанию ``--``.
+* ``possible_values``: Правила валидации значения. Может быть списком строк, регулярным выражением или значением из `PossibleValues`. По умолчанию `PossibleValues.ALL`.

 **Атрибуты:**

@@ -45,12 +45,12 @@ Flag

 .. py:attribute:: possible_values

-   Определяет допустимые значения для флага. Может быть:
-   
-   * Списком строк — флаг принимает только значения из этого списка
-   * Регулярным выражением (``Pattern[str]``) — значение проверяется на соответствие паттерну
-   * Значением ``PossibleValues.ALL`` — флаг принимает любое значение
-   * Значением ``PossibleValues.NEITHER`` — флаг не должен иметь значения
+   Определяет допустимые значения для флага:
+
+*   Список строк: флаг принимает только значения из этого списка.
+*   Регулярное выражение (`Pattern[str]`): значение проверяется на соответствие паттерну.
+*   `PossibleValues.ALL`: флаг принимает любое значение.
+*   `PossibleValues.NEITHER`: флаг не должен иметь значения.

 **Пример использования:**

@@ -72,11 +72,11 @@ string_entity
   @property
   string_entity(self) -> str

-Возвращает строковое представление флага в формате ``prefix + name``.
+Возвращает строковое представление флага в формате `prefix + name`.

 :return: Строковое представление флага

-Это свойство объединяет префикс и имя флага в единую строку, которая представляет, как флаг будет выглядеть в командной строке.
+Это свойство объединяет префикс и имя в единую строку, которая представляет флаг так, как он выглядел бы в командной строке.

 **Пример использования:**

@@ -97,7 +97,7 @@ __str__

   __str__(self) -> str

-Возвращает строковое представление флага (аналогично ``string_entity``).
+Возвращает строковое представление флага (аналогично `string_entity`).

 :return: Строковое представление флага

@@ -117,9 +117,9 @@ __repr__

   __repr__(self) -> str

-Возвращает отладочное представление объекта флага.
+Возвращает отладочное представление объекта.

-:return: Строка в формате ``Flag<prefix=..., name=...>``
+:return: Строка в формате `Flag<prefix=..., name=...>`.

 **Пример использования:**

@@ -137,13 +137,13 @@ __eq__

   __eq__(self, other: object) -> bool

-Сравнивает два флага на равенство по их строковому представлению.
+Сравнивает два флага на равенство по их строковому представлению (`string_entity`).

 :param other: Объект для сравнения
 :return: ``True``, если флаги равны, иначе ``False``
-:raises NotImplementedError: Если ``other`` не является экземпляром ``Flag``
+:raises NotImplementedError: Если `other` не является экземпляром `Flag`.

-Два флага считаются равными, если их ``string_entity`` идентичны.
+Два флага считаются равными, если их `string_entity` идентичны.

 **Пример использования:**

@@ -160,9 +160,9 @@ PredefinedFlags

 ``argenta.command.flag.defaults.PredefinedFlags``

-Класс ``PredefinedFlags`` предоставляет набор предопределенных флагов, которые можно использовать в приложениях без необходимости их ручного создания. Эти флаги покрывают наиболее распространенные сценарии использования и следуют общепринятым соглашениям командной строки.
+Класс `PredefinedFlags` предоставляет набор готовых флагов для использования в приложениях без их ручного создания. Эти флаги покрывают наиболее распространённые сценарии и следуют общепринятым соглашениям.

-Все предопределенные флаги являются атрибутами класса и представляют собой готовые экземпляры ``Flag``.
+Все предопределённые флаги являются атрибутами класса и представляют собой готовые экземпляры `Flag`.

 -----

@@ -3,15 +3,15 @@
 Flags
 ======

-Объект ``Flags`` представляет собой коллекцию флагов команды в приложении ``Argenta``. Его основная задача — группировать и управлять набором флагов, зарегистрированных для конкретной команды. ``Flags`` служит контейнером, который позволяет удобно добавлять, извлекать и итерировать флаги, а также проверять их наличие.
+`Flags` — это коллекция флагов команды. Её основная задача — группировать и управлять набором флагов, зарегистрированных для конкретной команды. `Flags` служит контейнером, который позволяет удобно добавлять, извлекать, итерировать флаги и проверять их наличие.

-``Flags`` наследуется от базового класса ``BaseFlags`` и специализируется для работы с объектами типа ``Flag``. Этот класс используется при создании команд с множественными флагами и предоставляет интерфейс для управления ими.
+`Flags` наследуется от базового класса `BaseFlags` и специализируется на работе с объектами типа `Flag`. Этот класс используется при создании команд с несколькими флагами и предоставляет интерфейс для управления ими.

 .. seealso::

   Документация по отдельным флагам (:ref:`Flag <root_api_command_flag>`, :ref:`InputFlag <root_api_command_input_flag>`)
   
-   Документация по :ref:`InputFlags <root_api_command_input_flags>` — коллекции распаршенных флагов пользователя
+   Документация по :ref:`InputFlags <root_api_command_input_flags>` — коллекция обработанных флагов, введённых пользователем.
   
   :ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``

@@ -25,15 +25,16 @@ Flags

   __init__(self, flags: list[Flag] | None = None) -> None

-Создает новую коллекцию флагов.
+Создаёт новую коллекцию флагов.

-* ``flags`` : Необязательный список флагов типа ``Flag`` для инициализации коллекции. Если не указан, создается пустая коллекция.
+* ``flags``: Необязательный список флагов типа `Flag` для инициализации коллекции. Если не указан, создаётся пустая коллекция.

 **Атрибуты:**

 .. py:attribute:: flags
+   :no-index:

-   Список всех зарегистрированных флагов типа ``Flag``. Пустой список, если флаги не были переданы при инициализации.
+   Список всех зарегистрированных флагов типа `Flag`. Пуст, если флаги не были переданы при инициализации.

 **Пример использования:**

@@ -54,12 +55,12 @@ add_flag

   add_flag(self, flag: Flag) -> None

-Добавляет один флаг в коллекцию.
+Добавляет флаг в коллекцию.

-:param flag: Флаг типа ``Flag`` для добавления в коллекцию
-:return: None
+:param flag: Флаг типа `Flag` для добавления.
+:return: None.

-Метод добавляет переданный флаг в конец списка ``flags``. Используется для динамического расширения набора флагов после создания коллекции.
+Метод добавляет флаг в конец списка `flags`. Используется для динамического расширения набора флагов.

 **Пример использования:**

@@ -77,12 +78,12 @@ add_flags

   add_flags(self, flags: list[Flag]) -> None

-Добавляет список флагов в коллекцию.
+Добавляет в коллекцию список флагов.

-:param flags: Список флагов типа ``Flag`` для добавления
-:return: None
+:param flags: Список флагов типа `Flag` для добавления.
+:return: None.

-Метод расширяет текущую коллекцию, добавляя все флаги из переданного списка. Эффективен для пакетного добавления множества флагов.
+Метод расширяет коллекцию, добавляя в неё все флаги из переданного списка. Эффективен для пакетного добавления.

 **Пример использования:**

@@ -100,12 +101,12 @@ get_flag_by_name

   get_flag_by_name(self, name: str) -> Flag | None

-Получает флаг по его имени.
+Возвращает флаг по имени.

-:param name: Имя искомого флага
-:return: Объект ``Flag`` с указанным именем или ``None``, если флаг не найден
+:param name: Имя искомого флага.
+:return: Объект `Flag` или `None`, если флаг не найден.

-Метод выполняет поиск по списку ``flags`` и возвращает первый флаг с соответствующим именем. Если флаг не найден, возвращается ``None``.
+Метод выполняет поиск по списку `flags` и возвращает первый флаг с соответствующим именем. Если флаг не найден, возвращается `None`.

 **Пример использования:**

@@ -126,9 +127,9 @@ __iter__

   __iter__(self) -> Iterator[Flag]

-Делает коллекцию итерируемой, позволяя использовать её в циклах.
+Делает коллекцию итерируемой для использования в циклах.

-:return: Итератор по списку флагов
+:return: Итератор по списку флагов.

 **Пример использования:**

@@ -146,10 +147,10 @@ __getitem__

   __getitem__(self, flag_index: int) -> Flag

-Позволяет получать флаги по индексу.
+Позволяет получать флаг по индексу.

-:param flag_index: Индекс флага в списке
-:return: Флаг с указанным индексом
+:param flag_index: Индекс флага в списке.
+:return: Флаг по указанному индексу.

 **Пример использования:**

@@ -3,9 +3,9 @@
 Command
 =======

-Объект ``Command`` представляет собой основную единицу функциональности в приложении ``Argenta``. Каждая команда определяет конкретное действие, которое пользователь может выполнить, введя соответствующий триггер. Команды регистрируются в роутерах и образуют интерфейс взаимодействия с приложением.
+``Command`` — это основная единица функциональности в приложении. Каждая команда определяет действие, которое пользователь может выполнить, введя соответствующий триггер. Команды регистрируются в роутерах и формируют интерфейс взаимодействия с приложением.

-``Command`` инкапсулирует всю необходимую информацию о команде: её триггер (ключевое слово для вызова), описание, набор флагов для настройки поведения и список псевдонимов для альтернативных способов вызова.
+``Command`` инкапсулирует всю информацию о команде: её триггер (ключевое слово для вызова), описание, набор флагов и список псевдонимов.

 -----

@@ -20,33 +20,30 @@ Command
            flags: Flag | Flags = DEFAULT_WITHOUT_FLAGS,
            aliases: list[str] | None = None) -> None

-Создает новую команду для регистрации в роутере.
+Создаёт новую команду для регистрации в роутере.

-* ``trigger`` : Строковый триггер команды, который пользователь должен ввести для её вызова. Это основной идентификатор команды в системе.
-
-* ``description`` : Необязательное описание команды, объясняющее её назначение. Если не указано, используется значение по умолчанию ``"Command without description"``. Отображается в справке и списке доступных команд.
-
-* ``flags`` : Набор флагов команды для настройки её поведения. Может быть одиночным объектом ``Flag`` или коллекцией ``Flags``. По умолчанию команда создается без флагов.
-
-* ``aliases`` : Список строковых синонимов для основного триггера. Позволяет вызывать команду альтернативными способами. По умолчанию список пуст.
+* ``trigger``: Строковый триггер, который пользователь вводит для вызова команды. Является основным идентификатором.
+* ``description``: Необязательное описание, объясняющее назначение команды. Отображается в справке.
+* ``flags``: Набор флагов для настройки поведения. Может быть одиночным объектом `Flag` или коллекцией `Flags`.
+* ``aliases``: Список строковых псевдонимов для основного триггера.

 **Атрибуты:**

 .. py:attribute:: trigger

-   Основной триггер команды в виде строки. Используется для идентификации команды при парсинге пользовательского ввода.
+   Основной триггер команды. Используется для её идентификации при обработке пользовательского ввода.

 .. py:attribute:: description

-   Текстовое описание команды. Если не было передано при инициализации, содержит значение ``"Command without description"``.
+   Текстовое описание команды. Если не передано, используется значение по умолчанию.

 .. py:attribute:: registered_flags

-   Объект ``Flags``, содержащий все зарегистрированные флаги команды. Автоматически конвертируется из одиночного ``Flag`` в коллекцию при инициализации.
+   Объект `Flags`, содержащий все зарегистрированные флаги. Автоматически конвертируется из одиночного `Flag` в коллекцию при инициализации.

 .. py:attribute:: aliases

-   Список строк с альтернативными триггерами команды. Пустой список, если псевдонимы не заданы.
+   Список строковых псевдонимов. Пуст, если псевдонимы не заданы.

 **Пример использования:**

@@ -61,7 +58,7 @@ Command
 Регистрация команд
 ------------------

-Команды регистрируются в роутерах с помощью декоратора ``@router.command()``. После регистрации команда становится доступной пользователям для вызова.
+Команды регистрируются в роутерах с помощью декоратора ``@router.command()``, после чего становятся доступными для вызова.

 **Базовый пример:**

@@ -78,7 +75,7 @@ Command
 Работа с псевдонимами
 ---------------------

-Псевдонимы позволяют вызывать один и тот же хэндлер разными триггерами, сохраняя при этом флаги команды и описание.
+Псевдонимы позволяют вызывать один и тот же обработчик разными триггерами, сохраняя флаги и описание команды.

 **Пример с псевдонимами:**

@@ -115,26 +112,27 @@ Command
 InputCommand
 ------------

-Класс ``InputCommand`` представляет собой распаршенную команду, введенную пользователем. Это внутренний класс, который создается автоматически при парсинге пользовательского ввода. Непосредственная работа с данным классом возможна при создании кастомного хэндлера для обработки неизвестных команд.
+``InputCommand`` представляет собой обработанную команду, введённую пользователем. Этот внутренний класс создаётся автоматически при обработке пользовательского ввода. Прямая работа с ним возможна при создании пользовательского обработчика для неизвестных команд.

 .. seealso ::
-   Подробнее про кастомные хэндлеры обработки исключений ввода :ref:`тут <root_error_handling>`
+   Подробнее о пользовательских обработчиках исключений см. :ref:`здесь <root_error_handling>`.

-Создает экземпляр распарсенной команды.
+Создаёт экземпляр обработанной команды.

-:param trigger: Триггер команды, извлеченный из пользовательского ввода
-:param input_flags: Флаги, переданные пользователем при вызове команды
+:param trigger: Триггер команды, извлечённый из пользовательского ввода.
+:param input_flags: Флаги, переданные пользователем.

 **Атрибуты:**

 .. py:attribute:: trigger
   :no-index:

-   Строковый триггер команды, введенный пользователем.
+   Строковый триггер, введённый пользователем.

 .. py:attribute:: input_flags
+   :no-index:

-   Объект ``InputFlags``, содержащий все флаги, переданные с командой. Автоматически конвертируется из одиночного ``InputFlag`` в коллекцию.
+   Объект `InputFlags`, содержащий все переданные с командой флаги. Автоматически конвертируется из одиночного `InputFlag` в коллекцию.

 .. toctree ::
    :hidden:
@@ -3,11 +3,11 @@
 InputFlag
 =========

-Объект ``InputFlag`` представляет собой сущность флага введённой команды. Он создаётся в результате парсинга пользовательского ввода и содержит информацию о распознанном флаге, включая его имя, префикс, введённое значение и статус валидации.
+Объект `InputFlag` представляет собой флаг, введённый пользователем. Он создаётся в результате обработки пользовательского ввода и содержит информацию о распознанном флаге: его имя, префикс, значение и статус валидации.

 .. seealso::

-   Документация по :ref:`Flag <root_api_command_flag>` — сущность флага, регистрируемого для последующей обработки.
+   Документация по :ref:`Flag <root_api_command_flag>` — класс для регистрации флага.

   Документация по :ref:`ValidationStatus <root_api_command_validation_status>` — статусы валидации флагов.

@@ -28,33 +28,34 @@ InputFlag

 Создаёт новый объект введённого флага.

-* ``name`` : Имя введённого флага (обязательный параметр)
-* ``prefix`` : Префикс флага. По умолчанию ``"--"``. Возможные значения: ``"-"``, ``"--"``, ``"---"``
-* ``input_value`` : Значение введённого флага. Может быть ``None`` если флаг не принимает значения
-* ``status`` : Статус валидации флага из перечисления ``ValidationStatus``
+* ``name``: Имя введённого флага.
+* ``prefix``: Префикс флага (``-``, ``--``, ``---``). По умолчанию ``--``.
+* ``input_value``: Значение, переданное с флагом. Может быть `None`.
+* ``status``: Статус валидации из перечисления `ValidationStatus`.

 .. warning ::
-   Экземпляры класса не предназначены для их прямого создания, они содержаться в контейнере :ref:`Response <root_api_response>`
+   Экземпляры этого класса не предназначены для прямого создания. Они содержатся в объекте :ref:`Response <root_api_response>`.

 **Атрибуты:**

 .. py:attribute:: name
   :no-index:

-   Имя введённого флага в виде строки.
+   Имя введённого флага.

 .. py:attribute:: prefix
   :no-index:

-   Префикс флага. Один из: ``"-"``, ``"--"``, ``"---"``.
+   Префикс флага: ``-``, ``--`` или ``---``.

 .. py:attribute:: input_value

-   Значение, переданное с флагом в командной строке. Может быть ``None`` для флагов без значений.
+   Значение, переданное с флагом. Может быть `None` для флагов без значений.

 .. py:attribute:: status
+   :no-index:

-   Статус валидации флага. Один из: ``ValidationStatus.VALID``, ``ValidationStatus.INVALID``, ``ValidationStatus.UNDEFINED``.
+   Статус валидации флага: `ValidationStatus.VALID`, `ValidationStatus.INVALID` или `ValidationStatus.UNDEFINED`.

 **Пример использования:**

@@ -76,11 +77,11 @@ string_entity
   @property
   string_entity(self) -> str

-Возвращает строковое представление флага в формате ``prefix + name``.
+Возвращает строковое представление флага в формате `prefix + name`.

 :return: Строковое представление флага

-Это свойство объединяет префикс и имя флага в единую строку, которая представляет, как флаг был введён в командной строке.
+Это свойство объединяет префикс и имя в строку, представляющую флаг так, как он был введён в командной строке.

 **Пример использования:**

@@ -101,9 +102,9 @@ __str__

   __str__(self) -> str

-Возвращает строковое представление введённого флага вместе с его значением.
+Возвращает строковое представление флага вместе с его значением.

-:return: Строка в формате ``флаг значение``
+:return: Строка в формате `флаг значение`.

 **Пример использования:**

@@ -121,9 +122,9 @@ __repr__

   __repr__(self) -> str

-Возвращает отладочное представление объекта введённого флага.
+Возвращает отладочное представление объекта.

-:return: Строка в формате ``InputFlag<prefix=..., name=..., value=..., status=...>``
+:return: Строка в формате `InputFlag<prefix=..., name=..., value=..., status=...>`.

 **Пример использования:**

@@ -141,13 +142,13 @@ __eq__

   __eq__(self, other: object) -> bool

-Сравнивает два введённых флага на равенство по их имени.
+Сравнивает два введённых флага на равенство по имени.

-:param other: Объект для сравнения
-:return: ``True``, если имена флагов совпадают, иначе ``False``
-:raises NotImplementedError: Если ``other`` не является экземпляром ``InputFlag``
+:param other: Объект для сравнения.
+:return: `True`, если имена флагов совпадают, иначе `False`.
+:raises NotImplementedError: Если `other` не является экземпляром `InputFlag`.

-Два введённых флага считаются равными, если их имена идентичны.
+Два введённых флага считаются равными, если их имена совпадают.

 **Пример использования:**

@@ -3,18 +3,18 @@
 InputFlags
 ==========

-Объект ``InputFlags`` представляет собой коллекцию введённых флагов команды в приложении ``Argenta``. Его основная задача — группировать и управлять набором флагов, которые были введены пользователем вместе с командой. ``InputFlags`` служит контейнером, который позволяет удобно извлекать, итерировать и проверять наличие введённых флагов, а также работать с их значениями и статусами валидации.
+`InputFlags` — это коллекция флагов, введённых пользователем. Её основная задача — группировать и управлять набором флагов, переданных вместе с командой. `InputFlags` служит контейнером, который позволяет удобно извлекать, итерировать и проверять наличие флагов, а также работать с их значениями и статусами валидации.

-``InputFlags`` наследуется от базового класса ``BaseFlags`` и специализируется для работы с объектами типа ``InputFlag``. Этот класс автоматически создаётся системой при парсинге пользовательского ввода и передаётся в обработчики команд через объект ``Response``.
+`InputFlags` наследуется от `BaseFlags` и специализируется на работе с объектами типа `InputFlag`. Этот класс создаётся автоматически при обработке пользовательского ввода и передаётся в обработчики команд через объект `Response`.

 .. seealso::

   Документация по отдельным флагам (:ref:`Flag <root_api_command_flag>`, :ref:`InputFlag <root_api_command_input_flag>`)
-   
-   Документация по :ref:`Flags <root_api_command_flags>` — коллекции зарегистрированных флагов команды
-   
+
+   Документация по :ref:`InputFlags <root_api_command_input_flags>` — коллекция обработанных флагов, введённых пользователем.
+
   Документация по :ref:`Response <root_api_response>` — объект ответа, содержащий ``InputFlags``
-   
+
   :ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``

 -----
@@ -27,18 +27,19 @@ InputFlags

   __init__(self, flags: list[InputFlag] | None = None) -> None

-Создает новую коллекцию введённых флагов.
+Создаёт новую коллекцию введённых флагов.

-* ``flags`` : Необязательный список введённых флагов типа ``InputFlag`` для инициализации коллекции. Если не указан, создается пустая коллекция.
+* ``flags``: Необязательный список флагов типа `InputFlag` для инициализации коллекции. Если не указан, создаётся пустая коллекция.

 .. warning ::
-   Экземпляры класса обычно не создаются напрямую. Они автоматически формируются системой при парсинге пользовательского ввода и доступны через атрибут ``input_flags`` объекта ``Response`` в обработчиках команд.
+   Экземпляры этого класса обычно не создаются напрямую. Они автоматически формируются системой при обработке пользовательского ввода и доступны через атрибут `input_flags` объекта `Response`.

 **Атрибуты:**

 .. py:attribute:: flags
+   :no-index:

-   Список всех введённых флагов типа ``InputFlag``. Пустой список, если флаги не были переданы при инициализации или пользователь не ввёл флагов с командой.
+   Список всех введённых флагов типа `InputFlag`. Пуст, если флаги не были переданы при инициализации или пользователь не ввёл их с командой.

 **Пример использования:**

@@ -59,12 +60,12 @@ get_flag_by_name

   get_flag_by_name(self, name: str) -> InputFlag | None

-Получает введённый флаг по его имени.
+Возвращает введённый флаг по имени.

-:param name: Имя искомого флага (без префикса)
-:return: Объект ``InputFlag`` с указанным именем или ``None``, если флаг не найден
+:param name: Имя искомого флага (без префикса).
+:return: Объект `InputFlag` или `None`, если флаг не найден.

-Метод выполняет поиск по списку ``flags`` и возвращает первый флаг с соответствующим именем. Поиск происходит по атрибуту ``name`` объекта ``InputFlag``, сравнивая только имена флагов, без учёта префикса.
+Метод выполняет поиск по списку `flags` и возвращает первый флаг с соответствующим именем (без учёта префикса).

 **Пример использования:**

@@ -82,15 +83,15 @@ add_flag

   add_flag(self, flag: InputFlag) -> None

-Добавляет один введённый флаг в коллекцию.
+Добавляет введённый флаг в коллекцию.

-:param flag: Флаг типа ``InputFlag`` для добавления в коллекцию
-:return: None
+:param flag: Флаг типа `InputFlag` для добавления.
+:return: None.

-Метод добавляет переданный флаг в конец списка ``flags``. Используется для динамического расширения набора флагов после создания коллекции.
+Метод добавляет флаг в конец списка `flags`. Используется для динамического расширения коллекции.

 .. note::
-   Этот метод используется редко, так как ``InputFlags`` обычно создаётся автоматически системой при парсинге пользовательского ввода. Однако он может быть полезен для тестирования или ручного создания коллекций флагов.
+   Этот метод используется редко, так как `InputFlags` обычно создаётся автоматически. Однако он может быть полезен для тестирования или ручного создания коллекций.

 **Пример использования:**

@@ -108,12 +109,12 @@ add_flags

   add_flags(self, flags: list[InputFlag]) -> None

-Добавляет список введённых флагов в коллекцию.
+Добавляет в коллекцию список введённых флагов.

-:param flags: Список флагов типа ``InputFlag`` для добавления
-:return: None
+:param flags: Список флагов типа `InputFlag` для добавления.
+:return: None.

-Метод расширяет текущую коллекцию, добавляя все флаги из переданного списка. Эффективен для пакетного добавления множества флагов.
+Метод расширяет коллекцию, добавляя в неё все флаги из переданного списка. Эффективен для пакетного добавления.

 **Пример использования:**

@@ -134,11 +135,11 @@ __iter__

   __iter__(self) -> Iterator[InputFlag]

-Делает коллекцию итерируемой, позволяя использовать её в циклах.
+Делает коллекцию итерируемой для использования в циклах.

-:return: Итератор по списку введённых флагов
+:return: Итератор по списку введённых флагов.

-Позволяет перебирать все введённые флаги команды, что особенно полезно для проверки статусов валидации или обработки всех флагов.
+Позволяет перебирать все введённые флаги, что полезно для проверки их статусов или пакетной обработки.

 **Пример использования:**

@@ -156,12 +157,12 @@ __getitem__

   __getitem__(self, flag_index: int) -> InputFlag

-Позволяет получать введённые флаги по индексу.
+Позволяет получать введённый флаг по индексу.

-:param flag_index: Индекс флага в списке
-:return: Флаг с указанным индексом
+:param flag_index: Индекс флага в списке.
+:return: Флаг по указанному индексу.

-Позволяет обращаться к флагам по их позиции в списке, что может быть полезно для обработки флагов в определённом порядке.
+Позволяет обращаться к флагам по их позиции, что может быть полезно для их обработки в определённом порядке.

 **Пример использования:**

@@ -179,11 +180,11 @@ __bool__

   __bool__(self) -> bool

-Определяет, содержит ли коллекция какие-либо флаги.
+Определяет, содержит ли коллекция флаги.

-:return: ``True``, если в коллекции есть хотя бы один флаг, иначе ``False``
+:return: `True`, если в коллекции есть хотя бы один флаг, иначе `False`.

-Позволяет проверять наличие флагов в команде, что удобно для условной логики.
+Позволяет проверять наличие флагов в команде для условной логики.

 **Пример использования:**

@@ -203,11 +204,11 @@ __eq__

 Сравнивает две коллекции введённых флагов на равенство.

-:param other: Объект для сравнения
-:return: ``True``, если коллекции равны, иначе ``False``
-:raises NotImplementedError: Если ``other`` не является экземпляром ``InputFlags``
+:param other: Объект для сравнения.
+:return: `True`, если коллекции равны, иначе `False`.
+:raises NotImplementedError: Если `other` не является экземпляром `InputFlags`.

-Две коллекции считаются равными, если они содержат одинаковое количество флагов и все соответствующие флаги равны (сравнение происходит по правилам ``InputFlag.__eq__``, то есть по имени).
+Две коллекции считаются равными, если они содержат одинаковое количество флагов и все соответствующие флаги равны (сравнение по имени, см. `InputFlag.__eq__`).

 **Пример использования:**

@@ -225,13 +226,13 @@ __contains__

   __contains__(self, ingressable_item: object) -> bool

-Проверяет, содержится ли указанный введённый флаг в коллекции.
+Проверяет, содержится ли введённый флаг в коллекции.

-:param ingressable_item: Объект ``InputFlag`` для проверки
-:return: ``True``, если флаг найден в коллекции, иначе ``False``
-:raises TypeError: Если ``ingressable_item`` не является экземпляром ``InputFlag``
+:param ingressable_item: Объект `InputFlag` для проверки.
+:return: `True`, если флаг найден, иначе `False`.
+:raises TypeError: Если `ingressable_item` не является экземпляром `InputFlag`.

-Позволяет использовать оператор ``in`` для проверки наличия флага в коллекции.
+Позволяет использовать оператор `in` для проверки наличия флага в коллекции.

 **Пример использования:**

@@ -247,7 +248,7 @@ __contains__
 Обработка всех флагов с проверкой статусов
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-Пример демонстрирует, как итерироваться по всем введённым флагам и проверять их статусы валидации:
+Пример демонстрирует итерацию по всем введённым флагам с проверкой их статусов валидации:

 .. literalinclude:: ../../../code_snippets/input_flags/snippet10.py
   :linenos:
@@ -4,18 +4,18 @@
 PossibleValues
 ==============

-Enum ``PossibleValues`` представляет собой перечисление, определяющее специальные режимы валидации значений флагов в приложении ``Argenta``. Его основная задача — предоставить стандартизированные константы для управления поведением флагов в отношении допустимых значений. ``PossibleValues`` используется в параметре ``possible_values`` класса ``Flag`` для определения того, может ли флаг принимать значения и какие ограничения на них накладываются.
+`PossibleValues` — это перечисление (`Enum`), которое определяет специальные режимы валидации для значений флагов. Его задача — предоставить стандартные константы для управления поведением флагов. `PossibleValues` используется в параметре `possible_values` класса `Flag`, чтобы указать, может ли флаг принимать значения и какие ограничения на них накладываются.

-``PossibleValues`` наследуется от стандартного класса ``Enum`` и содержит два основных значения: ``NEITHER`` для флагов без значений и ``ALL`` для флагов, принимающих любые значения. Этот enum используется совместно со списками строк и регулярными выражениями для создания гибкой системы валидации флагов.
+`PossibleValues` наследуется от `Enum` и содержит два основных значения: `NEITHER` (для флагов без значений) и `ALL` (для флагов, принимающих любые значения). Это перечисление используется вместе со списками строк и регулярными выражениями для создания гибкой системы валидации.

 .. note::
-   Результат валидации значений введенных флагов можно получить через атрибут ``status`` у экземпляра ``InputFlag``. Подробнее :ref:`тут <root_api_command_input_flag>`
+   Результат валидации доступен через атрибут `status` у экземпляра `InputFlag`. Подробнее см. :ref:`здесь <root_api_command_input_flag>`.

 .. seealso::

-   Документация по :ref:`Flag <root_api_command_flag>` — сущности флага, использующей ``PossibleValues``
+   Документация по :ref:`Flag <root_api_command_flag>` — класс флага, использующий `PossibleValues`.
   
-   Документация по :ref:`PredefinedFlags <root_api_command_flag_predefined_flags>` — предопределенным флагам с примерами использования ``PossibleValues``
+   Документация по :ref:`PredefinedFlags <root_api_command_flag_predefined_flags>` — готовые флаги с примерами использования `PossibleValues`.
   
   :ref:`Общая информация <root_flags>` о флагах и их использовании в приложении ``Argenta``

@@ -34,7 +34,7 @@ NEITHER

 Указывает, что флаг **не должен** иметь значения.

-Флаги с этим значением работают как булевы переключатели — их наличие в командной строке само по себе является информацией. Попытка передать значение такому флагу приведёт к ошибке валидации.
+Флаги с этим значением работают как булевы переключатели: их наличие в командной строке само по себе является информацией. Попытка передать такому флагу значение приведёт к ошибке валидации.

 **Примеры флагов с** ``NEITHER``:

@@ -59,9 +59,9 @@ ALL

   PossibleValues.ALL = 'ALL'

-Указывает, что флаг может принимать **любое** значение без ограничений.
+Указывает, что флаг может принимать **любое** значение.

-Флаги с этим значением являются универсальными и не накладывают никаких ограничений на передаваемые данные. Валидация всегда успешна для любой строки или её отсутствия.
+Флаги с этим значением универсальны и не накладывают ограничений на передаваемые данные. Валидация всегда будет успешной.

 **Примеры флагов с** ``ALL``:

@@ -84,14 +84,14 @@ ALL
 Параметр 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]`: флаг со значением, проверяемым по регулярному выражению.

 **Пример комбинированного использования:**

@@ -104,7 +104,7 @@ ALL
 Использование в PredefinedFlags
 -------------------------------

-Многие предопределенные флаги используют ``PossibleValues.NEITHER``:
+Многие предопределённые флаги используют `PossibleValues.NEITHER`:

 .. literalinclude:: ../../../code_snippets/possible_values/predefined.py
   :linenos:
@@ -3,21 +3,21 @@
 ValidationStatus
 ================

-Enum ``ValidationStatus`` представляет собой перечисление, определяющее состояние валидации значений флагов в приложении ``Argenta``. Его основная задача — предоставить стандартизированные константы для отображения результата проверки введённых пользователем флагов и их значений. ``ValidationStatus`` используется в атрибуте ``status`` класса ``InputFlag`` для информирования о том, прошёл ли флаг валидацию успешно.
+`ValidationStatus` — это перечисление (`Enum`), которое определяет состояние валидации флага. Его задача — предоставить стандартные константы для отображения результата проверки. `ValidationStatus` используется в атрибуте `status` класса `InputFlag`, чтобы сообщить, прошла ли валидация успешно.

-``ValidationStatus`` наследуется от стандартного класса ``Enum`` и содержит три основных значения: ``VALID`` для корректных флагов, ``INVALID`` для некорректных флагов и ``UNDEFINED`` для незарегистрированных флагов.
+`ValidationStatus` наследуется от `Enum` и содержит три значения: `VALID` (корректный флаг), `INVALID` (некорректный) и `UNDEFINED` (незарегистрированный).

 .. note::

-   Статус валидации устанавливается автоматически при создании экземпляра ``InputFlag`` на основе проверки через соответствующий ``Flag``.
+   Статус валидации устанавливается автоматически при создании экземпляра `InputFlag` на основе правил, заданных в соответствующем `Flag`.

 .. seealso::

-   Документация по :ref:`InputFlag <root_api_command_input_flag>` — сущности входного флага, использующей ``ValidationStatus``
+   Документация по :ref:`InputFlag <root_api_command_input_flag>` — класс введённого флага, использующий `ValidationStatus`.
   
-   Документация по :ref:`Flag <root_api_command_flag>` — сущности флага с методом валидации
+   Документация по :ref:`Flag <root_api_command_flag>` — класс флага с правилами валидации.
   
-   Документация по :ref:`PossibleValues <root_api_command_possible_values>` — типам допустимых значений флагов
+   Документация по :ref:`PossibleValues <root_api_command_possible_values>` — типы допустимых значений.

 -----

@@ -32,16 +32,16 @@ VALID

   ValidationStatus.VALID = 'VALID'

-Указывает, что флаг и его значение **прошли** валидацию успешно.
+Указывает, что флаг и его значение **прошли** валидацию.

-Флаги с этим статусом полностью соответствуют правилам, заданным в параметре ``possible_values`` соответствующего ``Flag``. Такие флаги могут быть безопасно использованы в логике приложения без дополнительных проверок.
+Флаги с этим статусом соответствуют правилам, заданным в `possible_values` соответствующего `Flag`. Их можно безопасно использовать в логике приложения без дополнительных проверок.

 **Условия получения статуса** ``VALID``:

-* Флаг с ``PossibleValues.NEITHER`` передан без значения
-* Флаг с ``PossibleValues.ALL`` передан с любым значением или без него
-* Флаг со списком значений передан с одним из допустимых значений
-* Флаг с регулярным выражением передан со значением, соответствующим паттерну
+*   Флаг с `PossibleValues.NEITHER` передан без значения.
+*   Флаг с `PossibleValues.ALL` передан с любым значением или без него.
+*   Значение флага входит в список разрешённых.
+*   Значение флага соответствует регулярному выражению.

 **Пример использования:**

@@ -61,14 +61,14 @@ INVALID

 Указывает, что флаг или его значение **не прошли** валидацию.

-Флаги с этим статусом нарушают правила, установленные в ``possible_values`` соответствующего ``Flag``. Такие флаги должны быть обработаны как ошибочные, и их использование может привести к некорректной работе приложения.
+Флаги с этим статусом нарушают правила, заданные в `possible_values` соответствующего `Flag`. Их следует обрабатывать как ошибочные.

 **Условия получения статуса** ``INVALID``:

-* Флаг с ``PossibleValues.NEITHER`` передан со значением
-* Флаг со списком значений передан с недопустимым значением
-* Флаг с регулярным выражением передан со значением, не соответствующим паттерну
-* Флаг требует значение, но передан без него (для определённых типов валидации)
+*   Флаг с `PossibleValues.NEITHER` передан со значением.
+*   Значение флага не входит в список разрешённых.
+*   Значение флага не соответствует регулярному выражению.
+*   Флаг требует значение, но передан без него.

 **Пример использования:**

@@ -86,11 +86,11 @@ UNDEFINED

   ValidationStatus.UNDEFINED = 'UNDEFINED'

-Указывает, что флаг был введён, но не зарегистрирован.
+Указывает, что введённый флаг не был зарегистрирован в команде.

 **Условия получения статуса** ``UNDEFINED``:

-* Флаг был введён с любым значением, но не зарегистрирован
+*   Введённый флаг не найден среди зарегистрированных для данной команды.

 -----

@@ -101,7 +101,7 @@ UNDEFINED
 Комплексный пример валидации
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-Пример демонстрирует использование всех статусов в реальном сценарии:
+Пример демонстрирует использование всех статусов в реальном сценарии.

 .. literalinclude:: ../../../code_snippets/validation_status/comprehensive.py
   :linenos:
@@ -7,14 +7,14 @@
 Описание раздела
 ----------------

-В данном разделе приводятся сведения о публичной части интерфейса библиотеки:
+В этом разделе описан публичный API библиотеки. Он включает:

- Классы и функции, предназначенные для прямой интеграции в сторонние приложения.
- Советы по совместимости, ограничения и поддерживаемые сценарии использования.
- Примеры типовой интеграции, подробные сигнатуры методов и описание возвращаемых сущностей.
- Гарантии стабильности API, поддержка и обратная совместимость между версиями.
+- Классы и функции для интеграции в ваши приложения.
+- Рекомендации по использованию и поддерживаемые сценарии.
+- Примеры кода, подробные сигнатуры и описание возвращаемых значений.
+- Гарантии стабильности и обратной совместимости.

-Интерфейсы, не указанные в этом разделе, считаются внутренними и не подлежат использованию вне самой библиотеки. При разработке собственных решений рекомендуем обращаться именно к описанным здесь компонентам — это даст стабильность и гарантии на будущее развитие ваших продуктов с использованием ``Argenta``.
+Интерфейсы, не описанные в этом разделе, считаются внутренними. Их использование может привести к ошибкам при обновлении библиотеки. При разработке собственных решений используйте только компоненты, описанные здесь. Это обеспечит стабильность и совместимость ваших продуктов с будущими версиями ``Argenta``.


 .. toctree::
@@ -3,7 +3,7 @@
 ArgParser
 ==========

-Объект ``ArgParser`` в ``Argenta`` предназначен для разбора и обработки **аргументов командной строки**, которые передаются вашему приложению при его запуске. Важно не путать их с флагами команд, которые пользователь вводит в интерактивном режиме работы приложения. ``ArgParser`` позволяет вашему приложению получать внешнюю конфигурацию в момент старта, например, путь к файлу настроек, флаги для отладки или режим запуска.
+``ArgParser`` предназначен для обработки **аргументов командной строки**, передаваемых приложению при запуске. Важно не путать их с флагами, которые пользователь вводит в интерактивном режиме. ``ArgParser`` позволяет получать внешнюю конфигурацию в момент старта (например, путь к файлу настроек, флаги отладки или режим запуска).

 -----

@@ -18,31 +18,31 @@ ArgParser
 	           description: str = "Argenta available arguments",
 	           epilog: str = "github.com/koloideal/Argenta | made by kolo")

-Создает экземпляр парсера аргументов командной строки.
+Создаёт экземпляр парсера аргументов командной строки.

-* ``processed_args``: Список аргументов, которые будут обрабатываться и парситься при запуске приложения, подробнее :ref:`тут <root_api_orchestrator_arguments>`.
-* ``name``: Имя приложения, которое будет отображаться в справке.
-* ``description``: Описание приложения, которое будет отображаться в справке.
-* ``epilog``: Дополнительная информация, которая будет отображаться в конце справки.
+* ``processed_args``: Список аргументов для обработки при запуске приложения. Подробнее см. :ref:`здесь <root_api_orchestrator_arguments>`.
+* ``name``: Имя приложения для отображения в справке.
+* ``description``: Описание приложения для отображения в справке.
+* ``epilog``: Дополнительная информация для отображения в конце справки.

 Основные методы и атрибуты
 ---------------------------

 .. py:attribute:: parsed_argspace: ArgSpace

-   Экземпляр класса ``ArgSpace``, который содержит все обработанные аргументы командной строки, подробнее :ref:`тут <root_api_orchestrator_argspace>`.
+   Экземпляр ``ArgSpace``, содержащий все обработанные аргументы командной строки. Подробнее см. :ref:`здесь <root_api_orchestrator_argspace>`.

 .. caution::
-   До инициализации инстанса ``Orchestrator``, которому в конструктор был передан соответствующий экземпляр ``ArgParser``, атрибут ``parsed_argspace`` будет равен пустому ``ArgSpace``.
+   До инициализации ``Orchestrator``, в конструктор которого был передан экземпляр ``ArgParser``, атрибут ``parsed_argspace`` будет содержать пустой ``ArgSpace``.
   
-   Парсинг и валидация аргументов командной строки происходит при инициализации ``Orchestrator``, соответственно использование атрибута ``parsed_argspace`` **целесообразно только после инициализации** ``Orchestrator``.
+   Парсинг и валидация аргументов происходят при инициализации ``Orchestrator``, поэтому использовать ``parsed_argspace`` **целесообразно только после** этого.

 -----
   
 Лучшие практики
 ------------------------

-Использование атрибута ``parsed_argspace`` рекомендуется только на этапе настройки приложения, в хэндлерах лучшей практикой является получение ``ArgSpace`` через ``di``,  подробнее :ref:`тут <root_dependency_injection>`.
+Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.

 Пример использования
 --------------------
@@ -3,9 +3,9 @@
 ArgSpace
 ==========

-Объект ``ArgSpace`` является контейнером для хранения и управления распаршенными аргументами командной строки в приложении ``Argenta``. Его основная задача — предоставить удобный интерфейс для доступа к значениям аргументов, переданных при запуске приложения.
+``ArgSpace`` — это контейнер для хранения и управления обработанными аргументами командной строки. Его основная задача — предоставить удобный интерфейс для доступа к значениям, переданным при запуске приложения.

-``ArgSpace`` автоматически создается после парсинга аргументов через ``ArgParser`` и содержит коллекцию объектов ``InputArgument``, представляющих собой финальные значения всех переданных параметров командной строки.
+``ArgSpace`` создаётся автоматически после обработки аргументов с помощью `ArgParser` и содержит коллекцию объектов `InputArgument`.

 -----

@@ -17,15 +17,15 @@ ArgSpace

   __init__(self, all_arguments: list[InputArgument]) -> None

-Создает новое пространство аргументов.
+Создаёт новое пространство аргументов.

-* ``all_arguments`` : Список распаршенных аргументов в виде объектов ``InputArgument``. Каждый элемент содержит имя, значение и тип исходного аргумента.
+* ``all_arguments``: Список обработанных аргументов в виде объектов `InputArgument`. Каждый элемент содержит имя, значение и тип исходного аргумента.

 **Атрибуты:**

 .. py:attribute:: all_arguments

-   Список всех распаршенных аргументов типа ``InputArgument``. Содержит все аргументы, переданные при запуске приложения, включая значения по умолчанию для не указанных параметров.
+   Список всех обработанных аргументов типа `InputArgument`, включая значения по умолчанию для не указанных параметров.

 -----

@@ -40,12 +40,12 @@ get_by_name

   get_by_name(self, name: str) -> InputArgument | None

-Возвращает аргумент по его имени.
+Возвращает аргумент по имени.

-:param name: Имя искомого аргумента
-:return: Объект ``InputArgument`` с указанным именем или ``None``, если аргумент не найден
+:param name: Имя искомого аргумента.
+:return: Объект `InputArgument` или `None`, если аргумент не найден.

-Метод выполняет линейный поиск по списку ``all_arguments`` и возвращает аргумент с соответствующим именем. Если аргумент не найден, возвращается ``None``.
+Метод выполняет линейный поиск по списку `all_arguments`. Если аргумент не найден, возвращается `None`.

 **Пример использования:**

@@ -76,12 +76,12 @@ get_by_type

   get_by_type(self, arg_type: type[BaseArgument]) -> list[InputArgument] | list[Never]

-Получает все аргументы определенного типа.
+Возвращает все аргументы определённого типа.

-:param arg_type: Тип аргумента (``BooleanArgument`` или ``ValueArgument``)
-:return: Список аргументов указанного типа или пустой список, если аргументы не найдены
+:param arg_type: Тип аргумента (`BooleanArgument` или `ValueArgument`).
+:return: Список аргументов указанного типа или пустой список.

-Метод фильтрует ``all_arguments`` по атрибуту ``founder_class`` каждого ``InputArgument`` и возвращает только те аргументы, которые были созданы из указанного типа.
+Метод фильтрует `all_arguments` по атрибуту `founder_class` и возвращает аргументы, созданные из указанного типа.

 **Пример использования:**

@@ -94,21 +94,21 @@ InputArgument
 -------------

 .. seealso ::
-   Документация по ``InputArgument`` находится :ref:`тут <root_api_orchestrator_arguments_inputargument>`
+   Документация по ``InputArgument`` находится :ref:`здесь <root_api_orchestrator_arguments_inputargument>`.

 -----

 Примеры испольования
 --------------------

-``ArgSpace`` используется для доступа к значениям аргументов после запуска приложения. Типичный сценарий работы включает парсинг аргументов через ``ArgParser`` и последующее извлечение значений из ``ArgSpace``.
+`ArgSpace` используется для доступа к значениям аргументов после запуска приложения. Типичный сценарий включает обработку аргументов через `ArgParser` и последующее извлечение значений из `ArgSpace`.

 **Полный пример:**

 .. literalinclude:: ../../../code_snippets/argspace/snippet.py
   :linenos:
   
-Доступ к аргументам из хэндлеров осуществляется с помощью ``di``, подробнее :ref:`тут <root_dependency_injection>`.
+Доступ к аргументам из обработчиков осуществляется с помощью DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.

 .. literalinclude:: ../../../code_snippets/argspace/snippet2.py
   :linenos:
@@ -3,16 +3,16 @@
 Arguments
 =========

-Модуль ``Arguments`` предоставляет набор классов для работы с аргументами командной строки при запуске приложения ``Argenta``. Эти аргументы позволяют настраивать поведение приложения на этапе его старта, передавая различные параметры конфигурации через интерфейс командной строки.
+Модуль ``Arguments`` предоставляет классы для работы с аргументами командной строки. Они позволяют настраивать поведение приложения в момент его запуска, передавая различные параметры конфигурации.

-Аргументы регистрируются в ``ArgParser`` и парсятся при запуске приложения, становясь доступными через объект ``ArgSpace``.
+Аргументы регистрируются в `ArgParser` и после обработки становятся доступными в объекте `ArgSpace`.

 -----

 ValueArgument
 -------------

-Класс для аргументов командной строки, требующих передачи значения. Используется для параметров конфигурации, которым необходимо указать конкретное значение при запуске приложения.
+Класс для аргументов, требующих передачи значения. Используется для параметров конфигурации, которым необходимо указать значение при запуске.

 .. py:class:: ValueArgument(BaseArgument)

@@ -27,15 +27,15 @@ ValueArgument
            is_required: bool = False,
            is_deprecated: bool = False) -> None

-Создает аргумент командной строки, требующий значения.
+Создаёт аргумент командной строки, требующий значения.

 :param name: Имя аргумента
-:param prefix: Префикс аргумента, по умолчанию ``--``
-:param help: Сообщение справки, отображаемое при ``--help``
-:param possible_values: Список допустимых значений для аргумента. Передается в параметр ``choices`` ArgumentParser
-:param default: Значение по умолчанию, используемое если аргумент не передан при запуске
-:param is_required: Обязатялен ли аргумент. Если ``True``, приложение не запустится без этого аргумента
-:param is_deprecated: Является ли аргумент устаревшим
+:param prefix: Префикс (по умолчанию ``--``)
+:param help: Сообщение для справки (``--help``)
+:param possible_values: Список допустимых значений (передаётся в `choices` `ArgumentParser`)
+:param default: Значение по умолчанию, если аргумент не передан
+:param is_required: Если ``True``, аргумент становится обязательным
+:param is_deprecated: Если ``True``, помечает аргумент как устаревший

 **Пример использования:**

@@ -83,7 +83,7 @@ ValueArgument
 BooleanArgument
 ---------------

-Класс для булевых аргументов командной строки, которые не требуют передачи значения. Наличие или отсутствие аргумента при запуске определяет состояние распаршенных аргументов(``True`` при наличии и ``False`` при отсутствии).
+Класс для булевых аргументов, не требующих значения. Их наличие при запуске устанавливает значение в `True`, отсутствие — в `False`.

 .. py:class:: BooleanArgument(BaseArgument)

@@ -95,12 +95,12 @@ BooleanArgument
            help: str = "Help message for the boolean argument",
            is_deprecated: bool = False) -> None

-Создает булевый аргумент командной строки без значения.
+Создаёт булев аргумент командной строки без значения.

 :param name: Имя аргумента
-:param prefix: Префикс аргумента, по умолчанию ``--``
-:param help: Сообщение справки, отображаемое при ``--help``
-:param is_deprecated: Является ли аргумент устаревшим
+:param prefix: Префикс (по умолчанию ``--``)
+:param help: Сообщение для справки (``--help``)
+:param is_deprecated: Если ``True``, помечает аргумент как устаревший

 **Пример использования:**

@@ -147,9 +147,9 @@ InputArgument
 -------------

 .. seealso::
-   ``InputArgument`` непосредственно связан и является наполнителем контейнера ``ArgSpace``, подробнее про него :ref:`тут <root_api_orchestrator_argspace>`.
+   ``InputArgument`` напрямую связан с контейнером ``ArgSpace`` и является его наполнителем. Подробнее о нём см. :ref:`здесь <root_api_orchestrator_argspace>`.

-Представляет собой распаршенный аргумент командной строки после запуска приложения. Этот класс используется внутри объекта ``ArgSpace`` для хранения значений аргументов, полученных при парсинге.
+Представляет собой обработанный аргумент командной строки. Этот класс используется внутри `ArgSpace` для хранения значений, полученных после парсинга.

 .. py:class:: InputArgument

@@ -160,35 +160,35 @@ InputArgument
            value: str | Literal[True],
            founder_class: type[BaseArgument]) -> None

-Создает экземпляр распарсенного входного аргумента.
+Создаёт экземпляр обработанного входного аргумента.

 :param name: Имя аргумента
-:param value: Значение аргумента. Для ``BooleanArgument`` всегда ``True`` если флаг передан, для ``ValueArgument`` — строка со значением
-:param founder_class: Класс-родитель, из которого был создан этот аргумент (``BooleanArgument`` или ``ValueArgument``)
+:param value: Значение аргумента. Для `BooleanArgument` — `True`, если флаг передан; для `ValueArgument` — строка со значением
+:param founder_class: Класс-родитель, из которого был создан аргумент (`BooleanArgument` или `ValueArgument`)

 **Атрибуты:**

 .. py:attribute:: name
   :no-index:

-   Имя аргумента в виде строки. Соответствует имени, указанному при создании ``ValueArgument`` или ``BooleanArgument``.
+   Имя аргумента, указанное при создании `ValueArgument` или `BooleanArgument`.

 .. py:attribute:: value

-   Значение аргумента. Тип значения зависит от исходного класса аргумента:
-   
-   * Для ``BooleanArgument``: ``True`` если флаг был передан при запуске
-   * Для ``ValueArgument``: строка с переданным значением или значением по умолчанию
+   Значение аргумента. Тип зависит от исходного класса:
+
+* Для `BooleanArgument`: `True`, если флаг был передан.
+* Для `ValueArgument`: строка с переданным значением или значением по умолчанию

 .. py:attribute:: founder_class

-   Ссылка на класс, из которого был создан этот аргумент. Используется для определения типа аргумента и фильтрации в методе ``get_by_type()``.
+   Ссылка на класс-родитель. Используется для определения типа и фильтрации в методе `get_by_type()`.

 **Методы:**

 .. py:method:: __str__() -> str

-   Возвращает строковое представление аргумента в формате ``InputArgument(name=value)``.
+   Возвращает строковое представление в формате `InputArgument(name=value)`.

   .. code-block:: python
      :linenos:
@@ -198,4 +198,4 @@ InputArgument

 .. py:method:: __repr__() -> str

-   Возвращает техническое представление объекта в виде строки.
+   Возвращает техническое представление объекта.
@@ -3,16 +3,16 @@
 Orchestrator
 ====================

-Объект ``Orchestrator`` в ``Argenta`` представляет собой высокоуровневый компонент, который стоит над ``App`` и отвечает за "оркестрацию" всего приложения. Его главная задача — инициализация и конфигурация сложных систем, таких как внедрение зависимостей (``di``), парсинг аргументов командной строки при запуске, и запуск основного цикла приложения.
+``Orchestrator`` — это высокоуровневый компонент, который управляет жизненным циклом приложения. Его главная задача — инициализация и конфигурация окружения, включая внедрение зависимостей (DI), парсинг аргументов командной строки и запуск основного цикла `App`.

-В то время как ``App`` отвечает за интерактивную сессию (ввод команд, роутинг), ``Orchestrator`` подготавливает окружение, в котором ``App`` будет работать. Он является точкой входа для приложений.
+В то время как `App` отвечает за логику интерактивной сессии (ввод команд, маршрутизация), `Orchestrator` подготавливает окружение для его работы и служит точкой входа в приложение.

 -----

 Инициализация
 -------------

-.. code-block:: rust
+.. code-block:: python
   :linenos:

   DEFAULT_ARGPARSER: ArgParser = ArgParser(processed_args=[])
@@ -25,11 +25,11 @@ Orchestrator
                   custom_providers: list[Provider] = [], 
                   auto_inject_handlers: bool = True) -> None

-Создает и конфигурирует экземпляр ``Orchestrator``.
+Создаёт и конфигурирует экземпляр ``Orchestrator``.

-* ``arg_parser``: Экземпляр :class:`argenta.orchestrator.argparser.ArgParser`, который отвечает за парсинг аргументов, переданных скрипту при запуске из командной строки (не путать с командами, вводимыми в интерактивном режиме).
-* ``custom_providers``: Список пользовательских провайдеров ``dishka.Provider``. Это основной механизм для добавления ваших собственных сервисов (например, подключений к базе данных, клиентов API) в контейнер внедрения зависимостей.
-* ``auto_inject_handlers``: Если **True** (по умолчанию), ``dishka`` будет автоматически инспектировать сигнатуры обработчиков команд и внедрять в них требуемые зависимости из контейнера.
+* ``arg_parser``: Экземпляр `ArgParser`, отвечающий за парсинг аргументов командной строки при запуске скрипта (не путать с командами в интерактивном режиме).
+* ``custom_providers``: Список пользовательских провайдеров `dishka.Provider` для добавления ваших сервисов (например, подключений к БД или API-клиентов) в DI-контейнер.
+* ``auto_inject_handlers``: Если `True` (по умолчанию), `dishka` автоматически внедрит зависимости в обработчики команд, инспектируя их сигнатуры.

 -----

@@ -38,26 +38,25 @@ Orchestrator

 .. py:method:: start_polling(self, app: App) -> None

-   Это главный метод, который запускает все приложение. Он выполняет следующие шаги:
+   Это главный метод, который запускает приложение. Он выполняет следующие шаги:

-   1.  **Настройка DI**: На основе системного провайдера (``SystemProvider``, который предоставляет ``ArgParser``) и списка ``custom_providers`` создается ``ioc`` - контейнер и настраивается внедрение зависимостей.
-   
-   3.  **Запуск основного цикла**: Запускает бесконечный цикл ожидания и обработки пользовательского ввода.
+   1.  **Настройка DI**: Создаёт DI-контейнер на основе системного провайдера (предоставляет `ArgParser`) и пользовательских `custom_providers`.
+   2.  **Запуск основного цикла**: Запускает бесконечный цикл ожидания и обработки пользовательского ввода.

-   :param app: Экземпляр класса :class:`~argenta.app.models.App`, который будет запущен.
+   :param app: Экземпляр `App`, который будет запущен.

 -----
   
 Назначение и использование
 ----------------------------

-``Orchestrator`` абстрагирует от вас всю сложность, связанную с настройкой внедрения зависимостей и парсингом стартовых аргументов. Типичный сценарий использования ``Argenta`` выглядит следующим образом:
+``Orchestrator`` абстрагирует сложность, связанную с настройкой DI и парсингом стартовых аргументов. Типичный сценарий использования выглядит так:

-1.  Создать экземпляр ``App`` и настроить его (добавить роутеры).
-2.  Создать экземпляр ``Orchestrator``, передав в него необходимые DI-провайдеры и, возможно, парсер аргументов.
-3.  Вызвать ``orchestrator.start_polling(app)``, чтобы запустить приложение.
+1.  Создайте и настройте экземпляр `App` (добавьте роутеры).
+2.  Создайте экземпляр `Orchestrator`, передав в него DI-провайдеры.
+3.  Вызовите `orchestrator.start_polling(app)`, чтобы запустить приложение.

-Такой подход позволяет сохранить код чистым и разделяет ответственность: ``App`` отвечает за логику интерактивной сессии, а ``Orchestrator`` — за подготовку и запуск окружения.
+Такой подход разделяет ответственности: `App` отвечает за логику интерактивной сессии, а `Orchestrator` — за подготовку и запуск окружения.

 Пример использования
 --------------------
@@ -3,9 +3,9 @@
 Response
 ========

-Объект ``Response`` представляет собой сущность ответа пользовательского ввода, передаваемого в обработчик команды. Он создаётся автоматически при парсинге пользовательского ввода и содержит информацию о статусе валидации флагов, введённые флаги, а также предоставляет механизм для передачи данных между обработчиками команд через глобальное хранилище данных.
+`Response` — это объект, который передаётся в обработчик команды. Он создаётся автоматически при обработке пользовательского ввода и содержит статус валидации, введённые флаги, а также предоставляет механизм для обмена данными между обработчиками.

-``Response`` наследуется от ``DataBridge``, который предоставляет методы для работы с глобальным хранилищем данных, позволяющим обмениваться данными между различными обработчиками команд в контексте приложения.
+`Response` наследует от `DataBridge` методы для работы с глобальным хранилищем, что позволяет обмениваться данными между обработчиками в рамках одной сессии.

 .. seealso::

@@ -29,23 +29,25 @@ Response
       input_flags: InputFlags = EMPTY_INPUT_FLAGS,
   )

-Создаёт новый объект ответа на пользовательский ввод.
+Создаёт новый объект ответа.

-* ``status`` : Статус валидации флагов команды из перечисления ``ResponseStatus``
-* ``input_flags`` : Коллекция введённых флагов команды. По умолчанию используется пустая коллекция ``EMPTY_INPUT_FLAGS``
+* ``status``: Общий статус валидации флагов из перечисления `ResponseStatus`.
+* ``input_flags``: Коллекция введённых флагов (`InputFlags`). По умолчанию — пустая.

 .. warning ::
-   Экземпляры класса не предназначены для их прямого создания. Они автоматически создаются системой при обработке пользовательского ввода и передаются в обработчики команд в качестве обязательного первого аргумента.
+   Экземпляры этого класса не предназначены для прямого создания. Они автоматически формируются системой и передаются в обработчик команды в качестве первого обязательного аргумента.

 **Атрибуты:**

 .. py:attribute:: status
+   :no-index:

-   Статус валидации всех флагов команды типа ``ResponseStatus``. Указывает, были ли среди введённых флагов невалидные или незарегистрированные.
+   Общий статус валидации всех флагов команды (`ResponseStatus`). Указывает, были ли среди введённых флагов некорректные или незарегистрированные.

 .. py:attribute:: input_flags
+   :no-index:

-   Коллекция всех флагов, переданных с командой, типа ``InputFlags``. Содержит все распарсенные флаги команды с их значениями и статусами валидации.
+   Коллекция всех флагов, переданных с командой (`InputFlags`). Содержит все обработанные флаги с их значениями и статусами валидации.

 **Пример использования:**

@@ -57,7 +59,7 @@ Response

 Методы DataBridge

-``Response`` наследует от ``DataBridge`` методы для работы с глобальным хранилищем данных, которое позволяет передавать информацию между различными обработчиками команд в рамках одного сеанса работы приложения.
+`Response` наследует от `DataBridge` методы для работы с глобальным хранилищем, которое позволяет обмениваться данными между обработчиками в рамках одной сессии.

 update_data
 ~~~~~~~~~~~
@@ -68,12 +70,12 @@ update_data
   @classmethod
   update_data(cls, data: dict[str, Any]) -> None

-Обновляет глобальное хранилище данных, добавляя или обновляя значения из переданного словаря.
+Обновляет глобальное хранилище, добавляя или изменяя значения из переданного словаря.

 :param data: Словарь с данными для обновления хранилища
 :return: None

-Метод объединяет переданные данные с существующими данными в хранилище. Если ключ уже существует, его значение будет обновлено.
+Метод объединяет переданный словарь с данными в хранилище. Если ключ уже существует, его значение обновляется.

 **Пример использования:**

@@ -92,7 +94,7 @@ get_data
   @classmethod
   get_data(cls) -> dict[str, Any]

-Получает все данные из глобального хранилища.
+Возвращает все данные из глобального хранилища.

 :return: Словарь со всеми данными из хранилища

@@ -113,7 +115,7 @@ clear_data
   @classmethod
   clear_data(cls) -> None

-Очищает все данные из глобального хранилища.
+Очищает глобальное хранилище.

 :return: None

@@ -134,11 +136,11 @@ delete_from_data
   @classmethod
   delete_from_data(cls, key: str) -> None

-Удаляет конкретный ключ и его значение из глобального хранилища данных.
+Удаляет ключ и его значение из глобального хранилища.

 :param key: Ключ, который необходимо удалить из хранилища
 :return: None
-:raises KeyError: Если указанный ключ не существует в хранилище
+:raises KeyError: Если ключ не найден в хранилище.

 **Пример использования:**

@@ -151,7 +153,7 @@ delete_from_data
 Работа с флагами
 ----------------

-``Response`` предоставляет доступ к введённым флагам команды через атрибут ``input_flags``. Вы можете проверять наличие флагов, получать их значения и статусы валидации.
+`Response` предоставляет доступ к введённым флагам через атрибут `input_flags`. Вы можете проверять их наличие, получать значения и статусы валидации.

 **Пример работы с флагами:**

@@ -166,7 +168,7 @@ delete_from_data
 ResponseStatus
 --------------

-Enum ``ResponseStatus`` представляет собой перечисление, определяющее общий статус валидации всех флагов команды. Используется в атрибуте ``status`` объекта ``Response`` для информирования о результате проверки всех введённых флагов.
+`ResponseStatus` — это перечисление (`Enum`), которое определяет общий статус валидации всех флагов команды. Используется в атрибуте `status` объекта `Response`.

 Значения enum
 ~~~~~~~~~~~~~
@@ -179,7 +181,7 @@ ALL_FLAGS_VALID

   ResponseStatus.ALL_FLAGS_VALID = 'ALL_FLAGS_VALID'

-Указывает, что все введённые флаги команды прошли валидацию успешно. Нет ни невалидных, ни незарегистрированных флагов.
+Все введённые флаги прошли валидацию. Нет ни некорректных, ни незарегистрированных флагов.

 UNDEFINED_FLAGS
 ~~~~~~~~~~~~~~~
@@ -189,7 +191,7 @@ UNDEFINED_FLAGS

   ResponseStatus.UNDEFINED_FLAGS = 'UNDEFINED_FLAGS'

-Указывает, что среди введённых флагов присутствуют незарегистрированные флаги, но нет флагов с невалидными значениями.
+Среди введённых флагов есть незарегистрированные, но нет флагов с некорректными значениями.

 INVALID_VALUE_FLAGS
 ~~~~~~~~~~~~~~~~~~~
@@ -199,7 +201,7 @@ INVALID_VALUE_FLAGS

   ResponseStatus.INVALID_VALUE_FLAGS = 'INVALID_VALUE_FLAGS'

-Указывает, что среди введённых флагов присутствуют флаги с невалидными значениями, но нет незарегистрированных флагов.
+Среди введённых флагов есть флаги с некорректными значениями, но нет незарегистрированных.

 UNDEFINED_AND_INVALID_FLAGS
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -209,4 +211,4 @@ UNDEFINED_AND_INVALID_FLAGS

   ResponseStatus.UNDEFINED_AND_INVALID_FLAGS = 'UNDEFINED_AND_INVALID_FLAGS'

-Указывает, что среди введённых флагов одновременно присутствуют и незарегистрированные флаги, и флаги с невалидными значениями.
+Среди введённых флагов есть как незарегистрированные, так и флаги с некорректными значениями.
@@ -3,9 +3,9 @@
 Router
 =============

-Объект ``Router`` является фундаментальным строительным блоком для организации логики в приложении ``Argenta``. Его основная задача — группировать связанные команды и их обработчики. Каждый роутер представляет собой логический контейнер для определенного набора функциональности.
+``Router`` — это основной строительный блок для организации логики в приложении. Его задача — группировать связанные команды и их обработчики. Каждый роутер представляет собой логический контейнер для определённого набора функций.

-Например, в приложении для управления пользователями один роутер может отвечать за команды, связанные с аутентификацией (``login``, ``logout``), а другой — за операции с профилем (``profile show``, ``profile edit``).
+Например, в приложении для управления пользователями один роутер может отвечать за аутентификацию (``login``, ``logout``), а другой — за операции с профилем (``profile-show``, ``profile-edit``).

 -----

@@ -18,23 +18,23 @@ Router
      __init__(self, title: str | None = None, 
               disable_redirect_stdout: bool = False) -> None

-Создаёт новый экземпляр маршрутизатора.
+Создаёт новый экземпляр роутера.

-* ``title`` : Необязательный заголовок для группы команд, которые регистрируются в этом роутере. Этот заголовок будет отображаться в списке доступных команд, помогая пользователю ориентироваться.
-* ``disable_redirect_stdout`` : Если установлено в ``True``, отключает механизм перехвата стандартного вывода (``stdout``) для всех команд этого роутера. Это необходимо для команд, которые требуют интерактивного ввода от пользователя (например, с помощью ``input()``). При отключении перехвата вывода автоматически используется статическая разделительная линия. Подробнее в :ref:`соответствующем разделе <root_redirect_stdout>`
+* ``title``: Необязательный заголовок для группы команд. Отображается в списке доступных команд, помогая пользователю ориентироваться.
+* ``disable_redirect_stdout``: Если ``True``, отключает перехват ``stdout`` для всех команд этого роутера. Это необходимо для интерактивных команд (например, с ``input()``). При отключении перехвата автоматически используется статическая разделительная линия. Подробнее см. в разделе :ref:`Переопределение стандартного вывода <root_redirect_stdout>`.

 -----

 Регистрация команд
 ------------------

-Для регистрации новой команды и привязки к ней функции-обработчика используется декоратор ``@command``.
+Для регистрации команды и привязки к ней обработчика используется декоратор ``@command``.

 .. py:method:: @command(self, command: Command | str)

-   Декоратор для регистрации функции как обработчика для указанной команды.
+   Декоратор для регистрации функции как обработчика команды.

-   :param command: Экземпляр класса ``argenta.command.Command``, описывающий триггер, флаги и описание команды. Также может быть просто строкой, которая будет являться триггером, в этом случае нет возможности настроить флаги, описание и всё остальное.
+   :param command: Экземпляр ``Command``, описывающий триггер, флаги и описание команды. Может быть строкой, которая станет триггером (без возможности настройки флагов и описания).

   **Пример использования:**

@@ -51,27 +51,27 @@ Router

 .. py:data:: system_router

-   Предопределенный экземпляр ``Router``, который содержит базовые системные команды. По умолчанию в него включена команда выхода из приложения (обычно **exit**). Он имеет заголовок **"System points:"**, который можно переопределить в инстансе приложения -> ``App``.
+   Предопределённый экземпляр ``Router`` с базовыми системными командами (по умолчанию — команда выхода). Имеет заголовок **«System points:»**, который можно переопределить в ``App``.

-   Вы можете добавлять свои команды в этот роутер, для этого импортируйте ``argenta.router.defaults.system_router`` и декорируйте необходимые хэндлеры его методом.
+   Вы можете добавлять свои команды в этот роутер. Для этого импортируйте ``argenta.router.defaults.system_router`` и используйте его декоратор ``@command``.

 -----   
   
 Возможные исключения
 --------------------

-При регистрации команд и флагов в ``Router`` могут возникнуть следующие исключения, сигнализирующие о некорректной конфигурации:
+При регистрации команд и флагов в ``Router`` могут возникнуть следующие исключения:

 .. py:exception:: TriggerContainSpacesException

-   Выбрасывается, если триггер команды, передаваемый в ``Command``, содержит пробелы. Триггеры команд должны быть одним словом.
+   Выбрасывается, если триггер команды в ``Command`` содержит пробелы. Триггеры должны быть одним словом.

   **Неправильно:** ``Command("add user")``
   **Правильно:** ``Command("add-user")``

 .. py:exception:: RepeatedFlagNameException

-   Возникает, если при определении флагов для одной команды были использованы дублирующиеся имена (как короткие, так и длинные). Каждое имя флага в рамках одной команды должно быть уникальным.
+   Возникает, если при определении флагов для команды были использованы дублирующиеся имена. Имена флагов в рамках одной команды должны быть уникальны.

   **Пример, вызывающий исключение:**

@@ -85,5 +85,5 @@ Router

 .. py:exception:: RequiredArgumentNotPassedException

-   Это исключение возникает, если какой-либо обработчик команды не ожидает обязательный аргумент, которым является объект ответа(``Response``).
+   Возникает, если обработчик команды не принимает обязательный аргумент ``Response``.