mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 18:15:28 +03:00
kolo
ce7e24b924
The entire public api is covered with documentation in two languages - Russian and English. the library now supports the latest three versions of python - 3.12, 3.13 and 3.14 minor design changes: now, when a Boolean flag is entered, its value is an empty string, not None. tests have been adapted to the supported versions of python, readmi has been redesigned in two languages, German is no longer available.
87 lines
4.2 KiB
ReStructuredText
87 lines
4.2 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
|