feat: impl docs (#4)

The entire public api is covered with documentation in two languages - Russian and English.

the library now supports the latest three versions of python - 3.12, 3.13 and 3.14

minor design changes: now, when a Boolean flag is entered, its value is an empty string, not None.

tests have been adapted to the supported versions of python, readmi has been redesigned in two languages, German is no longer available.

docs/locales/en/LC_MESSAGES/root/api/app/autocompleter.po

@@ -0,0 +1,120 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2025, kolo
+# This file is distributed under the same license as the Argenta package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2025.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: Argenta \n"
+"Report-Msgid-Bugs-To: \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"
+"Language-Team: en <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.17.0\n"
+
+#: ../../root/api/app/autocompleter.rst:4
+msgid "AutoCompleter"
+msgstr ""
+
+#: ../../root/api/app/autocompleter.rst:6
+msgid ""
+"``AutoCompleter`` — это компонент, отвечающий за интерактивное "
+"автодополнение команд. Он улучшает пользовательский опыт, предлагая "
+"подсказки и завершая ввод на основе истории команд, что ускоряет работу и"
+" снижает вероятность опечаток."
+msgstr ""
+"``AutoCompleter`` is a component responsible for interactive command autocompletion. "
+"It improves user experience by offering suggestions and completing input based on "
+"command history, which speeds up work and reduces the likelihood of typos."
+
+#: ../../root/api/app/autocompleter.rst:11
+msgid "Инициализация"
+msgstr "Initialization"
+
+#: ../../root/api/app/autocompleter.rst:18
+msgid "Создаёт и настраивает экземпляр ``AutoCompleter``."
+msgstr "Creates and configures an ``AutoCompleter`` instance."
+
+#: ../../root/api/app/autocompleter.rst:20
+msgid ""
+"``history_filename``: Имя файла для сохранения истории команд. Если "
+"указано, история будет сохраняться между сессиями. При значении ``None`` "
+"история хранится только в контексте сессии."
+msgstr ""
+"``history_filename``: Filename for saving command history. If specified, history "
+"will be saved between sessions. When set to ``None``, history is stored only within "
+"the session context."
+
+#: ../../root/api/app/autocompleter.rst:21
+msgid ""
+"``autocomplete_button``: Клавиша, активирующая автодополнение. По "
+"умолчанию — **Tab**."
+msgstr ""
+"``autocomplete_button``: Key that activates autocompletion. Defaults to **Tab**."
+
+#: ../../root/api/app/autocompleter.rst:26
+msgid "Назначение и возможности"
+msgstr "Purpose and Features"
+
+#: ../../root/api/app/autocompleter.rst:28
+msgid "Основные возможности ``AutoCompleter``:"
+msgstr "Main features of ``AutoCompleter``:"
+
+#: ../../root/api/app/autocompleter.rst:30
+msgid ""
+"**Автодополнение по истории**: При нажатии клавиши автодополнения (по "
+"умолчанию **Tab**) система ищет в истории команды, начинающиеся с уже "
+"введённого текста."
+msgstr ""
+"**History-based autocompletion**: When the autocompletion key is pressed (by default **Tab**), "
+"the system searches history for commands starting with the already entered text."
+
+#: ../../root/api/app/autocompleter.rst:32
+msgid ""
+"**Общий префикс**: Если найдено несколько команд с общим префиксом, будет"
+" подставлена только общая часть. Например, для команд ``show_users`` и "
+"``show_profile`` при вводе ``sho`` и нажатии **Tab** ввод дополнится до "
+"``show_``."
+msgstr ""
+"**Common prefix**: If multiple commands with a common prefix are found, only the common "
+"part will be inserted. For example, for commands ``show_users`` and ``show_profile``, "
+"when entering ``sho`` and pressing **Tab**, the input will be completed to ``show_``."
+
+#: ../../root/api/app/autocompleter.rst:34
+msgid ""
+"**Постоянная история**: Если указан ``history_filename``, история команд "
+"сохраняется в файл при выходе и загружается при следующем запуске. Это "
+"делает автодополнение со временем «умнее»."
+msgstr ""
+"**Persistent history**: If ``history_filename`` is specified, command history is saved "
+"to a file on exit and loaded on the next startup. This makes autocompletion \"smarter\" over time."
+
+#: ../../root/api/app/autocompleter.rst:36
+msgid ""
+"**Очистка истории**: При сохранении ``AutoCompleter`` удаляет дубликаты и"
+" несуществующие команды, поддерживая историю в актуальном состоянии."
+msgstr ""
+"**History cleanup**: When saving, ``AutoCompleter`` removes duplicates and non-existent "
+"commands, keeping the history up to date."
+
+#: ../../root/api/app/autocompleter.rst:38
+msgid ""
+"**Настройка клавиши**: Клавишу автодополнения можно изменить с помощью "
+"параметра ``autocomplete_button``."
+msgstr ""
+"**Key customization**: The autocompletion key can be changed using the ``autocomplete_button`` parameter."
+
+#: ../../root/api/app/autocompleter.rst:43
+msgid "Пример использования"
+msgstr "Usage Example"
+
+#: ../../root/api/app/autocompleter.rst:45
+msgid "``AutoCompleter`` передаётся как аргумент при инициализации `App`."
+msgstr "``AutoCompleter`` is passed as an argument when initializing `App`."
+

docs/locales/en/LC_MESSAGES/root/api/app/dividing_lines.po

@@ -0,0 +1,150 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2025, kolo
+# This file is distributed under the same license as the Argenta package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2025.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: Argenta \n"
+"Report-Msgid-Bugs-To: \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"
+"Language-Team: en <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.17.0\n"
+
+#: ../../root/api/app/dividing_lines.rst:4
+msgid "Dividing Lines"
+msgstr "Dividing Lines"
+
+#: ../../root/api/app/dividing_lines.rst:6
+msgid ""
+"Разделительные линии в ``Argenta`` используются для визуального "
+"структурирования вывода и отделения блоков информации друг от друга. "
+"Библиотека предлагает два типа линий: статическую и динамическую."
+msgstr ""
+"Dividing lines in ``Argenta`` are used for visual structuring of output and separating "
+"information blocks from each other. The library offers two types of lines: static and dynamic."
+
+#: ../../root/api/app/dividing_lines.rst:11
+msgid "``StaticDividingLine``"
+msgstr "``StaticDividingLine``"
+
+#: ../../root/api/app/dividing_lines.rst:13
+msgid ""
+"``StaticDividingLine`` создаёт разделительную линию **фиксированной** "
+"длины. Этот тип линии полезен для создания предсказуемого и "
+"унифицированного интерфейса."
+msgstr ""
+"``StaticDividingLine`` creates a dividing line of **fixed** length. This type of line "
+"is useful for creating a predictable and unified interface."
+
+#: ../../root/api/app/dividing_lines.rst:21
+msgid "Создаёт экземпляр статической разделительной линии."
+msgstr "Creates a static dividing line instance."
+
+#: ../../root/api/app/dividing_lines.rst:23
+msgid ""
+"``unit_part``: Символ для построения линии (учитывается только первый "
+"символ). По умолчанию: ``-``."
+msgstr ""
+"``unit_part``: Character for building the line (only the first character is considered). "
+"Defaults to: ``-``."
+
+#: ../../root/api/app/dividing_lines.rst:24
+msgid "``length``: Фиксированная длина линии. По умолчанию: ``25``."
+msgstr "``length``: Fixed line length. Defaults to: ``25``."
+
+#: ../../root/api/app/dividing_lines.rst:29
+msgid "``DynamicDividingLine``"
+msgstr "``DynamicDividingLine``"
+
+#: ../../root/api/app/dividing_lines.rst:31
+msgid ""
+"``DynamicDividingLine`` создаёт линию, длина которой **динамически** "
+"подстраивается под самую длинную строку в выводе команды. Это требует "
+"перехвата ``stdout``, в результате чего разделители идеально обрамляют "
+"выводимый контент."
+msgstr ""
+"``DynamicDividingLine`` creates a line whose length **dynamically** adjusts to the longest "
+"line in the command output. This requires capturing ``stdout``, resulting in dividers that "
+"perfectly frame the output content."
+
+#: ../../root/api/app/dividing_lines.rst:38
+msgid "Создаёт экземпляр динамической разделительной линии."
+msgstr "Creates a dynamic dividing line instance."
+
+#: ../../root/api/app/dividing_lines.rst:40
+msgid "``unit_part``: Символ для построения линии. По умолчанию: ``-``."
+msgstr "``unit_part``: Character for building the line. Defaults to: ``-``."
+
+#: ../../root/api/app/dividing_lines.rst:42
+msgid "Длина вычисляется автоматически и не задаётся при инициализации."
+msgstr "Length is calculated automatically and is not set during initialization."
+
+#: ../../root/api/app/dividing_lines.rst:45
+msgid ""
+"Обязательно почитайте про нюансы использования динамических линий и "
+"перехвата ``stdout`` в :ref:`этом разделе<root_redirect_stdout>`."
+msgstr ""
+"Be sure to read about the nuances of using dynamic lines and capturing ``stdout`` "
+"in :ref:`this section<root_redirect_stdout>`."
+
+#: ../../root/api/app/dividing_lines.rst:50
+msgid "Назначение и использование"
+msgstr "Purpose and Usage"
+
+#: ../../root/api/app/dividing_lines.rst:52
+msgid "Выбор между статической и динамической линией зависит от ваших задач."
+msgstr "The choice between static and dynamic lines depends on your needs."
+
+#: ../../root/api/app/dividing_lines.rst:54
+msgid "**StaticDividingLine** идеально подходит, если:"
+msgstr "**StaticDividingLine** is ideal if:"
+
+#: ../../root/api/app/dividing_lines.rst:56
+msgid "Вам нужен строгий и консистентный дизайн."
+msgstr "You need a strict and consistent design."
+
+#: ../../root/api/app/dividing_lines.rst:57
+msgid ""
+"Вы используете роутеры с отключённым перехватом ``stdout`` "
+"(``disable_redirect_stdout=True``), где динамическое вычисление длины "
+"невозможно."
+msgstr ""
+"You are using routers with disabled ``stdout`` capture (``disable_redirect_stdout=True``), "
+"where dynamic length calculation is not possible."
+
+#: ../../root/api/app/dividing_lines.rst:59
+msgid ""
+"**DynamicDividingLine** (поведение по умолчанию) — предпочтительный "
+"выбор, если:"
+msgstr "**DynamicDividingLine** (default behavior) is the preferred choice if:"
+
+#: ../../root/api/app/dividing_lines.rst:61
+msgid "Вы хотите, чтобы интерфейс был адаптивным."
+msgstr "You want the interface to be adaptive."
+
+#: ../../root/api/app/dividing_lines.rst:62
+msgid "Вывод ваших команд имеет разную длину."
+msgstr "Your command output has varying lengths."
+
+#: ../../root/api/app/dividing_lines.rst:63
+msgid ""
+"В ваших обработчиках нет интерактивных операций ввода (например, "
+"``input()``)."
+msgstr "Your handlers do not have interactive input operations (e.g., ``input()``)."
+
+#: ../../root/api/app/dividing_lines.rst:65
+msgid ""
+"Тип разделителя для всего приложения задаётся при инициализации ``App`` "
+"через параметр ``dividing_line``."
+msgstr ""
+"The divider type for the entire application is set during ``App`` initialization "
+"via the ``dividing_line`` parameter."
+

docs/locales/en/LC_MESSAGES/root/api/app/index.po

@@ -0,0 +1,280 @@
+# SOME DESCRIPTIVE TITLE.
+# Copyright (C) 2025, kolo
+# This file is distributed under the same license as the Argenta package.
+# FIRST AUTHOR <EMAIL@ADDRESS>, 2025.
+#
+msgid ""
+msgstr ""
+"Project-Id-Version: Argenta \n"
+"Report-Msgid-Bugs-To: \n"
+"POT-Creation-Date: 2025-12-04 20:39+0300\n"
+"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
+"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
+"Language: en\n"
+"Language-Team: en <LL@li.org>\n"
+"Plural-Forms: nplurals=2; plural=(n != 1);\n"
+"MIME-Version: 1.0\n"
+"Content-Type: text/plain; charset=utf-8\n"
+"Content-Transfer-Encoding: 8bit\n"
+"Generated-By: Babel 2.17.0\n"
+
+#: ../../root/api/app/index.rst:4
+msgid "App"
+msgstr "App"
+
+#: ../../root/api/app/index.rst:6
+msgid ""
+"Объект ``App`` — это ядро вашего консольного приложения. Он отвечает за "
+"конфигурацию, управление жизненным циклом, обработку команд и "
+"взаимодействие с пользователем, координируя работу всех компонентов: "
+"роутеров, обработчиков и системных сообщений."
+msgstr ""
+"The ``App`` object is the core of your console application. It handles "
+"configuration, lifecycle management, command processing, and user "
+"interaction, coordinating the work of all components: routers, handlers, "
+"and system messages."
+
+#: ../../root/api/app/index.rst:11
+msgid "Инициализация"
+msgstr "Initialization"
+
+#: ../../root/api/app/index.rst:38
+msgid "Создаёт и настраивает экземпляр приложения."
+msgstr "Creates and configures an application instance."
+
+#: ../../root/api/app/index.rst:40
+msgid "``prompt``: Приглашение к вводу, отображаемое перед каждой командой."
+msgstr "``prompt``: Input prompt displayed before each command."
+
+#: ../../root/api/app/index.rst:41
+msgid "``initial_message``: Сообщение, выводимое при запуске приложения."
+msgstr "``initial_message``: Message displayed when the application starts."
+
+#: ../../root/api/app/index.rst:42
+msgid "``farewell_message``: Сообщение, выводимое при выходе из приложения."
+msgstr "``farewell_message``: Message displayed when exiting the application."
+
+#: ../../root/api/app/index.rst:43
+msgid ""
+"``exit_command``: Команда, которая маркируется как триггер для выхода из "
+"приложения."
+msgstr ""
+"``exit_command``: Command that is marked as a trigger for exiting the "
+"application."
+
+#: ../../root/api/app/index.rst:44
+msgid ""
+"``system_router_title``: Заголовок для системного роутера (содержит "
+"команду выхода)."
+msgstr ""
+"``system_router_title``: Title for the system router (contains the exit "
+"command)."
+
+#: ../../root/api/app/index.rst:45
+msgid ""
+"``ignore_command_register``: Если ``True``, регистр вводимых команд "
+"игнорируется при поиске обработчика."
+msgstr ""
+"``ignore_command_register``: If ``True``, command case is ignored when "
+"searching for a handler."
+
+#: ../../root/api/app/index.rst:46
+msgid ""
+"``dividing_line``: Тип разделительной линии (``StaticDividingLine`` или "
+"``DynamicDividingLine``)."
+msgstr ""
+"``dividing_line``: Type of dividing line (``StaticDividingLine`` or "
+"``DynamicDividingLine``)."
+
+#: ../../root/api/app/index.rst:47
+msgid ""
+"``repeat_command_groups_printing``: Если ``True``, список доступных "
+"команд выводится перед каждым вводом."
+msgstr ""
+"``repeat_command_groups_printing``: If ``True``, the list of available "
+"commands is displayed before each input."
+
+#: ../../root/api/app/index.rst:48
+msgid ""
+"``override_system_messages``: Если ``True``, стандартное форматирование "
+"(цвета, ASCII-арт) отключается."
+msgstr ""
+"``override_system_messages``: If ``True``, standard formatting (colors, "
+"ASCII art) is disabled."
+
+#: ../../root/api/app/index.rst:49
+msgid ""
+"``autocompleter``: Экземпляр класса :ref:`AutoCompleter "
+"<root_api_app_autocompleter>`, отвечающий за автодополнение команд."
+msgstr ""
+"``autocompleter``: Instance of the :ref:`AutoCompleter "
+"<root_api_app_autocompleter>` class responsible for command "
+"autocompletion."
+
+#: ../../root/api/app/index.rst:50
+msgid ""
+"``print_func``: Функция для вывода всех системных сообщений (по умолчанию"
+" ``rich.Console().print``)."
+msgstr ""
+"``print_func``: Function for outputting all system messages (defaults to "
+"``rich.Console().print``)."
+
+#: ../../root/api/app/index.rst:55
+msgid "Основные методы"
+msgstr "Main Methods"
+
+#: ../../root/api/app/index.rst:59
+msgid ""
+"Регистрирует роутер в приложении. Все команды из этого роутера становятся"
+" доступными для вызова."
+msgstr ""
+"Registers a router in the application. All commands from this router "
+"become available for invocation."
+
+#: ../../root/api/app/index.rst
+msgid "Parameters"
+msgstr "Parameters"
+
+#: ../../root/api/app/index.rst:61
+msgid "Экземпляр ``Router`` для регистрации."
+msgstr "``Router`` instance to register."
+
+#: ../../root/api/app/index.rst:65
+msgid "Регистрирует несколько роутеров одновременно."
+msgstr "Registers multiple routers simultaneously."
+
+#: ../../root/api/app/index.rst:67
+msgid "Последовательность экземпляров ``Router`` для регистрации."
+msgstr "Sequence of ``Router`` instances to register."
+
+#: ../../root/api/app/index.rst:71
+msgid ""
+"Добавляет текстовое сообщение, которое выводится при запуске приложения "
+"после ``initial_message``."
+msgstr ""
+"Adds a text message that is displayed when the application starts after "
+"``initial_message``."
+
+#: ../../root/api/app/index.rst:73
+msgid "Строка с сообщением."
+msgstr "String with the message."
+
+#: ../../root/api/app/index.rst:76
+msgid ""
+"Для вывода стандартных сообщений можно использовать готовые шаблоны из "
+":ref:`PredefinedMessages <root_api_predefined_messages>`."
+msgstr ""
+"For outputting standard messages, you can use ready-made templates from "
+":ref:`PredefinedMessages <root_api_predefined_messages>`."
+
+#: ../../root/api/app/index.rst:81
+msgid "Методы установки обработчиков"
+msgstr "Handler Setup Methods"
+
+#: ../../root/api/app/index.rst:83
+msgid ""
+"``App`` позволяет настраивать реакцию на различные события, такие как "
+"ошибки ввода или неизвестные команды."
+msgstr ""
+"``App`` allows you to configure responses to various events, such as "
+"input errors or unknown commands."
+
+#: ../../root/api/app/index.rst:86
+msgid ""
+"Подробнее об исключениях и их обработке в соответствующем :ref:`разделе "
+"документации <root_error_handling>`."
+msgstr ""
+"For more details on exceptions and their handling, see the corresponding "
+":ref:`documentation section <root_error_handling>`."
+
+#: ../../root/api/app/index.rst:92
+msgid "Устанавливает шаблон для форматирования описания команды."
+msgstr "Sets the template for formatting command descriptions."
+
+#: ../../root/api/app/index.rst:94
+msgid "Обработчик принимает триггер команды (``str``) и её описание (``str``)."
+msgstr ""
+"The handler accepts the command trigger (``str``) and its description "
+"(``str``)."
+
+#: ../../root/api/app/index.rst:100
+msgid "Устанавливает обработчик при некорректном введённом синтаксисе флагов."
+msgstr "Sets the handler for incorrect flag syntax input."
+
+#: ../../root/api/app/index.rst:102 ../../root/api/app/index.rst:110
+msgid "Обработчик принимает строку, введённую пользователем."
+msgstr "The handler accepts the string entered by the user."
+
+#: ../../root/api/app/index.rst:108
+msgid "Устанавливает обработчик при повторяющихся флагах в введённой команде."
+msgstr "Sets the handler for duplicate flags in the entered command."
+
+#: ../../root/api/app/index.rst:116
+msgid "Устанавливает обработчик при вводе неизвестной команды."
+msgstr "Sets the handler for entering an unknown command."
+
+#: ../../root/api/app/index.rst:118
+msgid "Обработчик принимает объект ``InputCommand`` - объект введённой команды."
+msgstr ""
+"The handler accepts an ``InputCommand`` object - the entered command "
+"object."
+
+#: ../../root/api/app/index.rst:124
+msgid "Устанавливает обработчик при вводе пустой строки."
+msgstr "Sets the handler for entering an empty string."
+
+#: ../../root/api/app/index.rst:126
+msgid "Обработчик не принимает аргументов."
+msgstr "The handler accepts no arguments."
+
+#: ../../root/api/app/index.rst:132
+msgid "Переопределяет стандартное поведение при вызове команды выхода."
+msgstr "Overrides the default behavior when the exit command is invoked."
+
+#: ../../root/api/app/index.rst:134
+msgid "Обработчик принимает объект ``Response``."
+msgstr "The handler accepts a ``Response`` object."
+
+#: ../../root/api/app/index.rst:147
+msgid "PredefinedMessages"
+msgstr "PredefinedMessages"
+
+#: ../../root/api/app/index.rst:149
+msgid ""
+"``PredefinedMessages`` — это контейнер, содержащий набор готовых к "
+"использованию сообщений. Они отформатированы с использованием синтаксиса "
+"``rich`` и предназначены для вывода стандартной информации, такой как "
+"подсказки по использованию."
+msgstr ""
+"``PredefinedMessages`` is a container containing a set of ready-to-use "
+"messages. They are formatted using ``rich`` syntax and are intended for "
+"displaying standard information, such as usage hints."
+
+#: ../../root/api/app/index.rst:151
+msgid "Рекомендуется использовать их при старте приложения."
+msgstr "It is recommended to use them when starting the application."
+
+#: ../../root/api/app/index.rst:178
+msgid "Строка: ``[b dim]Usage[/b dim]: [i]<command> <[green]flags[/green]>[/i]``"
+msgstr "String: ``[b dim]Usage[/b dim]: [i]<command> <[green]flags[/green]>[/i]``"
+
+#: ../../root/api/app/index.rst:180
+msgid "Отображается как: ``Usage: <command> <flags>``"
+msgstr "Displayed as: ``Usage: <command> <flags>``"
+
+#: ../../root/api/app/index.rst:184
+msgid "Строка: ``[b dim]Help[/b dim]: [i]<command>[/i] [b red]--help[/b red]``"
+msgstr "String: ``[b dim]Help[/b dim]: [i]<command>[/i] [b red]--help[/b red]``"
+
+#: ../../root/api/app/index.rst:186
+msgid "Отображается как: ``Help: <command> --help``"
+msgstr "Displayed as: ``Help: <command> --help``"
+
+#: ../../root/api/app/index.rst:190
+msgid "Строка: ``[b dim]Autocomplete[/b dim]: [i]<part>[/i] [bold]<tab>``"
+msgstr "String: ``[b dim]Autocomplete[/b dim]: [i]<part>[/i] [bold]<tab>``"
+
+#: ../../root/api/app/index.rst:192
+msgid "Отображается как: ``Autocomplete: <part> <tab>``"
+msgstr "Displayed as: ``Autocomplete: <part> <tab>``"
+