mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
92 lines
4.4 KiB
ReStructuredText
92 lines
4.4 KiB
ReStructuredText
.. _root_api_orchestrator_argparser:
|
|
|
|
ArgParser
|
|
==========
|
|
|
|
``ArgParser`` предназначен для обработки **аргументов командной строки**, передаваемых приложению при запуске. Важно не путать их с флагами, которые пользователь вводит в интерактивном режиме. ``ArgParser`` позволяет получать внешнюю конфигурацию в момент старта (например, путь к файлу настроек, флаги отладки или режим запуска).
|
|
|
|
-----
|
|
|
|
Инициализация
|
|
-------------
|
|
|
|
.. code-block:: python
|
|
: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``: Список аргументов для обработки при запуске приложения. Подробнее см. :ref:`здесь <root_api_orchestrator_arguments>`.
|
|
* ``name``: Имя приложения для отображения в справке.
|
|
* ``description``: Описание приложения для отображения в справке.
|
|
* ``epilog``: Дополнительная информация для отображения в конце справки.
|
|
|
|
-----
|
|
|
|
Атрибуты
|
|
--------
|
|
|
|
.. py:attribute:: parsed_argspace: ArgSpace
|
|
|
|
Экземпляр ``ArgSpace``, содержащий все обработанные аргументы командной строки. Подробнее см. :ref:`здесь <root_api_orchestrator_argspace>`.
|
|
|
|
.. caution::
|
|
До инициализации ``Orchestrator``, в конструктор которого был передан экземпляр ``ArgParser``, атрибут ``parsed_argspace`` будет содержать пустой ``ArgSpace``.
|
|
|
|
Парсинг и валидация аргументов происходят при инициализации ``Orchestrator``, поэтому использовать ``parsed_argspace`` **целесообразно только после** этого.
|
|
|
|
-----
|
|
|
|
Лучшие практики
|
|
---------------
|
|
|
|
Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.
|
|
|
|
**Пример использования:**
|
|
|
|
.. literalinclude:: ../../../code_snippets/argparser/snippet.py
|
|
:language: python
|
|
:linenos:
|
|
|
|
Обработка ошибок
|
|
----------------
|
|
|
|
.. seealso::
|
|
Про типы аргументов подробнее в :ref:`Arguments <root_api_orchestrator_arguments>`
|
|
|
|
При работе с аргументами командной строки стандартный ``ArgumentParser`` автоматически обрабатывает следующие ситуации:
|
|
|
|
**Отсутствие обязательного аргумента:**
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python app.py
|
|
usage: Argenta [-h] --config CONFIG
|
|
Argenta: error: the following arguments are required: --config
|
|
|
|
**Недопустимое значение из списка possible_values:**
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python app.py --config app.yaml --log-level TRACE
|
|
usage: Argenta [-h] --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
|
|
Argenta: error: argument --log-level: invalid choice: 'TRACE'
|
|
|
|
**Использование устаревшего аргумента:**
|
|
|
|
При использовании аргумента с ``is_deprecated=True`` выводится предупреждение, но выполнение продолжается:
|
|
|
|
.. code-block:: bash
|
|
|
|
$ python app.py --old-param value
|
|
Warning: argument --old-param is deprecated
|
|
|
|
.. warning::
|
|
|
|
Параметр поддерживается начиная с версии CPython 3.13, если версия ниже, то параметр будет игнорироваться.
|
|
|