docs

docs/root/error_handling.rst

@@ -6,15 +6,13 @@
 О разделе
 ------------
 
-``Argenta`` в рантайме вызывает исключения в пограничных случаях пользовательского ввода.
-Все исключения обрабатываются системными хэндлерами, но у вас есть возможность их переопределить. Переопределение осуществляется
-с помощью сеттеров инстанса ``App`` - ``.set_*_handler(_)``, где ``_`` - это протокол хэндлера нестандартного поведения, подробнее
-о каждом протоколе и соответствующем сеттере :ref:`ниже <possible_errors>`
+Argenta выбрасывает исключения в пограничных случаях, связанных с пользовательским вводом.
+По умолчанию они обрабатываются системными хэндлерами, но вы можете их переопределить. Это делается с помощью сеттеров экземпляра ``App`` вида ``.set_*_handler()``. Подробнее о каждом из них рассказано :ref:`ниже <possible_errors>`.
 
 .. note::
-    Все исключения никогда не остаются необработанными, так как у них есть стандартные хэндлеры. Поэтому переопределение опционально.
+    Ни одно исключение не остаётся необработанным, так как для каждого случая предусмотрен стандартный хэндлер. Поэтому переопределение является опциональным.
 
-Краткий пример кода, переопределяющего хэндлер ввода пустой команды:
+Пример переопределения обработчика для пустой команды:
 
 .. literalinclude:: ../code_snippets/error_handling/snippet.py
     :language: python
@@ -26,12 +24,10 @@
 Возможные исключения и нестандартное поведение
 ----------------------------------------------
 
-``UnprocessedInputFlagException``: Необрабатываемый ввод от пользователя
+``UnprocessedInputFlagException``: Некорректный синтаксис флагов
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Исключение вызывается, когда пользователь вводит команду с некорректным синтаксисом и, как следствие, парсер не может
-*распарсить* её. В большинстве случаев это означает, что проблема в синтаксисе введённых флагов команды, подробнее о
-флагах и их синтаксисе в :ref:`Flags <root_flags>`.
+Это исключение выбрасывается, когда парсер не может обработать команду из-за некорректного синтаксиса. Чаще всего это связано с ошибкой в синтаксисе флагов. Подробнее о них можно прочитать в разделе :ref:`Flags <root_flags>`.
 
 Стандартный хэндлер выводит в консоль
 
@@ -39,9 +35,7 @@
 
     Incorrect flag syntax: <raw input command>
 
-Для переопределения стандартного поведения используется сеттер ``.set_incorrect_input_syntax_handler(_: NonStandardBehaviorHandler[str])``,
-протокол ``NonStandardBehaviorHandler[str]`` соответствует ``Callable[[str], None]``, то есть хэндлер должен быть вызываемым объектом,
-к примеру функция или лямбда, которая принимает единственный аргумент - строку, которая представляет собой необработанную введённую команду, и ничего не возвращает.
+Для переопределения используется сеттер ``.set_incorrect_input_syntax_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[str], None]``, где единственный аргумент — это строка с необработанной командой.
 
 Пример кода, переопределяющего хэндлер ввода команды с некорректным синтаксисом:
 
@@ -51,11 +45,10 @@
 
 ---------------
 
-``RepeatedInputFlagsException``: Повторяющийся флаг в введённой команде
+``RepeatedInputFlagsException``: Повторяющиеся флаги в команде
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Исключение вызывается, когда пользователь вводит команду с повторяющимся флагом, пара введённых флагов(:ref:`InputFlag <root_api_command_input_flag>`) считается
-равной, если у них одинаковые имена. Подробнее о флагах и их синтаксисе в :ref:`Flags <root_flags>`.
+Исключение выбрасывается, если пользователь ввёл команду с повторяющимися флагами. Два флага (:ref:`InputFlag <root_api_command_input_flag>`) считаются одинаковыми, если у них совпадают имена. Подробнее о флагах и их синтаксисе — в разделе :ref:`Flags <root_flags>`.
 
 .. note::
     Сравнение на равенство у регистрируемых флагов(Flag) происходит иначе, подробнее в :ref:`Flag <root_flags>`.
@@ -66,9 +59,7 @@
 
     Repeated input flags: <raw input command>
 
-Для переопределения стандартного поведения используется сеттер ``.set_repeated_input_flags_handler(_: NonStandardBehaviorHandler[str])``,
-протокол ``NonStandardBehaviorHandler[str]`` соответствует ``Callable[[str], None]``, то есть хэндлер должен быть вызываемым объектом,
-к примеру функция или лямбда, которая принимает единственный аргумент - строку, которая представляет собой необработанную введённую команду, и ничего не возвращает.
+Для переопределения используется сеттер ``.set_repeated_input_flags_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[str], None]``, где единственный аргумент — это строка с необработанной командой.
 
 Пример кода, переопределяющего хэндлер ввода команды с повторяющимися флагами:
 
@@ -81,7 +72,7 @@
 ``EmptyInputCommandException``: Введена пустая команда
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Исключение вызывается, когда пользователь вводит команду в виде строки из пробельных символов - ``\n``, ``\t``, пробел и т.д.
+Исключение выбрасывается, если пользователь ввёл пустую строку или строку, состоящую только из пробельных символов (``\n``, ``\t``, пробел и т.д.).
 
 Стандартный хэндлер выводит в консоль
 
@@ -89,9 +80,7 @@
 
     Empty input command
 
-Для переопределения стандартного поведения используется сеттер ``.set_empty_command_handler(_: EmptyCommandHandler)``,
-протокол ``EmptyCommandHandler`` соответствует ``Callable[[], None]``, то есть хэндлер должен быть вызываемым объектом,
-к примеру функция или лямбда, которая не принимает аргументов и ничего не возвращает.
+Для переопределения используется сеттер ``.set_empty_command_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[], None]`` (без аргументов).
 
 Пример кода, переопределяющего хэндлер ввода пустой команды:
 
@@ -101,11 +90,10 @@
 
 ---------------
 
-``Поведение обработки неизвестной команды``: Введена неизвестная команда
+Обработка неизвестной команды
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Поведение триггерится, когда пользователь вводит команду, которая не зарегистрирована ни в одном роутере и не является алиасом ни для
-одной зарегистрированной команды.
+Это поведение активируется, когда пользователь вводит команду, которая не зарегистрирована ни в одном из роутеров и не является псевдонимом (alias) для существующей команды.
 
 Стандартный хэндлер выводит в консоль
 
@@ -113,9 +101,7 @@
 
     Unknown command: <trigger of the input command>
 
-Для переопределения стандартного поведения используется сеттер ``.set_unknown_command_handler(_: NonStandardBehaviorHandler[InputCommand])``,
-протокол ``NonStandardBehaviorHandler[InputCommand]`` соответствует ``Callable[[InputCommand], None]``, то есть хэндлер должен быть вызываемым объектом,
-к примеру функция или лямбда, которая принимает обязательный аргумент типа :ref:`InputCommand <root_api_command_input_command>` и ничего не возвращает.
+Для переопределения используется сеттер ``.set_unknown_command_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[InputCommand], None]``, где аргумент — объект :ref:`InputCommand <root_api_command_input_command>`.
 
 Пример кода, переопределяющего хэндлер ввода неизвестной команды:
 
@@ -125,10 +111,10 @@
 
 ---------------
 
-``Поведение выхода из приложения``: Введена команда выхода
+Выход из приложения
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-Поведение триггерится, когда пользователь вводит команду, которая маркирована как команда завершения работы.
+Это поведение активируется, когда пользователь вводит команду, помеченную как команда выхода.
 
 Стандартный хэндлер выводит в консоль текст и завершает работу приложения.
 
@@ -136,9 +122,7 @@
 
     See you
 
-Для переопределения стандартного поведения используется сеттер ``.set_exit_command_handler(_: NonStandardBehaviorHandler[Response])``,
-протокол ``NonStandardBehaviorHandler[Response]`` соответствует ``Callable[[Response], None]``, то есть хэндлер должен быть вызываемым объектом,
-к примеру функция или лямбда, которая принимает обязательный аргумент типа :ref:`Response <root_api_response>` и ничего не возвращает.
+Для переопределения используется сеттер ``.set_exit_command_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[Response], None]``, где аргумент — объект :ref:`Response <root_api_response>`.
 
 Пример кода, переопределяющего хэндлер ввода команды выхода: