docs

2026-06-10 10:05:28 +03:00 · 2025-11-02 18:34:33 +03:00
parent 6f90712a17
commit f0a18e89c8
9 changed files with 184 additions and 355 deletions
@@ -0,0 +1,60 @@
+.. _root_api_bridge:
+
+DataBridge
+==========
+
+`DataBridge` — это сущность, предоставляющая временное хранилище данных, которое существует в рамках одной сессии приложения (от запуска до выхода). Она предназначена для обмена данными между вызовами разных команд.
+
+Основной способ получения доступа к `DataBridge` — через систему внедрения зависимостей (DI).
+
+.. code-block:: python
+   :linenos:
+
+   from dishka.integrations.fastapi import FromDishka
+   from argenta.bridge import DataBridge
+
+   def my_handler(data_bridge: FromDishka[DataBridge]):
+       # ... ваш код
+
+**Практический пример: Аутентификация**
+
+Рассмотрим пример, где команда `login` сохраняет токен аутентификации, а команда `get-profile` использует его.
+
+.. literalinclude:: ../../code_snippets/response/data_sharing.py
+   :language: python
+   :linenos:
+
+**Как это работает:**
+
+1.  При вызове обработчика `dishka` автоматически внедряет экземпляр `DataBridge`.
+2.  Команда ``login --username <имя>`` вызывает `login_handler`, который через внедрённый `data_bridge` сохраняет токен.
+3.  Команда `get-profile` вызывает `get_profile_handler`, который так же получает `data_bridge` и извлекает из него токен.
+
+API класса
+-----------
+
+.. py:class:: DataBridge
+
+   .. py:method:: __init__(self, initial_data: dict | None = None)
+
+      Инициализирует хранилище. При использовании через DI вызывается автоматически.
+
+   .. py:method:: update(self, data: dict) -> None
+
+      Обновляет хранилище данными из словаря.
+
+   .. py:method:: get_all(self) -> dict
+
+      Возвращает все данные из хранилища.
+
+   .. py:method:: get_by_key(self, key: str) -> Any
+
+      Возвращает значение по ключу или `None`, если ключ не найден.
+
+   .. py:method:: delete_by_key(self, key: str) -> None
+
+      Удаляет значение по ключу. Вызывает `KeyError`, если ключ не найден.
+
+   .. py:method:: clear_all(self) -> None
+
+      Полностью очищает хранилище.
@@ -95,4 +95,5 @@
    router
    orchestrator/index
    command/index
-    response
+    response
+    bridge
@@ -5,7 +5,6 @@ Response

 `Response` — это объект, который передаётся в обработчик команды. Он создаётся автоматически при обработке пользовательского ввода и содержит статус валидации, введённые флаги, а также предоставляет механизм для обмена данными между обработчиками.

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

 .. seealso::

@@ -57,99 +56,6 @@ Response

 -----

-Методы DataBridge
-
-`Response` наследует от `DataBridge` методы для работы с глобальным хранилищем, которое позволяет обмениваться данными между обработчиками в рамках одной сессии.
-
-update_data
-~~~~~~~~~~~
-
-.. code-block:: python
-   :linenos:
-
-   @classmethod
-   update_data(cls, data: dict[str, Any]) -> None
-
-Обновляет глобальное хранилище, добавляя или изменяя значения из переданного словаря.
-
-:param data: Словарь с данными для обновления хранилища
-:return: None
-
-Метод объединяет переданный словарь с данными в хранилище. Если ключ уже существует, его значение обновляется.
-
-**Пример использования:**
-
-.. literalinclude:: ../../code_snippets/response/snippet2.py
-   :linenos:
-   :language: python
-
-----
-
-get_data
-~~~~~~~~
-
-.. code-block:: python
-   :linenos:
-
-   @classmethod
-   get_data(cls) -> dict[str, Any]
-
-Возвращает все данные из глобального хранилища.
-
-:return: Словарь со всеми данными из хранилища
-
-**Пример использования:**
-
-.. literalinclude:: ../../code_snippets/response/snippet3.py
-   :linenos:
-   :language: python
-
-----
-
-clear_data
-~~~~~~~~~~
-
-.. code-block:: python
-   :linenos:
-
-   @classmethod
-   clear_data(cls) -> None
-
-Очищает глобальное хранилище.
-
-:return: None
-
-**Пример использования:**
-
-.. literalinclude:: ../../code_snippets/response/snippet4.py
-   :linenos:
-   :language: python
-
-----
-
-delete_from_data
-~~~~~~~~~~~~~~~~
-
-.. code-block:: python
-   :linenos:
-
-   @classmethod
-   delete_from_data(cls, key: str) -> None
-
-Удаляет ключ и его значение из глобального хранилища.
-
-:param key: Ключ, который необходимо удалить из хранилища
-:return: None
-:raises KeyError: Если ключ не найден в хранилище.
-
-**Пример использования:**
-
-.. literalinclude:: ../../code_snippets/response/snippet5.py
-   :linenos:
-   :language: python
-
-----
-
 Работа с флагами
 ----------------