mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
docs
This commit is contained in:
@@ -3,7 +3,7 @@
|
||||
ArgParser
|
||||
==========
|
||||
|
||||
Объект ``ArgParser`` в ``Argenta`` предназначен для разбора и обработки **аргументов командной строки**, которые передаются вашему приложению при его запуске. Важно не путать их с флагами команд, которые пользователь вводит в интерактивном режиме работы приложения. ``ArgParser`` позволяет вашему приложению получать внешнюю конфигурацию в момент старта, например, путь к файлу настроек, флаги для отладки или режим запуска.
|
||||
``ArgParser`` предназначен для обработки **аргументов командной строки**, передаваемых приложению при запуске. Важно не путать их с флагами, которые пользователь вводит в интерактивном режиме. ``ArgParser`` позволяет получать внешнюю конфигурацию в момент старта (например, путь к файлу настроек, флаги отладки или режим запуска).
|
||||
|
||||
-----
|
||||
|
||||
@@ -18,31 +18,31 @@ ArgParser
|
||||
description: str = "Argenta available arguments",
|
||||
epilog: str = "github.com/koloideal/Argenta | made by kolo")
|
||||
|
||||
Создает экземпляр парсера аргументов командной строки.
|
||||
Создаёт экземпляр парсера аргументов командной строки.
|
||||
|
||||
* ``processed_args``: Список аргументов, которые будут обрабатываться и парситься при запуске приложения, подробнее :ref:`тут <root_api_orchestrator_arguments>`.
|
||||
* ``name``: Имя приложения, которое будет отображаться в справке.
|
||||
* ``description``: Описание приложения, которое будет отображаться в справке.
|
||||
* ``epilog``: Дополнительная информация, которая будет отображаться в конце справки.
|
||||
* ``processed_args``: Список аргументов для обработки при запуске приложения. Подробнее см. :ref:`здесь <root_api_orchestrator_arguments>`.
|
||||
* ``name``: Имя приложения для отображения в справке.
|
||||
* ``description``: Описание приложения для отображения в справке.
|
||||
* ``epilog``: Дополнительная информация для отображения в конце справки.
|
||||
|
||||
Основные методы и атрибуты
|
||||
---------------------------
|
||||
|
||||
.. py:attribute:: parsed_argspace: ArgSpace
|
||||
|
||||
Экземпляр класса ``ArgSpace``, который содержит все обработанные аргументы командной строки, подробнее :ref:`тут <root_api_orchestrator_argspace>`.
|
||||
Экземпляр ``ArgSpace``, содержащий все обработанные аргументы командной строки. Подробнее см. :ref:`здесь <root_api_orchestrator_argspace>`.
|
||||
|
||||
.. caution::
|
||||
До инициализации инстанса ``Orchestrator``, которому в конструктор был передан соответствующий экземпляр ``ArgParser``, атрибут ``parsed_argspace`` будет равен пустому ``ArgSpace``.
|
||||
До инициализации ``Orchestrator``, в конструктор которого был передан экземпляр ``ArgParser``, атрибут ``parsed_argspace`` будет содержать пустой ``ArgSpace``.
|
||||
|
||||
Парсинг и валидация аргументов командной строки происходит при инициализации ``Orchestrator``, соответственно использование атрибута ``parsed_argspace`` **целесообразно только после инициализации** ``Orchestrator``.
|
||||
Парсинг и валидация аргументов происходят при инициализации ``Orchestrator``, поэтому использовать ``parsed_argspace`` **целесообразно только после** этого.
|
||||
|
||||
-----
|
||||
|
||||
Лучшие практики
|
||||
------------------------
|
||||
|
||||
Использование атрибута ``parsed_argspace`` рекомендуется только на этапе настройки приложения, в хэндлерах лучшей практикой является получение ``ArgSpace`` через ``di``, подробнее :ref:`тут <root_dependency_injection>`.
|
||||
Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.
|
||||
|
||||
Пример использования
|
||||
--------------------
|
||||
|
||||
@@ -3,9 +3,9 @@
|
||||
ArgSpace
|
||||
==========
|
||||
|
||||
Объект ``ArgSpace`` является контейнером для хранения и управления распаршенными аргументами командной строки в приложении ``Argenta``. Его основная задача — предоставить удобный интерфейс для доступа к значениям аргументов, переданных при запуске приложения.
|
||||
``ArgSpace`` — это контейнер для хранения и управления обработанными аргументами командной строки. Его основная задача — предоставить удобный интерфейс для доступа к значениям, переданным при запуске приложения.
|
||||
|
||||
``ArgSpace`` автоматически создается после парсинга аргументов через ``ArgParser`` и содержит коллекцию объектов ``InputArgument``, представляющих собой финальные значения всех переданных параметров командной строки.
|
||||
``ArgSpace`` создаётся автоматически после обработки аргументов с помощью `ArgParser` и содержит коллекцию объектов `InputArgument`.
|
||||
|
||||
-----
|
||||
|
||||
@@ -17,15 +17,15 @@ ArgSpace
|
||||
|
||||
__init__(self, all_arguments: list[InputArgument]) -> None
|
||||
|
||||
Создает новое пространство аргументов.
|
||||
Создаёт новое пространство аргументов.
|
||||
|
||||
* ``all_arguments`` : Список распаршенных аргументов в виде объектов ``InputArgument``. Каждый элемент содержит имя, значение и тип исходного аргумента.
|
||||
* ``all_arguments``: Список обработанных аргументов в виде объектов `InputArgument`. Каждый элемент содержит имя, значение и тип исходного аргумента.
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: all_arguments
|
||||
|
||||
Список всех распаршенных аргументов типа ``InputArgument``. Содержит все аргументы, переданные при запуске приложения, включая значения по умолчанию для не указанных параметров.
|
||||
Список всех обработанных аргументов типа `InputArgument`, включая значения по умолчанию для не указанных параметров.
|
||||
|
||||
-----
|
||||
|
||||
@@ -40,12 +40,12 @@ get_by_name
|
||||
|
||||
get_by_name(self, name: str) -> InputArgument | None
|
||||
|
||||
Возвращает аргумент по его имени.
|
||||
Возвращает аргумент по имени.
|
||||
|
||||
:param name: Имя искомого аргумента
|
||||
:return: Объект ``InputArgument`` с указанным именем или ``None``, если аргумент не найден
|
||||
:param name: Имя искомого аргумента.
|
||||
:return: Объект `InputArgument` или `None`, если аргумент не найден.
|
||||
|
||||
Метод выполняет линейный поиск по списку ``all_arguments`` и возвращает аргумент с соответствующим именем. Если аргумент не найден, возвращается ``None``.
|
||||
Метод выполняет линейный поиск по списку `all_arguments`. Если аргумент не найден, возвращается `None`.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -76,12 +76,12 @@ get_by_type
|
||||
|
||||
get_by_type(self, arg_type: type[BaseArgument]) -> list[InputArgument] | list[Never]
|
||||
|
||||
Получает все аргументы определенного типа.
|
||||
Возвращает все аргументы определённого типа.
|
||||
|
||||
:param arg_type: Тип аргумента (``BooleanArgument`` или ``ValueArgument``)
|
||||
:return: Список аргументов указанного типа или пустой список, если аргументы не найдены
|
||||
:param arg_type: Тип аргумента (`BooleanArgument` или `ValueArgument`).
|
||||
:return: Список аргументов указанного типа или пустой список.
|
||||
|
||||
Метод фильтрует ``all_arguments`` по атрибуту ``founder_class`` каждого ``InputArgument`` и возвращает только те аргументы, которые были созданы из указанного типа.
|
||||
Метод фильтрует `all_arguments` по атрибуту `founder_class` и возвращает аргументы, созданные из указанного типа.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -94,21 +94,21 @@ InputArgument
|
||||
-------------
|
||||
|
||||
.. seealso ::
|
||||
Документация по ``InputArgument`` находится :ref:`тут <root_api_orchestrator_arguments_inputargument>`
|
||||
Документация по ``InputArgument`` находится :ref:`здесь <root_api_orchestrator_arguments_inputargument>`.
|
||||
|
||||
-----
|
||||
|
||||
Примеры испольования
|
||||
--------------------
|
||||
|
||||
``ArgSpace`` используется для доступа к значениям аргументов после запуска приложения. Типичный сценарий работы включает парсинг аргументов через ``ArgParser`` и последующее извлечение значений из ``ArgSpace``.
|
||||
`ArgSpace` используется для доступа к значениям аргументов после запуска приложения. Типичный сценарий включает обработку аргументов через `ArgParser` и последующее извлечение значений из `ArgSpace`.
|
||||
|
||||
**Полный пример:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/argspace/snippet.py
|
||||
:linenos:
|
||||
|
||||
Доступ к аргументам из хэндлеров осуществляется с помощью ``di``, подробнее :ref:`тут <root_dependency_injection>`.
|
||||
Доступ к аргументам из обработчиков осуществляется с помощью DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/argspace/snippet2.py
|
||||
:linenos:
|
||||
|
||||
@@ -3,16 +3,16 @@
|
||||
Arguments
|
||||
=========
|
||||
|
||||
Модуль ``Arguments`` предоставляет набор классов для работы с аргументами командной строки при запуске приложения ``Argenta``. Эти аргументы позволяют настраивать поведение приложения на этапе его старта, передавая различные параметры конфигурации через интерфейс командной строки.
|
||||
Модуль ``Arguments`` предоставляет классы для работы с аргументами командной строки. Они позволяют настраивать поведение приложения в момент его запуска, передавая различные параметры конфигурации.
|
||||
|
||||
Аргументы регистрируются в ``ArgParser`` и парсятся при запуске приложения, становясь доступными через объект ``ArgSpace``.
|
||||
Аргументы регистрируются в `ArgParser` и после обработки становятся доступными в объекте `ArgSpace`.
|
||||
|
||||
-----
|
||||
|
||||
ValueArgument
|
||||
-------------
|
||||
|
||||
Класс для аргументов командной строки, требующих передачи значения. Используется для параметров конфигурации, которым необходимо указать конкретное значение при запуске приложения.
|
||||
Класс для аргументов, требующих передачи значения. Используется для параметров конфигурации, которым необходимо указать значение при запуске.
|
||||
|
||||
.. py:class:: ValueArgument(BaseArgument)
|
||||
|
||||
@@ -27,15 +27,15 @@ ValueArgument
|
||||
is_required: bool = False,
|
||||
is_deprecated: bool = False) -> None
|
||||
|
||||
Создает аргумент командной строки, требующий значения.
|
||||
Создаёт аргумент командной строки, требующий значения.
|
||||
|
||||
:param name: Имя аргумента
|
||||
:param prefix: Префикс аргумента, по умолчанию ``--``
|
||||
:param help: Сообщение справки, отображаемое при ``--help``
|
||||
:param possible_values: Список допустимых значений для аргумента. Передается в параметр ``choices`` ArgumentParser
|
||||
:param default: Значение по умолчанию, используемое если аргумент не передан при запуске
|
||||
:param is_required: Обязатялен ли аргумент. Если ``True``, приложение не запустится без этого аргумента
|
||||
:param is_deprecated: Является ли аргумент устаревшим
|
||||
:param prefix: Префикс (по умолчанию ``--``)
|
||||
:param help: Сообщение для справки (``--help``)
|
||||
:param possible_values: Список допустимых значений (передаётся в `choices` `ArgumentParser`)
|
||||
:param default: Значение по умолчанию, если аргумент не передан
|
||||
:param is_required: Если ``True``, аргумент становится обязательным
|
||||
:param is_deprecated: Если ``True``, помечает аргумент как устаревший
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -83,7 +83,7 @@ ValueArgument
|
||||
BooleanArgument
|
||||
---------------
|
||||
|
||||
Класс для булевых аргументов командной строки, которые не требуют передачи значения. Наличие или отсутствие аргумента при запуске определяет состояние распаршенных аргументов(``True`` при наличии и ``False`` при отсутствии).
|
||||
Класс для булевых аргументов, не требующих значения. Их наличие при запуске устанавливает значение в `True`, отсутствие — в `False`.
|
||||
|
||||
.. py:class:: BooleanArgument(BaseArgument)
|
||||
|
||||
@@ -95,12 +95,12 @@ BooleanArgument
|
||||
help: str = "Help message for the boolean argument",
|
||||
is_deprecated: bool = False) -> None
|
||||
|
||||
Создает булевый аргумент командной строки без значения.
|
||||
Создаёт булев аргумент командной строки без значения.
|
||||
|
||||
:param name: Имя аргумента
|
||||
:param prefix: Префикс аргумента, по умолчанию ``--``
|
||||
:param help: Сообщение справки, отображаемое при ``--help``
|
||||
:param is_deprecated: Является ли аргумент устаревшим
|
||||
:param prefix: Префикс (по умолчанию ``--``)
|
||||
:param help: Сообщение для справки (``--help``)
|
||||
:param is_deprecated: Если ``True``, помечает аргумент как устаревший
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
@@ -147,9 +147,9 @@ InputArgument
|
||||
-------------
|
||||
|
||||
.. seealso::
|
||||
``InputArgument`` непосредственно связан и является наполнителем контейнера ``ArgSpace``, подробнее про него :ref:`тут <root_api_orchestrator_argspace>`.
|
||||
``InputArgument`` напрямую связан с контейнером ``ArgSpace`` и является его наполнителем. Подробнее о нём см. :ref:`здесь <root_api_orchestrator_argspace>`.
|
||||
|
||||
Представляет собой распаршенный аргумент командной строки после запуска приложения. Этот класс используется внутри объекта ``ArgSpace`` для хранения значений аргументов, полученных при парсинге.
|
||||
Представляет собой обработанный аргумент командной строки. Этот класс используется внутри `ArgSpace` для хранения значений, полученных после парсинга.
|
||||
|
||||
.. py:class:: InputArgument
|
||||
|
||||
@@ -160,35 +160,35 @@ InputArgument
|
||||
value: str | Literal[True],
|
||||
founder_class: type[BaseArgument]) -> None
|
||||
|
||||
Создает экземпляр распарсенного входного аргумента.
|
||||
Создаёт экземпляр обработанного входного аргумента.
|
||||
|
||||
:param name: Имя аргумента
|
||||
:param value: Значение аргумента. Для ``BooleanArgument`` всегда ``True`` если флаг передан, для ``ValueArgument`` — строка со значением
|
||||
:param founder_class: Класс-родитель, из которого был создан этот аргумент (``BooleanArgument`` или ``ValueArgument``)
|
||||
:param value: Значение аргумента. Для `BooleanArgument` — `True`, если флаг передан; для `ValueArgument` — строка со значением
|
||||
:param founder_class: Класс-родитель, из которого был создан аргумент (`BooleanArgument` или `ValueArgument`)
|
||||
|
||||
**Атрибуты:**
|
||||
|
||||
.. py:attribute:: name
|
||||
:no-index:
|
||||
|
||||
Имя аргумента в виде строки. Соответствует имени, указанному при создании ``ValueArgument`` или ``BooleanArgument``.
|
||||
Имя аргумента, указанное при создании `ValueArgument` или `BooleanArgument`.
|
||||
|
||||
.. py:attribute:: value
|
||||
|
||||
Значение аргумента. Тип значения зависит от исходного класса аргумента:
|
||||
|
||||
* Для ``BooleanArgument``: ``True`` если флаг был передан при запуске
|
||||
* Для ``ValueArgument``: строка с переданным значением или значением по умолчанию
|
||||
Значение аргумента. Тип зависит от исходного класса:
|
||||
|
||||
* Для `BooleanArgument`: `True`, если флаг был передан.
|
||||
* Для `ValueArgument`: строка с переданным значением или значением по умолчанию
|
||||
|
||||
.. py:attribute:: founder_class
|
||||
|
||||
Ссылка на класс, из которого был создан этот аргумент. Используется для определения типа аргумента и фильтрации в методе ``get_by_type()``.
|
||||
Ссылка на класс-родитель. Используется для определения типа и фильтрации в методе `get_by_type()`.
|
||||
|
||||
**Методы:**
|
||||
|
||||
.. py:method:: __str__() -> str
|
||||
|
||||
Возвращает строковое представление аргумента в формате ``InputArgument(name=value)``.
|
||||
Возвращает строковое представление в формате `InputArgument(name=value)`.
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
@@ -198,4 +198,4 @@ InputArgument
|
||||
|
||||
.. py:method:: __repr__() -> str
|
||||
|
||||
Возвращает техническое представление объекта в виде строки.
|
||||
Возвращает техническое представление объекта.
|
||||
@@ -3,16 +3,16 @@
|
||||
Orchestrator
|
||||
====================
|
||||
|
||||
Объект ``Orchestrator`` в ``Argenta`` представляет собой высокоуровневый компонент, который стоит над ``App`` и отвечает за "оркестрацию" всего приложения. Его главная задача — инициализация и конфигурация сложных систем, таких как внедрение зависимостей (``di``), парсинг аргументов командной строки при запуске, и запуск основного цикла приложения.
|
||||
``Orchestrator`` — это высокоуровневый компонент, который управляет жизненным циклом приложения. Его главная задача — инициализация и конфигурация окружения, включая внедрение зависимостей (DI), парсинг аргументов командной строки и запуск основного цикла `App`.
|
||||
|
||||
В то время как ``App`` отвечает за интерактивную сессию (ввод команд, роутинг), ``Orchestrator`` подготавливает окружение, в котором ``App`` будет работать. Он является точкой входа для приложений.
|
||||
В то время как `App` отвечает за логику интерактивной сессии (ввод команд, маршрутизация), `Orchestrator` подготавливает окружение для его работы и служит точкой входа в приложение.
|
||||
|
||||
-----
|
||||
|
||||
Инициализация
|
||||
-------------
|
||||
|
||||
.. code-block:: rust
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
DEFAULT_ARGPARSER: ArgParser = ArgParser(processed_args=[])
|
||||
@@ -25,11 +25,11 @@ Orchestrator
|
||||
custom_providers: list[Provider] = [],
|
||||
auto_inject_handlers: bool = True) -> None
|
||||
|
||||
Создает и конфигурирует экземпляр ``Orchestrator``.
|
||||
Создаёт и конфигурирует экземпляр ``Orchestrator``.
|
||||
|
||||
* ``arg_parser``: Экземпляр :class:`argenta.orchestrator.argparser.ArgParser`, который отвечает за парсинг аргументов, переданных скрипту при запуске из командной строки (не путать с командами, вводимыми в интерактивном режиме).
|
||||
* ``custom_providers``: Список пользовательских провайдеров ``dishka.Provider``. Это основной механизм для добавления ваших собственных сервисов (например, подключений к базе данных, клиентов API) в контейнер внедрения зависимостей.
|
||||
* ``auto_inject_handlers``: Если **True** (по умолчанию), ``dishka`` будет автоматически инспектировать сигнатуры обработчиков команд и внедрять в них требуемые зависимости из контейнера.
|
||||
* ``arg_parser``: Экземпляр `ArgParser`, отвечающий за парсинг аргументов командной строки при запуске скрипта (не путать с командами в интерактивном режиме).
|
||||
* ``custom_providers``: Список пользовательских провайдеров `dishka.Provider` для добавления ваших сервисов (например, подключений к БД или API-клиентов) в DI-контейнер.
|
||||
* ``auto_inject_handlers``: Если `True` (по умолчанию), `dishka` автоматически внедрит зависимости в обработчики команд, инспектируя их сигнатуры.
|
||||
|
||||
-----
|
||||
|
||||
@@ -38,26 +38,25 @@ Orchestrator
|
||||
|
||||
.. py:method:: start_polling(self, app: App) -> None
|
||||
|
||||
Это главный метод, который запускает все приложение. Он выполняет следующие шаги:
|
||||
Это главный метод, который запускает приложение. Он выполняет следующие шаги:
|
||||
|
||||
1. **Настройка DI**: На основе системного провайдера (``SystemProvider``, который предоставляет ``ArgParser``) и списка ``custom_providers`` создается ``ioc`` - контейнер и настраивается внедрение зависимостей.
|
||||
|
||||
3. **Запуск основного цикла**: Запускает бесконечный цикл ожидания и обработки пользовательского ввода.
|
||||
1. **Настройка DI**: Создаёт DI-контейнер на основе системного провайдера (предоставляет `ArgParser`) и пользовательских `custom_providers`.
|
||||
2. **Запуск основного цикла**: Запускает бесконечный цикл ожидания и обработки пользовательского ввода.
|
||||
|
||||
:param app: Экземпляр класса :class:`~argenta.app.models.App`, который будет запущен.
|
||||
:param app: Экземпляр `App`, который будет запущен.
|
||||
|
||||
-----
|
||||
|
||||
Назначение и использование
|
||||
----------------------------
|
||||
|
||||
``Orchestrator`` абстрагирует от вас всю сложность, связанную с настройкой внедрения зависимостей и парсингом стартовых аргументов. Типичный сценарий использования ``Argenta`` выглядит следующим образом:
|
||||
``Orchestrator`` абстрагирует сложность, связанную с настройкой DI и парсингом стартовых аргументов. Типичный сценарий использования выглядит так:
|
||||
|
||||
1. Создать экземпляр ``App`` и настроить его (добавить роутеры).
|
||||
2. Создать экземпляр ``Orchestrator``, передав в него необходимые DI-провайдеры и, возможно, парсер аргументов.
|
||||
3. Вызвать ``orchestrator.start_polling(app)``, чтобы запустить приложение.
|
||||
1. Создайте и настройте экземпляр `App` (добавьте роутеры).
|
||||
2. Создайте экземпляр `Orchestrator`, передав в него DI-провайдеры.
|
||||
3. Вызовите `orchestrator.start_polling(app)`, чтобы запустить приложение.
|
||||
|
||||
Такой подход позволяет сохранить код чистым и разделяет ответственность: ``App`` отвечает за логику интерактивной сессии, а ``Orchestrator`` — за подготовку и запуск окружения.
|
||||
Такой подход разделяет ответственности: `App` отвечает за логику интерактивной сессии, а `Orchestrator` — за подготовку и запуск окружения.
|
||||
|
||||
Пример использования
|
||||
--------------------
|
||||
|
||||
Reference in New Issue
Block a user