docs

docs/root/dependency_injection.rst

@@ -1,6 +1,61 @@
 .. _root_dependency_injection:
 
 Внедрение зависимостей
-****************************
+=======================
 
-мда мда мда
+Внедрение зависимостей (Dependency Injection, DI) — это паттерн проектирования, который помогает писать слабосвязанный, легко тестируемый и расширяемый код. Вместо того чтобы хендлеры сами создавали нужные им объекты (зависимости) они лишь объявляют о необходимости в их получении, а ``Argenta`` "внедряет" их в хендлеры в момент вызова.
+
+``Argenta`` использует популярную библиотеку ``dishka`` для реализации DI, что позволяет вам декларативно объявлять зависимости прямо в сигнатурах ваших хендлеров.
+Более подробно про ``DI``, ``IoC``, ``API`` создания провайдеров и другое вы можете прочитать тут_.
+
+.. _тут : https://dishka.readthedocs.io/en/stable/di_intro.html
+
+Основная идея
+-------------
+
+Представьте, что вашему хендлеру для работы нужен доступ к базе данных. Вместо того чтобы импортировать и инициализировать соединение внутри функции, вы просто объявляете его как аргумент с тайп-хинтом:
+
+.. note::
+   ``argenta.di.FromDishka`` это алиас к ``dishka.FromDishka``, они полностью взаимозаменяемы.
+
+.. literalinclude:: ../code_snippets/dependency_injection_example_sample.py
+   :language: python
+
+``Argenta`` -> ``dishka`` зарезолвит тайпхинты и внедрит зависимость с возвращаемым типом ``Connection``, прежде чем использовать зависимость её нужно создать, для этого нужно создать соответствующий провайдер.
+
+.. literalinclude:: ../code_snippets/dependency_injection_example_sample2.py
+   :language: python
+   
+После создания провайдера, его нужно зарегистрировать в оркестраторе.
+
+.. literalinclude:: ../code_snippets/dependency_injection_example_sample3.py
+   :language: python
+
+Как это работает?
+-----------------
+
+В основе DI в Argente лежат **провайдеры** и **контейнер**.
+
+*   **Провайдер (Provider)** — это "рецепт", который объясняет, как создавать и настраивать ту или иную зависимость (например, подключение к БД, API-клиент или любой другой сервис).
+*   **Контейнер (IoC Container)** — это "фабрика", которая хранит все рецепты (провайдеры) и по запросу создаёт и выдаёт готовые зависимости.
+
+Встроенные провайдеры
+-----------------------
+
+``Argenta`` поставляется с предопределённым провайдером, который даёт доступ к важным системным зависимостям без какой-либо настройки. К примеру вы можете получить объект ``ArgSpace``, который представляет из себя распаршенные аргументы командной строки при запуске приложения.
+
+Краткий сэмпл кода, который получает объект ``ArgSpace`` и выводит в консоль аргумент с именем "type":
+
+.. literalinclude:: ../code_snippets/dependency_injection_example_sample4.py
+   :language: python
+
+Обмен данными между хендлерами
+------------------------------
+
+Помимо DI, хендлеры могут общаться друг с другом в контексте приложения через **объект контекста** (в ``Argenta`` эту роль выполняет объект ``Response``).
+
+Каждый хендлер может записывать данные, читать, обновлять и удалять.
+
+.. seealso::
+
+   Подробнее об этом можно прочитать в разделе :ref:`root_api_response`.