docs and fix

docs/code_snippets/orchestrator_snippet.py

@@ -0,0 +1,26 @@
+import sqlite3
+from sqlite3 import Connection
+from typing import Iterable
+
+from dishka import Provider, Scope, provide
+
+from argenta import App, Orchestrator
+
+
+class ConnectionProvider(Provider):
+    @provide(scope=Scope.REQUEST)
+    def new_connection(self) -> Iterable[Connection]:
+        conn = sqlite3.connect(":memory:")
+        yield conn
+        conn.close()
+
+# 2. Создаем и настраиваем App
+app = App()
+# ... здесь можно добавить роутеры ...
+
+# 3. Создаем Orchestrator, передавая наш провайдер
+orchestrator = Orchestrator(custom_providers=[ConnectionProvider()])
+
+# 4. Запускаем приложение
+if __name__ == "__main__":
+    orchestrator.start_polling(app)

docs/root/api/app/autocompleter.rst

@@ -46,6 +46,6 @@ AutoCompleter
 
 ``AutoCompleter`` передается как аргумент при инициализации `App`.
 
-.. literalinclude:: ../../../code_snippets/autocompleter_example_sample.py
+.. literalinclude:: ../../../code_snippets/autocompleter_snippet.py
     :language: python
     :linenos:

docs/root/api/app/dividing_lines.rst

@@ -70,6 +70,6 @@ Dividing Lines
 Пример конфигурации
 --------------------
 
-.. literalinclude:: ../../../code_snippets/dividing_lines_example_sample.py
+.. literalinclude:: ../../../code_snippets/dividing_lines_snippet.py
     :language: python
     :linenos:

docs/root/api/orchestrator/argparser.rst

@@ -1,6 +1,93 @@
 .. _root_api_orchestrator_argparser:
 
 Argparser
-****************
+==========
+
+Объект ``ArgParser`` в ``Argenta`` предназначен для разбора и обработки **аргументов командной строки**, которые передаются вашему приложению при его запуске. Важно не путать их с командами, которые пользователь вводит в интерактивном режиме работы приложения. `ArgParser` позволяет вашему приложению получать внешнюю конфигурацию в момент старта, например, путь к файлу настроек, флаги для отладки или режим запуска.
+
+-----
+
+Инициализация
+-------------
+
+.. code-block:: python
+
+   def __init__(self, processed_args: list[argenta.orchestrator.InputArgument] = []) -> None
+
+Создает экземпляр парсера аргументов командной строки.
+
+* ``processed_args``: Список аргументов, которые будут обрабатываться и парситься при запуске приложения.
+
+Основные методы
+---------------
+
+.. py:method:: parse(self) -> dict[str, str | list[str]]
+
+   Основной метод, который выполняет разбор списка `processed_args`. Он анализирует аргументы и преобразует их в структурированный словарь.
+
+   *   Аргументы, имеющие вид флага (например, `--verbose`), получают значение `True`.
+   *   Аргументы, за которыми следует значение (например, `--config settings.yaml`), сохраняются как пара "ключ-значение".
+   *   Если один и тот же аргумент встречается несколько раз, его значения могут быть собраны в список.
+
+   :returns: Словарь, где ключи — это имена аргументов, а значения — их соответствующие значения.
+
+.. py:method:: get(self, key: str, default: str | None = None) -> str | None
+
+   Удобный метод для получения значения конкретного аргумента по его имени (ключу). Если аргумент не был найден, возвращается значение `default`.
+
+   :param key: Имя аргумента (например, `"--config"`).
+   :param default: Значение, которое будет возвращено, если аргумент `key` отсутствует. По умолчанию `None`.
+   :returns: Значение аргумента или значение по умолчанию.
+
+.. py:method:: all_args(self) -> list[str]
+
+   Возвращает список всех имен (ключей) аргументов, которые были распознаны парсером после вызова метода `parse()`.
+
+Назначение и интеграция
+------------------------
+
+`ArgParser` является неотъемлемой частью `Orchestrator`. При создании `Orchestrator` ему передается экземпляр `ArgParser`, который обычно инициализируется с `sys.argv[1:]`.
+
+После этого `Orchestrator` помещает `ArgParser` в DI-контейнер. Это означает, что любой ваш сервис или обработчик команды может запросить `ArgParser` через внедрение зависимостей и получить доступ к стартовым аргументам приложения. Это предпочтительный способ для конфигурации компонентов на основе параметров запуска.
+
+Пример использования
+--------------------
+
+.. code-block:: python
+
+    import sys
+    from argenta.orchestrator import Orchestrator
+    from argenta.orchestrator.argparser import ArgParser
+    from argenta.app import App
+    from dishka import Provider, Scope, provide
+
+    # 1. Создаем парсер на основе реальных аргументов командной строки
+    # Например, если запустить: python main.py --config prod.json --debug
+    arg_parser = ArgParser(processed_args=sys.argv[1:])
+
+    # 2. Определяем сервис, который будет использовать эти аргументы
+    class Settings:
+        def __init__(self, config_path: str, is_debug: bool):
+            self.config_path = config_path
+            self.is_debug = is_debug
+
+    class SettingsProvider(Provider):
+        @provide(scope=Scope.APP)
+        def get_settings(self, parser: ArgParser) -> Settings:
+            # Запрашиваем ArgParser из DI и используем его для конфигурации
+            path = parser.get('--config', default='default.json')
+            debug_mode = bool(parser.get('--debug'))
+            return Settings(config_path=path, is_debug=debug_mode)
+
+    # 3. Создаем Orchestrator, передавая ему парсер и провайдер
+    app = App()
+    orchestrator = Orchestrator(
+        arg_parser=arg_parser,
+        custom_providers=[SettingsProvider()]
+    )
+
+    # 4. Запускаем приложение
+    if __name__ == "__main__":
+        orchestrator.start_polling(app)
+
 
-nu

docs/root/api/orchestrator/index.rst

@@ -1,7 +1,69 @@
 .. _root_api_orchestrator_index:
 
 Orchestrator
-****************
+====================
+
+Объект ``Orchestrator`` в ``Argenta`` представляет собой высокоуровневый компонент, который стоит над ``App`` и отвечает за "оркестрацию" всего приложения. Его главная задача — инициализация и конфигурация сложных систем, таких как внедрение зависимостей (``di``), парсинг аргументов командной строки при запуске, и запуск основного цикла приложения.
+
+В то время как ``App`` отвечает за интерактивную сессию (ввод команд, роутинг), ``Orchestrator`` подготавливает окружение, в котором ``App`` будет работать. Он является точкой входа для приложений.
+
+-----
+
+Инициализация
+-------------
+
+.. code-block:: rust
+   :linenos:
+
+   DEFAULT_ARGPARSER: ArgParser = ArgParser(processed_args=[])
+
+   
+.. code-block:: python
+      :linenos:
+   
+      def __init__(self, arg_parser: ArgParser = DEFAULT_ARGPARSER, 
+                   custom_providers: list[Provider] = [], 
+                   auto_inject_handlers: bool = True) -> None
+
+Создает и конфигурирует экземпляр ``Orchestrator``.
+
+* ``arg_parser``: Экземпляр :class:`argenta.orchestrator.argparser.ArgParser`, который отвечает за парсинг аргументов, переданных скрипту при запуске из командной строки (не путать с командами, вводимыми в интерактивном режиме).
+* ``custom_providers``: Список пользовательских провайдеров ``dishka.Provider``. Это основной механизм для добавления ваших собственных сервисов (например, подключений к базе данных, клиентов API) в контейнер внедрения зависимостей.
+* ``auto_inject_handlers``: Если **True** (по умолчанию), ``dishka`` будет автоматически инспектировать сигнатуры обработчиков команд и внедрять в них требуемые зависимости из контейнера.
+
+-----
+
+Основные методы
+--------------
+
+.. py:method:: start_polling(self, app: App) -> None
+
+   Это главный метод, который запускает все приложение. Он выполняет следующие шаги:
+
+   1.  **Настройка DI**: На основе системного провайдера (``SystemProvider``, который предоставляет ``ArgParser``) и списка ``custom_providers`` создается ``ioc`` - контейнер и настраивается внедрение зависимостей.
+   
+   3.  **Запуск основного цикла**: Запускает бесконечный цикл ожидания и обработки пользовательского ввода.
+
+   :param app: Экземпляр класса :class:`~argenta.app.models.App`, который будет запущен.
+
+-----
+   
+Назначение и использование
+--------------------------
+
+``Orchestrator`` абстрагирует от вас всю сложность, связанную с настройкой внедрения зависимостей и парсингом стартовых аргументов. Типичный сценарий использования ``Argenta`` выглядит следующим образом:
+
+1.  Создать экземпляр ``App`` и настроить его (добавить роутеры).
+2.  Создать экземпляр ``Orchestrator``, передав в него необходимые DI-провайдеры и, возможно, парсер аргументов.
+3.  Вызвать ``orchestrator.start_polling(app)``, чтобы запустить приложение.
+
+Такой подход позволяет сохранить код чистым и разделяет ответственность: ``App`` отвечает за логику интерактивной сессии, а ``Orchestrator`` — за подготовку и запуск окружения.
+
+Пример использования
+--------------------
+
+.. literalinclude:: ../../../code_snippets/orchestrator_snippet.py
+   :language: python
 
 .. toctree::
     :hidden:

docs/root/api/router.rst

@@ -13,6 +13,7 @@ Router
 -------------
 
 .. code-block:: python
+   :linenos:
 
       __init__(self, title: str | None = None, 
                disable_redirect_stdout: bool = False) -> None
@@ -38,6 +39,7 @@ Router
    **Пример использования:**
 
    .. literalinclude:: ../../code_snippets/router_snippet.py
+      :linenos:
       :language: python
       
 -----
@@ -62,7 +64,7 @@ Router
 
 .. py:exception:: TriggerContainSpacesException
 
-   Выбрасывается, если триггер команды, передаваемый в `Command`, содержит пробелы. Триггеры команд должны быть одним словом.
+   Выбрасывается, если триггер команды, передаваемый в ``Command``, содержит пробелы. Триггеры команд должны быть одним словом.
 
    **Неправильно:** ``Command("add user")``
    **Правильно:** ``Command("add-user")``
@@ -74,16 +76,14 @@ Router
    **Пример, вызывающий исключение:**
 
    .. code-block:: python
+      :linenos:
 
       Command("send", flags=[
-          Flag("message", short_name="m"),
-          Flag("recipient", short_name="m")  # Ошибка: short_name 'm' повторяется
+          Flag("recipient"),
+          Flag("recipient") 
       ])
 
 .. py:exception:: RequiredArgumentNotPassedException
 
-   Это исключение выбрасывается на этапе выполнения, а не регистрации. Оно возникает, если обработчик команды ожидает обязательный аргумент, который не был предоставлен при вызове.
-
-   .. note::
-      Это исключение, как правило, должно перехватываться и обрабатываться внутри `Orchestrator` для вывода пользователю сообщения об ошибке, а не приводить к падению всего приложения.
+   Это исключение возникает, если какой-либо обработчик команды не ожидает обязательный аргумент, которым является объект ответа(``Response``).
 

docs/root/dependency_injection.rst

@@ -18,19 +18,19 @@
 .. note::
    ``argenta.di.FromDishka`` это алиас к ``dishka.FromDishka``, они полностью взаимозаменяемы.
 
-.. literalinclude:: ../code_snippets/dependency_injection_example_sample.py
+.. literalinclude:: ../code_snippets/dependency_injection_snippet.py
    :language: python
    :linenos:
 
 ``Argenta`` -> ``dishka`` зарезолвит тайпхинты и внедрит зависимость с возвращаемым типом ``Connection``, прежде чем использовать зависимость её нужно создать, для этого нужно создать соответствующий провайдер.
 
-.. literalinclude:: ../code_snippets/dependency_injection_example_sample2.py
+.. literalinclude:: ../code_snippets/dependency_injection_snippet2.py
    :language: python
    :linenos:
    
 После создания провайдера, его нужно зарегистрировать в оркестраторе.
 
-.. literalinclude:: ../code_snippets/dependency_injection_example_sample3.py
+.. literalinclude:: ../code_snippets/dependency_injection_snippet3.py
    :language: python
    :linenos:
 
@@ -49,7 +49,7 @@
 
 Краткий сэмпл кода, который получает объект ``ArgSpace`` и выводит в консоль аргумент с именем "type":
 
-.. literalinclude:: ../code_snippets/dependency_injection_example_sample4.py
+.. literalinclude:: ../code_snippets/dependency_injection_snippet4.py
    :language: python
    :linenos:
 

docs/root/error_handling.rst

@@ -17,7 +17,7 @@
 Краткий сэмпл кода, переопределяющего хэндлер ввода
 пустой команды
 
-.. literalinclude:: ../code_snippets/error_handling_example_sample.py
+.. literalinclude:: ../code_snippets/error_handling_snippet.py
     :language: python
     :linenos:
 
@@ -46,7 +46,7 @@
 
 Сэмпл кода, переопределяющего хэндлер ввода команды с некорректным синтаксисом:
 
-.. literalinclude:: ../code_snippets/error_handling_example_sample2.py
+.. literalinclude:: ../code_snippets/error_handling_snippet2.py
    :language: python
    :linenos:
 
@@ -73,7 +73,7 @@
 
 Сэмпл кода, переопределяющего хэндлер ввода команды с повторяющимися флагами:
 
-.. literalinclude:: ../code_snippets/error_handling_example_sample3.py
+.. literalinclude:: ../code_snippets/error_handling_snippet3.py
    :language: python
    :linenos:
 
@@ -96,7 +96,7 @@
 
 Сэмпл кода, переопределяющего хэндлер ввода пустой команды:
 
-.. literalinclude:: ../code_snippets/error_handling_example_sample4.py
+.. literalinclude:: ../code_snippets/error_handling_snippet4.py
     :language: python
     :linenos:
 
@@ -120,7 +120,7 @@
 
 Сэмпл кода, переопределяющего хэндлер ввода неизвестной команды:
 
-.. literalinclude:: ../code_snippets/error_handling_example_sample5.py
+.. literalinclude:: ../code_snippets/error_handling_snippet5.py
     :language: python
     :linenos:
 
@@ -143,6 +143,6 @@
 
 Сэмпл кода, переопределяющего хэндлер ввода команды выхода:
 
-.. literalinclude:: ../code_snippets/error_handling_example_sample6.py
+.. literalinclude:: ../code_snippets/error_handling_snippet6.py
     :language: python
     :linenos: