Argenta

---

Описание

Argenta — Python library for creating custom shells

---

Установка

pip install argenta

or

poetry add argenta

---

Быстрый старт

# routers.py
import re
from argenta.router import Router
from argenta.command import Command
from argenta.command.params.flag import FlagsGroup, Flag


router = Router()


list_of_flags = [
  Flag(flag_name='host',
       flag_prefix='--',
       possible_flag_values=re.compile(r'^192.168.\d{1,3}.\d{1,3}$')),
  Flag(flag_name='port',
       flag_prefix='---',
       possible_flag_values=re.compile(r'^[0-9]{1,4}$'))
]


@router.command(Command("hello"))
def handler():
  print("Hello, world!")


@router.command(Command(command="ssh", 
                        description='connect via ssh', 
                        flags=FlagsGroup(list_of_flags)))
def handler_with_flags(flags: dict):
  for flag in flags:
    print(f'Flag name: {flag['name']}\n
          f'Flag value: {flag['value']}')

#main.py
from argenta.app import App
from routers import router

app: App = App()

def main() -> None:
    app.include_router(router)
    app.start_polling()

    
if __name__ == '__main__':
    main()

---

Техническая документация

---

declared classes :

---

class :: App

Класс, определяющий поведение и состояние приложения

Конструктор

App(prompt: str = 'Enter a command',
    initial_greeting: str = '\nHello, I am Argenta\n',
    farewell_message: str = '\nGoodBye\n',
    exit_command: str = 'Q',
    exit_command_description: str = 'Exit command',
    system_points_title: str = 'System points:',
    ignore_exit_command_register: bool = True,
    ignore_command_register: bool = False,
    line_separate: str = '',
    command_group_description_separate: str = '',
    repeat_command_groups: bool = True,
    print_func: Callable[[str], None] = print)

Аргументы:

• name : mean
• prompt (str): Сообщение перед вводом команды.
• initial_greeting (str): Приветственное сообщение при запуске.
• farewell_message (str): Сообщение при выходе.
• exit_command (str): Команда выхода (по умолчанию 'Q').
• exit_command_description (str): Описание команды выхода.
• system_points_title (str): Заголовок перед списком системных команд.
• ignore_exit_command_register (bool): Игнорировать регистр команды выхода.
• ignore_command_register (bool): Игнорировать регистр всех команд.
• line_separate (str): Разделительная строка между командами.
• command_group_description_separate (str): Разделитель между группами команд.
• repeat_command_groups (bool): Повторять описание команд перед вводом.
• print_func (Callable[[str], None]): Функция вывода текста в терминал (по умолчанию print).

---

declared methods

---

App().start_polling() -> None

method mean :: запускает жизненный цикл приложения

---

App().include_router(router: Router) -> None

param router: Router :: регистрируемый роутер

method mean :: регистрирует роутер в приложении

---

App().set_initial_message(message: str) -> None

param message: str :: устанавливаемое приветственное сообщение
example :: "Hello, I'm a example app"

method mean :: устанавливает сообщение, которое будет отображено при запуске программы

---

App().set_farewell_message(message: str) -> None

param message: str :: устанавливаемое сообщение при выходе
example :: "GoodBye !"

method mean :: устанавливает сообщение, которое будет отображено при выходе

---

App().set_description_message_pattern(pattern: str) -> None

param pattern: str :: паттерн описания команды при её выводе в консоль
example :: "[{command}] *=*=* {description}"

method mean :: устанавливает паттерн описания команд, который будет использован при выводе в консоль

---

App().set_repeated_input_flags_handler(handler: Callable[[str], None]) -> None

param handler: Callable[[str], None] :: функция или лямбда функция, которой будет передано управление при вводе юзером повторяющихся флагов example :: lambda raw_command: print_func(f'Repeated input flags: "{raw_command}"')

method mean :: устанавливает функцию, которой будет передано управление при вводе юзером повторяющихся флагов

---

App().set_invalid_input_flags_handler(self, handler: Callable[[str], None]) -> None

param handler: Callable[[str], None] :: функция или лямбда функция, которой будет передано управление при вводе юзером команды с некорректным синтаксисом флагов example :: lambda raw_command: print_func(f'Incorrect flag syntax: "{raw_command}"')

method mean :: устанавливает функцию, которой будет передано управление при вводе юзером команды с некорректным синтаксисом флагов

---

App().set_unknown_command_handler(self, handler: Callable[[str], None]) -> None

param handler: Callable[[str], None] :: функция или лямбда функция, которой будет передано управление при вводе юзером неизвестной команды example :: lambda command: print_func(f"Unknown command: {command.get_string_entity()}")

method mean :: устанавливает функцию, которой будет передано управление при вводе юзером неизвестной команды

---

App().set_empty_command_handler(self, handler: Callable[[str], None]) -> None

param handler: Callable[[str], None] :: функция или лямбда функция, которой будет передано управление при вводе юзером пустой команды example :: lambda: print_func(f'Empty input command')

method mean :: устанавливает функцию, которой будет передано управление при вводе юзером пустой команды

---

Примечания

• В устанавливаемом паттерне сообщения описания команды необходимы быть два ключевых слова: command и description, каждое из которых должно быть заключено в фигурные скобки, после обработки паттерна на места этих ключевых слов будут подставлены соответствующие значения команды, при отсутствии этих двух ключевых слов будет вызвано исключение InvalidDescriptionMessagePatternException

• Команды приложения не должны повторяться, при значении атрибута ignore_command_register равным True допускается создание обработчиков для разных регистров одинаковых символов в команде, для примера u и U, при значении атрибута ignore_command_register класса App равным False тот же пример вызывает исключение RepeatedCommandInDifferentRoutersException. Исключение вызывается только при наличии пересекающихся команд у разных роутеров

router = Router()

@router.unknown_command
def unknown_command(command):
    print(f'Command "{command}" undefined')

При отсутствии обработчика неизвестных команд у главного роутера будет вызвано исключение MissingHandlerForUnknownCommandsException. При регистрации обработчика неизвестных команд у не главного роутера будет вызвано исключение HandlerForUnknownCommandsOnNonMainRouterException

Исключения

• InvalidRouterInstanceException — Переданный объект в метод App().include_router() не является экземпляром класса Router.
• InvalidDescriptionMessagePatternException — Неправильный формат паттерна описания команд.
• OnlyOneMainRouterIsAllowedException — Регистрация более одного главного роутера.
• MissingMainRouterException — Отсутствует главный роутер.
• MissingHandlerForUnknownCommandsException — В основном роутере отсутствует обработчик неизвестных команд.
• HandlerForUnknownCommandsOnNonMainRouterException — Обработчик неизвестных команд определён не у основного роутера.
• NoRegisteredRoutersException — Отсутствуют зарегистрированные роутеры.
• NoRegisteredHandlersException — У роутера нет ни одного обработчика команд.
• RepeatedCommandInDifferentRoutersException — Одна и та же команда зарегистрирована в разных роутерах.

---

class :: Router

Класс, который определяет и конфигурирует обработчики команд

Конструктор

Router(title: str = 'Commands group title:',
       name: str = 'subordinate')

Аргументы:

• name : mean
• title (str): Заголовок группы команд.
• name (str): Персональное название роутера

declared methods

---

@Router().command(command: Command)

param command: Command :: строковый триггер, который будет выполнять указанные действия
example :: U / update / ExaMPLE

method mean :: декоратор регистрирует функцию как обработчик команды

---

@Router().unknown_command

method mean :: декоратор регистрирует функцию как обработчик неизвестных команд

---

Router().get_name() -> str

method mean :: возвращает установленное название роутера

---

Router().get_title() -> str

method mean :: возвращает установленный заголовок группы команд данного роутера

---

Router().get_router_info() -> dict

method mean :: возвращает информацию о роутере

---

Router().get_all_commands() -> list[str]

method mean :: возвращает все зарегистрированные команды для данного роутера

---

Исключения

• InvalidCommandInstanceException - Переданный объект для регистрации команды не является строкой
• InvalidDescriptionInstanceException - Переданный объект для регистрации описания команды не является строкой
• UnknownCommandHandlerHasAlreadyBeenCreatedException - Обработчик неизвестных команд уже создан
• RepeatedCommandException - Одна и та же команда зарегистрирована в одном роутере