mirror of
https://github.com/koloideal/Argenta.git
synced 2026-06-10 10:05:28 +03:00
feat: impl docs (#4)
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.
This commit is contained in:
kolo
+71
-32
@@ -1,69 +1,108 @@
|
||||
# Argenta
|
||||
|
||||
|
||||
### Библиотека для создания модульных CLI приложeний
|
||||
**Argenta** — это простой и элегантный фреймворк для создания модульных CLI-приложений. Он предоставляет чистый и интуитивный способ создания контекстно-зависимых инструментов командной строки с изолированными областями команд.
|
||||
|
||||
Argenta позволяет инкапсулировать CLI фукциональность в изолированные, абстрагированные **среды**. К примеру: вы создаете утилиту, подобную Metasploit Framework, где пользователь сначала входит в определенный скоуп (например, выбирает модуль для сканирования), а затем получает доступ к набору команд, специфичных только для этого контекста. Argenta предоставляет простой и лаконичный способ для построения такой архитектуры.
|
||||
Argenta — это **"Самый простой"**, **"Самый модульный"** и **"Самый элегантный"** способ создания интерактивных CLI-приложений на Python.
|
||||
|
||||
📖 **Читайте полную документацию:** [argenta.readthedocs.io](https://argenta.readthedocs.io/)<br>
|
||||
🌍 **Другие языки:** [EN](https://github.com/koloideal/Argenta/blob/main/README.md)
|
||||
|
||||
---
|
||||
|
||||
|
||||
|
||||
|
||||
---
|
||||
**Argenta** позволяет создавать интерактивные CLI-приложения невероятно легко. Не нужно вручную парсить сложные структуры команд или управлять переходами состояний — просто используйте роутеры и команды!
|
||||
|
||||
# Установка
|
||||
```bash
|
||||
pip install argenta
|
||||
```
|
||||
or
|
||||
```bash
|
||||
poetry add argenta
|
||||
## ✨ Установка 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.router import Router
|
||||
from argenta.command import Command
|
||||
from argenta.response import Response
|
||||
|
||||
from argenta import Router, Response
|
||||
from argenta.command import Flag, Command
|
||||
|
||||
router = Router()
|
||||
|
||||
@router.command(Command("hello"))
|
||||
def handler(response: Response):
|
||||
print("Hello, world!")
|
||||
"""Простая команда 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.app import App
|
||||
from argenta.orchestrator import Orchestrator
|
||||
from routers import router
|
||||
|
||||
app: App = App()
|
||||
orchestrator: Orchestrator = Orchestrator()
|
||||
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/)
|
||||
|
||||
---
|
||||
|
||||
# Фичи в разработке
|
||||
|
||||
- Полноценная поддержка автокомплитера на Linux
|
||||
|
||||
## Полная [документация](https://argenta-docs.vercel.app) | MIT 2025 kolo | made by [kolo](https://t.me/kolo_id)
|
||||
MIT 2025 kolo | made by [kolo](https://t.me/kolo_id)
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user