docs

2026-06-10 10:05:28 +03:00 · 2025-11-01 12:00:23 +03:00
parent 9b28ef17ff
commit acddb1fbc6
6 changed files with 29 additions and 30 deletions
@@ -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:
@@ -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:`соответствующем разделе <root_redirect_stdout>`
@@ -53,7 +53,7 @@ Router
   Предопределенный экземпляр ``Router``, который содержит базовые системные команды. По умолчанию в него включена команда выхода из приложения (обычно **exit**). Он имеет заголовок **"System points:"**, который можно переопределить в инстансе приложения -> ``App``.
-   Вы можете добавлять свои команды в этот роутер, для этого импортируйте ``argenta.router.defaults.system_router`` и декорируйте его методом необходимые хэндлеры.
+   Вы можете добавлять свои команды в этот роутер, для этого импортируйте ``argenta.router.defaults.system_router`` и декорируйте необходимые хэндлеры его методом.
 -----   
@@ -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
@@ -14,8 +14,7 @@
 .. note::
    Все исключения никогда не остаются необработанными, так как у них есть стандартные хэндлеры. Поэтому переопределение опционально.
-Краткий сэмпл кода, переопределяющего хэндлер ввода
+Краткий пример кода, переопределяющего хэндлер ввода пустой команды:
 пустой команды
 .. literalinclude:: ../code_snippets/error_handling/snippet.py
    :language: python
@@ -30,11 +29,11 @@
 ``UnprocessedInputFlagException``: Необрабатываемый ввод от пользователя
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-Исключение вызывается, когда пользователь вводит команду с некорректным синтаксисом и как следствие парсер не может
+Исключение вызывается, когда пользователь вводит команду с некорректным синтаксисом и, как следствие, парсер не может
-*распарсить* её. В большинстве случаев это означат, что проблема в синтаксисе введённых флагов команды, подробнее о
+*распарсить* её. В большинстве случаев это означает, что проблема в синтаксисе введённых флагов команды, подробнее о
 флагах и их синтаксисе в :ref:`Flags <root_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 <root_flags>`.
-Дефолтный хэндлер выводит в консоль
+Стандартный хэндлер выводит в консоль
 .. 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 <root_api_command_input_command>` и ничего не возвращает.
-Сэмпл кода, переопределяющего хэндлер ввода неизвестной команды:
+Пример кода, переопределяющего хэндлер ввода неизвестной команды:
 .. 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 <root_api_response>` и ничего не возвращает.
-Сэмпл кода, переопределяющего хэндлер ввода команды выхода:
+Пример кода, переопределяющего хэндлер ввода команды выхода:
 .. literalinclude:: ../code_snippets/error_handling/snippet6.py
    :language: python
@@ -16,8 +16,8 @@
   <command_name> <flag_prefix: Literal['-', '--', '---']><flag_name> <flag_value: Optional>
-То есть, у флага обязательно должен быть префикс, который может быть одним, двум или трем минусам. После префикса следует имя флага, без
+То есть у флага обязательно должен быть префикс, который может быть одним, двумя или тремя минусами. После префикса следует имя флага, без
-пробела, после, через пробел, идёт значение флага, если оно есть.
+пробела, после чего, через пробел, идёт значение флага, если оно есть.
 -----
@@ -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