mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
kolo
ce7e24b924
The entire public api is covered with documentation in two languages - Russian and English. the library now supports the latest three versions of python - 3.12, 3.13 and 3.14 minor design changes: now, when a Boolean flag is entered, its value is an empty string, not None. tests have been adapted to the supported versions of python, readmi has been redesigned in two languages, German is no longer available.
109 lines
6.7 KiB
Markdown
109 lines
6.7 KiB
Markdown
|
|
|
|
**Argenta** — это простой и элегантный фреймворк для создания модульных CLI-приложений. Он предоставляет чистый и интуитивный способ создания контекстно-зависимых инструментов командной строки с изолированными областями команд.
|
|
|
|
Argenta — это **"Самый простой"**, **"Самый модульный"** и **"Самый элегантный"** способ создания интерактивных CLI-приложений на Python.
|
|
|
|
📖 **Читайте полную документацию:** [argenta.readthedocs.io](https://argenta.readthedocs.io/)<br>
|
|
🌍 **Другие языки:** [EN](https://github.com/koloideal/Argenta/blob/main/README.md)
|
|
|
|
---
|
|
|
|
|
|
|
|
**Argenta** позволяет создавать интерактивные CLI-приложения невероятно легко. Не нужно вручную парсить сложные структуры команд или управлять переходами состояний — просто используйте роутеры и команды!
|
|
|
|
## ✨ Установка Argenta
|
|
|
|
Argenta доступна на ``PyPI``:
|
|
|
|
```console
|
|
$ python -m pip install argenta
|
|
```
|
|
|
|
или с использованием ``uv``:
|
|
|
|
```console
|
|
$ uv add argenta
|
|
```
|
|
|
|
Argenta официально поддерживает Python 3.12+.
|
|
|
|
## 🚀 Поддерживаемые возможности и лучшие практики
|
|
|
|
Argenta готова к требованиям создания масштабируемых, надежных и поддерживаемых CLI-приложений.
|
|
|
|
- **Интерактивные сессии**: В отличие от традиционных CLI-инструментов, ``Argenta`` создаёт циклические сессии, позволяя пользователю выполнять команды последовательно, не перезапуская приложение.
|
|
- **Декларативный синтаксис**: Команды и их обработчики объявляются с помощью простых декораторов, что делает код интуитивно понятным и позволяет сосредоточиться на том, "что" вы хотите сделать, а не "как".
|
|
- **Нативный DI**: Благодаря интеграции с [dishka](https://dishka.readthedocs.io/en/stable/), вы можете легко внедрять зависимости прямо в обработчики команд, что упрощает их тестирование, позволяет избежать мутабельных глобалов и многое другое.
|
|
- **Автоматическая валидация и парсинг**: Библиотека берёт на себя обработку флагов и аргументов командной строки, включая их парсинг, валидацию и преобразование типов.
|
|
- **Гибкая настройка**: Вы можете легко кастомизировать системные сообщения, форматирование вывода, ссоздавать кастомные обработчики нестандартного поведения и т.д.
|
|
|
|
Нужно что-то еще? Создайте **issue**, мы открыты к предложениям.
|
|
|
|
## 📝 Зачем мы это создали?
|
|
|
|
Создание сложных CLI-приложений часто требует управления различными контекстами и областями команд. Например, при создании утилиты, подобной Metasploit Framework, пользователям нужно входить в определенные области (например, выбирать модуль сканирования), а затем получать доступ к командам, специфичным только для этого контекста.
|
|
|
|
Традиционные CLI-фреймворки не предоставляют элегантного способа обработки такой модульной, контекстно-зависимой архитектуры. Argenta была создана для решения этой проблемы, предоставляя простой и лаконичный способ инкапсуляции CLI-функциональности в изолированные, абстрагированные среды.
|
|
|
|
Мы считаем, что создание CLI-приложений должно быть таким же приятным, как создание веб-приложений с современными фреймворками. Argenta привносит паттерн роутеров и чистое разделение ответственности в мир CLI.
|
|
|
|
## 🚀 Быстрый старт
|
|
|
|
Вот простой пример для начала работы:
|
|
|
|
```python
|
|
# routers.py
|
|
from argenta import Router, Response
|
|
from argenta.command import Flag, Command
|
|
|
|
router = Router()
|
|
|
|
@router.command(Command("hello"))
|
|
def handler(response: Response):
|
|
"""Простая команда hello world"""
|
|
print("Привет, мир!")
|
|
|
|
@router.command(Command("greet", flags=Flag('name')))
|
|
def greet_handler(response: Response):
|
|
"""Поприветствовать пользователя по имени"""
|
|
name_flag = response.input_flags.get_flag_by_name('name')
|
|
if name_flag:
|
|
print(f"Привет, {name_flag.input_value}!")
|
|
else:
|
|
print("Привет, Незнакомец!")
|
|
```
|
|
|
|
```python
|
|
# main.py
|
|
from argenta import App, Orchestrator
|
|
from .routers import router
|
|
|
|
app = App()
|
|
orchestrator = Orchestrator()
|
|
|
|
def main() -> None:
|
|
# Подключите ваши роутеры
|
|
app.include_router(router)
|
|
|
|
# Запустите интерактивный CLI
|
|
orchestrator.start_polling(app)
|
|
|
|
if __name__ == '__main__':
|
|
main()
|
|
```
|
|
|
|
Вот и всё! Теперь у вас есть полностью функциональное интерактивное CLI-приложение.
|
|
|
|
## 📚 Документация
|
|
|
|
Полная документация доступна на [argenta.readthedocs.io](https://argenta.readthedocs.io/)
|
|
|
|
---
|
|
|
|
MIT 2025 kolo | made by [kolo](https://t.me/kolo_id)
|
|
|
|
|
|
|