Skip to main content
Pre-release

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.

Лицензия

MIT

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)

Source distribution for voiceroute.py 0.1.0.dev0
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)

Table of built distributions (wheels) for voiceroute.py 0.1.0.dev0
File Interpreter ABI Platform Actions
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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page