mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
Update documentation and code snippets
This commit is contained in:
+1
-1
@@ -19,7 +19,7 @@ Argenta
|
||||
|
||||
Argenta предназначена для создания приложений, работающих в собственном контексте (scope). Это означает, что приложение запускается один раз и создаёт интерактивную сессию, похожую на Python REPL или MySQL консоль. При запуске пользователь входит в эту сессию, где ему доступна вся реализованная вами функциональность.
|
||||
|
||||
Один из ключевых принципов библиотеки — цикличность. После выполнения команды пользователь остаётся в интерактивной сессии и имеет доступ к созданной вами функциональности, в отличие от таких библиотек, как ``argparse``, ``click`` и ``typer``. Выход из сессии контролируется пользователем.
|
||||
Один из ключевых принципов библиотеки — цикличность. После выполнения команды пользователь остаётся в интерактивной сессии, в отличие от таких библиотек, как ``argparse``, ``click`` и ``typer``, где приложение завершается после каждой команды. Выход из сессии контролируется пользователем.
|
||||
|
||||
**Ключевые особенности:**
|
||||
|
||||
|
||||
@@ -5,7 +5,7 @@ DataBridge
|
||||
|
||||
``DataBridge`` — это сущность, предоставляющая временное хранилище данных, которое существует в рамках одной сессии приложения (от запуска до выхода). Она предназначена для обмена данными между обработчиками.
|
||||
|
||||
Основной способ получения доступа к ``DataBridge`` — через ``di``.
|
||||
Основной способ получения доступа к ``DataBridge`` — через DI.
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
@@ -39,7 +39,7 @@ DataBridge
|
||||
.. py:method:: __init__(self, initial_data: dict | None = None)
|
||||
:no-index:
|
||||
|
||||
Инициализирует хранилище. При использовании через ``di`` вызывается автоматически.
|
||||
Инициализирует хранилище. При использовании через DI вызывается автоматически.
|
||||
|
||||
.. py:method:: update(self, data: dict) -> None
|
||||
|
||||
|
||||
@@ -44,7 +44,7 @@ ArgParser
|
||||
Лучшие практики
|
||||
---------------
|
||||
|
||||
Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через ``di``. Подробнее см. :ref:`здесь <root_dependency_injection>`.
|
||||
Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
|
||||
@@ -85,7 +85,7 @@ InputArgument
|
||||
.. literalinclude:: ../../../code_snippets/argspace/snippet.py
|
||||
:linenos:
|
||||
|
||||
Доступ к аргументам из обработчиков осуществляется с помощью ``di``. Подробнее см. :ref:`здесь <root_dependency_injection>`.
|
||||
Доступ к аргументам из обработчиков осуществляется с помощью DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
|
||||
@@ -3,7 +3,7 @@
|
||||
Orchestrator
|
||||
====================
|
||||
|
||||
``Orchestrator`` — это высокоуровневый компонент, который конфигурирует и оркестрирует приложение, парсер командной строки, ``di`` и остальные компоненты, находящиеся по иерархии на уровне с ``App``.
|
||||
``Orchestrator`` — это высокоуровневый компонент, который конфигурирует и оркестрирует приложение, парсер командной строки, DI и остальные компоненты, находящиеся по иерархии на уровне с ``App``.
|
||||
|
||||
В то время как ``App`` отвечает за логику интерактивной сессии (ввод команд, маршрутизация), ``Orchestrator`` подготавливает окружение для его работы и служит точкой входа в приложение.
|
||||
|
||||
@@ -47,7 +47,7 @@ Orchestrator
|
||||
Назначение и использование
|
||||
----------------------------
|
||||
|
||||
``Orchestrator`` абстрагирует сложность, связанную с настройкой ``di`` и парсингом стартовых аргументов.
|
||||
``Orchestrator`` абстрагирует сложность, связанную с настройкой DI и парсингом стартовых аргументов.
|
||||
|
||||
Такой подход разделяет ответственности: ``App`` отвечает за логику интерактивной сессии, а ``Orchestrator`` — за подготовку окружения и запуск приложения.
|
||||
|
||||
|
||||
@@ -3,10 +3,10 @@
|
||||
Внедрение зависимостей
|
||||
=======================
|
||||
|
||||
Внедрение зависимостей (Dependency Injection, ``di`` ) — это паттерн проектирования, который помогает писать слабосвязанный, легко тестируемый и расширяемый код. Вместо того чтобы обработчики сами создавали нужные им объекты (зависимости), они получают их извне.
|
||||
Внедрение зависимостей (Dependency Injection, DI) — это паттерн проектирования, который помогает писать слабосвязанный, легко тестируемый и расширяемый код. Вместо того чтобы обработчики сами создавали нужные им объекты (зависимости), они получают их извне.
|
||||
|
||||
``Argenta`` использует библиотеку ``dishka`` для реализации ``di``, что позволяет декларативно объявлять зависимости прямо в сигнатурах ваших обработчиков.
|
||||
Подробнее о **DI**, **IoC** и API для создания провайдеров можно прочитать в `официальной документации dishka <https://dishka.readthedocs.io/en/stable/di_intro.html>`_.
|
||||
``Argenta`` использует библиотеку ``dishka`` для реализации DI, что позволяет декларативно объявлять зависимости прямо в сигнатурах ваших обработчиков.
|
||||
Подробнее о DI, IoC и API для создания провайдеров можно прочитать в `официальной документации dishka <https://dishka.readthedocs.io/en/stable/di_intro.html>`_.
|
||||
|
||||
-----
|
||||
|
||||
@@ -35,7 +35,7 @@
|
||||
После создания провайдера его необходимо зарегистрировать в оркестраторе.
|
||||
|
||||
.. note::
|
||||
Провайдеры регистрируются в ``Orchestrator``, а не в ``App``, так как оркестратор отвечает за настройку di-контейнера на уровне всего приложения. Вы можете передать список из нескольких провайдеров через параметр ``custom_providers``.
|
||||
Провайдеры регистрируются в ``Orchestrator``, а не в ``App``, так как оркестратор отвечает за настройку DI-контейнера на уровне всего приложения. Вы можете передать список из нескольких провайдеров через параметр ``custom_providers``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -48,7 +48,7 @@
|
||||
Как это работает?
|
||||
-----------------
|
||||
|
||||
В основе ``di`` в Argenta лежат **провайдеры** и **контейнер**.
|
||||
В основе DI в Argenta лежат **провайдеры** и **контейнер**.
|
||||
|
||||
* **Провайдер (Provider)** — это "рецепт", который объясняет, как создавать и настраивать ту или иную зависимость (например, подключение к БД, API-клиент или любой другой сервис).
|
||||
* **Контейнер (IoC Container)** — это "фабрика", которая хранит все рецепты (провайдеры) и по запросу создаёт и выдаёт готовые зависимости.
|
||||
@@ -71,7 +71,7 @@
|
||||
Обмен данными между обработчиками
|
||||
----------------------------------
|
||||
|
||||
Помимо ``di``, обработчики могут обмениваться данными в рамках сессии через **объект контекста**. В ``Argenta`` эту роль выполняет объект ``DataBridge``.
|
||||
Помимо DI, обработчики могут обмениваться данными в рамках сессии через **объект контекста**. В ``Argenta`` эту роль выполняет объект ``DataBridge``.
|
||||
|
||||
Каждый обработчик может записывать в него данные, а также читать, обновлять и удалять их.
|
||||
|
||||
|
||||
+11
-6
@@ -1,7 +1,7 @@
|
||||
.. _root_flags:
|
||||
|
||||
Флаги команд
|
||||
============
|
||||
Флаги вводимых команд
|
||||
=====================
|
||||
|
||||
Флаги — это специальные параметры, которые пользователь может добавлять к командам для управления их поведением.
|
||||
|
||||
@@ -60,9 +60,9 @@
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
greet --name John # Flag with value
|
||||
deploy --verbose # Flag without value (switch)
|
||||
backup -f --compress # Several flags
|
||||
greet --name John
|
||||
deploy --verbose
|
||||
backup -f --compress
|
||||
|
||||
-----
|
||||
|
||||
@@ -91,7 +91,12 @@
|
||||
Два типа флагов
|
||||
---------------
|
||||
|
||||
Флаги бывают двух основных видов: без значений (переключатели) и со значениями. ``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности для одной команды.
|
||||
Флаги бывают двух основных видов:
|
||||
|
||||
1. **Флаги со значениями** — принимают параметр после имени флага (например, ``--name John``, ``--port 8080``)
|
||||
2. **Флаги-переключатели** — не принимают значения, их наличие само по себе является сигналом (например, ``--verbose``, ``--force``)
|
||||
|
||||
``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности для одной команды.
|
||||
|
||||
.. note::
|
||||
Ошибки валидации не выбрасывают исключений. Вместо этого у каждого объекта :ref:`InputFlag <root_api_command_input_flag>` есть атрибут ``status``, по которому можно определить, прошла ли валидация успешно. Подробное описание API для создания флагов находится в разделе :ref:`Flag <root_api_command_flag>`.
|
||||
|
||||
@@ -41,25 +41,33 @@
|
||||
Промежуточный пример: Калькулятор с флагами
|
||||
--------------------------------------------
|
||||
|
||||
Прежде чем перейти к сложному примеру с ``di``, рассмотрим промежуточный вариант — калькулятор, который использует флаги для управления поведением.
|
||||
Прежде чем перейти к сложному примеру с DI, рассмотрим промежуточный вариант — калькулятор, который использует флаги для управления поведением.
|
||||
|
||||
.. literalinclude:: ../code_snippets/quickstart/calculator_app.py
|
||||
:language: python
|
||||
:linenos:
|
||||
|
||||
**Запуск:**
|
||||
|
||||
Сохраните код в файл ``calculator.py`` и запустите:
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
python calculator.py
|
||||
|
||||
**Использование:**
|
||||
|
||||
.. code-block:: shell
|
||||
|
||||
calc --a 10 --b 5 --operation add # Result: 15.0
|
||||
calc --a 10 --b 5 --operation mul # Result: 50.0
|
||||
calc --a 10 --b 5 --operation add
|
||||
calc --a 10 --b 5 --operation mul
|
||||
|
||||
Этот пример показывает, как работать с флагами без использования ``di``. Теперь перейдём к более сложному примеру.
|
||||
Этот пример показывает, как работать с флагами без использования DI. Теперь перейдём к более сложному примеру.
|
||||
|
||||
-----
|
||||
|
||||
Сложный пример: Менеджер задач с ``di``
|
||||
--------------------------------------
|
||||
Сложный пример: Менеджер задач с DI
|
||||
------------------------------------
|
||||
|
||||
В этом руководстве мы создадим полнофункциональное CLI-приложение «Менеджер задач», которое продемонстрирует работу с внедрением зависимостей.
|
||||
|
||||
|
||||
Reference in New Issue
Block a user