docs

2026-06-10 10:05:28 +03:00 · 2025-11-07 21:25:35 +03:00
parent 16e7cc21fb
commit 8edd59c1b8
11 changed files with 48 additions and 78 deletions
@@ -3,10 +3,12 @@
 Внедрение зависимостей
 =======================

-Внедрение зависимостей (Dependency Injection, DI) — это паттерн проектирования, который помогает писать слабосвязанный, легко тестируемый и расширяемый код. Вместо того чтобы обработчики сами создавали нужные им объекты (зависимости), они лишь объявляют их в качестве аргументов. В момент вызова ``Argenta`` автоматически "внедряет" эти зависимости.
+Внедрение зависимостей (Dependency Injection, DI) — это паттерн проектирования, который помогает писать слабосвязанный, легко тестируемый и расширяемый код. Вместо того чтобы обработчики сами создавали нужные им объекты (зависимости), они получают их извне.

 ``Argenta`` использует библиотеку ``dishka`` для реализации DI, что позволяет декларативно объявлять зависимости прямо в сигнатурах ваших обработчиков.
-Подробнее о `DI`, `IoC` и API для создания провайдеров можно прочитать в `официальной документации dishka <https://dishka.readthedocs.io/en/stable/di_intro.html>`_.
+Подробнее о **DI**, **IoC** и API для создания провайдеров можно прочитать в `официальной документации dishka <https://dishka.readthedocs.io/en/stable/di_intro.html>`_.
+
+-----

 Основная идея
 -------------
@@ -14,7 +16,7 @@
 Представьте, что вашему обработчику для работы нужен доступ к базе данных. Вместо импорта и инициализации соединения внутри функции, вы просто объявляете его как аргумент с аннотацией типа:

 .. note::
-   ``argenta.di.FromDishka`` является псевдонимом для ``dishka.FromDishka``, и они полностью взаимозаменяемы.
+   ``argenta.di.FromDishka`` является алиасом для ``dishka.FromDishka``, и они полностью взаимозаменяемы.

 .. literalinclude:: ../code_snippets/dependency_injection/snippet.py
   :language: python
@@ -32,6 +34,8 @@
   :language: python
   :linenos:

+-----
+
 Как это работает?
 -----------------

@@ -40,6 +44,8 @@
 *   **Провайдер (Provider)** — это "рецепт", который объясняет, как создавать и настраивать ту или иную зависимость (например, подключение к БД, API-клиент или любой другой сервис).
 *   **Контейнер (IoC Container)** — это "фабрика", которая хранит все рецепты (провайдеры) и по запросу создаёт и выдаёт готовые зависимости.

+-----
+
 Встроенные провайдеры
 -----------------------

@@ -50,14 +56,15 @@
 .. literalinclude:: ../code_snippets/dependency_injection/snippet4.py
   :language: python
   :linenos:
+   
+-----

 Обмен данными между хендлерами
 ------------------------------

-Помимо DI, обработчики могут обмениваться данными в рамках сессии через **объект контекста**. В ``Argenta`` эту роль выполняет объект ``Response``.
+Помимо DI, обработчики могут обмениваться данными в рамках сессии через **объект контекста**. В ``Argenta`` эту роль выполняет объект ``DataBridge``.

 Каждый обработчик может записывать в него данные, а также читать, обновлять и удалять их.

 .. seealso::
-
-   Подробнее об этом можно прочитать в разделе :ref:`root_api_response`.
+   Подробнее об этом можно прочитать в разделе :ref:`root_api_bridge`.
@@ -29,14 +29,10 @@
 Кастомизация вывода
 -------------------

-Для полной замены логики вывода в конструкторе ``App`` предусмотрен параметр ``print_func``.
+Для полной замены логики вывода текста в конструкторе ``App`` предусмотрен параметр ``print_func``.

 *   **print_func**: ``Callable[[str], None]``
-    Этот параметр позволяет передать любую вызываемую сущность (например, функцию), которая будет использоваться для вывода всех системных сообщений. По умолчанию это обёртка над ``rich.console.Console().print``. Вы можете передать сюда свою функцию, чтобы, например, логировать вывод в файл или отправлять его по сети.
+    Этот параметр позволяет передать любую вызываемую сущность (например, функцию), которая будет использоваться для вывода всех системных сообщений. По умолчанию это ``rich.console.Console().print``. Вы можете передать сюда свою функцию, чтобы, например, логировать вывод в файл или отправлять его по сети.

-Пример использования
--------------------
-
-.. literalinclude:: ../code_snippets/overriding_formatting/sample.py
-   :language: python
-   :linenos:
+.. important::
+   При переопределении функции вывода вам следует убедиться, что она поддерживает разметку ``rich``, иначе системные сообщения будут выводиться в сыром виде, в этом случае рекомендуется переопределить стандартное форматирование с помощью ``override_system_messages=True``.
@@ -14,14 +14,14 @@

 Пример приложения с динамической разделительной линией:

-.. image:: https://i.ibb.co/ZptzLJ1n/2025-11-03-121308.png
+.. image:: https://i.ibb.co/yn9rWnNC/2025-11-07-180751.png
  :alt: Example of an application with a dynamic dividing line

 Как вы можете заметить разделительная линия ровно той же длины, что и самая длинная строка в выводе.

 То же приложение с статической линией:

-.. image:: https://i.ibb.co/YFGRY2c0/2025-11-03-121650.png
+.. image:: https://i.ibb.co/P8B4xyp/2025-11-07-180330.png
  :alt: Example of an application with a static dividing line

 В этом примере разделительная линия имеет фиксированную длину (по умолчанию 25 символов).
@@ -31,7 +31,7 @@
 Побочные эффекты перехвата ``stdout``
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

-Главный побочный эффект этого механизма проявляется при использовании функций, которые одновременно ожидают ввод от пользователя и выводят приглашение в консоль. Классический пример — стандартная функция ``input()``.
+Побочный эффект этого механизма проявляется при использовании функций, которые последовательно выводят текст в консоль и ожидают ввод от пользователя. Классический пример — стандартная функция ``input()``.

 .. code-block:: python
    :linenos:
@@ -41,7 +41,7 @@
    print(f"Привет, {user_name}!")

 .. warning::
-   При включённом перехвате ``stdout`` текст-приглашение (например, ``"Введите ваше имя: "``) **не будет выведен в консоль немедленно**. Он попадёт в буфер, и пользователь увидит только мигающий курсор. Текст приглашения отобразится лишь после завершения работы обработчика вместе с остальным выводом. Это может сбить пользователя с толку.
+   При включённом перехвате ``stdout`` текст (например, ``"Введите ваше имя: "``) **не будет выведен в консоль немедленно**. Он попадёт в буфер и отобразится лишь после завершения работы обработчика вместе с остальным выводом. Это может сбить пользователя с толку.

 -----

@@ -72,9 +72,11 @@
 	*  Требует включённого перехвата ``stdout`` (``disable_redirect_stdout=False`` в роутере).

 2.  **StaticDividingLine(length: int = 25)**
-	*  Линия имеет фиксированную длину (по умолчанию 25 символов), которую можно задать через аргумент `length`.
+	*  Линия имеет фиксированную длину (по умолчанию 25 символов), которую можно задать через аргумент ``length``.
 	*  Используется принудительно для роутеров с ``disable_redirect_stdout=True``, так как без перехвата вывода невозможно определить динамическую длину.

+-----
+
 Настройка разделительной линии в `App`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~