diff --git a/docs/index.rst b/docs/index.rst index d600571..c571115 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -19,15 +19,15 @@ Argenta Argenta предназначена для создания приложений, работающих в собственном контексте (scope). Это означает, что при запуске пользователь входит в интерактивную сессию, где ему доступна вся реализованная вами функциональность. -Один из ключевых принципов библиотеки — цикличность. После выполнения команды пользователь остаётся в интерактивной сессии, в отличие от таких библиотек, как ``argparse``, ``click`` и ``typer``. Выход из сессии контролируется самим пользователем. +Один из ключевых принципов библиотеки — цикличность. После выполнения команды пользователь остаётся в интерактивной сессии, в отличие от таких библиотек, как ``argparse``, ``click`` и ``typer``. Выход из сессии контролируется пользователем. **Ключевые особенности:** -* **Интерактивные сессии**. В отличие от традиционных CLI-инструментов, Argenta создаёт циклические сессии, позволяя пользователю выполнять команды последовательно, не перезапуская приложение. -* **Декларативный синтаксис**. Команды и их обработчики объявляются с помощью простых декораторов, что делает код чистым и интуитивно понятным. -* **Нативный DI**. Благодаря интеграции с `dishka `_, вы можете легко внедрять зависимости прямо в обработчики команд, что упрощает их тестирование и переиспользование. -* **Автоматическая валидация и парсинг**. Библиотека берёт на себя обработку флагов и аргументов командной строки, включая их парсинг, валидацию и преобразование типов. -* **Гибкая настройка**. Вы можете легко кастомизировать системные сообщения, форматирование вывода и т.д. +* **Интерактивные сессии**: В отличие от традиционных CLI-инструментов, ``Argenta`` создаёт циклические сессии, позволяя пользователю выполнять команды последовательно, не перезапуская приложение. +* **Декларативный синтаксис**: Команды и их обработчики объявляются с помощью простых декораторов, что делает код чистым и интуитивно понятным. +* **Нативный DI**: Благодаря интеграции с `dishka `_, вы можете легко внедрять зависимости прямо в обработчики команд, что упрощает их тестирование и переиспользование. +* **Автоматическая валидация и парсинг**: Библиотека берёт на себя обработку флагов и аргументов командной строки, включая их парсинг, валидацию и преобразование типов. +* **Гибкая настройка**: Вы можете легко кастомизировать системные сообщения, форматирование вывода и т.д. ----- diff --git a/docs/root/api/app/dividing_lines.rst b/docs/root/api/app/dividing_lines.rst index e120562..bcb70fd 100644 --- a/docs/root/api/app/dividing_lines.rst +++ b/docs/root/api/app/dividing_lines.rst @@ -5,10 +5,10 @@ Dividing Lines Разделительные линии в ``Argenta`` используются для визуального структурирования вывода и отделения блоков информации друг от друга. Библиотека предлагает два типа линий: статическую и динамическую. ----- +----- ``StaticDividingLine`` ------------------------------ +---------------------- ``StaticDividingLine`` создаёт разделительную линию **фиксированной** длины. Этот тип линии полезен для создания предсказуемого и унифицированного интерфейса. @@ -26,7 +26,7 @@ Dividing Lines ----- ``DynamicDividingLine`` ------------------------------- +----------------------- ``DynamicDividingLine`` создаёт линию, длина которой **динамически** подстраивается под самую длинную строку в выводе команды. Это требует перехвата ``stdout``, в результате чего разделители идеально обрамляют выводимый контент. @@ -45,9 +45,9 @@ Dividing Lines Обязательно почитайте про нюансы использования динамических линий и перехвата ``stdout`` в :ref:`этом разделе`. ----- - + Назначение и использование --------------------------- +--------------------------- Выбор между статической и динамической линией зависит от ваших задач. diff --git a/docs/root/api/command/flag.rst b/docs/root/api/command/flag.rst index 7fa886e..1979edb 100644 --- a/docs/root/api/command/flag.rst +++ b/docs/root/api/command/flag.rst @@ -67,7 +67,7 @@ string_entity @property string_entity(self) -> str -Возвращает строковое представление флага в формате `prefix + name`. +Возвращает строковое представление флага в формате ``prefix + name``. :return: Строковое представление флага diff --git a/docs/root/api/command/input_flag.rst b/docs/root/api/command/input_flag.rst index 27e8df5..21ca776 100644 --- a/docs/root/api/command/input_flag.rst +++ b/docs/root/api/command/input_flag.rst @@ -51,7 +51,7 @@ string_entity @property string_entity(self) -> str -Возвращает строковое представление флага в формате `prefix + name`. +Возвращает строковое представление флага в формате ``prefix + name``. :return: Строковое представление флага @@ -70,7 +70,7 @@ __str__ Возвращает строковое представление флага вместе с его значением. -:return: Строка в формате `флаг значение`. +:return: Строка в формате ``флаг значение``. **Пример использования:** diff --git a/docs/root/api/command/input_flags.rst b/docs/root/api/command/input_flags.rst index 782863c..64bea46 100644 --- a/docs/root/api/command/input_flags.rst +++ b/docs/root/api/command/input_flags.rst @@ -83,10 +83,10 @@ add_flag Добавляет введённый флаг в коллекцию. -:param flag: Флаг типа `InputFlag` для добавления. +:param flag: Флаг типа ``InputFlag`` для добавления. :return: None. -Метод добавляет флаг в конец списка `flags`. Используется для динамического расширения коллекции. +Метод добавляет флаг в конец списка ``flags``. Используется для динамического расширения коллекции. .. note:: Этот метод используется редко, так как `InputFlags` обычно создаётся автоматически. Однако он может быть полезен для тестирования или ручного создания коллекций. @@ -109,7 +109,7 @@ add_flags Добавляет в коллекцию список введённых флагов. -:param flags: Список флагов типа `InputFlag` для добавления. +:param flags: Список флагов типа ``InputFlag`` для добавления. :return: None. Метод расширяет коллекцию, добавляя в неё все флаги из переданного списка. Эффективен для пакетного добавления. @@ -128,7 +128,7 @@ add_flags Обработка всех флагов с проверкой статусов ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Пример демонстрирует итерацию по всем введённым флагам с проверкой их статусов валидации: +**Пример использования:** .. literalinclude:: ../../../code_snippets/input_flags/snippet10.py :linenos: diff --git a/docs/root/api/orchestrator/argparser.rst b/docs/root/api/orchestrator/argparser.rst index b8cef0c..859ed48 100644 --- a/docs/root/api/orchestrator/argparser.rst +++ b/docs/root/api/orchestrator/argparser.rst @@ -25,8 +25,10 @@ ArgParser * ``description``: Описание приложения для отображения в справке. * ``epilog``: Дополнительная информация для отображения в конце справки. +----- + Атрибуты ---------------------------- +-------- .. py:attribute:: parsed_argspace: ArgSpace @@ -39,13 +41,14 @@ ArgParser ----- +----- + Лучшие практики ------------------------- +--------------- Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через DI. Подробнее см. :ref:`здесь `. -Пример использования --------------------- +**Пример использования:** .. literalinclude:: ../../../code_snippets/argparser/snippet.py :language: python diff --git a/docs/root/api/orchestrator/argspace.rst b/docs/root/api/orchestrator/argspace.rst index 082d733..322e537 100644 --- a/docs/root/api/orchestrator/argspace.rst +++ b/docs/root/api/orchestrator/argspace.rst @@ -75,8 +75,8 @@ InputArgument ----- -Примеры испольования --------------------- +Примеры использования +--------------------- ``ArgSpace`` используется для доступа к значениям аргументов после запуска приложения. Типичный сценарий включает обработку аргументов через ``ArgParser`` и последующее извлечение значений из ``ArgSpace``. @@ -87,6 +87,8 @@ InputArgument Доступ к аргументам из обработчиков осуществляется с помощью ``di``. Подробнее см. :ref:`здесь `. +**Пример использования:** + .. literalinclude:: ../../../code_snippets/argspace/snippet2.py :linenos: diff --git a/docs/root/api/orchestrator/arguments.rst b/docs/root/api/orchestrator/arguments.rst index 40093a4..f060168 100644 --- a/docs/root/api/orchestrator/arguments.rst +++ b/docs/root/api/orchestrator/arguments.rst @@ -35,8 +35,8 @@ ValueArgument :param help: Сообщение для справки (``--help``) :param possible_values: Список допустимых значений :param default: Значение по умолчанию, если аргумент не передан -:param is_required: Если ``True``, аргумент становится обязательным, если не передать при запуске приложение не запустится -:param is_deprecated: Если ``True``, помечает аргумент как устаревший, если передать при запуске, то будет выведено предупреждение в консоль +:param is_required: Если ``True``, аргумент становится обязательным. Если не передать при запуске, приложение не запустится +:param is_deprecated: Если ``True``, помечает аргумент как устаревший. Если передать при запуске, будет выведено предупреждение в консоль **Пример использования:** @@ -115,7 +115,7 @@ InputArgument Создаёт экземпляр обработанного входного аргумента. :param name: Имя аргумента -:param value: Значение аргумента. Для ``BooleanArgument`` — **True**, если аргумент передан и **False**, если нет; для **ValueArgument** — введённая строка +:param value: Значение аргумента. Для ``BooleanArgument`` — **True**, если аргумент передан, и **False**, если нет; для ``ValueArgument`` — введённая строка :param founder_class: Класс-родитель, из которого был создан аргумент (``BooleanArgument`` или ``ValueArgument``) **Атрибуты:** @@ -128,8 +128,8 @@ InputArgument Значение аргумента. Тип зависит от исходного класса: -* Для ``BooleanArgument``: **True**, если аргумент был передан. -* Для ``ValueArgument``: строка с переданным значением или значением по умолчанию + * Для ``BooleanArgument``: **True**, если аргумент был передан + * Для ``ValueArgument``: строка с переданным значением или значением по умолчанию .. py:attribute:: founder_class diff --git a/docs/root/api/orchestrator/index.rst b/docs/root/api/orchestrator/index.rst index 296f05c..826c85e 100644 --- a/docs/root/api/orchestrator/index.rst +++ b/docs/root/api/orchestrator/index.rst @@ -47,12 +47,11 @@ Orchestrator Назначение и использование ---------------------------- -``Orchestrator`` абстрагирует сложность, связанную с настройкой ``di`` и парсингом стартовых аргументов. Типичный сценарий использования выглядит так. +``Orchestrator`` абстрагирует сложность, связанную с настройкой ``di`` и парсингом стартовых аргументов. Такой подход разделяет ответственности: ``App`` отвечает за логику интерактивной сессии, а ``Orchestrator`` — за подготовку окружения и запуск приложения. -Пример использования --------------------- +**Пример использования:** .. literalinclude:: ../../../code_snippets/orchestrator/snippet.py :language: python diff --git a/docs/root/dependency_injection.rst b/docs/root/dependency_injection.rst index 20a4a67..9dc8205 100644 --- a/docs/root/dependency_injection.rst +++ b/docs/root/dependency_injection.rst @@ -18,17 +18,23 @@ .. note:: ``argenta.di.FromDishka`` является алиасом для ``dishka.FromDishka``, и они полностью взаимозаменяемы. +**Пример использования:** + .. literalinclude:: ../code_snippets/dependency_injection/snippet.py :language: python :linenos: -``Argenta`` с помощью ``dishka`` разрешит зависимость по типу ``Connection`` и внедрит её. Но прежде чем использовать зависимость, её необходимо объявить в провайдере. +``Argenta`` с помощью ``dishka`` разрешит зависимость по типу ``Connection`` и внедрит её. Но прежде чем использовать зависимость, её необходимо объявить в провайдере: + +**Пример использования:** .. literalinclude:: ../code_snippets/dependency_injection/snippet2.py :language: python :linenos: -После создания провайдера его необходимо зарегистрировать в оркестраторе. +После создания провайдера его необходимо зарегистрировать в оркестраторе: + +**Пример использования:** .. literalinclude:: ../code_snippets/dependency_injection/snippet3.py :language: python @@ -51,7 +57,7 @@ ``Argenta`` поставляется со встроенным провайдером, который даёт доступ к важным системным зависимостям без дополнительной настройки. Например, вы можете получить объект ``ArgSpace``, который содержит аргументы командной строки, переданные при запуске приложения. -Пример получения объекта ``ArgSpace`` и вывода в консоль значения аргумента `type`: +**Пример использования:** .. literalinclude:: ../code_snippets/dependency_injection/snippet4.py :language: python @@ -59,8 +65,8 @@ ----- -Обмен данными между хендлерами ------------------------------- +Обмен данными между обработчиками +---------------------------------- Помимо DI, обработчики могут обмениваться данными в рамках сессии через **объект контекста**. В ``Argenta`` эту роль выполняет объект ``DataBridge``. diff --git a/docs/root/error_handling.rst b/docs/root/error_handling.rst index d28c46d..d269478 100644 --- a/docs/root/error_handling.rst +++ b/docs/root/error_handling.rst @@ -3,16 +3,13 @@ Обработка ошибок ========================================== -О разделе ------------- - -Argenta выбрасывает исключения в пограничных случаях, связанных с пользовательским вводом. -По умолчанию они обрабатываются системными хэндлерами, но вы можете их переопределить. Это делается с помощью сеттеров экземпляра ``App`` вида ``.set_*_handler()``. Подробнее о каждом из них рассказано :ref:`ниже `. +``Argenta`` выбрасывает исключения в пограничных случаях, связанных с пользовательским вводом. +По умолчанию они обрабатываются системными обработчиками, но вы можете их переопределить. Это делается с помощью сеттеров экземпляра ``App`` вида ``.set_*_handler()``. Подробнее о каждом из них рассказано :ref:`ниже `. .. note:: - Ни одно исключение не остаётся необработанным, так как для каждого случая предусмотрен стандартный хэндлер. Поэтому переопределение является опциональным. + Ни одно исключение не остаётся необработанным, так как для каждого случая предусмотрен стандартный обработчик. Поэтому переопределение является опциональным. -Пример переопределения обработчика для пустой команды: +**Пример использования:** .. literalinclude:: ../code_snippets/error_handling/snippet.py :language: python @@ -29,7 +26,7 @@ Argenta выбрасывает исключения в пограничных с Это исключение выбрасывается, когда парсер не может обработать команду из-за некорректного синтаксиса. Чаще всего это связано с ошибкой в синтаксисе флагов. Подробнее о них можно прочитать в разделе :ref:`Flags `. -Стандартный хэндлер выводит в консоль +Стандартный обработчик выводит в консоль: .. code-block:: shell @@ -37,7 +34,7 @@ Argenta выбрасывает исключения в пограничных с Для переопределения используется сеттер ``.set_incorrect_input_syntax_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[str], None]``, где единственный аргумент — это строка с необработанной командой. -Пример кода, переопределяющего хэндлер ввода команды с некорректным синтаксисом: +**Пример использования:** .. literalinclude:: ../code_snippets/error_handling/snippet2.py :language: python @@ -53,7 +50,7 @@ Argenta выбрасывает исключения в пограничных с .. note:: Сравнение на равенство у регистрируемых флагов (``Flag``) происходит иначе, подробнее в :ref:`Flag `. -Стандартный хэндлер выводит в консоль +Стандартный обработчик выводит в консоль: .. code-block:: shell @@ -61,7 +58,7 @@ Argenta выбрасывает исключения в пограничных с Для переопределения используется сеттер ``.set_repeated_input_flags_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[str], None]``, где единственный аргумент — это строка с необработанной командой. -Пример кода, переопределяющего хэндлер ввода команды с повторяющимися флагами: +**Пример использования:** .. literalinclude:: ../code_snippets/error_handling/snippet3.py :language: python @@ -74,7 +71,7 @@ Argenta выбрасывает исключения в пограничных с Исключение выбрасывается, если пользователь ввёл пустую строку или строку, состоящую только из пробельных символов (``\n``, ``\t``, пробел и т.д.). -Стандартный хэндлер выводит в консоль +Стандартный обработчик выводит в консоль: .. code-block:: shell @@ -82,7 +79,7 @@ Argenta выбрасывает исключения в пограничных с Для переопределения используется сеттер ``.set_empty_command_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[], None]`` (без аргументов). -Пример кода, переопределяющего хэндлер ввода пустой команды: +**Пример использования:** .. literalinclude:: ../code_snippets/error_handling/snippet4.py :language: python @@ -97,7 +94,7 @@ Argenta выбрасывает исключения в пограничных с Это поведение активируется, когда пользователь вводит команду, которая не зарегистрирована ни в одном из роутеров и не является псевдонимом (alias) для существующей команды. -Стандартный хэндлер выводит в консоль +Стандартный обработчик выводит в консоль: .. code-block:: shell @@ -105,7 +102,7 @@ Argenta выбрасывает исключения в пограничных с Для переопределения используется сеттер ``.set_unknown_command_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[InputCommand], None]``, где аргумент — объект :ref:`InputCommand `. -Пример кода, переопределяющего хэндлер ввода неизвестной команды: +**Пример использования:** .. literalinclude:: ../code_snippets/error_handling/snippet5.py :language: python @@ -118,7 +115,7 @@ Argenta выбрасывает исключения в пограничных с Это поведение активируется, когда пользователь вводит команду, помеченную как команда выхода. -Стандартный хэндлер выводит в консоль текст и завершает работу приложения. +Стандартный обработчик выводит в консоль текст и завершает работу приложения: .. code-block:: shell @@ -126,7 +123,7 @@ Argenta выбрасывает исключения в пограничных с Для переопределения используется сеттер ``.set_exit_command_handler()``. Он принимает на вход обработчик с сигнатурой ``Callable[[Response], None]``, где аргумент — объект :ref:`Response `. -Пример кода, переопределяющего хэндлер ввода команды выхода: +**Пример использования:** .. literalinclude:: ../code_snippets/error_handling/snippet6.py :language: python diff --git a/docs/root/flags.rst b/docs/root/flags.rst index e0c92d1..de9d04f 100644 --- a/docs/root/flags.rst +++ b/docs/root/flags.rst @@ -92,7 +92,7 @@ ~~~~~~~~~~~~~~~~~ **Время жизни и область действия** - Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы(скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**. + Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы (скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**. **Частота изменения** Для изменения аргументов необходимо перезапустить приложение. Флаги можно менять между каждым вводом команды без остановки приложения. diff --git a/docs/root/redirect_stdout.rst b/docs/root/redirect_stdout.rst index f12ecb3..32833a8 100644 --- a/docs/root/redirect_stdout.rst +++ b/docs/root/redirect_stdout.rst @@ -54,6 +54,8 @@ Если при создании роутера установить ``disable_redirect_stdout=True``, механизм перехвата ``stdout`` будет отключён для всех его обработчиков. +**Пример использования:** + .. literalinclude:: ../code_snippets/redirect_stdout/sample.py :language: python :linenos: @@ -82,6 +84,8 @@ Вы можете глобально задать тип разделителя для всего приложения через аргумент ``dividing_line`` в конструкторе ``App``. +**Пример использования:** + .. literalinclude:: ../code_snippets/redirect_stdout/sample2.py :language: python :linenos: diff --git a/docs/root/testing.rst b/docs/root/testing.rst index 652ddc0..22e7b29 100644 --- a/docs/root/testing.rst +++ b/docs/root/testing.rst @@ -3,12 +3,12 @@ В этом разделе описаны практики тестирования приложений на основе ``Argenta``. Примеры основаны на фактическом публичном API. -Модульное тестирование хендлеров --------------------------------- +Модульное тестирование обработчиков +------------------------------------ -Обработчики в Argenta — обычные функции. Их удобно тестировать как чистые функции, не поднимая весь цикл приложения. Рекомендуются ``unittest`` или ``pytest``. +Обработчики в ``Argenta`` — обычные функции. Их удобно тестировать как чистые функции, не поднимая весь цикл приложения. Рекомендуются ``unittest`` или ``pytest``. -Пример для простого хендлера без DI: +**Пример использования:** .. literalinclude:: ../code_snippets/testing/simple_handler_unittest.py :language: python @@ -19,7 +19,9 @@ Тестирование с внедрением зависимостей (DI) ------------------------------------------- -Если хендлеру нужны зависимости, используйте ``dishka`` и интеграцию Argenta: +Если обработчику нужны зависимости, используйте ``dishka`` и интеграцию ``Argenta``: + +**Пример использования:** .. literalinclude:: ../code_snippets/testing/di_handler_unittest.py :language: python @@ -30,7 +32,9 @@ Интеграционное тестирование приложения -------------------------------------- -Для более высокого уровня тестов собирайте ``App`` и ``Router`` и вызывайте хендлеры через парсинг команд, обходя бесконечный цикл ввода. Это даёт близкое к реальности поведение без необходимости симулировать ``stdin``. +Для более высокого уровня тестов собирайте ``App`` и ``Router`` и вызывайте обработчики через парсинг команд, обходя бесконечный цикл ввода. Это даёт близкое к реальности поведение без необходимости симулировать ``stdin``. + +**Пример использования:** .. literalinclude:: ../code_snippets/testing/app_integration_unittest.py :language: python @@ -39,13 +43,15 @@ ----- E2E-тестирование цикла ------------------------------------- +---------------------- Полный запуск цикла ``start_polling`` можно покрывать через подпроцесс с передачей строк в ``stdin``. Это тяжелее и обычно не требуется. Если всё же необходимо — пример ниже. -.. danger :: +.. danger:: Обязательно передавайте строковый триггер команды выхода последним элементом в списке, который передаёте в контекстном менеджере при патче ``input`` как аргумент ``side_effects``, иначе тестируемое приложение будет ожидать ввода следующей команды и не сможет корректно завершиться. +**Пример использования:** + .. literalinclude:: ../code_snippets/testing/app_e2e_test.py :language: python :linenos: