Update documentation and code snippets

This commit is contained in:
2025-12-02 22:59:58 +03:00
parent e6645730f0
commit 2800a7ffc2
30 changed files with 1494 additions and 3962 deletions
@@ -8,7 +8,7 @@ msgid ""
msgstr ""
"Project-Id-Version: Argenta \n"
"Report-Msgid-Bugs-To: \n"
"POT-Creation-Date: 2025-11-03 19:01+0300\n"
"POT-Creation-Date: 2025-12-02 22:27+0300\n"
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
"Language: en\n"
@@ -20,43 +20,40 @@ msgstr ""
"Generated-By: Babel 2.17.0\n"
#: ../../root/error_handling.rst:4
#, fuzzy
msgid "Стандартная обработка ошибок"
msgstr "Errors handling"
#: ../../root/error_handling.rst:7
msgid "О разделе"
msgid "Обработка ошибок"
msgstr ""
#: ../../root/error_handling.rst:9
#: ../../root/error_handling.rst:6
msgid ""
"Argenta выбрасывает исключения в пограничных случаях, связанных с "
"``Argenta`` выбрасывает исключения в пограничных случаях, связанных с "
"пользовательским вводом. По умолчанию они обрабатываются системными "
"хэндлерами, но вы можете их переопределить. Это делается с помощью "
"обработчиками, но вы можете их переопределить. Это делается с помощью "
"сеттеров экземпляра ``App`` вида ``.set_*_handler()``. Подробнее о каждом"
" из них рассказано :ref:`ниже <possible_errors>`."
msgstr ""
#: ../../root/error_handling.rst:13
#: ../../root/error_handling.rst:10
msgid ""
"Ни одно исключение не остаётся необработанным, так как для каждого случая"
" предусмотрен стандартный хэндлер. Поэтому переопределение является "
" предусмотрен стандартный обработчик. Поэтому переопределение является "
"опциональным."
msgstr ""
#: ../../root/error_handling.rst:15
msgid "Пример переопределения обработчика для пустой команды:"
#: ../../root/error_handling.rst:12 ../../root/error_handling.rst:37
#: ../../root/error_handling.rst:61 ../../root/error_handling.rst:82
#: ../../root/error_handling.rst:105 ../../root/error_handling.rst:126
msgid "**Пример использования:**"
msgstr ""
#: ../../root/error_handling.rst:25
#: ../../root/error_handling.rst:22
msgid "Возможные исключения и нестандартное поведение"
msgstr ""
#: ../../root/error_handling.rst:28
#: ../../root/error_handling.rst:25
msgid "``UnprocessedInputFlagException``: Некорректный синтаксис флагов"
msgstr ""
#: ../../root/error_handling.rst:30
#: ../../root/error_handling.rst:27
msgid ""
"Это исключение выбрасывается, когда парсер не может обработать команду "
"из-за некорректного синтаксиса. Чаще всего это связано с ошибкой в "
@@ -64,12 +61,12 @@ msgid ""
"<root_flags>`."
msgstr ""
#: ../../root/error_handling.rst:32 ../../root/error_handling.rst:56
#: ../../root/error_handling.rst:77 ../../root/error_handling.rst:98
msgid "Стандартный хэндлер выводит в консоль"
#: ../../root/error_handling.rst:29 ../../root/error_handling.rst:53
#: ../../root/error_handling.rst:74 ../../root/error_handling.rst:97
msgid "Стандартный обработчик выводит в консоль:"
msgstr ""
#: ../../root/error_handling.rst:38
#: ../../root/error_handling.rst:35
msgid ""
"Для переопределения используется сеттер "
"``.set_incorrect_input_syntax_handler()``. Он принимает на вход "
@@ -77,17 +74,11 @@ msgid ""
"аргумент — это строка с необработанной командой."
msgstr ""
#: ../../root/error_handling.rst:40
msgid ""
"Пример кода, переопределяющего хэндлер ввода команды с некорректным "
"синтаксисом:"
msgstr ""
#: ../../root/error_handling.rst:49
#: ../../root/error_handling.rst:46
msgid "``RepeatedInputFlagsException``: Повторяющиеся флаги в команде"
msgstr ""
#: ../../root/error_handling.rst:51
#: ../../root/error_handling.rst:48
msgid ""
"Исключение выбрасывается, если пользователь ввёл команду с повторяющимися"
" флагами. Два флага (:ref:`InputFlag <root_api_command_input_flag>`) "
@@ -95,13 +86,13 @@ msgid ""
"их синтаксисе — в разделе :ref:`Flags <root_flags>`."
msgstr ""
#: ../../root/error_handling.rst:54
#: ../../root/error_handling.rst:51
msgid ""
"Сравнение на равенство у регистрируемых флагов(Flag) происходит иначе, "
"подробнее в :ref:`Flag <root_flags>`."
"Сравнение на равенство у регистрируемых флагов (``Flag``) происходит "
"иначе, подробнее в :ref:`Flag <root_flags>`."
msgstr ""
#: ../../root/error_handling.rst:62
#: ../../root/error_handling.rst:59
msgid ""
"Для переопределения используется сеттер "
"``.set_repeated_input_flags_handler()``. Он принимает на вход обработчик "
@@ -109,46 +100,36 @@ msgid ""
"строка с необработанной командой."
msgstr ""
#: ../../root/error_handling.rst:64
msgid ""
"Пример кода, переопределяющего хэндлер ввода команды с повторяющимися "
"флагами:"
msgstr ""
#: ../../root/error_handling.rst:73
#: ../../root/error_handling.rst:70
msgid "``EmptyInputCommandException``: Введена пустая команда"
msgstr ""
#: ../../root/error_handling.rst:75
#: ../../root/error_handling.rst:72
msgid ""
"Исключение выбрасывается, если пользователь ввёл пустую строку или "
"строку, состоящую только из пробельных символов (``\\n``, ``\\t``, пробел"
" и т.д.)."
msgstr ""
#: ../../root/error_handling.rst:83
#: ../../root/error_handling.rst:80
msgid ""
"Для переопределения используется сеттер ``.set_empty_command_handler()``."
" Он принимает на вход обработчик с сигнатурой ``Callable[[], None]`` (без"
" аргументов)."
msgstr ""
#: ../../root/error_handling.rst:85
msgid "Пример кода, переопределяющего хэндлер ввода пустой команды:"
msgstr ""
#: ../../root/error_handling.rst:94
#: ../../root/error_handling.rst:93
msgid "Обработка неизвестной команды"
msgstr ""
#: ../../root/error_handling.rst:96
#: ../../root/error_handling.rst:95
msgid ""
"Это поведение активируется, когда пользователь вводит команду, которая не"
" зарегистрирована ни в одном из роутеров и не является псевдонимом "
"(alias) для существующей команды."
msgstr ""
#: ../../root/error_handling.rst:104
#: ../../root/error_handling.rst:103
msgid ""
"Для переопределения используется сеттер "
"``.set_unknown_command_handler()``. Он принимает на вход обработчик с "
@@ -156,469 +137,26 @@ msgid ""
":ref:`InputCommand <root_api_command_input_command>`."
msgstr ""
#: ../../root/error_handling.rst:106
msgid "Пример кода, переопределяющего хэндлер ввода неизвестной команды:"
msgstr ""
#: ../../root/error_handling.rst:115
#: ../../root/error_handling.rst:114
msgid "Выход из приложения"
msgstr ""
#: ../../root/error_handling.rst:117
#: ../../root/error_handling.rst:116
msgid ""
"Это поведение активируется, когда пользователь вводит команду, помеченную"
" как команда выхода."
msgstr ""
#: ../../root/error_handling.rst:119
msgid "Стандартный хэндлер выводит в консоль текст и завершает работу приложения."
#: ../../root/error_handling.rst:118
msgid ""
"Стандартный обработчик выводит в консоль текст и завершает работу "
"приложения:"
msgstr ""
#: ../../root/error_handling.rst:125
#: ../../root/error_handling.rst:124
msgid ""
"Для переопределения используется сеттер ``.set_exit_command_handler()``. "
"Он принимает на вход обработчик с сигнатурой ``Callable[[Response], "
"None]``, где аргумент — объект :ref:`Response <root_api_response>`."
msgstr ""
#: ../../root/error_handling.rst:127
msgid "Пример кода, переопределяющего хэндлер ввода команды выхода:"
msgstr ""
#~ msgid "привет"
#~ msgstr ""
#~ msgid ""
#~ "``Argenta`` в рантайме вызывает исключения "
#~ "в пограничных случаях. Подробнее о типах"
#~ " исключений :ref:`ниже <possible_errors>`. Все"
#~ " исключения обрабатываются системными хэндлерами,"
#~ " но у вас есть возможность их "
#~ "переопределить. Переопределение осуществляется с "
#~ "помощью сеттеров инстанса ``App`` - "
#~ "``.set_*_handler(_)``, где ``_`` - это "
#~ "протокол хэндлера нестандартного поведения, "
#~ "подробнее о каждом протоколе и "
#~ "соответствующем сеттере :ref:`ниже "
#~ "<possible_errors>`"
#~ msgstr ""
#~ msgid "UnprocessedInputFlagException: Необрабатываемый ввод от пользователя"
#~ msgstr ""
#~ msgid ""
#~ "Исключение вызывается, когда пользователь "
#~ "вводит команду с некорректным синтаксисом "
#~ "и парсер не может *распарсить* её. "
#~ "В большинстве случаев это означат, что"
#~ " проблема в синтаксисе введённых флагов "
#~ "команды, подробнее в"
#~ msgstr ""
#~ msgid ""
#~ "This error means that one of the"
#~ " objects cannot be created because "
#~ "some of its dependencies depend on "
#~ "itself. You can see the whole path"
#~ " in the error message with types "
#~ "and provider methods."
#~ msgstr ""
#~ msgid "Possible actions:"
#~ msgstr ""
#~ msgid ""
#~ "**Remove cycle dependency.** If the "
#~ "cycle was introduced as a result "
#~ "of typo you can fix it. But "
#~ "in other cases this can lead to"
#~ " a refactoring of your object "
#~ "structure"
#~ msgstr ""
#~ msgid ""
#~ "**Implement two-phase initialization.** "
#~ "Instead of doing constructor injection "
#~ "using dishka you can do attribute "
#~ "injection later when both objects are"
#~ " available."
#~ msgstr ""
#~ msgid "GraphMissingFactoryError: Cannot find factory for ..."
#~ msgstr ""
#~ msgid ""
#~ "There are multiple reasons for this "
#~ "error. If possible, dishka tries to "
#~ "predict possible fixes."
#~ msgstr ""
#~ msgid ""
#~ "**Factory is simply missing.** Check "
#~ "that you added all required providers"
#~ " and they contain appropriate ``provide``."
#~ msgstr ""
#~ msgid ""
#~ "**Context data is not marked with "
#~ "from_context** Check that you added all"
#~ " required providers and they contain "
#~ "appropriate ``from_context``."
#~ msgstr ""
#~ msgid ""
#~ "**Object has invalid scope** Check the"
#~ " scope of provided type and the "
#~ "types dependent on it. Note, that "
#~ "long-living objects cannot depend on "
#~ "short-living ones. E.g. object with "
#~ "``Scope.APP`` cannot depend on one with"
#~ " ``Scope.REQUEST``."
#~ msgstr ""
#~ msgid "You should review used scopes."
#~ msgstr ""
#~ msgid ""
#~ "**Object is provided in another "
#~ "component** Components are isolated and "
#~ "cannot implicitly share objects. You "
#~ "should either use ``FromComponent`` to "
#~ "call another component directly or "
#~ "create object separately for appropriate "
#~ "component using ``provide`` annotation"
#~ msgstr ""
#~ msgid ""
#~ "**Dependency is parent class while "
#~ "provided child class (or vice versa)**"
#~ " Use ``provides=`` argument to mark "
#~ "that source and provided types are "
#~ "different. Use ``WithParents[X]`` to provide"
#~ " an object as its type with "
#~ "parent classes"
#~ msgstr ""
#~ msgid "CannotUseProtocolError: Cannot use ... as a factory"
#~ msgstr ""
#~ msgid ""
#~ "This error means that you used "
#~ "some protocol class as a source "
#~ "argument of ``provide`` function. Protocols"
#~ " cannot be instantiated. Check that "
#~ "you have an implementation for that "
#~ "protocol, and use it. You can try"
#~ " using the form ``provide(YourImpl, "
#~ "provides=YourProtocol)``."
#~ msgstr ""
#~ msgid "NotAFactoryError: Cannot use ... as a factory."
#~ msgstr ""
#~ msgid ""
#~ "Check what are you passing to "
#~ "``provide`` function. Probably that object "
#~ "cannot be instantiated directly."
#~ msgstr ""
#~ msgid ""
#~ "Note, that you can provide some "
#~ "type by creating an instance of "
#~ "another one using the form "
#~ "``provide(YourClass, provides=SomeTypeHint)``."
#~ msgstr ""
#~ msgid "ImplicitOverrideDetectedError: Detected multiple factories for ..."
#~ msgstr ""
#~ msgid ""
#~ "This error can be seen only if "
#~ "you enabled ``implicit_override=True`` in "
#~ "validation settings. It means that you"
#~ " have 2 factories for the same "
#~ "type without specifying that the second"
#~ " one should replace the first one."
#~ msgstr ""
#~ msgid "**You meant to have one of factories**. Just remove the second one."
#~ msgstr ""
#~ msgid ""
#~ "**You want to override dependency for"
#~ " tests or other purposes**. Specify "
#~ "``override=True`` when creating second "
#~ "factory."
#~ msgstr ""
#~ msgid "Error text will contain details on both option with names of providers."
#~ msgstr ""
#~ msgid ""
#~ "NothingOverriddenError: Overriding factory found "
#~ "for ..., but there is nothing to"
#~ " override."
#~ msgstr ""
#~ msgid ""
#~ "This error can be seen only if "
#~ "you enabled ``nothing_overridden=True`` in "
#~ "validation settings. That means you set"
#~ " ``override=True``, but there is no "
#~ "second factory to be overriden or "
#~ "the order of providers is incorrect."
#~ msgstr ""
#~ msgid ""
#~ "Check, that you have specified all "
#~ "expected providers in correct order or"
#~ " remove the flag."
#~ msgstr ""
#~ msgid ""
#~ "IndependentDecoratorError: Decorator ... does "
#~ "not depend on provided type."
#~ msgstr ""
#~ msgid ""
#~ "Using ``decorate`` is a special case "
#~ "if you need to apply decorator "
#~ "patter or do modifications with an "
#~ "object created in another provider. Is"
#~ " requests an object of some type "
#~ "(additional dependencies are allowed) and "
#~ "returns the same type."
#~ msgstr ""
#~ msgid ""
#~ "If you are not going to use "
#~ "an object received from another factory,"
#~ " probably you meant to use simple "
#~ "``provide`` instead?"
#~ msgstr ""
#~ msgid "Возможные исключения"
#~ msgstr ""
#~ msgid "``UnknownCommandException``: Введена неизвестная команда"
#~ msgstr ""
#~ msgid ""
#~ "Исключение вызывается, когда пользователь "
#~ "вводит команду, которая не зарегистрирована"
#~ " ни в одном роутере и не "
#~ "является алиасом ни для одной "
#~ "зарегистрированной команды."
#~ msgstr ""
#~ msgid "Конфигурация"
#~ msgstr ""
#~ msgid ""
#~ "Исключение вызывается, когда пользователь "
#~ "вводит команду с некорректным синтаксисом "
#~ "и парсер не может *распарсить* её. "
#~ "В большинстве случаев это означат, что"
#~ " проблема в синтаксисе введённых флагов "
#~ "команды, подробнее о флагах и их "
#~ "синтаксисе в :ref:`Flags <root_flags>`."
#~ msgstr ""
#~ msgid ""
#~ "Исключение вызывается, когда пользователь "
#~ "вводит команду с повторяющимся флагом, "
#~ "флаг(:ref:`InputFlag <input_flag>`) считается "
#~ "повторяющимся, если введён флаг с таким"
#~ " же именем, именно именем, без "
#~ "префикса. Подробнее о флагах и их "
#~ "синтаксисе в :ref:`Flags <root_flags>`."
#~ msgstr ""
#~ msgid ""
#~ "Для переопределения стандартного поведения "
#~ "используется сеттер ``.set_exit_command_handler(_: "
#~ "NonStandardBehaviorHandler[Response])``, протокол "
#~ "``NonStandardBehaviorHandler[Response]`` соответствует "
#~ "``Callable[[Response], None]``, то есть "
#~ "хэндлер должен быть вызываемым объектом, "
#~ "к примеру функция или лямбда, которая"
#~ " принимает обязательный аргумент типа "
#~ ":ref:`Response <response>` и ничего не "
#~ "возвращает."
#~ msgstr ""
#~ msgid ""
#~ "``Argenta`` в рантайме вызывает исключения "
#~ "в пограничных случаях пользовательского ввода."
#~ " Все исключения обрабатываются системными "
#~ "хэндлерами, но у вас есть возможность"
#~ " их переопределить. Переопределение "
#~ "осуществляется с помощью сеттеров инстанса "
#~ "``App`` - ``.set_*_handler(_)``, где ``_`` "
#~ "- это протокол хэндлера нестандартного "
#~ "поведения, подробнее о каждом протоколе "
#~ "и соответствующем сеттере :ref:`ниже "
#~ "<possible_errors>`"
#~ msgstr ""
#~ msgid ""
#~ "Все исключения никогда не остаются "
#~ "необработанными, так как у них есть "
#~ "стандартные хэндлеры. Поэтому переопределение "
#~ "опционально."
#~ msgstr ""
#~ msgid "Краткий сэмпл кода, переопределяющего хэндлер ввода пустой команды"
#~ msgstr ""
#~ msgid ""
#~ "``UnprocessedInputFlagException``: Необрабатываемый ввод"
#~ " от пользователя"
#~ msgstr ""
#~ msgid ""
#~ "Исключение вызывается, когда пользователь "
#~ "вводит команду с некорректным синтаксисом "
#~ "и как следствие парсер не может "
#~ "*распарсить* её. В большинстве случаев "
#~ "это означат, что проблема в синтаксисе"
#~ " введённых флагов команды, подробнее о "
#~ "флагах и их синтаксисе в :ref:`Flags "
#~ "<root_flags>`."
#~ msgstr ""
#~ msgid "Дефолтный хэндлер выводит в консоль"
#~ msgstr ""
#~ msgid ""
#~ "Для переопределения стандартного поведения "
#~ "используется сеттер "
#~ "``.set_incorrect_input_syntax_handler(_: "
#~ "NonStandardBehaviorHandler[str])``, протокол "
#~ "``NonStandardBehaviorHandler[str]`` соответствует "
#~ "``Callable[[str], None]``, то есть хэндлер "
#~ "должен быть вызываемым объектом, к "
#~ "примеру функция или лямбда, которая "
#~ "принимает единственный аргумент - строку, "
#~ "которая представляет собой необработанную "
#~ "введённую команду, и ничего не "
#~ "возвращает."
#~ msgstr ""
#~ msgid ""
#~ "Сэмпл кода, переопределяющего хэндлер ввода"
#~ " команды с некорректным синтаксисом:"
#~ msgstr ""
#~ msgid "``RepeatedInputFlagsException``: Повторяющийся флаг в введённой команде"
#~ msgstr ""
#~ msgid ""
#~ "Исключение вызывается, когда пользователь "
#~ "вводит команду с повторяющимся флагом, "
#~ "пара введённых флагов(:ref:`InputFlag "
#~ "<root_api_command_input_flag>`) считается равной, "
#~ "если у них одинаковые имена. Подробнее"
#~ " о флагах и их синтаксисе в "
#~ ":ref:`Flags <root_flags>`."
#~ msgstr ""
#~ msgid ""
#~ "Для переопределения стандартного поведения "
#~ "используется сеттер ``.set_repeated_input_flags_handler(_:"
#~ " NonStandardBehaviorHandler[str])``, протокол "
#~ "``NonStandardBehaviorHandler[str]`` соответствует "
#~ "``Callable[[str], None]``, то есть хэндлер "
#~ "должен быть вызываемым объектом, к "
#~ "примеру функция или лямбда, которая "
#~ "принимает единственный аргумент - строку, "
#~ "которая представляет собой необработанную "
#~ "введённую команду, и ничего не "
#~ "возвращает."
#~ msgstr ""
#~ msgid ""
#~ "Сэмпл кода, переопределяющего хэндлер ввода"
#~ " команды с повторяющимися флагами:"
#~ msgstr ""
#~ msgid ""
#~ "Исключение вызывается, когда пользователь "
#~ "вводит команду в виде строки из "
#~ "пробельных символов - ``\\n``, ``\\t``, "
#~ "пробел и т.д."
#~ msgstr ""
#~ msgid ""
#~ "Для переопределения стандартного поведения "
#~ "используется сеттер ``.set_empty_command_handler(_: "
#~ "EmptyCommandHandler)``, протокол ``EmptyCommandHandler``"
#~ " соответствует ``Callable[[], None]``, то "
#~ "есть хэндлер должен быть вызываемым "
#~ "объектом, к примеру функция или лямбда,"
#~ " которая не принимает аргументов и "
#~ "ничего не возвращает."
#~ msgstr ""
#~ msgid "Сэмпл кода, переопределяющего хэндлер ввода пустой команды:"
#~ msgstr ""
#~ msgid ""
#~ "``Поведение обработки неизвестной команды``: "
#~ "Введена неизвестная команда"
#~ msgstr ""
#~ msgid ""
#~ "Поведение триггерится, когда пользователь "
#~ "вводит команду, которая не зарегистрирована"
#~ " ни в одном роутере и не "
#~ "является алиасом ни для одной "
#~ "зарегистрированной команды."
#~ msgstr ""
#~ msgid ""
#~ "Для переопределения стандартного поведения "
#~ "используется сеттер ``.set_unknown_command_handler(_: "
#~ "NonStandardBehaviorHandler[InputCommand])``, протокол "
#~ "``NonStandardBehaviorHandler[InputCommand]`` соответствует "
#~ "``Callable[[InputCommand], None]``, то есть "
#~ "хэндлер должен быть вызываемым объектом, "
#~ "к примеру функция или лямбда, которая"
#~ " принимает обязательный аргумент типа "
#~ ":ref:`InputCommand <input_command>` и ничего "
#~ "не возвращает."
#~ msgstr ""
#~ msgid "Сэмпл кода, переопределяющего хэндлер ввода неизвестной команды:"
#~ msgstr ""
#~ msgid "``Поведение выхода из приложения``: Введена команда выхода"
#~ msgstr ""
#~ msgid ""
#~ "Поведение триггерится, когда пользователь "
#~ "вводит команду, которая маркирована как "
#~ "команда завершения работы."
#~ msgstr ""
#~ msgid ""
#~ "Дефолтный хэндлер выводит в консоль "
#~ "текст и завершает работу приложения."
#~ msgstr ""
#~ msgid ""
#~ "Для переопределения стандартного поведения "
#~ "используется сеттер ``.set_exit_command_handler(_: "
#~ "NonStandardBehaviorHandler[Response])``, протокол "
#~ "``NonStandardBehaviorHandler[Response]`` соответствует "
#~ "``Callable[[Response], None]``, то есть "
#~ "хэндлер должен быть вызываемым объектом, "
#~ "к примеру функция или лямбда, которая"
#~ " принимает обязательный аргумент типа "
#~ ":ref:`Response <root_api_response>` и ничего "
#~ "не возвращает."
#~ msgstr ""
#~ msgid "Сэмпл кода, переопределяющего хэндлер ввода команды выхода:"
#~ msgstr ""