docs

docs/root/api/orchestrator/argspace.rst

@@ -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