docs

2026-06-10 10:05:28 +03:00 · 2025-10-27 11:59:03 +03:00
parent fc8597504f
commit 7b40fff4c5
16 changed files with 1691 additions and 22 deletions
@@ -39,7 +39,7 @@ ArgParser

 -----
   
-Назначение и интеграция
+Лучшие практики
 ------------------------

 Использование атрибута ``parsed_argspace`` рекомендуется только на этапе настройки приложения, в хэндлерах лучшей практикой является получение ``ArgSpace`` через ``di``,  подробнее :ref:`тут <root_dependency_injection>`.
@@ -50,3 +50,36 @@ ArgParser
 .. literalinclude:: ../../../code_snippets/argparser_snippet.py
   :language: python
   :linenos:
+   
+Обработка ошибок
+----------------
+
+.. seealso:: 
+   Про типы аргументов подробнее в :ref:`Arguments <root_api_orchestrator_arguments>`
+
+При работе с аргументами командной строки стандартный ``ArgumentParser`` автоматически обрабатывает следующие ситуации:
+
+**Отсутствие обязательного аргумента:**
+
+.. code-block:: bash
+
+    $ python app.py
+    usage: MyApp [-h] --config CONFIG
+    MyApp: error: the following arguments are required: --config
+
+**Недопустимое значение из списка choices:**
+
+.. code-block:: bash
+
+    $ python app.py --config app.yaml --log-level TRACE
+    usage: MyApp [-h] --log-level {DEBUG,INFO,WARNING,ERROR,CRITICAL}
+    MyApp: 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
@@ -1,4 +1,147 @@
 .. _root_api_orchestrator_argspace:

 ArgSpace
-==========
+==========
+
+Объект ``ArgSpace`` является контейнером для хранения и управления распаршенными аргументами командной строки в приложении ``Argenta``. Его основная задача — предоставить удобный интерфейс для доступа к значениям аргументов, переданных при запуске приложения.
+
+``ArgSpace`` автоматически создается после парсинга аргументов через ``ArgParser`` и содержит коллекцию объектов ``InputArgument``, представляющих собой финальные значения всех переданных параметров командной строки.
+
+-----
+
+Инициализация
+-------------
+
+.. code-block:: python
+   :linenos:
+
+   __init__(self, all_arguments: list[InputArgument]) -> None
+
+Создает новое пространство аргументов.
+
+* ``all_arguments`` : Список распаршенных аргументов в виде объектов ``InputArgument``. Каждый элемент содержит имя, значение и тип исходного аргумента.
+
+**Атрибуты:**
+
+.. py:attribute:: all_arguments
+
+   Список всех распаршенных аргументов типа ``InputArgument``. Содержит все аргументы, переданные при запуске приложения, включая значения по умолчанию для не указанных параметров.
+
+-----
+
+Методы
+------  
+
+get_by_name
+~~~~~~~~~~~
+
+.. code-block:: python
+   :linenos:
+
+   get_by_name(self, name: str) -> InputArgument | None
+
+Возвращает аргумент по его имени.
+
+:param name: Имя искомого аргумента
+:return: Объект ``InputArgument`` с указанным именем или ``None``, если аргумент не найден
+
+Метод выполняет линейный поиск по списку ``all_arguments`` и возвращает аргумент с соответствующим именем. Если аргумент не найден, возвращается ``None``.
+
+**Пример использования:**
+
+.. code-block:: python
+   :linenos:
+
+   # Получение значения конкретного аргумента
+   config_arg = argspace.get_by_name("config")
+   if config_arg:
+       print(f"Config path: {config_arg.value}")
+   
+   verbose_arg = argspace.get_by_name("verbose")
+   if verbose_arg and verbose_arg.value:
+       print("Verbose mode enabled")
+   
+   # Обработка отсутствующего аргумента
+   unknown_arg = argspace.get_by_name("nonexistent")
+   if unknown_arg is None:
+       print("Argument not found")
+
+-----
+
+get_by_type
+~~~~~~~~~~~
+
+.. code-block:: python
+   :linenos:
+
+   get_by_type(self, arg_type: type[BaseArgument]) -> list[InputArgument] | list[Never]
+
+Получает все аргументы определенного типа.
+
+:param arg_type: Тип аргумента (``BooleanArgument`` или ``ValueArgument``)
+:return: Список аргументов указанного типа или пустой список, если аргументы не найдены
+
+Метод фильтрует ``all_arguments`` по атрибуту ``founder_class`` каждого ``InputArgument`` и возвращает только те аргументы, которые были созданы из указанного типа.
+
+**Пример использования:**
+
+.. code-block:: python
+   :linenos:
+
+   from argenta import BooleanArgument, ValueArgument
+
+   # Получение всех булевых флагов
+   boolean_flags = argspace.get_by_type(BooleanArgument)
+   print(f"Active flags: {[arg.name for arg in boolean_flags if arg.value]}")
+   
+   # Получение всех аргументов со значениями
+   value_args = argspace.get_by_type(ValueArgument)
+   for arg in value_args:
+       print(f"{arg.name} = {arg.value}")
+   
+   # Подсчет количества аргументов каждого типа
+   print(f"Boolean arguments: {len(argspace.get_by_type(BooleanArgument))}")
+   print(f"Value arguments: {len(argspace.get_by_type(ValueArgument))}")
+
+-----
+
+InputArgument
+-------------
+
+.. seealso ::
+   Документация по ``InputArgument`` находится :ref:`тут <root_api_orchestrator_arguments_inputargument>`
+
+-----
+
+Примеры испольования
+--------------------
+
+``ArgSpace`` используется для доступа к значениям аргументов после запуска приложения. Типичный сценарий работы включает парсинг аргументов через ``ArgParser`` и последующее извлечение значений из ``ArgSpace``.
+
+**Полный пример:**
+
+.. literalinclude:: ../../../code_snippets/argspace_snippet.py
+   :linenos:
+   
+Доступ к аргументам из хэндлеров осуществляется с помощью ``di``, подробнее :ref:`тут <root_dependency_injection>`.
+
+.. literalinclude:: ../../../code_snippets/argspace_snippet2.py
+   :linenos:
+
+**Запуск приложения:**
+
+.. code-block:: bash
+
+   # С параметрами по умолчанию
+   python server.py
+   # Output:
+   # Server configuration:
+   #   Host: localhost
+   #   Port: 8080
+
+   # С кастомными параметрами
+   python server.py --host 0.0.0.0 --port 9000
+   # Output:
+   # Server configuration:
+   #   Host: 0.0.0.0
+   #   Port: 9000
@@ -1,6 +1,200 @@
 .. _root_api_orchestrator_arguments:

 Arguments
-****************
+=========

-prikol
+Модуль ``Arguments`` предоставляет набор классов для работы с аргументами командной строки при запуске приложения ``Argenta``. Эти аргументы позволяют настраивать поведение приложения на этапе его старта, передавая различные параметры конфигурации через интерфейс командной строки.
+
+Аргументы регистрируются в ``ArgParser`` и парсятся при запуске приложения, становясь доступными через объект ``ArgSpace``.
+
+-----
+
+ValueArgument
+-------------
+
+Класс для аргументов командной строки, требующих передачи значения. Используется для параметров конфигурации, которым необходимо указать конкретное значение при запуске приложения.
+
+.. py:class:: ValueArgument(BaseArgument)
+
+.. code-block:: python
+   :linenos:
+
+   __init__(self, name: str, *,
+            prefix: Literal["-", "--", "---"] = "--",
+            help: str = "Help message for the value argument",
+            possible_values: list[str] | None = None,
+            default: str | None = None,
+            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: Является ли аргумент устаревшим
+
+**Пример использования:**
+
+.. code-block:: python
+   :linenos:
+
+   from argenta import ArgParser, ValueArgument
+
+   # Создание аргументов
+   config_arg = ValueArgument(
+       "config",
+       help="Path to configuration file",
+       default="config.yaml"
+   )
+
+   log_level_arg = ValueArgument(
+       "log-level",
+       help="Logging level",
+       possible_values=["DEBUG", "INFO", "WARNING", "ERROR"],
+       default="INFO"
+   )
+
+   host_arg = ValueArgument(
+       "host",
+       help="Server host address",
+       is_required=True
+   )
+
+   # Регистрация в ArgParser
+   parser = ArgParser(
+       processed_args=[config_arg, log_level_arg, host_arg],
+       name="MyApp",
+       description="My application with CLI arguments"
+   )
+
+**Запуск приложения:**
+
+.. code-block:: bash
+
+   python app.py --host 127.0.0.1
+   python app.py --host 127.0.0.1 --config custom.yaml --log-level DEBUG
+
+-----
+
+BooleanArgument
+---------------
+
+Класс для булевых аргументов командной строки, которые не требуют передачи значения. Наличие или отсутствие аргумента при запуске определяет состояние распаршенных аргументов(``True`` при наличии и ``False`` при отсутствии).
+
+.. py:class:: BooleanArgument(BaseArgument)
+
+.. code-block:: python
+   :linenos:
+
+   __init__(self, name: str, *,
+            prefix: Literal["-", "--", "---"] = "--",
+            help: str = "Help message for the boolean argument",
+            is_deprecated: bool = False) -> None
+
+Создает булевый аргумент командной строки без значения.
+
+:param name: Имя аргумента
+:param prefix: Префикс аргумента, по умолчанию ``--``
+:param help: Сообщение справки, отображаемое при ``--help``
+:param is_deprecated: Является ли аргумент устаревшим
+
+**Пример использования:**
+
+.. code-block:: python
+   :linenos:
+
+   from argenta import ArgParser, BooleanArgument
+
+   # Создание булевых аргументов
+   verbose_arg = BooleanArgument(
+       "verbose",
+       help="Enable verbose output"
+   )
+
+   debug_arg = BooleanArgument(
+       "debug",
+       help="Enable debug mode"
+   )
+
+   no_cache_arg = BooleanArgument(
+       "no-cache",
+       help="Disable caching"
+   )
+
+   # Регистрация в ArgParser
+   parser = ArgParser(
+       processed_args=[verbose_arg, debug_arg, no_cache_arg],
+       name="MyApp"
+   )
+
+**Запуск приложения:**
+
+.. code-block:: bash
+
+   python app.py --verbose
+   python app.py --debug --no-cache
+   python app.py  # без флагов
+
+-----
+
+.. _root_api_orchestrator_arguments_inputargument:
+
+InputArgument
+-------------
+
+.. seealso::
+   ``InputArgument`` непосредственно связан и является наполнителем контейнера ``ArgSpace``, подробнее про него :ref:`тут <root_api_orchestrator_argspace>`.
+
+Представляет собой распаршенный аргумент командной строки после запуска приложения. Этот класс используется внутри объекта ``ArgSpace`` для хранения значений аргументов, полученных при парсинге.
+
+.. py:class:: InputArgument
+
+.. code-block:: python
+   :linenos:
+
+   __init__(self, name: str,
+            value: str | Literal[True],
+            founder_class: type[BaseArgument]) -> None
+
+Создает экземпляр распарсенного входного аргумента.
+
+:param name: Имя аргумента
+:param value: Значение аргумента. Для ``BooleanArgument`` всегда ``True`` если флаг передан, для ``ValueArgument`` — строка со значением
+:param founder_class: Класс-родитель, из которого был создан этот аргумент (``BooleanArgument`` или ``ValueArgument``)
+
+**Атрибуты:**
+
+.. py:attribute:: name
+
+   Имя аргумента в виде строки. Соответствует имени, указанному при создании ``ValueArgument`` или ``BooleanArgument``.
+
+.. py:attribute:: value
+
+   Значение аргумента. Тип значения зависит от исходного класса аргумента:
+   
+   * Для ``BooleanArgument``: ``True`` если флаг был передан при запуске
+   * Для ``ValueArgument``: строка с переданным значением или значением по умолчанию
+
+.. py:attribute:: founder_class
+
+   Ссылка на класс, из которого был создан этот аргумент. Используется для определения типа аргумента и фильтрации в методе ``get_by_type()``.
+
+**Методы:**
+
+.. py:method:: __str__() -> str
+
+   Возвращает строковое представление аргумента в формате ``InputArgument(name=value)``.
+
+   .. code-block:: python
+      :linenos:
+
+      arg = InputArgument("verbose", True, BooleanArgument)
+      print(str(arg))  # InputArgument(verbose=True)
+
+.. py:method:: __repr__() -> str
+
+   Возвращает техническое представление объекта в виде строки.