diff --git a/docs/code_snippets/argparser_snippet.py b/docs/code_snippets/argparser_snippet.py new file mode 100644 index 0000000..67cd1e6 --- /dev/null +++ b/docs/code_snippets/argparser_snippet.py @@ -0,0 +1,10 @@ +from argenta import Orchestrator, App +from argenta.orchestrator.argparser import BooleanArgument, ArgParser + +arg_parser = ArgParser(processed_args=[BooleanArgument('config')]) +orchestrator = Orchestrator( + arg_parser=arg_parser, +) + +if __name__ == "__main__": + orchestrator.start_polling(App()) \ No newline at end of file diff --git a/docs/root/api/orchestrator/argparser.rst b/docs/root/api/orchestrator/argparser.rst index 53bb514..91d434e 100644 --- a/docs/root/api/orchestrator/argparser.rst +++ b/docs/root/api/orchestrator/argparser.rst @@ -1,9 +1,9 @@ .. _root_api_orchestrator_argparser: -Argparser +ArgParser ========== -Объект ``ArgParser`` в ``Argenta`` предназначен для разбора и обработки **аргументов командной строки**, которые передаются вашему приложению при его запуске. Важно не путать их с командами, которые пользователь вводит в интерактивном режиме работы приложения. `ArgParser` позволяет вашему приложению получать внешнюю конфигурацию в момент старта, например, путь к файлу настроек, флаги для отладки или режим запуска. +Объект ``ArgParser`` в ``Argenta`` предназначен для разбора и обработки **аргументов командной строки**, которые передаются вашему приложению при его запуске. Важно не путать их с флагами команд, которые пользователь вводит в интерактивном режиме работы приложения. ``ArgParser`` позволяет вашему приложению получать внешнюю конфигурацию в момент старта, например, путь к файлу настроек, флаги для отладки или режим запуска. ----- @@ -11,83 +11,42 @@ Argparser ------------- .. code-block:: python - - def __init__(self, processed_args: list[argenta.orchestrator.InputArgument] = []) -> None + :linenos: + + def __init__(self, processed_args: list[ValueArgument | BooleanArgument], *, + name: str = "Argenta", + description: str = "Argenta available arguments", + epilog: str = "github.com/koloideal/Argenta | made by kolo") Создает экземпляр парсера аргументов командной строки. -* ``processed_args``: Список аргументов, которые будут обрабатываться и парситься при запуске приложения. +* ``processed_args``: Список аргументов, которые будут обрабатываться и парситься при запуске приложения, подробнее :ref:`тут `. +* ``name``: Имя приложения, которое будет отображаться в справке. +* ``description``: Описание приложения, которое будет отображаться в справке. +* ``epilog``: Дополнительная информация, которая будет отображаться в конце справки. -Основные методы ---------------- +Основные методы и атрибуты +--------------------------- -.. py:method:: parse(self) -> dict[str, str | list[str]] +.. py:attribute:: parsed_argspace: ArgSpace - Основной метод, который выполняет разбор списка `processed_args`. Он анализирует аргументы и преобразует их в структурированный словарь. + Экземпляр класса ``ArgSpace``, который содержит все обработанные аргументы командной строки, подробнее :ref:`тут `. - * Аргументы, имеющие вид флага (например, `--verbose`), получают значение `True`. - * Аргументы, за которыми следует значение (например, `--config settings.yaml`), сохраняются как пара "ключ-значение". - * Если один и тот же аргумент встречается несколько раз, его значения могут быть собраны в список. - - :returns: Словарь, где ключи — это имена аргументов, а значения — их соответствующие значения. - -.. py:method:: get(self, key: str, default: str | None = None) -> str | None - - Удобный метод для получения значения конкретного аргумента по его имени (ключу). Если аргумент не был найден, возвращается значение `default`. - - :param key: Имя аргумента (например, `"--config"`). - :param default: Значение, которое будет возвращено, если аргумент `key` отсутствует. По умолчанию `None`. - :returns: Значение аргумента или значение по умолчанию. - -.. py:method:: all_args(self) -> list[str] - - Возвращает список всех имен (ключей) аргументов, которые были распознаны парсером после вызова метода `parse()`. +.. caution:: + До инициализации инстанса ``Orchestrator``, которому в конструктор был передан соответствующий экземпляр ``ArgParser``, атрибут ``parsed_argspace`` будет равен пустому ``ArgSpace``. + + Парсинг и валидация аргументов командной строки происходит при инициализации ``Orchestrator``, соответственно использование атрибута ``parsed_argspace`` **целесообразно только после инициализации** ``Orchestrator``. +----- + Назначение и интеграция ------------------------ -`ArgParser` является неотъемлемой частью `Orchestrator`. При создании `Orchestrator` ему передается экземпляр `ArgParser`, который обычно инициализируется с `sys.argv[1:]`. - -После этого `Orchestrator` помещает `ArgParser` в DI-контейнер. Это означает, что любой ваш сервис или обработчик команды может запросить `ArgParser` через внедрение зависимостей и получить доступ к стартовым аргументам приложения. Это предпочтительный способ для конфигурации компонентов на основе параметров запуска. +Использование атрибута ``parsed_argspace`` рекомендуется только на этапе настройки приложения, в хэндлерах лучшей практикой является получение ``ArgSpace`` через ``di``, подробнее :ref:`тут `. Пример использования -------------------- -.. code-block:: python - - import sys - from argenta.orchestrator import Orchestrator - from argenta.orchestrator.argparser import ArgParser - from argenta.app import App - from dishka import Provider, Scope, provide - - # 1. Создаем парсер на основе реальных аргументов командной строки - # Например, если запустить: python main.py --config prod.json --debug - arg_parser = ArgParser(processed_args=sys.argv[1:]) - - # 2. Определяем сервис, который будет использовать эти аргументы - class Settings: - def __init__(self, config_path: str, is_debug: bool): - self.config_path = config_path - self.is_debug = is_debug - - class SettingsProvider(Provider): - @provide(scope=Scope.APP) - def get_settings(self, parser: ArgParser) -> Settings: - # Запрашиваем ArgParser из DI и используем его для конфигурации - path = parser.get('--config', default='default.json') - debug_mode = bool(parser.get('--debug')) - return Settings(config_path=path, is_debug=debug_mode) - - # 3. Создаем Orchestrator, передавая ему парсер и провайдер - app = App() - orchestrator = Orchestrator( - arg_parser=arg_parser, - custom_providers=[SettingsProvider()] - ) - - # 4. Запускаем приложение - if __name__ == "__main__": - orchestrator.start_polling(app) - - +.. literalinclude:: ../../../code_snippets/argparser_snippet.py + :language: python + :linenos: diff --git a/mock/mock_app/main.py b/mock/mock_app/main.py index 056dfc1..4511214 100644 --- a/mock/mock_app/main.py +++ b/mock/mock_app/main.py @@ -12,11 +12,14 @@ arg_parser: ArgParser = ArgParser( ValueArgument(name="required", is_required=True), ] ) + +print(arg_parser.parsed_argspace.all_arguments) app: App = App( dividing_line=DynamicDividingLine(), autocompleter=AutoCompleter(history_filename="history.txt") ) orchestrator: Orchestrator = Orchestrator(arg_parser) +print(arg_parser.parsed_argspace.all_arguments) def main(): diff --git a/src/argenta/orchestrator/entity.py b/src/argenta/orchestrator/entity.py index 1d2b3db..f6fc7f1 100644 --- a/src/argenta/orchestrator/entity.py +++ b/src/argenta/orchestrator/entity.py @@ -22,7 +22,7 @@ class Orchestrator: self._arg_parser: ArgParser = arg_parser self._custom_providers: list[Provider] = custom_providers self._auto_inject_handlers: bool = auto_inject_handlers - + self._arg_parser._parse_args() def start_polling(self, app: App) -> None: