mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
docs
This commit is contained in:
@@ -1,4 +1,51 @@
|
||||
.. _root_api_app_autocompleter:
|
||||
|
||||
Autocompleter
|
||||
****************
|
||||
AutoCompleter
|
||||
=====================
|
||||
|
||||
Объект ``AutoCompleter`` является компонентом ``Argenta``, отвечающим за интерактивное автодополнение команд. Его основная задача — улучшить опыт взаимодействия пользователя с командной строкой, предоставляя подсказки и автоматически завершая ввод на основе ранее введенных команд. Это значительно ускоряет работу и снижает вероятность опечаток.
|
||||
|
||||
``AutoCompleter`` использует ``pyreadline3`` для имплементации ``readline GNU`` на ``Windows`` для управления историей команд и реализации логики автодополнения.
|
||||
|
||||
-----
|
||||
|
||||
Инициализация
|
||||
-------------
|
||||
|
||||
.. code:: python
|
||||
|
||||
__init__(self, history_filename: str | None = None,
|
||||
autocomplete_button: str = "tab") -> None
|
||||
|
||||
Создает и настраивает экземпляр ``AutoCompleter``.
|
||||
|
||||
* ``history_filename``: Имя файла для сохранения и загрузки истории команд. Если указано, история будет персистентной между сессиями приложения. Если **None**, история будет храниться только в памяти текущей сессии.
|
||||
* ``autocomplete_button``: Название клавиши, которая активирует автодополнение. По умолчанию используется клавиша **"tab"**.
|
||||
|
||||
-----
|
||||
|
||||
Назначение и возможности
|
||||
-------------------------
|
||||
|
||||
``AutoCompleter`` обладает следующими возможностями:
|
||||
|
||||
* **Автодополнение по истории**: Основная логика автодополнения основана на истории команд, которые пользователь вводил ранее. Когда пользователь начинает вводить команду и нажимает клавишу автодополнения (по умолчанию **Tab**), система ищет в истории все команды, начинающиеся с введенного текста.
|
||||
|
||||
* **Завершение по общему префиксу**: Если найдено несколько команд с общим префиксом, автодокомплитер подставит только общую часть. Например, если в истории есть команды ``show_users`` и ``show_profile``, при вводе ``sho`` и нажатии **Tab** будет подставлено ``show_``.
|
||||
|
||||
* **Персистентная история**: При указании параметра ``history_filename`` в конструкторе, вся история команд сохраняется в файл при выходе из приложения и загружается при следующем запуске. Это делает автодополнение со временем все более "умным" и персонализированным.
|
||||
|
||||
* **Очистка истории**: При сохранении истории ``AutoCompleter`` автоматически удаляет дубликаты и команды, которые больше не зарегистрированы в приложении, поддерживая актуальность и чистоту файла истории.
|
||||
|
||||
* **Настройка клавиши активации**: Вы можете изменить клавишу, отвечающую за автодополнение, через параметр ``autocomplete_button``.
|
||||
|
||||
-----
|
||||
|
||||
Пример использования
|
||||
--------------------
|
||||
|
||||
``AutoCompleter`` передается как аргумент при инициализации `App`.
|
||||
|
||||
.. literalinclude:: ../../../code_snippets/autocompleter_example_sample.py
|
||||
:language: python
|
||||
:linenos:
|
||||
|
||||
@@ -1,4 +1,81 @@
|
||||
.. _root_api_app_dividing_lines:
|
||||
|
||||
DividingLines
|
||||
****************
|
||||
Dividing Lines
|
||||
==============
|
||||
|
||||
Разделительные линии в ``Argenta`` играют важную роль в визуальном оформлении консольного интерфейса. Они используются для структурирования вывода, отделения блоков информации друг от друга (например, вывода команды от следующего приглашения к вводу).
|
||||
Библиотека предлагает два подхода к управлению разделительными линиями: статический и динамический, каждый из которых имеет свои преимущества и сценарии использования.
|
||||
|
||||
----
|
||||
|
||||
Класс ``StaticDividingLine``
|
||||
--------------------------
|
||||
|
||||
``StaticDividingLine`` — это класс, который создает разделительную линию **фиксированной** длины. Длина и символ-заполнитель задаются при инициализации объекта. Этот тип линии полезен, когда вам нужен предсказуемый и унифицированный внешний вид интерфейса, независимо от содержимого вывода.
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
def __init__(self, unit_part: str = "-", *,
|
||||
length: int = 25) -> None
|
||||
|
||||
Создает экземпляр статической разделительной линии.
|
||||
|
||||
* ``unit_part``: Символ, который будет использоваться для построения линии. Учитывается только первый символ строки. По умолчанию: ``-``.
|
||||
* ``length``: Целое число, определяющее фиксированную длину линии в символах. Является keyword-only аргументом. По умолчанию: ``25``.
|
||||
|
||||
-----
|
||||
|
||||
Класс ``DynamicDividingLine``
|
||||
---------------------------
|
||||
|
||||
``DynamicDividingLine`` представляет собой более "умный" подход. Этот класс создает линию, длина которой **динамически** подстраивается под самую длинную строку, выведенную в консоль, в рамках выполнения одной команды. Это достигается за счет механизма перехвата `stdout`. В результате разделительные линии всегда идеально обрамляют выводимый контент, что выглядит очень аккуратно.
|
||||
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
__init__(self, unit_part: str = "-") -> None
|
||||
|
||||
Создает экземпляр динамической разделительной линии.
|
||||
|
||||
* ``unit_part``: Символ, который будет использоваться для построения линии. По умолчанию: ``-``.
|
||||
|
||||
Длина для этой линии не задается при инициализации, так как она вычисляется автоматически во время выполнения.
|
||||
|
||||
.. warning::
|
||||
Обязательно почитайте про нюансы использования динамических линий и перехвата ``stdout`` в :ref:`этом разделе<root_redirect_stdout>`.
|
||||
|
||||
Назначение и использование
|
||||
--------------------------
|
||||
|
||||
Выбор между статической и динамической линией зависит от ваших потребностей в конкретном приложении или даже для конкретного `Router`.
|
||||
|
||||
* **`StaticDividingLine`** идеально подходит, если:
|
||||
* Вам нужен строгий, консистентный дизайн.
|
||||
* Вы используете роутеры с отключенным перехватом `stdout` (`disable_redirect_stdout=True`), так как в этом случае динамическое вычисление длины невозможно.
|
||||
|
||||
* **`DynamicDividingLine`** (используется по умолчанию) является предпочтительным выбором, если:
|
||||
* Вы хотите, чтобы интерфейс выглядел аккуратно и адаптивно.
|
||||
* Вывод ваших команд имеет разную длину, и вы хотите, чтобы рамки всегда соответствовали контенту.
|
||||
|
||||
Тип разделительной линии для всего приложения задается при инициализации `App` через параметр `dividing_line`.
|
||||
|
||||
Пример конфигурации
|
||||
--------------------
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from argenta.app import App
|
||||
from argenta.app.dividing_line.models import StaticDividingLine, DynamicDividingLine
|
||||
|
||||
# Создание статической линии из символов "=" длиной 40
|
||||
static_line = StaticDividingLine(unit_part="=", length=40)
|
||||
|
||||
# Создание динамической линии из символов "*"
|
||||
dynamic_line = DynamicDividingLine(unit_part="*")
|
||||
|
||||
# Приложение со статической линией
|
||||
app_with_static_line = App(dividing_line=static_line)
|
||||
|
||||
# Приложение с динамической линией (поведение по умолчанию, но с кастомным символом)
|
||||
app_with_dynamic_line = App(dividing_line=dynamic_line)
|
||||
|
||||
+63
-18
@@ -10,7 +10,8 @@ App
|
||||
Инициализация
|
||||
-------------
|
||||
|
||||
.. code:: rust
|
||||
.. code-block:: rust
|
||||
:linenos:
|
||||
|
||||
AVAILABLE_DIVIDING_LINES: TypeAlias = StaticDividingLine | DynamicDividingLine
|
||||
DEFAULT_DIVIDING_LINE: StaticDividingLine = StaticDividingLine()
|
||||
@@ -19,7 +20,8 @@ App
|
||||
DEFAULT_AUTOCOMPLETER: AutoCompleter = AutoCompleter()
|
||||
DEFAULT_EXIT_COMMAND: Command = Command("Q", description="Exit command")
|
||||
|
||||
.. code:: python
|
||||
.. code-block:: python
|
||||
:linenos:
|
||||
|
||||
def __init__(self, *, prompt: str = "What do you want to do?\n\n",
|
||||
initial_message: str = "Argenta\n",
|
||||
@@ -33,7 +35,7 @@ App
|
||||
autocompleter: AutoCompleter = DEFAULT_AUTOCOMPLETER,
|
||||
print_func: Printer = DEFAULT_PRINT_FUNC) -> None
|
||||
|
||||
Создает и настраивает экземпляр приложения `Argenta`.
|
||||
Создает и настраивает экземпляр приложения ``Argenta``.
|
||||
|
||||
* ``prompt``: Строка-приглашение, которая отображается перед вводом каждой команды. По умолчанию: **"What do you want to do?\\n\\n"**.
|
||||
* ``initial_message``: Приветственное сообщение, которое выводится при запуске приложения.
|
||||
@@ -47,55 +49,98 @@ App
|
||||
* ``autocompleter``: Объект, отвечающий за логику автодополнения команд.
|
||||
* ``print_func``: Функция, используемая для вывода всех системных сообщений. По умолчанию используется ``rich.console.Console().print``.
|
||||
|
||||
-----
|
||||
|
||||
Основные методы
|
||||
---------------
|
||||
|
||||
.. py:method:: include_router(self, router: Router) -> None
|
||||
- .. py:method:: include_router(self, router: Router) -> None
|
||||
|
||||
Регистрирует один `Router` в приложении. Все команды, определенные в этом роутере, становятся доступными для вызова.
|
||||
Регистрирует один ``Router`` в приложении. Все команды, определенные в этом роутере, становятся доступными для вызова.
|
||||
|
||||
:param router: Объект роутера, который нужно зарегистрировать.
|
||||
|
||||
:param router: Объект роутера, который нужно зарегистрировать.
|
||||
- .. py:method:: include_routers(self, *routers: Router) -> None
|
||||
|
||||
.. py:method:: include_routers(self, *routers: Router) -> None
|
||||
Регистрирует несколько роутеров одновременно. Является удобной оберткой над ``include_router``.
|
||||
|
||||
:param routers: Последовательность объектов ``Router`` для регистрации.
|
||||
|
||||
Регистрирует несколько роутеров одновременно. Является удобной оберткой над `include_router`.
|
||||
|
||||
:param routers: Последовательность объектов `Router` для регистрации.
|
||||
|
||||
.. py:method:: add_message_on_startup(self, message: str) -> None
|
||||
|
||||
Добавляет дополнительное текстовое сообщение, которое будет выведено на экран при запуске приложения, сразу после `initial_message`.
|
||||
|
||||
:param message: Строка с сообщением.
|
||||
- .. py:method:: add_message_on_startup(self, message: str) -> None
|
||||
|
||||
Добавляет дополнительное текстовое сообщение, которое будет выведено на экран при запуске приложения, сразу после `initial_message`.
|
||||
|
||||
:param message: Строка с сообщением.
|
||||
|
||||
-----
|
||||
|
||||
Методы установки обработчиков
|
||||
-------------------------------
|
||||
|
||||
`App` позволяет гибко настраивать реакцию на различные события, такие как ошибки ввода или ввод неизвестной команды.
|
||||
``App`` позволяет гибко настраивать реакцию на различные события, такие как ошибки ввода или ввод неизвестной команды.
|
||||
|
||||
.. hint::
|
||||
Подробнее о исключениях и их обработке в соответствующем :ref:`разделе документации <root_error_handling>`.
|
||||
|
||||
-----
|
||||
|
||||
.. py:method:: set_description_message_pattern(self, handler: DescriptionMessageGenerator) -> None
|
||||
|
||||
Устанавливает пользовательский шаблон для форматирования строки, описывающей доступную команду (триггер + описание).
|
||||
|
||||
``DescriptionMessageGenerator`` -> ``Callable[[str, str], str]``
|
||||
|
||||
Где первый аргумент - это триггер команды, а второй - ее описание, возвращает строку, которая является форматированной строкой.
|
||||
|
||||
------
|
||||
|
||||
.. py:method:: set_incorrect_input_syntax_handler(self, handler: NonStandardBehaviorHandler[str]) -> None
|
||||
|
||||
Устанавливает обработчик, который вызывается при некорректном синтаксисе флагов в введенной команде.
|
||||
|
||||
``NonStandardBehaviorHandler[str]`` -> ``Callable[[str], None]``
|
||||
|
||||
Где первый и единственный аргумент - это необработанная строка пользовательского ввода.
|
||||
|
||||
------
|
||||
|
||||
.. py:method:: set_repeated_input_flags_handler(self, handler: NonStandardBehaviorHandler[str]) -> None
|
||||
|
||||
Устанавливает обработчик для ситуации, когда пользователь вводит один и тот же флаг несколько раз.
|
||||
|
||||
``NonStandardBehaviorHandler[str]`` -> ``Callable[[str], None]``
|
||||
|
||||
Где первый и единственный аргумент - это необработанная строка пользовательского ввода.
|
||||
|
||||
------
|
||||
|
||||
.. py:method:: set_unknown_command_handler(self, handler: NonStandardBehaviorHandler[InputCommand]) -> None
|
||||
|
||||
Устанавливает обработчик, который срабатывает, если введенная команда не была найдена ни в одном из зарегистрированных роутеров.
|
||||
|
||||
``NonStandardBehaviorHandler[InputCommand]`` -> ``Callable[[InputCommand], None]``
|
||||
|
||||
Где первый и единственный аргумент - это распаршенный в объект InputCommand ввод пользователя.
|
||||
|
||||
-----
|
||||
|
||||
.. py:method:: set_empty_command_handler(self, handler: EmptyCommandHandler) -> None
|
||||
|
||||
Устанавливает обработчик для случая, когда пользователь отправляет пустую строку вместо команды.
|
||||
|
||||
``EmptyCommandHandler`` -> ``Callable[[], None]``
|
||||
|
||||
Не принимает и не возвращает ничего.
|
||||
|
||||
-----
|
||||
|
||||
.. py:method:: set_exit_command_handler(self, handler: NonStandardBehaviorHandler[Response]) -> None
|
||||
|
||||
Позволяет переопределить стандартное поведение при вызове команды выхода. По умолчанию просто выводится `farewell_message`.
|
||||
Позволяет переопределить стандартное поведение при вызове команды выхода. По умолчанию просто выводится ``farewell_message``.
|
||||
|
||||
``NonStandardBehaviorHandler[Response]`` -> ``Callable[[Response], None]``
|
||||
|
||||
Где первый и единственный аргумент - это объект ответа, ``Response``.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
Reference in New Issue
Block a user