docs

2026-06-10 10:05:28 +03:00 · 2025-10-20 16:38:17 +03:00
parent 6fa431a27a
commit 9ac24926af
13 changed files with 1490 additions and 70 deletions
@@ -1,7 +1,101 @@
 .. _root_api_app_index:

 App
-****************
+===
+
+Объект ``App`` является центральной сущностью библиотеки ``Argenta``. Он выступает в роли ядра вашего консольного приложения, отвечая за его конфигурацию, управление жизненным циклом, обработку команд и взаимодействие с пользователем. ``App`` координирует работу всех остальных компонентов, таких как роутеры, обработчики команд и системные сообщения.
+
+------
+
+Инициализация
+-------------
+
+.. code:: rust
+
+    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:: python
+    
+    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: bool = True, 
+                override_system_messages: bool = False, 
+                autocompleter: AutoCompleter = DEFAULT_AUTOCOMPLETER, 
+                print_func: Printer = DEFAULT_PRINT_FUNC) -> None
+
+Создает и настраивает экземпляр приложения `Argenta`.
+
+    * ``prompt``:  Строка-приглашение, которая отображается перед вводом каждой команды. По умолчанию: **"What do you want to do?\\n\\n"**.
+    * ``initial_message``: Приветственное сообщение, которое выводится при запуске приложения.
+    * ``farewell_message``: Прощальное сообщение при завершении работы приложения.
+    * ``exit_command``: Сущность команды, которая будет маркирована как команда для выхода из приложения.
+    * ``system_router_title``: Заголовок для системного роутера, который содержит команду выхода и другие системные команды.
+    * ``ignore_command_register``: Если **True** (по умолчанию), регистр введенных команд будет игнорироваться при поиске обработчика.
+    * ``dividing_line``: Объект, управляющий стилем разделительной линии. Может быть **StaticDividingLine** или **DynamicDividingLine**.
+    * ``repeat_command_groups``: Если **True** (по умолчанию), описание доступных команд будет выводиться перед каждым вводом.
+    * ``override_system_messages``: Если **True** (по умолчанию), стандартное форматирование системных сообщений (цвета, ASCII-арт) будет отключено.
+    * ``autocompleter``: Объект, отвечающий за логику автодополнения команд.
+    * ``print_func``: Функция, используемая для вывода всех системных сообщений. По умолчанию используется ``rich.console.Console().print``.
+
+Основные методы
+---------------
+
+.. py:method:: include_router(self, router: Router) -> None
+
+   Регистрирует один `Router` в приложении. Все команды, определенные в этом роутере, становятся доступными для вызова.
+
+   :param router: Объект роутера, который нужно зарегистрировать.
+
+.. py:method:: include_routers(self, *routers: Router) -> None
+
+   Регистрирует несколько роутеров одновременно. Является удобной оберткой над `include_router`.
+
+   :param routers: Последовательность объектов `Router` для регистрации.
+
+.. py:method:: add_message_on_startup(self, message: str) -> None
+
+   Добавляет дополнительное текстовое сообщение, которое будет выведено на экран при запуске приложения, сразу после `initial_message`.
+
+   :param message: Строка с сообщением.
+
+Методы установки обработчиков
+-------------------------------
+
+`App` позволяет гибко настраивать реакцию на различные события, такие как ошибки ввода или ввод неизвестной команды.
+
+.. py:method:: set_description_message_pattern(self, handler: DescriptionMessageGenerator) -> None
+
+   Устанавливает пользовательский шаблон для форматирования строки, описывающей доступную команду (триггер + описание).
+
+.. py:method:: set_incorrect_input_syntax_handler(self, handler: NonStandardBehaviorHandler[str]) -> None
+
+   Устанавливает обработчик, который вызывается при некорректном синтаксисе флагов в введенной команде.
+
+.. py:method:: set_repeated_input_flags_handler(self, handler: NonStandardBehaviorHandler[str]) -> None
+
+   Устанавливает обработчик для ситуации, когда пользователь вводит один и тот же флаг несколько раз.
+
+.. py:method:: set_unknown_command_handler(self, handler: NonStandardBehaviorHandler[InputCommand]) -> None
+
+   Устанавливает обработчик, который срабатывает, если введенная команда не была найдена ни в одном из зарегистрированных роутеров.
+
+.. py:method:: set_empty_command_handler(self, handler: EmptyCommandHandler) -> None
+
+   Устанавливает обработчик для случая, когда пользователь отправляет пустую строку вместо команды.
+
+.. py:method:: set_exit_command_handler(self, handler: NonStandardBehaviorHandler[Response]) -> None
+
+   Позволяет переопределить стандартное поведение при вызове команды выхода. По умолчанию просто выводится `farewell_message`.

 .. toctree::
    :hidden:
@@ -1,20 +1,18 @@
 .. _root_api_command_flags:

 Flags
-****************
+======


-.. _root_api_command_flag:
-
 Flag
-****************
+=====


 InputFlags
-****************
+===========


 .. _root_api_command_input_flag:

 InputFlag
-****************
+==========
@@ -1,8 +1,21 @@
 .. _root_api_index:


-Публичный API
-****************
+Публичное API
+=============
+
+Описание раздела
+----------------
+
+В данном разделе приводятся сведения о публичной части интерфейса библиотеки:
+
+- Классы и функции, предназначенные для прямой интеграции в сторонние приложения.
+- Советы по совместимости, ограничения и поддерживаемые сценарии использования.
+- Примеры типовой интеграции, подробные сигнатуры методов и описание возвращаемых сущностей.
+- Гарантии стабильности API, поддержка и обратная совместимость между версиями.
+
+Интерфейсы, не указанные в этом разделе, считаются внутренними и не подлежат использованию вне самой библиотеки. При разработке собственных решений рекомендуем обращаться именно к описанным здесь компонентам — это даст стабильность и гарантии на будущее развитие ваших продуктов с использованием ``Argenta``.
+

 .. toctree::
    :hidden:
@@ -12,3 +25,4 @@
    orchestrator/index
    command/index
    response
+    
@@ -15,7 +15,7 @@
   
   * Поставить звезду проекту
   * Написать о нем в ``Twitter``
-   * Ссылаться на этот проект в `Readme` вашего проекта
+   * Ссылаться на этот проект в ``Readme`` вашего проекта
   * Упомянуть проект на местных встречах и рассказать о нем друзьям/коллегам

 .. _Содержание:
@@ -53,7 +53,7 @@

   Если вы хотите задать вопрос, мы предполагаем, что вы уже ознакомились с доступной `Документацией <https://argenta.readthedocs.io>`_.

-Прежде чем задать вопрос, лучше всего поискать существующие `Issue <https://github.com/koloideal/Argenta/issues>`_, которые могут вам помочь. Если вы нашли подходящий ``issue``, но все еще нуждаетесь в разъяснениях, вы можете написать свой вопрос в этом ``issue``. Также рекомендуется сначала поискать ответы в интернете.
+Прежде чем задать вопрос, лучше всего поискать существующие `Issues <https://github.com/koloideal/Argenta/issues>`_, которые могут вам помочь. Если вы нашли подходящий ``issue``, но все еще нуждаетесь в разъяснениях, вы можете написать свой вопрос в этом ``issue``. Также рекомендуется сначала поискать ответы в интернете.

 Если после этого вы все еще чувствуете необходимость задать вопрос, мы рекомендуем следующее: