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.
2026-06-10 10:05:28 +03:00 · 2025-12-04 21:55:19 +03:00
parent a2ac6a608f
commit ce7e24b924
210 changed files with 13770 additions and 1183 deletions
@@ -0,0 +1,49 @@
+.. _root_api_app_autocompleter:
+
+AutoCompleter
+=====================
+
+``AutoCompleter`` — это компонент, отвечающий за интерактивное автодополнение команд. Он улучшает пользовательский опыт, предлагая подсказки и завершая ввод на основе истории команд, что ускоряет работу и снижает вероятность опечаток.
+
+-----
+
+Инициализация
+-------------
+
+.. code-block:: python
+
+  __init__(self, history_filename: str | None = None, 
+           autocomplete_button: str = "tab") -> None
+
+Создаёт и настраивает экземпляр ``AutoCompleter``.
+
+* ``history_filename``: Имя файла для сохранения истории команд. Если указано, история будет сохраняться между сессиями. При значении ``None`` история хранится только в контексте сессии.
+* ``autocomplete_button``: Клавиша, активирующая автодополнение. По умолчанию — **Tab**.
+
+-----
+
+Назначение и возможности
+-------------------------
+
+Основные возможности ``AutoCompleter``:
+
+*   **Автодополнение по истории**: При нажатии клавиши автодополнения (по умолчанию **Tab**) система ищет в истории команды, начинающиеся с уже введённого текста.
+
+*   **Общий префикс**: Если найдено несколько команд с общим префиксом, будет подставлена только общая часть. Например, для команд ``show_users`` и ``show_profile`` при вводе ``sho`` и нажатии **Tab** ввод дополнится до ``show_``.
+
+*   **Постоянная история**: Если указан ``history_filename``, история команд сохраняется в файл при выходе и загружается при следующем запуске. Это делает автодополнение со временем «умнее».
+
+*   **Очистка истории**: При сохранении ``AutoCompleter`` удаляет дубликаты и несуществующие команды, поддерживая историю в актуальном состоянии.
+
+*   **Настройка клавиши**: Клавишу автодополнения можно изменить с помощью параметра ``autocomplete_button``.
+ 
+-----
+
+Пример использования
+--------------------
+
+``AutoCompleter`` передаётся как аргумент при инициализации `App`.
+
+.. literalinclude:: ../../../code_snippets/autocompleter/snippet.py
+    :language: python
+    :linenos:
@@ -0,0 +1,65 @@
+.. _root_api_app_dividing_lines:
+
+Dividing Lines
+==============
+
+Разделительные линии в ``Argenta`` используются для визуального структурирования вывода и отделения блоков информации друг от друга. Библиотека предлагает два типа линий: статическую и динамическую.
+
+-----
+
+``StaticDividingLine``
+----------------------
+
+``StaticDividingLine`` создаёт разделительную линию **фиксированной** длины. Этот тип линии полезен для создания предсказуемого и унифицированного интерфейса.
+
+.. code-block:: python
+   :linenos:
+   
+      def __init__(self, unit_part: str = "-", *, 
+                   length: int = 25) -> None
+
+Создаёт экземпляр статической разделительной линии.
+
+* ``unit_part``: Символ для построения линии (учитывается только первый символ). По умолчанию: ``-``.
+* ``length``: Фиксированная длина линии. По умолчанию: ``25``.
+
+-----
+
+``DynamicDividingLine``
+-----------------------
+
+``DynamicDividingLine`` создаёт линию, длина которой **динамически** подстраивается под самую длинную строку в выводе команды. Это требует перехвата ``stdout``, в результате чего разделители идеально обрамляют выводимый контент.
+
+.. code-block:: python
+  :linenos:
+
+   __init__(self, unit_part: str = "-") -> None
+
+Создаёт экземпляр динамической разделительной линии.
+
+* ``unit_part``: Символ для построения линии. По умолчанию: ``-``.
+
+Длина вычисляется автоматически и не задаётся при инициализации.
+
+.. warning::
+    Обязательно почитайте про нюансы использования динамических линий и перехвата ``stdout`` в :ref:`этом разделе<root_redirect_stdout>`.
+
+-----
+
+Назначение и использование
+---------------------------
+
+Выбор между статической и динамической линией зависит от ваших задач.
+
+*   **StaticDividingLine** идеально подходит, если:
+
+    *   Вам нужен строгий и консистентный дизайн.
+    *   Вы используете роутеры с отключённым перехватом ``stdout`` (``disable_redirect_stdout=True``), где динамическое вычисление длины невозможно.
+
+*   **DynamicDividingLine** (поведение по умолчанию) — предпочтительный выбор, если:
+
+    *   Вы хотите, чтобы интерфейс был адаптивным.
+    *   Вывод ваших команд имеет разную длину.
+    *   В ваших обработчиках нет интерактивных операций ввода (например, ``input()``).
+
+Тип разделителя для всего приложения задаётся при инициализации ``App`` через параметр ``dividing_line``.
@@ -0,0 +1,192 @@
+.. _root_api_app_index:
+
+App
+===
+
+Объект ``App`` — это ядро вашего консольного приложения. Он отвечает за конфигурацию, управление жизненным циклом, обработку команд и взаимодействие с пользователем, координируя работу всех компонентов: роутеров, обработчиков и системных сообщений.
+
+------
+
+Инициализация
+-------------
+
+.. code-block:: python
+   :linenos:
+
+    AVAILABLE_DIVIDING_LINES: TypeAlias = StaticDividingLine | DynamicDividingLine
+    DEFAULT_DIVIDING_LINE: StaticDividingLine = StaticDividingLine()
+    
+    DEFAULT_PRINT_FUNC: Printer = Console().print
+    DEFAULT_AUTOCOMPLETER: AutoCompleter = AutoCompleter()
+    DEFAULT_EXIT_COMMAND: Command = Command("Q", description="Exit command")
+
+.. code-block:: python
+    :linenos:
+    
+    def __init__(self, *, prompt: str = "What do you want to do?\n\n", 
+                initial_message: str = "Argenta\n", 
+                farewell_message: str = "\nSee you\n", 
+                exit_command: Command = DEFAULT_EXIT_COMMAND, 
+                system_router_title: str | None = "System points:", 
+                ignore_command_register: bool = True, 
+                dividing_line: AVAILABLE_DIVIDING_LINES = DEFAULT_DIVIDING_LINE, 
+                repeat_command_groups_printing: bool = True, 
+                override_system_messages: bool = False, 
+                autocompleter: AutoCompleter = DEFAULT_AUTOCOMPLETER, 
+                print_func: Printer = DEFAULT_PRINT_FUNC) -> None
+
+Создаёт и настраивает экземпляр приложения.
+
+    * ``prompt``: Приглашение к вводу, отображаемое перед каждой командой.
+    * ``initial_message``: Сообщение, выводимое при запуске приложения.
+    * ``farewell_message``: Сообщение, выводимое при выходе из приложения.
+    * ``exit_command``: Команда, которая маркируется как триггер для выхода из приложения.
+    * ``system_router_title``: Заголовок для системного роутера (содержит команду выхода).
+    * ``ignore_command_register``: Если ``True``, регистр вводимых команд игнорируется при поиске обработчика.
+    * ``dividing_line``: Тип разделительной линии (``StaticDividingLine`` или ``DynamicDividingLine``).
+    * ``repeat_command_groups_printing``: Если ``True``, список доступных команд выводится перед каждым вводом.
+    * ``override_system_messages``: Если ``True``, стандартное форматирование (цвета, ASCII-арт) отключается.
+    * ``autocompleter``: Экземпляр класса :ref:`AutoCompleter <root_api_app_autocompleter>`, отвечающий за автодополнение команд.
+    * ``print_func``: Функция для вывода всех системных сообщений (по умолчанию ``rich.Console().print``).
+
+-----
+    
+Основные методы
+---------------
+
+- .. py:method:: include_router(self, router: Router) -> None
+
+    Регистрирует роутер в приложении. Все команды из этого роутера становятся доступными для вызова.
+    
+    :param router: Экземпляр ``Router`` для регистрации.
+
+- .. py:method:: include_routers(self, *routers: Router) -> None
+
+    Регистрирует несколько роутеров одновременно.
+    
+    :param routers: Последовательность экземпляров ``Router`` для регистрации.
+
+- .. py:method:: add_message_on_startup(self, message: str) -> None
+
+    Добавляет текстовое сообщение, которое выводится при запуске приложения после ``initial_message``.
+
+    :param message: Строка с сообщением.
+
+    .. seealso::
+       Для вывода стандартных сообщений можно использовать готовые шаблоны из :ref:`PredefinedMessages <root_api_predefined_messages>`.
+    
+-----
+
+Методы установки обработчиков
+-------------------------------
+
+``App`` позволяет настраивать реакцию на различные события, такие как ошибки ввода или неизвестные команды.
+
+.. hint::
+   Подробнее об исключениях и их обработке в соответствующем :ref:`разделе документации <root_error_handling>`.
+   
+-----
+
+.. py:method:: set_description_message_pattern(self, handler: Callable[[str, str], str]) -> None
+
+   Устанавливает шаблон для форматирования описания команды.
+   
+   Обработчик принимает триггер команды (``str``) и её описание (``str``).
+   
+------
+
+.. py:method:: set_incorrect_input_syntax_handler(self, handler: Callable[[str], None]) -> None
+
+   Устанавливает обработчик при некорректном введённом синтаксисе флагов.
+   
+   Обработчик принимает строку, введённую пользователем.
+   
+------
+
+.. py:method:: set_repeated_input_flags_handler(self, handler: Callable[[str], None]) -> None
+
+   Устанавливает обработчик при повторяющихся флагах в введённой команде.
+   
+   Обработчик принимает строку, введённую пользователем.
+   
+------
+
+.. py:method:: set_unknown_command_handler(self, handler: Callable[[InputCommand], None]) -> None
+
+   Устанавливает обработчик при вводе неизвестной команды.
+   
+   Обработчик принимает объект ``InputCommand`` - объект введённой команды.
+   
+-----
+
+.. py:method:: set_empty_command_handler(self, handler: Callable[[], None]) -> None
+
+   Устанавливает обработчик при вводе пустой строки.
+   
+   Обработчик не принимает аргументов.
+   
+-----
+
+.. py:method:: set_exit_command_handler(self, handler: Callable[[Response], None]) -> None
+
+   Переопределяет стандартное поведение при вызове команды выхода.
+   
+   Обработчик принимает объект ``Response``.
+
+.. toctree::
+    :hidden:
+
+    autocompleter
+    dividing_lines
+
+-----
+
+.. _root_api_predefined_messages:
+
+PredefinedMessages
+------------------
+
+``PredefinedMessages`` — это контейнер, содержащий набор готовых к использованию сообщений. Они отформатированы с использованием синтаксиса ``rich`` и предназначены для вывода стандартной информации, такой как подсказки по использованию.
+
+Рекомендуется использовать их при старте приложения.
+
+.. code-block:: python
+   :linenos:
+
+   from argenta import App, Orchestrator
+   from argenta.app import PredefinedMessages
+
+   app: App = App()
+   orchestrator: Orchestrator = Orchestrator()
+
+   def main():
+      app.add_message_on_startup(PredefinedMessages.USAGE)
+      app.add_message_on_startup(PredefinedMessages.AUTOCOMPLETE)
+      app.add_message_on_startup(PredefinedMessages.HELP)
+
+      orchestrator.start_polling(app)
+
+   if __name__ == "__main__":
+      main()
+    
+
+.. py:class:: PredefinedMessages
+   :no-index:
+
+   .. py:attribute:: USAGE
+
+      Строка: ``[b dim]Usage[/b dim]: [i]<command> <[green]flags[/green]>[/i]``
+
+      Отображается как: ``Usage: <command> <flags>``
+
+   .. py:attribute:: HELP
+
+      Строка: ``[b dim]Help[/b dim]: [i]<command>[/i] [b red]--help[/b red]``
+
+      Отображается как: ``Help: <command> --help``
+
+   .. py:attribute:: AUTOCOMPLETE
+
+      Строка: ``[b dim]Autocomplete[/b dim]: [i]<part>[/i] [bold]<tab>``
+
+      Отображается как: ``Autocomplete: <part> <tab>``