diff --git a/docs/index.rst b/docs/index.rst index 96be5bf..630125a 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -9,16 +9,16 @@ Argenta **Библиотека для построения модульных CLI-приложений с простым и приятным API.** У вас есть некая функциональность и вы хотите распространять её в виде CLI? Argenta поможет вам. -Основная цель библиотеки дать возможность разработчикам сфокусироваться на реализации своих идей, предоставляя для этого удобные абстракциию. +Основная цель библиотеки — дать возможность разработчикам сфокусироваться на реализации своих идей, предоставляя для этого удобные абстракции. .. image:: https://github.com/koloideal/Argenta/blob/main/imgs/mock_app_preview4.png?raw=True :alt: Пример приложения -Argenta нужна для создания приложений, которым необходим свой скоуп, то есть: при запуске приложения юзер входит в абстрагированный скоуп, +Argenta нужна для создания приложений, которым необходим свой скоуп, то есть: при запуске приложения пользователь входит в абстрагированный скоуп, в котором у него есть доступ к созданной функциональности. -Один из основных принципов библиотеки это цикличность, это значит, что после ввода юзером команды он не выходит из скоупа, в этом основное -отличие от таких библиотек, как ``argparse``, ``click`` и ``typer``. Выход из скоупа контролируется самим юзером. +Один из основных принципов библиотеки — это цикличность, это значит, что после ввода пользователем команды он не выходит из скоупа, в этом основное +отличие от таких библиотек, как ``argparse``, ``click`` и ``typer``. Выход из скоупа контролируется самим пользователем. **Ключевые особенности:** @@ -26,12 +26,12 @@ Argenta нужна для создания приложений, которым * **Маршрутизаторы**. Объекты маршрутизации, которые регистрируют обработчиков, позволяя создавать кастомные настройки для групп обработчиков, а также семантически их разделять. * **Приложение**. Объект управления жизненным циклом приложения, подключения созданных маршрутизаторов, конфигурирования различных вторичных утилит, таких как автокомплит, логирование и т.д. * **Оркестратор**. Объект *оркестрации*, который конфигурирует, запускает и управляет всеми остальными компонентами программы. -* **Внедрение зависимостей**. ``Argenta`` нативно поддерживает ``dishka`` и предоставляет возможность инжектирования зависимостей в хэндлерах, резолвя тайпхинты, подробнее_. +* **Внедрение зависимостей**. ``Argenta`` нативно поддерживает ``dishka`` и предоставляет возможность инжектирования зависимостей в хэндлерах, разрешая типы, подробнее_. .. _подробнее: https://dishka.readthedocs.io/en/stable/di_intro.html * **Поддержка флагов**. Библиотека поддерживает определение флагов, введённых вместе с командой, ``Argenta`` сама парсит и валидирует их, отдавая понятные сущности. -* **Поддержка аргументов**. Осуществленна поддержка аргументов командной строки, позволяя пользователю передавать различные параметры при запуске приложения. +* **Поддержка аргументов**. Осуществлена поддержка аргументов командной строки, позволяющая пользователю передавать различные параметры при запуске приложения. .. toctree:: :hidden: diff --git a/docs/root/api/router.rst b/docs/root/api/router.rst index fd3900d..635f8cb 100644 --- a/docs/root/api/router.rst +++ b/docs/root/api/router.rst @@ -18,7 +18,7 @@ Router __init__(self, title: str | None = None, disable_redirect_stdout: bool = False) -> None -Создает новый экземпляр маршрутизатора. +Создаёт новый экземпляр маршрутизатора. * ``title`` : Необязательный заголовок для группы команд, которые регистрируются в этом роутере. Этот заголовок будет отображаться в списке доступных команд, помогая пользователю ориентироваться. * ``disable_redirect_stdout`` : Если установлено в ``True``, отключает механизм перехвата стандартного вывода (``stdout``) для всех команд этого роутера. Это необходимо для команд, которые требуют интерактивного ввода от пользователя (например, с помощью ``input()``). При отключении перехвата вывода автоматически используется статическая разделительная линия. Подробнее в :ref:`соответствующем разделе ` @@ -53,7 +53,7 @@ Router Предопределенный экземпляр ``Router``, который содержит базовые системные команды. По умолчанию в него включена команда выхода из приложения (обычно **exit**). Он имеет заголовок **"System points:"**, который можно переопределить в инстансе приложения -> ``App``. - Вы можете добавлять свои команды в этот роутер, для этого импортируйте ``argenta.router.defaults.system_router`` и декорируйте его методом необходимые хэндлеры. + Вы можете добавлять свои команды в этот роутер, для этого импортируйте ``argenta.router.defaults.system_router`` и декорируйте необходимые хэндлеры его методом. ----- diff --git a/docs/root/dependency_injection.rst b/docs/root/dependency_injection.rst index 5118f53..9269430 100644 --- a/docs/root/dependency_injection.rst +++ b/docs/root/dependency_injection.rst @@ -22,13 +22,13 @@ :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 @@ -37,7 +37,7 @@ Как это работает? ----------------- -В основе DI в Argente лежат **провайдеры** и **контейнер**. +В основе DI в Argenta лежат **провайдеры** и **контейнер**. * **Провайдер (Provider)** — это "рецепт", который объясняет, как создавать и настраивать ту или иную зависимость (например, подключение к БД, API-клиент или любой другой сервис). * **Контейнер (IoC Container)** — это "фабрика", которая хранит все рецепты (провайдеры) и по запросу создаёт и выдаёт готовые зависимости. @@ -47,7 +47,7 @@ ``Argenta`` поставляется с предопределённым провайдером, который даёт доступ к важным системным зависимостям без какой-либо настройки. К примеру вы можете получить объект ``ArgSpace``, который представляет из себя распаршенные аргументы командной строки при запуске приложения. -Краткий сэмпл кода, который получает объект ``ArgSpace`` и выводит в консоль аргумент с именем "type": +Краткий пример кода, который получает объект ``ArgSpace`` и выводит в консоль аргумент с именем "type": .. literalinclude:: ../code_snippets/dependency_injection/snippet4.py :language: python diff --git a/docs/root/error_handling.rst b/docs/root/error_handling.rst index b6d117b..7a2d169 100644 --- a/docs/root/error_handling.rst +++ b/docs/root/error_handling.rst @@ -14,8 +14,7 @@ .. note:: Все исключения никогда не остаются необработанными, так как у них есть стандартные хэндлеры. Поэтому переопределение опционально. -Краткий сэмпл кода, переопределяющего хэндлер ввода -пустой команды +Краткий пример кода, переопределяющего хэндлер ввода пустой команды: .. literalinclude:: ../code_snippets/error_handling/snippet.py :language: python @@ -30,11 +29,11 @@ ``UnprocessedInputFlagException``: Необрабатываемый ввод от пользователя ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Исключение вызывается, когда пользователь вводит команду с некорректным синтаксисом и как следствие парсер не может -*распарсить* её. В большинстве случаев это означат, что проблема в синтаксисе введённых флагов команды, подробнее о +Исключение вызывается, когда пользователь вводит команду с некорректным синтаксисом и, как следствие, парсер не может +*распарсить* её. В большинстве случаев это означает, что проблема в синтаксисе введённых флагов команды, подробнее о флагах и их синтаксисе в :ref:`Flags `. -Дефолтный хэндлер выводит в консоль +Стандартный хэндлер выводит в консоль .. code-block:: shell @@ -44,7 +43,7 @@ протокол ``NonStandardBehaviorHandler[str]`` соответствует ``Callable[[str], None]``, то есть хэндлер должен быть вызываемым объектом, к примеру функция или лямбда, которая принимает единственный аргумент - строку, которая представляет собой необработанную введённую команду, и ничего не возвращает. -Сэмпл кода, переопределяющего хэндлер ввода команды с некорректным синтаксисом: +Пример кода, переопределяющего хэндлер ввода команды с некорректным синтаксисом: .. literalinclude:: ../code_snippets/error_handling/snippet2.py :language: python @@ -61,7 +60,7 @@ .. note:: Сравнение на равенство у регистрируемых флагов(Flag) происходит иначе, подробнее в :ref:`Flag `. -Дефолтный хэндлер выводит в консоль +Стандартный хэндлер выводит в консоль .. code-block:: shell @@ -71,7 +70,7 @@ протокол ``NonStandardBehaviorHandler[str]`` соответствует ``Callable[[str], None]``, то есть хэндлер должен быть вызываемым объектом, к примеру функция или лямбда, которая принимает единственный аргумент - строку, которая представляет собой необработанную введённую команду, и ничего не возвращает. -Сэмпл кода, переопределяющего хэндлер ввода команды с повторяющимися флагами: +Пример кода, переопределяющего хэндлер ввода команды с повторяющимися флагами: .. literalinclude:: ../code_snippets/error_handling/snippet3.py :language: python @@ -84,7 +83,7 @@ Исключение вызывается, когда пользователь вводит команду в виде строки из пробельных символов - ``\n``, ``\t``, пробел и т.д. -Дефолтный хэндлер выводит в консоль +Стандартный хэндлер выводит в консоль .. code-block:: shell @@ -94,7 +93,7 @@ протокол ``EmptyCommandHandler`` соответствует ``Callable[[], None]``, то есть хэндлер должен быть вызываемым объектом, к примеру функция или лямбда, которая не принимает аргументов и ничего не возвращает. -Сэмпл кода, переопределяющего хэндлер ввода пустой команды: +Пример кода, переопределяющего хэндлер ввода пустой команды: .. literalinclude:: ../code_snippets/error_handling/snippet4.py :language: python @@ -108,7 +107,7 @@ Поведение триггерится, когда пользователь вводит команду, которая не зарегистрирована ни в одном роутере и не является алиасом ни для одной зарегистрированной команды. -Дефолтный хэндлер выводит в консоль +Стандартный хэндлер выводит в консоль .. code-block:: shell @@ -118,7 +117,7 @@ протокол ``NonStandardBehaviorHandler[InputCommand]`` соответствует ``Callable[[InputCommand], None]``, то есть хэндлер должен быть вызываемым объектом, к примеру функция или лямбда, которая принимает обязательный аргумент типа :ref:`InputCommand ` и ничего не возвращает. -Сэмпл кода, переопределяющего хэндлер ввода неизвестной команды: +Пример кода, переопределяющего хэндлер ввода неизвестной команды: .. literalinclude:: ../code_snippets/error_handling/snippet5.py :language: python @@ -131,7 +130,7 @@ Поведение триггерится, когда пользователь вводит команду, которая маркирована как команда завершения работы. -Дефолтный хэндлер выводит в консоль текст и завершает работу приложения. +Стандартный хэндлер выводит в консоль текст и завершает работу приложения. .. code-block:: shell @@ -141,7 +140,7 @@ протокол ``NonStandardBehaviorHandler[Response]`` соответствует ``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 0be338e..53dec82 100644 --- a/docs/root/flags.rst +++ b/docs/root/flags.rst @@ -16,15 +16,15 @@ -То есть, у флага обязательно должен быть префикс, который может быть одним, двум или трем минусам. После префикса следует имя флага, без -пробела, после, через пробел, идёт значение флага, если оно есть. +То есть у флага обязательно должен быть префикс, который может быть одним, двумя или тремя минусами. После префикса следует имя флага, без +пробела, после чего, через пробел, идёт значение флага, если оно есть. ----- Два типа флагов --------------- -Флаги бывают двух основных видов: без значений (переключатели) и со значениями. ``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности для одной команды. +Флаги бывают двух основных видов: без значений (переключатели) и со значениями. ``Argenta`` позволяет регистрировать и вводить флаги обоих типов в любой последовательности для одной команды. .. note:: Ошибки валидации значений являются пассивными, их не нужно обрабатывать явно. У каждого инстанса :ref:`InputFlag ` есть поле ``status``, по которому можно определить результат валидации флага. **Конкретная реализация и описание API вы можете найти в разделе** :ref:`Flag `. diff --git a/docs/root/quickstart.rst b/docs/root/quickstart.rst index 135674f..1579117 100644 --- a/docs/root/quickstart.rst +++ b/docs/root/quickstart.rst @@ -15,7 +15,7 @@ :language: python :linenos: -3. **Определение приложения и оркестратора**. Для запуска приложения необходимо вызвать ``.include_router()`` у созданного приложения и передать ему раннее созданный роутер, после этого необходимо вызвать ``.start_polling()`` у созданного оркестратора и передать ему созданное приложение. +3. **Определение приложения и оркестратора**. Для запуска приложения необходимо вызвать ``.include_router()`` у созданного приложения и передать ему ранее созданный роутер, после этого необходимо вызвать ``.start_polling()`` у созданного оркестратора и передать ему созданное приложение. .. literalinclude:: ../code_snippets/quickstart/main.py :language: python