.. _root_error_handling: Обработка ошибок ========================================== Конфигурация ------------ ``Argenta`` в рантайме вызывает исключения в пограничных случаях пользовательского ввода. Все исключения обрабатываются системными хэндлерами, но у вас есть возможность их переопределить. Переопределение осуществляется с помощью сеттеров инстанса ``App`` - ``.set_*_handler(_)``, где ``_`` - это протокол хэндлера нестандартного поведения, подробнее о каждом протоколе и соответствующем сеттере :ref:`ниже ` .. note:: Все исключения никогда не остаются необработанными, так как у них есть стандартные хэндлеры. Поэтому переопределение опционально. Краткий сэмпл кода, переопределяющего хэндлер ввода пустой команды .. literalinclude:: ../code_snippets/error_handling_example_sample.py :language: python .. _possible_errors: Возможные исключения и нестандартное поведение ---------------------------------------------- ``UnprocessedInputFlagException``: Необрабатываемый ввод от пользователя ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Исключение вызывается, когда пользователь вводит команду с некорректным синтаксисом и парсер не может *распарсить* её. В большинстве случаев это означат, что проблема в синтаксисе введённых флагов команды, подробнее о флагах и их синтаксисе в :ref:`Flags `. Дефолтный хэндлер выводит в консоль .. code-block:: shell Incorrect flag syntax: Для переопределения стандартного поведения используется сеттер ``.set_incorrect_input_syntax_handler(_: NonStandardBehaviorHandler[str])``, протокол ``NonStandardBehaviorHandler[str]`` соответствует ``Callable[[str], None]``, то есть хэндлер должен быть вызываемым объектом, к примеру функция или лямбда, которая принимает единственный аргумент - строку, которая представляет собой необработанную введённую команду, и ничего не возвращает. Сэмпл кода, переопределяющего хэндлер ввода команды с некорректным синтаксисом: .. literalinclude:: ../code_snippets/error_handling_example_sample2.py :language: python --------------- ``RepeatedInputFlagsException``: Повторяющийся флаг в введённой команде ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Исключение вызывается, когда пользователь вводит команду с повторяющимся флагом, пара введённых флагов(:ref:`InputFlag `) считается равной, если у них одинаковые имена. Подробнее о флагах и их синтаксисе в :ref:`Flags `. .. note:: Сравнение на равенство у регистрируемых флагов(Flag) происходит иначе, подробнее в :ref:`Flag `. Дефолтный хэндлер выводит в консоль .. code-block:: shell Repeated input flags: Для переопределения стандартного поведения используется сеттер ``.set_repeated_input_flags_handler(_: NonStandardBehaviorHandler[str])``, протокол ``NonStandardBehaviorHandler[str]`` соответствует ``Callable[[str], None]``, то есть хэндлер должен быть вызываемым объектом, к примеру функция или лямбда, которая принимает единственный аргумент - строку, которая представляет собой необработанную введённую команду, и ничего не возвращает. Сэмпл кода, переопределяющего хэндлер ввода команды с повторяющимися флагами: .. literalinclude:: ../code_snippets/error_handling_example_sample3.py :language: python --------------- ``EmptyInputCommandException``: Введена пустая команда ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Исключение вызывается, когда пользователь вводит команду в виде строки из пробельных символов - ``\n``, ``\t``, пробел и т.д. Дефолтный хэндлер выводит в консоль .. code-block:: shell Empty input command Для переопределения стандартного поведения используется сеттер ``.set_empty_command_handler(_: EmptyCommandHandler)``, протокол ``EmptyCommandHandler`` соответствует ``Callable[[], None]``, то есть хэндлер должен быть вызываемым объектом, к примеру функция или лямбда, которая не принимает аргументов и ничего не возвращает. Сэмпл кода, переопределяющего хэндлер ввода пустой команды: .. literalinclude:: ../code_snippets/error_handling_example_sample4.py :language: python --------------- ``Поведение обработки неизвестной команды``: Введена неизвестная команда ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Поведение триггерится, когда пользователь вводит команду, которая не зарегистрирована ни в одном роутере и не является алиасом ни для одной зарегистрированной команды. Дефолтный хэндлер выводит в консоль .. code-block:: shell Unknown command: Для переопределения стандартного поведения используется сеттер ``.set_unknown_command_handler(_: NonStandardBehaviorHandler[InputCommand])``, протокол ``NonStandardBehaviorHandler[InputCommand]`` соответствует ``Callable[[InputCommand], None]``, то есть хэндлер должен быть вызываемым объектом, к примеру функция или лямбда, которая принимает обязательный аргумент типа :ref:`InputCommand ` и ничего не возвращает. Сэмпл кода, переопределяющего хэндлер ввода неизвестной команды: .. literalinclude:: ../code_snippets/error_handling_example_sample5.py :language: python --------------- ``Поведение выхода из приложения``: Введена команда выхода ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Поведение триггерится, когда пользователь вводит команду, которая маркирована как команда завершения работы. Дефолтный хэндлер выводит в консоль текст и завершает работу приложения. .. code-block:: shell See you Для переопределения стандартного поведения используется сеттер ``.set_exit_command_handler(_: NonStandardBehaviorHandler[Response])``, протокол ``NonStandardBehaviorHandler[Response]`` соответствует ``Callable[[Response], None]``, то есть хэндлер должен быть вызываемым объектом, к примеру функция или лямбда, которая принимает обязательный аргумент типа :ref:`Response ` и ничего не возвращает. Сэмпл кода, переопределяющего хэндлер ввода команды выхода: .. literalinclude:: ../code_snippets/error_handling_example_sample6.py :language: python