This release is a pre-release and may not be stable for production use.
voiceroute.py
Асинхронный Python SDK и фреймворк для разработки ботов в VoiceRoute.
Цели проекта
- типизированный асинхронный клиент HTTP API;
- надёжная обработка SSE с восстановлением курсора;
- идемпотентная отправка сообщений;
- удобная событийная модель и команды в стиле современных bot-фреймворков;
- расширяемая архитектура без смешивания bot token и пользовательской сессии;
- безопасная работа с лимитами запросов, повторными попытками и секретами.
Установка для разработки
Требуется Python 3.11 или новее.
python -m venv .venv
source .venv/bin/activate
python -m pip install -e '.[dev]'
Примеры автоматически читают локальный .env из корня репозитория. В нём
достаточно указать VOICEROUTE_BOT_TOKEN; production используется по умолчанию.
Полноценный демонстрационный пример: Community Assistant Bot.
Минимальный бот
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 можно будет подключить отдельным адаптером. Подробнее: командный фреймворк.
Команды и listeners больших ботов можно объединять в расширения с атомарной загрузкой, выгрузкой и reload. Подробнее: расширения.
Runtime поддерживает явные состояния, graceful shutdown и изоляцию channel consumers с ограниченным backoff. Подробнее: жизненный цикл runtime.
Клиент умеет редактировать и удалять сообщения, управлять закреплением и реакцией, читать pins и выполнять поиск. Подробнее: контентный API.
По умолчанию бот обнаруживает все доступные ему сообщества и текстовые каналы.
Для ограничения одним каналом можно явно передать community_id и channel_id.
При первом подключении он запрашивает историю после seq=0, чтобы не пропустить
команды, отправленные незадолго до запуска. Идемпотентные ответы защищают от
дубликатов при повторном получении тех же сообщений.
FileCursorStore атомарно сохраняет обработанную позицию с правами 0600.
Cursor обновляется только после успешного завершения обработчика, поэтому после
сбоя событие будет доставлено повторно. Для нескольких процессов доступны SQLite и
Redis. Подробнее: события и восстановление.
Все HTTP-операции одного клиента используют общий лимитер 50 запросов в секунду.
Безопасные запросы и идемпотентная отправка сообщений повторяются после временных
сетевых ошибок; 429 соблюдает Retry-After. Подробнее: сеть и повторы.
Состояние реализации
| Возможность | Состояние |
|---|---|
| Bot-аутентификация | Основа готова |
| Профиль текущего бота | Основа готова |
| Сообщества и каналы | Базовое чтение готово |
| Сообщения | История, отправка и изменение готовы |
| Реакции, закрепления и поиск | Основа готова |
| SSE и восстановление курсора | Основа готова |
| Prefix-команды | Основа готова |
| Middleware | Основа готова |
| Треды и вложения | Запланировано |
| Роли и модерация | Запланировано |
| Голос для сторонних ботов | Не поддерживается API VoiceRoute |
Подробная последовательность работ находится в дорожной карте, текущее покрытие — в матрице API, а принятые границы проекта — в описании архитектуры.
Разработка
ruff check .
ruff format --check .
mypy src
pytest --cov=voiceroute --cov-report=term-missing
Правила веток, коммитов и слияний описаны в CONTRIBUTING.md.
Безопасность
Не добавляйте bot token в исходный код, URL, query-параметры или логи. Используйте переменные окружения и передавайте токен только через официальный заголовок авторизации. Инструкции по сообщению об уязвимостях находятся в SECURITY.md.
Лицензия
Metadata
Release files for voiceroute.py 0.1.0.dev0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| voiceroute_py-0.1.0.dev0.tar.gz | 82.4 kB | Without provenance | Details for voiceroute_py-0.1.0.dev0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| voiceroute_py-0.1.0.dev0-py3-none-any.whl | Python 3 | none | any | Details for voiceroute_py-0.1.0.dev0-py3-none-any.whl |
Total release size: 122.7 kB
Release files / voiceroute_py-0.1.0.dev0.tar.gz
| Download URL | voiceroute_py-0.1.0.dev0.tar.gz |
|---|---|
| Size | 82.4 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
6b13b191dcf17e9b00574dfe2ce32db5fc298a6b1e00772ddc637deebc549107
|
|
BLAKE2b-256 checksum How to use checksums |
b5aacd672086264d9bb21015eb9fbbb5785804c3c2a75e5d30a95ebafe89bd3d
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.9
|
Release files / voiceroute_py-0.1.0.dev0-py3-none-any.whl
| Download URL | voiceroute_py-0.1.0.dev0-py3-none-any.whl |
|---|---|
| Size | 40.3 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
49b4fa194b8ddc5c79a5f8a255042eaf95a9ae9a48b4cd58d814831143907849
|
|
BLAKE2b-256 checksum How to use checksums |
6a5e3847f126eceaf62ef26c8382bb02a4cedf5af6dcd553a543409f05b56676
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.13.9
|
Security for voiceroute.py 0.1.0.dev0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.