mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
Update documentation and code snippets
This commit is contained in:
@@ -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:`этом разделе<root_redirect_stdout>`.
|
||||
|
||||
-----
|
||||
|
||||
|
||||
Назначение и использование
|
||||
--------------------------
|
||||
---------------------------
|
||||
|
||||
Выбор между статической и динамической линией зависит от ваших задач.
|
||||
|
||||
|
||||
@@ -67,7 +67,7 @@ string_entity
|
||||
@property
|
||||
string_entity(self) -> str
|
||||
|
||||
Возвращает строковое представление флага в формате `prefix + name`.
|
||||
Возвращает строковое представление флага в формате ``prefix + name``.
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
|
||||
@@ -51,7 +51,7 @@ string_entity
|
||||
@property
|
||||
string_entity(self) -> str
|
||||
|
||||
Возвращает строковое представление флага в формате `prefix + name`.
|
||||
Возвращает строковое представление флага в формате ``prefix + name``.
|
||||
|
||||
:return: Строковое представление флага
|
||||
|
||||
@@ -70,7 +70,7 @@ __str__
|
||||
|
||||
Возвращает строковое представление флага вместе с его значением.
|
||||
|
||||
:return: Строка в формате `флаг значение`.
|
||||
:return: Строка в формате ``флаг значение``.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
|
||||
@@ -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:
|
||||
|
||||
@@ -25,8 +25,10 @@ ArgParser
|
||||
* ``description``: Описание приложения для отображения в справке.
|
||||
* ``epilog``: Дополнительная информация для отображения в конце справки.
|
||||
|
||||
-----
|
||||
|
||||
Атрибуты
|
||||
---------------------------
|
||||
--------
|
||||
|
||||
.. py:attribute:: parsed_argspace: ArgSpace
|
||||
|
||||
@@ -39,13 +41,14 @@ ArgParser
|
||||
|
||||
-----
|
||||
|
||||
-----
|
||||
|
||||
Лучшие практики
|
||||
------------------------
|
||||
---------------
|
||||
|
||||
Использовать атрибут ``parsed_argspace`` рекомендуется только на этапе настройки приложения. В обработчиках лучшей практикой является получение ``ArgSpace`` через DI. Подробнее см. :ref:`здесь <root_dependency_injection>`.
|
||||
|
||||
Пример использования
|
||||
--------------------
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/argparser/snippet.py
|
||||
:language: python
|
||||
|
||||
@@ -75,8 +75,8 @@ InputArgument
|
||||
|
||||
-----
|
||||
|
||||
Примеры испольования
|
||||
--------------------
|
||||
Примеры использования
|
||||
---------------------
|
||||
|
||||
``ArgSpace`` используется для доступа к значениям аргументов после запуска приложения. Типичный сценарий включает обработку аргументов через ``ArgParser`` и последующее извлечение значений из ``ArgSpace``.
|
||||
|
||||
@@ -87,6 +87,8 @@ InputArgument
|
||||
|
||||
Доступ к аргументам из обработчиков осуществляется с помощью ``di``. Подробнее см. :ref:`здесь <root_dependency_injection>`.
|
||||
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/argspace/snippet2.py
|
||||
:linenos:
|
||||
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
@@ -47,12 +47,11 @@ Orchestrator
|
||||
Назначение и использование
|
||||
----------------------------
|
||||
|
||||
``Orchestrator`` абстрагирует сложность, связанную с настройкой ``di`` и парсингом стартовых аргументов. Типичный сценарий использования выглядит так.
|
||||
``Orchestrator`` абстрагирует сложность, связанную с настройкой ``di`` и парсингом стартовых аргументов.
|
||||
|
||||
Такой подход разделяет ответственности: ``App`` отвечает за логику интерактивной сессии, а ``Orchestrator`` — за подготовку окружения и запуск приложения.
|
||||
|
||||
Пример использования
|
||||
--------------------
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/orchestrator/snippet.py
|
||||
:language: python
|
||||
|
||||
@@ -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``.
|
||||
|
||||
|
||||
@@ -3,16 +3,13 @@
|
||||
Обработка ошибок
|
||||
==========================================
|
||||
|
||||
О разделе
|
||||
------------
|
||||
|
||||
Argenta выбрасывает исключения в пограничных случаях, связанных с пользовательским вводом.
|
||||
По умолчанию они обрабатываются системными хэндлерами, но вы можете их переопределить. Это делается с помощью сеттеров экземпляра ``App`` вида ``.set_*_handler()``. Подробнее о каждом из них рассказано :ref:`ниже <possible_errors>`.
|
||||
``Argenta`` выбрасывает исключения в пограничных случаях, связанных с пользовательским вводом.
|
||||
По умолчанию они обрабатываются системными обработчиками, но вы можете их переопределить. Это делается с помощью сеттеров экземпляра ``App`` вида ``.set_*_handler()``. Подробнее о каждом из них рассказано :ref:`ниже <possible_errors>`.
|
||||
|
||||
.. note::
|
||||
Ни одно исключение не остаётся необработанным, так как для каждого случая предусмотрен стандартный хэндлер. Поэтому переопределение является опциональным.
|
||||
Ни одно исключение не остаётся необработанным, так как для каждого случая предусмотрен стандартный обработчик. Поэтому переопределение является опциональным.
|
||||
|
||||
Пример переопределения обработчика для пустой команды:
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../code_snippets/error_handling/snippet.py
|
||||
:language: python
|
||||
@@ -29,7 +26,7 @@ Argenta выбрасывает исключения в пограничных с
|
||||
|
||||
Это исключение выбрасывается, когда парсер не может обработать команду из-за некорректного синтаксиса. Чаще всего это связано с ошибкой в синтаксисе флагов. Подробнее о них можно прочитать в разделе :ref:`Flags <root_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 <root_flags>`.
|
||||
|
||||
Стандартный хэндлер выводит в консоль
|
||||
Стандартный обработчик выводит в консоль:
|
||||
|
||||
.. 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 <root_api_command_input_command>`.
|
||||
|
||||
Пример кода, переопределяющего хэндлер ввода неизвестной команды:
|
||||
**Пример использования:**
|
||||
|
||||
.. 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 <root_api_response>`.
|
||||
|
||||
Пример кода, переопределяющего хэндлер ввода команды выхода:
|
||||
**Пример использования:**
|
||||
|
||||
.. literalinclude:: ../code_snippets/error_handling/snippet6.py
|
||||
:language: python
|
||||
|
||||
+1
-1
@@ -92,7 +92,7 @@
|
||||
~~~~~~~~~~~~~~~~~
|
||||
|
||||
**Время жизни и область действия**
|
||||
Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы(скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**.
|
||||
Аргументы передаются один раз при запуске приложения и сохраняют действие на весь период работы (скоуп **APP**). Флаги наоборот локальны и живут в рамках скоупа **REQUEST**.
|
||||
|
||||
**Частота изменения**
|
||||
Для изменения аргументов необходимо перезапустить приложение. Флаги можно менять между каждым вводом команды без остановки приложения.
|
||||
|
||||
@@ -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:
|
||||
|
||||
+14
-8
@@ -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:
|
||||
|
||||
Reference in New Issue
Block a user