docs

docs/root/api/router.rst

@@ -1,4 +1,89 @@
 .. _root_api_router:
 
 Router
-****************
+=============
+
+Объект ``Router`` является фундаментальным строительным блоком для организации логики в приложении ``Argenta``. Его основная задача — группировать связанные команды и их обработчики. Каждый роутер представляет собой логический контейнер для определенного набора функциональности.
+
+Например, в приложении для управления пользователями один роутер может отвечать за команды, связанные с аутентификацией (``login``, ``logout``), а другой — за операции с профилем (``profile show``, ``profile edit``).
+
+-----
+
+Инициализация
+-------------
+
+.. code-block:: python
+
+      __init__(self, title: str | None = None, 
+               disable_redirect_stdout: bool = False) -> None
+
+Создает новый экземпляр маршрутизатора.
+
+* ``title`` : Необязательный заголовок для группы команд, которые регистрируются в этом роутере. Этот заголовок будет отображаться в списке доступных команд, помогая пользователю ориентироваться.
+* ``disable_redirect_stdout`` : Если установлено в ``True``, отключает механизм перехвата стандартного вывода (``stdout``) для всех команд этого роутера. Это необходимо для команд, которые требуют интерактивного ввода от пользователя (например, с помощью ``input()``). При отключении перехвата вывода автоматически используется статическая разделительная линия. Подробнее в :ref:`соответствующем разделе <root_redirect_stdout>`
+
+-----
+
+Регистрация команд
+------------------
+
+Для регистрации новой команды и привязки к ней функции-обработчика используется декоратор ``@command``.
+
+.. py:method:: @command(self, command: Command | str)
+
+   Декоратор для регистрации функции как обработчика для указанной команды.
+
+   :param command: Экземпляр класса ``argenta.command.Command``, описывающий триггер, флаги и описание команды. Также может быть просто строкой, которая будет являться триггером, в этом случае нет возможности настроить флаги, описание и всё остальное.
+
+   **Пример использования:**
+
+   .. literalinclude:: ../../code_snippets/router_snippet.py
+      :language: python
+      
+-----
+
+Системный роутер по умолчанию
+-----------------------------
+
+``Argenta`` поставляется со встроенным системным роутером, который автоматически подключается к каждому приложению.
+
+.. py:data:: system_router
+
+   Предопределенный экземпляр ``Router``, который содержит базовые системные команды. По умолчанию в него включена команда выхода из приложения (обычно **exit**). Он имеет заголовок **"System points:"**, который можно переопределить в инстансе приложения -> ``App``.
+
+   Вы можете добавлять свои команды в этот роутер, для этого импортируйте ``argenta.router.defaults.system_router`` и декорируйте его методом необходимые хэндлеры.
+
+-----   
+   
+Возможные исключения
+--------------------
+
+При регистрации команд и флагов в ``Router`` могут возникнуть следующие исключения, сигнализирующие о некорректной конфигурации:
+
+.. py:exception:: TriggerContainSpacesException
+
+   Выбрасывается, если триггер команды, передаваемый в `Command`, содержит пробелы. Триггеры команд должны быть одним словом.
+
+   **Неправильно:** ``Command("add user")``
+   **Правильно:** ``Command("add-user")``
+
+.. py:exception:: RepeatedFlagNameException
+
+   Возникает, если при определении флагов для одной команды были использованы дублирующиеся имена (как короткие, так и длинные). Каждое имя флага в рамках одной команды должно быть уникальным.
+
+   **Пример, вызывающий исключение:**
+
+   .. code-block:: python
+
+      Command("send", flags=[
+          Flag("message", short_name="m"),
+          Flag("recipient", short_name="m")  # Ошибка: short_name 'm' повторяется
+      ])
+
+.. py:exception:: RequiredArgumentNotPassedException
+
+   Это исключение выбрасывается на этапе выполнения, а не регистрации. Оно возникает, если обработчик команды ожидает обязательный аргумент, который не был предоставлен при вызове.
+
+   .. note::
+      Это исключение, как правило, должно перехватываться и обрабатываться внутри `Orchestrator` для вывода пользователю сообщения об ошибке, а не приводить к падению всего приложения.
+