GoyGram
A Telegram framework where Bot API and MTProto run side by side, with the crypto in Rust.
Read the docs »
Documentation
·
Wiki
·
PyPI
·
Report bug
·
Request feature
Table of contents
GoyGram
Bot API and MTProto in one process, with the crypto in Rust
GoyGram is a Telegram framework for Python. Bot API and MTProto run in the same process and share one event loop and one set of handlers, so a bot and a userbot can live in the same app instead of two. Nothing on the hot path is Python: AES for every packet and the TL codec are Rust, compiled straight into the package.
import asyncio
from goygram import GoyGram, filters
app = GoyGram(bot_token="123456:ABC_TOKEN")
@app.on_msg(filt=filters.text)
async def echo(msg):
await msg.reply("Hello from GoyGram")
asyncio.run(app.run())
Key features
- Ready:
pip install goygram. Python 3.13 and newer, with wheels for Linux, Windows and macOS. - Two transports: Bot API and MTProto in one app. Switch per call with
via="api"orvia="mtproto", and a reply goes back the way the original message arrived. - Fast to start: 77 ms to import, about 11 MB of memory. Telethon takes 342 ms and 48 MB for the same job.
- Rust core: AES-256-IGE for MTProto packets, AES-256-GCM for vaults, with AES-NI used when the CPU has it.
- No generated wrappers: any Bot API method works right away, in snake_case or camelCase. MTProto methods go through the
mt_prefix. A method Telegram adds tomorrow works without a new release of GoyGram. - One event object:
MsgObj,CbObj,PollObj,MemberObjandInlineObjare aliases of a single dynamicObj. Fields are read on demand, so you only pay for the ones you touch. - Sessions in one place: a
Sessionis your in-memory state, the.vaultfile and a portable encrypted string at once. No separate MemorySession, StringSession and SQLiteSession classes to keep in sync. - OpSec: the vault key comes out of PBKDF2-SHA256 at 600,000 rounds over your machine id. Memory is zeroized on shutdown, and a wrong key raises instead of quietly falling back to plaintext.
- Light:
aiohttp,richandqrcode. That is the whole dependency list. - Bots over MTProto: pass
bot_tokentogether withapi_idandapi_hash, and the bot speaks raw MTProto instead of HTTP.
Benchmarks
Cold import, memory footprint and MTProto crypto, measured against telethon, pyrogram, aiogram and python-telegram-bot.
| goygram | telethon | pyrogram | aiogram | python-telegram-bot | |
|---|---|---|---|---|---|
| cold import (ms) | 77.2 | 342.0 | 461.5 | 3016.3 | 142.8 |
| RSS delta (MB) | 10.8 | 48.4 | 35.6 | 152.2 | 18.8 |
| AES-256-IGE (MB/s, 64 KiB) | 1062.5 | 10.8 | 202.4 | — | — |
loads message (ops/s) |
577,821 | — | — | — | — |
loads updateNewMessage (ops/s) |
225,347 | — | — | — | — |
There is no C extension to install separately, the crypto is already in the package. For scale, tgcrypto reaches 204.3 MB/s on the same hardware. Parsing a realistic updateNewMessage costs 3.8 µs at p50 and 8.9 µs at p99. How the numbers were taken is written up in benchmarks/.
Getting started
Prerequisites
Python 3.13 or newer. The prebuilt wheels pull nothing else in, and Rust is only needed when you build from source.
A bot needs a token from @BotFather. A user account needs an api_id and an api_hash from my.telegram.org.
Installation
pip install goygram
The wheels are built against the stable ABI and carry the cp38-abi3 tag, so one native build loads on CPython 3.13 and everything newer, on Linux, Windows and macOS. To build from source when your platform has no wheel, Rust has to be on the machine:
git clone https://github.com/GoyGram/GoyGram
cd GoyGram
python -m pip install --no-build-isolation .
Usage
A user account talks MTProto, so it needs an api_id and an api_hash:
import asyncio
from goygram import GoyGram
app = GoyGram(api_id=123456, api_hash="0123456789abcdef0123456789abcdef")
@app.on_cmd("ping")
async def ping(msg):
await msg.reply("pong")
asyncio.run(app.run())
The first run opens a login screen in the terminal. Pick a QR code or a phone number, and give the 2FA password if the account has one. The session lands in default.vault, encrypted with AES-256-GCM.
# several accounts out of one process
app = GoyGram(api_id=..., api_hash=..., session_name="farm_worker_1")
# one message through Bot API, the next through MTProto
await app.send_msg("123456789", "via Bot API", via="api")
await app.send_msg("123456789", "via MTProto", via="mtproto")
Documentation
The rest of the library has its own pages:
- Documentation site, the full guide in English and Russian
- Quick start, Bot API
- Quick start, MTProto userbot
- Sessions and authentication
- Bot API calls and MTProto calls
- Architecture and runtime behaviour
- Benchmarks
Contributing
Bug reports and pull requests are welcome.
CI is strict about two things: the type check has to pass, and commits have to be signed (git commit -S).
License
GoyGram is released under the GNU Affero General Public License v3.0. The full text is in LICENSE.
Contact
Questions and bug reports go to GitHub issues.
1 maintainer
Metadata
1 maintainer
Release files for goygram 0.8.20
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| goygram-0.8.20.tar.gz | 128.9 kB | Details |
Built distributions (wheels)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| goygram-0.8.20-cp38-abi3-win_amd64.whl | CPython 3.8 | abi3 | Windows x86-64 | Details |
| goygram-0.8.20-cp38-abi3-manylinux_2_34_x86_64.whl | CPython 3.8 | abi3 | Linux glibc 2.34+ x86-64 | Details |
| goygram-0.8.20-cp38-abi3-macosx_11_0_arm64.whl | CPython 3.8 | abi3 | macOS 11.0+ ARM64 | Details |
Total release size: 1.3 MB
Release files / goygram-0.8.20.tar.gz
| Download URL | goygram-0.8.20.tar.gz |
|---|---|
| Size | 128.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
904e96bd9440e8c2bec5a4dd86252286f7584d2f8d96fed46aa8cc9048f5691c
|
|
BLAKE2b-256 checksum How to use checksums |
50e38f7791748a0c6433c8f6613e22268d6163eda94494e5c9ce6924b6310a65
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / goygram-0.8.20-cp38-abi3-win_amd64.whl
| Download URL | goygram-0.8.20-cp38-abi3-win_amd64.whl |
|---|---|
| Size | 354.3 kB |
| Tags | CPython 3.8 Windows x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
5684d3855649735eb0fe455cc605647432d7a6db65fa15f2497e6681857056b1
|
|
BLAKE2b-256 checksum How to use checksums |
51a3b23c14982453461e4a161d237154c17935e18f97fee14101df1dba418c97
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / goygram-0.8.20-cp38-abi3-manylinux_2_34_x86_64.whl
| Download URL | goygram-0.8.20-cp38-abi3-manylinux_2_34_x86_64.whl |
|---|---|
| Size | 435.2 kB |
| Tags | CPython 3.8 Linux glibc 2.34+ x86-64 abi3 |
|
SHA-256 checksum How to use checksums |
d12fb193f427e5e0f923ad11b02bdfe769300d1727fc3edb592a4dbbf3c594d1
|
|
BLAKE2b-256 checksum How to use checksums |
f644d9d3df367a3554f5cee4bee4cba933db4238808c5b4a6c476c0e3a2a0dad
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
Release files / goygram-0.8.20-cp38-abi3-macosx_11_0_arm64.whl
| Download URL | goygram-0.8.20-cp38-abi3-macosx_11_0_arm64.whl |
|---|---|
| Size | 408.8 kB |
| Tags | CPython 3.8 abi3 macOS 11.0+ ARM64 |
|
SHA-256 checksum How to use checksums |
532f157007767b0dba13ac16c4b3df7ca7553c3fb31c747219ff65baaee1640e
|
|
BLAKE2b-256 checksum How to use checksums |
d9ff5a145aaf2a4dc321818d677bea91fbd8403248651f75534ef1df4eec4ec2
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
maturin/1.15.0
|
