Metadata-Version: 2.5
Name: voiceroute.py
Version: 0.1.0.dev1
Summary: Async Python SDK and bot framework for the VoiceRoute HTTP and SSE APIs.
Project-URL: Homepage, https://github.com/dog-bobik/voiceroute.py
Project-URL: Documentation, https://github.com/dog-bobik/voiceroute.py#readme
Project-URL: Issues, https://github.com/dog-bobik/voiceroute.py/issues
Project-URL: Repository, https://github.com/dog-bobik/voiceroute.py.git
Author: dog-bobik
License-Expression: MIT
License-File: LICENSE
Keywords: asyncio,bot,sdk,sse,voiceroute
Classifier: Development Status :: 2 - Pre-Alpha
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Requires-Python: >=3.11
Requires-Dist: httpx<1,>=0.27
Provides-Extra: dev
Requires-Dist: mypy>=1.13; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.24; extra == 'dev'
Requires-Dist: pytest-cov>=6; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: python-dotenv<2,>=1.0; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.27; extra == 'docs'
Provides-Extra: examples
Requires-Dist: python-dotenv<2,>=1.0; extra == 'examples'
Provides-Extra: redis
Requires-Dist: redis<8,>=5; extra == 'redis'
Description-Content-Type: text/markdown

# voiceroute.py

Асинхронный Python SDK и фреймворк для разработки ботов в
[VoiceRoute](https://voiceroute.cc).

> [!WARNING]
> Проект находится на ранней стадии разработки. Публичный API может меняться до
> выпуска версии `1.0.0`.

## Цели проекта

- типизированный асинхронный клиент HTTP API;
- надёжная обработка SSE с восстановлением курсора;
- идемпотентная отправка сообщений;
- удобная событийная модель и команды в стиле современных bot-фреймворков;
- расширяемая архитектура без смешивания bot token и пользовательской сессии;
- безопасная работа с лимитами запросов, повторными попытками и секретами.

## Установка для разработки

Требуется Python 3.11 или новее.

```bash
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
```

Примеры автоматически читают локальный `.env` из корня репозитория. В нём
достаточно указать `VOICEROUTE_BOT_TOKEN`; production используется по умолчанию.

Полноценный демонстрационный пример: [Community Assistant Bot](examples/community_assistant/README.md).

## Минимальный бот

```python
import os

from voiceroute import Bot, Context, FileCursorStore

bot = Bot(
    token=os.environ["VOICEROUTE_BOT_TOKEN"],
    cursor_store=FileCursorStore(".voiceroute/cursors.json"),
)


@bot.command()
async def ping(context: Context) -> None:
    await context.reply("Pong!")


bot.run()
```

Ответ использует стабильный UUID, производный от исходного сообщения. Повторная
доставка SSE-события поэтому не создаст дубликат ответа.

По умолчанию команды принимают оба привычных префикса: `/ping` и `!ping`.
Собственный префикс задаётся через `Bot(..., command_prefix="?")`.

Команды поддерживают aliases, группы и типизированные позиционные аргументы. Метаданные и
вызов не зависят от prefix transport, поэтому будущие server-native interactions можно
будет подключить отдельным адаптером. Подробнее: [командный фреймворк](docs/commands.md).

Команды и listeners больших ботов можно объединять в расширения с атомарной загрузкой,
выгрузкой и reload. Подробнее: [расширения](docs/extensions.md).

Runtime поддерживает явные состояния, graceful shutdown и изоляцию channel consumers с
ограниченным backoff. Подробнее: [жизненный цикл runtime](docs/runtime.md).

Клиент умеет редактировать и удалять сообщения, управлять закреплением и реакцией,
читать pins и выполнять поиск. Подробнее: [контентный API](docs/content-api.md).

По умолчанию бот обнаруживает все доступные ему сообщества и текстовые каналы.
Для ограничения одним каналом можно явно передать `community_id` и `channel_id`.
При первом подключении он запрашивает историю после `seq=0`, чтобы не пропустить
команды, отправленные незадолго до запуска. Идемпотентные ответы защищают от
дубликатов при повторном получении тех же сообщений.

`FileCursorStore` атомарно сохраняет обработанную позицию с правами `0600`.
Cursor обновляется только после успешного завершения обработчика, поэтому после
сбоя событие будет доставлено повторно. Для нескольких процессов доступны SQLite и
Redis. Подробнее: [события и восстановление](docs/events.md).

Все HTTP-операции одного клиента используют общий лимитер 50 запросов в секунду.
Безопасные запросы и идемпотентная отправка сообщений повторяются после временных
сетевых ошибок; `429` соблюдает `Retry-After`. Подробнее: [сеть и повторы](docs/network.md).

## Состояние реализации

| Возможность | Состояние |
| --- | --- |
| Bot-аутентификация | Основа готова |
| Профиль текущего бота | Основа готова |
| Сообщества и каналы | Базовое чтение готово |
| Сообщения | История, отправка и изменение готовы |
| Реакции, закрепления и поиск | Основа готова |
| SSE и восстановление курсора | Основа готова |
| Prefix-команды | Основа готова |
| Middleware | Основа готова |
| Треды и вложения | Запланировано |
| Роли и права каналов | CRUD, назначения и overrides готовы |
| Модерация участников | Kick, bans и timeout готовы |
| AutoMod | Чтение и настройка политики готовы |
| Журнал аудита | Фильтры и cursor pagination готовы |
| Голос для сторонних ботов | Не поддерживается API [VoiceRoute](https://voiceroute.cc) |

Подробная последовательность работ находится в [дорожной карте](docs/roadmap.md),
текущее покрытие — в [матрице API](docs/api-coverage.md), а принятые границы проекта —
в [описании архитектуры](docs/architecture.md).

## Разработка

```bash
ruff check .
ruff format --check .
mypy src
pytest --cov=voiceroute --cov-report=term-missing
```

Правила веток, коммитов и слияний описаны в [CONTRIBUTING.md](CONTRIBUTING.md).

## Безопасность

Не добавляйте bot token в исходный код, URL, query-параметры или логи. Используйте
переменные окружения и передавайте токен только через официальный заголовок
авторизации. Инструкции по сообщению об уязвимостях находятся в
[SECURITY.md](SECURITY.md).

## Лицензия

[MIT](LICENSE)

