docs

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())

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
+      :linenos:
    
-   def __init__(self, processed_args: list[argenta.orchestrator.InputArgument] = []) -> None
+      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:`тут <root_api_orchestrator_arguments>`.
+* ``name``: Имя приложения, которое будет отображаться в справке.
+* ``description``: Описание приложения, которое будет отображаться в справке.
+* ``epilog``: Дополнительная информация, которая будет отображаться в конце справки.
 
-Основные методы
+Основные методы и атрибуты
----------------
+---------------------------
 
-.. py:method:: parse(self) -> dict[str, str | list[str]]
+.. py:attribute:: parsed_argspace: ArgSpace
 
-   Основной метод, который выполняет разбор списка `processed_args`. Он анализирует аргументы и преобразует их в структурированный словарь.
+   Экземпляр класса ``ArgSpace``, который содержит все обработанные аргументы командной строки, подробнее :ref:`тут <root_api_orchestrator_argspace>`.
 
-   *   Аргументы, имеющие вид флага (например, `--verbose`), получают значение `True`.
+.. caution::
-   *   Аргументы, за которыми следует значение (например, `--config settings.yaml`), сохраняются как пара "ключ-значение".
+   До инициализации инстанса ``Orchestrator``, которому в конструктор был передан соответствующий экземпляр ``ArgParser``, атрибут ``parsed_argspace`` будет равен пустому ``ArgSpace``.
-   *   Если один и тот же аргумент встречается несколько раз, его значения могут быть собраны в список.
    
-   :returns: Словарь, где ключи — это имена аргументов, а значения — их соответствующие значения.
+   Парсинг и валидация аргументов командной строки происходит при инициализации ``Orchestrator``, соответственно использование атрибута ``parsed_argspace`` **целесообразно только после инициализации** ``Orchestrator``.
 
-.. 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()`.
    
 Назначение и интеграция
 ------------------------
 
-`ArgParser` является неотъемлемой частью `Orchestrator`. При создании `Orchestrator` ему передается экземпляр `ArgParser`, который обычно инициализируется с `sys.argv[1:]`.
+Использование атрибута ``parsed_argspace`` рекомендуется только на этапе настройки приложения, в хэндлерах лучшей практикой является получение ``ArgSpace`` через ``di``,  подробнее :ref:`тут <root_dependency_injection>`.
-
-После этого `Orchestrator` помещает `ArgParser` в DI-контейнер. Это означает, что любой ваш сервис или обработчик команды может запросить `ArgParser` через внедрение зависимостей и получить доступ к стартовым аргументам приложения. Это предпочтительный способ для конфигурации компонентов на основе параметров запуска.
 
 Пример использования
 --------------------
 
-.. code-block:: python
+.. literalinclude:: ../../../code_snippets/argparser_snippet.py
-
+   :language: python
-    import sys
+   :linenos:
-    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)
-
-

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():