.. _root_api_orchestrator_index:

Orchestrator
====================

``Orchestrator`` — это высокоуровневый компонент, который управляет жизненным циклом приложения. Его главная задача — инициализация и конфигурация окружения, включая внедрение зависимостей (DI), парсинг аргументов командной строки и запуск основного цикла `App`.

В то время как `App` отвечает за логику интерактивной сессии (ввод команд, маршрутизация), `Orchestrator` подготавливает окружение для его работы и служит точкой входа в приложение.

-----

Инициализация
-------------

.. code-block:: python
   :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``: Экземпляр `ArgParser`, отвечающий за парсинг аргументов командной строки при запуске скрипта (не путать с командами в интерактивном режиме).
* ``custom_providers``: Список пользовательских провайдеров `dishka.Provider` для добавления ваших сервисов (например, подключений к БД или API-клиентов) в DI-контейнер.
* ``auto_inject_handlers``: Если `True` (по умолчанию), `dishka` автоматически внедрит зависимости в обработчики команд, инспектируя их сигнатуры.

-----

Основные методы
----------------

.. py:method:: start_polling(self, app: App) -> None

   Это главный метод, который запускает приложение. Он выполняет следующие шаги:

   1.  **Настройка DI**: Создаёт DI-контейнер на основе системного провайдера (предоставляет `ArgParser`) и пользовательских `custom_providers`.
   2.  **Запуск основного цикла**: Запускает бесконечный цикл ожидания и обработки пользовательского ввода.

   :param app: Экземпляр `App`, который будет запущен.

-----
   
Назначение и использование
----------------------------

``Orchestrator`` абстрагирует сложность, связанную с настройкой DI и парсингом стартовых аргументов. Типичный сценарий использования выглядит так:

1.  Создайте и настройте экземпляр `App` (добавьте роутеры).
2.  Создайте экземпляр `Orchestrator`, передав в него DI-провайдеры.
3.  Вызовите `orchestrator.start_polling(app)`, чтобы запустить приложение.

Такой подход разделяет ответственности: `App` отвечает за логику интерактивной сессии, а `Orchestrator` — за подготовку и запуск окружения.

Пример использования
--------------------

.. literalinclude:: ../../../code_snippets/orchestrator/snippet.py
   :language: python

.. toctree::
    :hidden:

    argparser
    arguments
    argspace