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 Основа готова
Треды и вложения Запланировано
Роли и права каналов CRUD, назначения и overrides готовы
Модерация участников Kick, bans и timeout готовы
AutoMod Чтение и настройка политики готовы
Журнал аудита Фильтры и cursor pagination готовы
Голос для сторонних ботов Не поддерживается 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.dev1

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.dev1
File Size Uploaded Provenance Actions
voiceroute_py-0.1.0.dev1.tar.gz 105.2 kB Without provenance Details for voiceroute_py-0.1.0.dev1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for voiceroute.py 0.1.0.dev1
File Interpreter ABI Platform Actions
voiceroute_py-0.1.0.dev1-py3-none-any.whl Python 3 none any Details for voiceroute_py-0.1.0.dev1-py3-none-any.whl

Total release size: 165.5 kB

Release files / voiceroute_py-0.1.0.dev1.tar.gz

Download URL voiceroute_py-0.1.0.dev1.tar.gz
Size 105.2 kB
Tags Source
SHA-256 checksum
How to use checksums
5304bc24c758a04b726726e1bbc4e49074857bbc774a39467257d9ea4fd5469d
BLAKE2b-256 checksum
How to use checksums
78888c0eb9e7f446ed8c1291af92e0028637d9d7a4e7f3e72fb5c5cc5294d9c2
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.dev1-py3-none-any.whl

Download URL voiceroute_py-0.1.0.dev1-py3-none-any.whl
Size 60.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3bc93fb726b9fde2a395a815f0603524640bba0955cb81f4f01364959bfa396d
BLAKE2b-256 checksum
How to use checksums
3cbf3864c5afe80b81a90e17da526f0c4e8a78bad2b8ddba373cd4d627f47d4f
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.dev1

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