mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
docs
This commit is contained in:
@@ -0,0 +1,49 @@
|
||||
from argenta import Router, Response, Command
|
||||
from argenta.command import Flag
|
||||
from argenta.data_bridge import DataBridge
|
||||
from argenta.di import FromDishka
|
||||
|
||||
# 1. Создаём роутер
|
||||
router = Router(title='Authentication')
|
||||
|
||||
# 2. Определяем сервис и обработчики
|
||||
def authenticate_user(username: str) -> str:
|
||||
"""Возвращает фиктивный токен для пользователя."""
|
||||
return f"token_for_{username}"
|
||||
|
||||
@router.command(Command('login', flags=Flag('username')))
|
||||
def login_handler(response: Response, data_bridge: FromDishka[DataBridge]):
|
||||
"""Обработчик для команды 'login'. Сохраняет токен в хранилище."""
|
||||
username_flag = response.input_flags.get_flag_by_name('username')
|
||||
if not username_flag or not username_flag.input_value:
|
||||
print("[red]Ошибка:[/red] необходимо указать имя пользователя с помощью флага --username.")
|
||||
return
|
||||
|
||||
username = username_flag.input_value
|
||||
token = authenticate_user(username)
|
||||
|
||||
# Сохраняем токен в общем хранилище сессии
|
||||
data_bridge.update({"auth_token": token})
|
||||
print(f"[green]Успешный вход![/green] Пользователь '{username}' аутентифицирован.")
|
||||
|
||||
@router.command('get-profile')
|
||||
def get_profile_handler(response: Response, data_bridge: FromDishka[DataBridge]):
|
||||
"""Обработчик для команды 'get-profile'. Использует токен из хранилища."""
|
||||
session_data = data_bridge.get_all()
|
||||
token = session_data.get("auth_token")
|
||||
|
||||
if not token:
|
||||
print("[red]Ошибка:[/red] вы не аутентифицированы. Сначала выполните команду 'login'.")
|
||||
return
|
||||
|
||||
print(f"Загрузка профиля с использованием токена: [yellow]{token}[/yellow]")
|
||||
|
||||
@router.command('logout')
|
||||
def logout_handler(response: Response, data_bridge: FromDishka[DataBridge]):
|
||||
"""Обработчик для команды 'logout'. Очищает токен."""
|
||||
try:
|
||||
data_bridge.delete_by_key("auth_token")
|
||||
print("[green]Выход выполнен.[/green] Данные сессии очищены.")
|
||||
except KeyError:
|
||||
print("Вы и так не были аутентифицированы.")
|
||||
|
||||
@@ -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
|
||||
|
||||
-----
|
||||
|
||||
Работа с флагами
|
||||
----------------
|
||||
|
||||
|
||||
Reference in New Issue
Block a user