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

В этом руководстве мы рассмотрим два примера создания CLI-приложения с помощью Argenta:

• Простой пример: минимальное приложение для быстрого знакомства с основными компонентами.

• Пример средней сложности: приложение «Калькулятор» с использованием и настройкой флагов.

• Более сложный пример: полнофункциональное приложение «Менеджер задач» с внедрением зависимостей и бизнес-логикой.

Простой пример

Установка

pip install argenta

Этот пример демонстрирует абсолютный минимум, необходимый для создания и запуска приложения. Вы можете скопировать этот код, запустить его и сразу увидеть результат.

from argenta import App, Command, Orchestrator, Router, Response
from argenta.command import Flag

# 1. Create app and orchestrator instances
app = App(
    prompt=">> ",
    initial_message="Simple App",
    farewell_message="Goodbye!",
    repeat_command_groups_printing=False,
)
orchestrator = Orchestrator()

# 2. Create router for grouping commands
main_router = Router(title="Main commands")


# 3. Define command and its handler
@main_router.command(Command("hello", description="Prints greeting message", flags=Flag("name")))
def hello_handler(response: Response):
    """This handler will be called for 'hello' command."""
    name = response.input_flags.get_flag_by_name("name")
    if name:
        print(f"Hello, {name.input_value}!")
    else:
        print("Hello, world!")


# 4. Include router to application
app.include_router(main_router)

# 5. Start application
if __name__ == "__main__":
    orchestrator.start_polling(app)

Запуск

Сохраните код в файл (например, main.py) и запустите:

python main.py

Результат

---

Промежуточный пример: Калькулятор с флагами

Прежде чем перейти к сложному примеру с DI, рассмотрим промежуточный вариант — калькулятор, который использует флаги для управления поведением.

import operator
import re

from argenta import App, Orchestrator, Response, Router
from argenta.app import DynamicDividingLine
from argenta.command import Command, Flag, Flags
from argenta.response.status import ResponseStatus

router = Router("Calculator")

operations = {"mul": operator.mul, "sub": operator.sub, "add": operator.add}


@router.command(
    Command(
        "calc",
        description="Calculator with two numbers",
        flags=Flags(
            [
                Flag("a", possible_values=re.compile(r"^\d{,5}$")),  # First number
                Flag("b", possible_values=re.compile(r"^\d{,5}$")),  # Second number
                Flag(
                    "operation", possible_values=["add", "sub", "mul"]
                ),  # Operation: add, sub, mul
            ]
        ),
    )
)
def calc_handler(response: Response):
    # Get flag values
    a_flag = response.input_flags.get_flag_by_name("a")
    b_flag = response.input_flags.get_flag_by_name("b")
    op_flag = response.input_flags.get_flag_by_name("op")

    # Check that all flags are provided
    if response.status != ResponseStatus.ALL_FLAGS_VALID or not all([a_flag, b_flag, op_flag]):
        print("Error: must specify --a, --b and --op")
        return

    a = float(a_flag.input_value)
    b = float(b_flag.input_value)
    operation = op_flag.input_value

    try:
        result = operations[operation](a, b)
    except ZeroDivisionError:
        print("Can't divide by zero")
    else:
        print(f"Result: {result}")


app = App(
    initial_message="Calculator",
    repeat_command_groups_printing=False,
    prompt=">> ",
    dividing_line=DynamicDividingLine("~"),
)
orchestrator = Orchestrator()


def main():
    app.include_router(router)
    orchestrator.start_polling(app)


if __name__ == "__main__":
    main()

Запуск:

Сохраните код в файл calculator.py и запустите:

python calculator.py

Использование:

calc --a 10 --b 5 --operation add
calc --a 10 --b 5 --operation mul

Этот пример показывает, как работать с флагами без использования DI. Теперь перейдём к более сложному примеру.

---

Сложный пример: Менеджер задач с DI

В этом руководстве мы создадим полнофункциональное CLI-приложение «Менеджер задач», которое продемонстрирует работу с внедрением зависимостей.

1. Установка

pip install argenta

2. Определение моделей данных и репозитория

Сначала определим модели данных для задачи и репозиторий для их хранения.

from dataclasses import dataclass
from typing import Literal

Priority = Literal["low", "medium", "high"]


@dataclass
class Task:
    description: str
    priority: Priority = "medium"


class TaskRepository:
    def __init__(self):
        self._tasks: list[Task] = []

    def add_task(self, task: Task):
        self._tasks.append(task)

    def get_all_tasks(self) -> list[Task]:
        return self._tasks

3. Создание провайдера для DI

Чтобы Argenta могла внедрять TaskRepository в наши обработчики, мы создадим провайдер для dishka.

from dishka import Provider, Scope, provide

from .repository import TaskRepository


class TaskProvider(Provider):
    @provide(scope=Scope.APP)
    def get_repository(self) -> TaskRepository:
        return TaskRepository()

4. Создание обработчиков команд

Теперь создадим обработчики для команд add-task и list-tasks. Обратите внимание, как мы используем флаги и внедряем TaskRepository.

from typing import cast

from argenta import Command, Response, Router
from argenta.command.flag import Flag, ValidationStatus
from argenta.command import Flags
from argenta.di import FromDishka

from .repository import Priority, Task, TaskRepository

router = Router(title="Task Manager")


@router.command(
    Command(
        "add-task",
        description="Add a new task",
        flags=Flags(
            [
                Flag("description"),
                Flag("priority", possible_values=["low", "medium", "high"]),
            ]
        ),
    )
)
def add_task(response: Response, repo: FromDishka[TaskRepository]):
    description_flag = response.input_flags.get_flag_by_name("description")

    if not description_flag or not description_flag.status == ValidationStatus.VALID:
        print("Error: --description flag is required.")
        return

    task_description = description_flag.input_value or ""

    priority_flag = response.input_flags.get_flag_by_name("priority")

    if priority_flag and priority_flag.status == ValidationStatus.VALID:
        priority_value = priority_flag.input_value
    else:
        priority_value = "medium"

    priority = cast(Priority, priority_value)

    task = Task(description=task_description, priority=priority)
    repo.add_task(task)

    print(f"Added task: '{task.description}' with priority '{task.priority}'")


@router.command(Command("list-tasks", description="List all tasks"))
def list_tasks(response: Response, repo: FromDishka[TaskRepository]):
    tasks = repo.get_all_tasks()

    if not tasks:
        print("No tasks found.")
        return

    print("Tasks:")
    for i, task in enumerate(tasks, 1):
        print(f"  {i}. {task.description} (Priority: {task.priority})")

5. Сборка и запуск приложения

Наконец, соберем все вместе: создадим экземпляр App, подключим роутер и провайдер, а затем запустим приложение.

from argenta import App, Orchestrator

from .handlers import router
from .provider import TaskProvider

# 1. Create app and orchestrator instances
app = App(
    initial_message="Task Manager",
    prompt="Enter a command: ",
)
orchestrator = Orchestrator(custom_providers=[TaskProvider()])

# 2. Include router with our commands
app.include_router(router)

# 3. Start polling via orchestrator
if __name__ == "__main__":
    orchestrator.start_polling(app)

6. Результат

Теперь вы можете запустить main.py и взаимодействовать с вашим новым CLI-приложением.