feat: impl docs (#4)

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.
2026-06-10 10:05:28 +03:00 · 2025-12-04 21:55:19 +03:00
parent a2ac6a608f
commit ce7e24b924
210 changed files with 13770 additions and 1183 deletions
@@ -0,0 +1,86 @@
+.. _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
@@ -0,0 +1,103 @@
+.. _root_api_orchestrator_argspace:
+
+ArgSpace
+==========
+
+``ArgSpace`` — это контейнер для хранения и управления обработанными аргументами командной строки. Его основная задача — предоставить удобный интерфейс для доступа к значениям, переданным при запуске приложения.
+
+``ArgSpace`` создаётся автоматически после обработки аргументов с помощью ``ArgParser`` и содержит коллекцию объектов ``InputArgument``.
+
+-----
+
+Инициализация
+-------------
+
+Создание экземпляров класса ``ArgSpace`` происходит под `капотом`, вам не нужно создавать их вручную.
+
+**Атрибуты:**
+
+.. 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``, если аргумент не найден.
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/argspace/snippet4.py
+   :linenos:
+
+-----
+
+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`` и возвращает аргументы, созданные из указанного типа.
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/argspace/snippet3.py
+   :linenos:
+
+-----
+
+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 --host 0.0.0.0 --port 9000
+   # Output:
+   # Server configuration:
+   #   Host: 0.0.0.0
+   #   Port: 9000
@@ -0,0 +1,137 @@
+.. _root_api_orchestrator_arguments:
+
+Arguments
+=========
+
+Модуль ``Arguments`` предоставляет классы для работы с аргументами командной строки. Они позволяют настраивать поведение приложения в момент его запуска, передавая различные параметры конфигурации.
+
+Аргументы регистрируются в ``ArgParser`` и после обработки становятся доступными в объекте ``ArgSpace``.
+
+-----
+
+ValueArgument
+-------------
+
+Класс для аргументов, требующих передачи значения.
+
+.. py:class:: ValueArgument(BaseArgument)
+    :no-index:
+
+.. 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: Список допустимых значений 
+:param default: Значение по умолчанию, если аргумент не передан
+:param is_required: Если ``True``, аргумент становится обязательным. Если не передать при запуске, приложение не запустится
+:param is_deprecated: Если ``True``, помечает аргумент как устаревший. Если передать при запуске, будет выведено предупреждение в консоль
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/arguments/snippet.py
+   :language: python
+   :linenos:
+
+**Запуск приложения:**
+
+.. 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)
+    :no-index:
+
+.. 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: Если ``True``, помечает аргумент как устаревший
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/arguments/snippet2.py
+   :language: python
+   :linenos:
+
+**Запуск приложения:**
+
+.. code-block:: bash
+
+   python app.py --verbose
+   python app.py --debug --no-cache
+   python app.py  # without arguments
+
+-----
+
+.. _root_api_orchestrator_arguments_inputargument:
+
+InputArgument
+-------------
+
+.. seealso::
+   ``InputArgument`` напрямую связан с контейнером ``ArgSpace`` и является его наполнителем. Подробнее о нём см. :ref:`здесь <root_api_orchestrator_argspace>`.
+
+Представляет собой обработанный аргумент командной строки. Этот класс используется внутри ``ArgSpace`` для хранения значений, полученных после парсинга.
+
+.. py:class:: InputArgument
+    :no-index:
+
+.. code-block:: python
+   :linenos:
+
+   __init__(self, name: str,
+            value: str | Literal[True],
+            founder_class: type[BaseArgument]) -> None
+
+Создаёт экземпляр обработанного входного аргумента.
+
+:param name: Имя аргумента
+:param value: Значение аргумента. Для ``BooleanArgument`` — **True**, если аргумент передан, и **False**, если нет; для ``ValueArgument`` — введённая строка 
+:param founder_class: Класс-родитель, из которого был создан аргумент (``BooleanArgument`` или ``ValueArgument``)
+
+**Атрибуты:**
+
+.. py:attribute:: name
+   :no-index:
+
+   Имя аргумента, указанное при создании ``ValueArgument`` или ``BooleanArgument``.
+
+.. py:attribute:: value
+
+   Значение аргумента. Тип зависит от исходного класса:
+
+   * Для ``BooleanArgument``: **True**, если аргумент был передан
+   * Для ``ValueArgument``: строка с переданным значением или значением по умолчанию
+
+.. py:attribute:: founder_class
+
+   Ссылка на класс-родитель. Используется для определения типа и фильтрации.
@@ -0,0 +1,64 @@
+.. _root_api_orchestrator_index:
+
+Orchestrator
+====================
+
+``Orchestrator`` — это высокоуровневый компонент, который конфигурирует и оркестрирует приложение, парсер командной строки, DI и остальные компоненты, находящиеся по иерархии на уровне с ``App``.
+
+В то время как ``App`` отвечает за логику интерактивной сессии (ввод команд, маршрутизация), ``Orchestrator`` подготавливает окружение для его работы и служит точкой входа в приложение.
+
+-----
+
+Инициализация
+-------------
+
+.. code-block:: python
+   :linenos:
+
+   DEFAULT_ARGPARSER: ArgParser = ArgParser(processed_args=[])
+
+   
+.. code-block:: python
+      :linenos:
+   
+      def __init__(self, arg_parser: ArgParser = DEFAULT_ARGPARSER, 
+                   custom_providers: list[Provider] = [], 
+                   auto_inject_handlers: bool = True) -> None
+
+Создаёт и конфигурирует экземпляр ``Orchestrator``.
+
+* ``arg_parser``: Экземпляр ``ArgParser``, отвечающий за парсинг аргументов командной строки при запуске скрипта (не путать с командами в интерактивном режиме).
+* ``custom_providers``: Список пользовательских провайдеров ``dishka.Provider`` для добавления ваших сервисов (например, подключений к БД или API-клиентов) в di-контейнер.
+* ``auto_inject_handlers``: Если **True** (по умолчанию), ``dishka`` автоматически внедрит зависимости в обработчики команд, инспектируя их сигнатуры.
+
+-----
+
+Основные методы
+----------------
+
+.. py:method:: start_polling(self, app: App) -> None
+
+   Это главный метод, который запускает приложение. Он запускает бесконечный цикл ввода -> вывода.
+
+   :param app: Экземпляр ``App``, который будет запущен.
+
+-----
+   
+Назначение и использование
+----------------------------
+
+``Orchestrator`` абстрагирует сложность, связанную с настройкой DI и парсингом стартовых аргументов.
+
+Такой подход разделяет ответственности: ``App`` отвечает за логику интерактивной сессии, а ``Orchestrator`` — за подготовку окружения и запуск приложения.
+
+**Пример использования:**
+
+.. literalinclude:: ../../../code_snippets/orchestrator/snippet.py
+   :language: python
+
+.. toctree::
+    :hidden:
+
+    argparser
+    arguments
+    argspace