TelePy

Pyrogram-style framework for Telegram bots — bot-only, ringan, multi-tenant.

Drop-in kompatibel dengan Pyrogram asli. Backend Bot API 8.x via aiohttp. Tanpa userbot. Tanpa MTProto. Tanpa crypto.

---

Daftar Isi

• Apa itu TelePy?
• Fitur
• Instalasi
• Mulai Cepat — Bot Tunggal
• Multi-Bot (Hemat RAM)
• Handlers
• Filters
• Keyboard
• Contoh Struktur Bot
• Prinsip Desain
• Yang Tidak Didukung
• Migrasi dari Pyrogram
• Contoh
• Test
• Kontribusi
• Lisensi
• Kredit

---

🔷 Apa itu TelePy?

TelePy adalah framework Python async-first untuk membangun bot Telegram. Nama paket dan import-nya tetap pyrogram, sehingga bot yang sudah berjalan di Pyrogram bisa langsung pindah tanpa mengubah satu baris pun — cukup ganti sumber instalasi.

Bedanya:

• Bot-only. Tidak ada login user, tidak ada MTProto, tidak ada secret chat, tidak ada crypto.
• Backend Bot API. Semua request ke https://api.telegram.org/bot<TOKEN>/... lewat aiohttp.
• Sinkron Telegram terbaru. Mengikuti Bot API 8.x: reply_parameters, link_preview_options, business_connection, message_reaction, chat_boost, paid_media, copy_text_button, dll.
• Hemat RAM. Semua tipe memakai __slots__, tanpa cache history, tanpa peer cache, raw tidak disimpan default.
• Multi-bot. Banyak Client dalam satu event loop; satu pool aiohttp dibagi untuk semuanya.

Struktur paket:

TelePy/                ← nama repo di GitHub
├── pyrogram/          ← nama folder paket (import: import pyrogram)
│   ├── __init__.py
│   ├── client.py
│   ├── http.py
│   ├── session.py
│   ├── idle.py
│   ├── errors.py
│   ├── filters.py
│   ├── enums/
│   ├── handlers/
│   ├── types/
│   ├── methods/
│   └── utils/
├── examples/
├── requirements.txt
├── pyproject.toml
└── README.md

---

✨ Fitur

• ⚡ Async-first — dibangun dengan asyncio, cocok untuk beban tinggi.
• 🧩 API Pyrogram — Client, filters, on_message, on_callback_query, on_inline_query, dst.
• 🧠 Types lengkap Bot API 8.x — Message, User, Chat, ChatMember (union), CallbackQuery, InlineQuery, Poll, PollAnswer, ChatMemberUpdated, ChatJoinRequest, MessageReactionUpdated, ChatBoostUpdated, BusinessConnection, dll.
• 🛠 Admin & moderasi grup — ban_chat_member, restrict_chat_member, promote_chat_member, approve_chat_join_request, pin_chat_message, set_message_reaction, export_chat_invite_link.
• 🎛 Keyboard builder — InlineKeyboardMarkup, ReplyKeyboardMarkup, ForceReply, ReplyKeyboardRemove, CopyTextButton.
• 🧵 Middleware pipeline — untuk antiflood, antispam, dan pipeline custom.
• 🔌 Handler lengkap — lihat bagian Handlers.
• 🪶 Dependency minimal — hanya aiohttp.
• 🧮 Multi-bot — 1 proses, N bot, 1 pool HTTP, 1 event loop.
• 🧊 Storage opsional — MemoryStorage (default) atau SQLiteStorage (persisten).
• 🧭 Drop-in — kode bot lama jalan tanpa diubah.

---

🚀 Instalasi

# dari repo ini (folder paket di dalamnya bernama "pyrogram")
pip install -e .

# atau dari GitHub
pip install git+https://github.com/ArangVolte/TelePy.git

Dependency satu-satunya:

aiohttp>=3.9

Persyaratan: Python 3.9+.

Setelah instalasi, import tetap seperti biasa:

from pyrogram import Client, filters

---

⚡ Mulai Cepat — Bot Tunggal

from pyrogram import Client, filters

app = Client("BOT_TOKEN")

@app.on_message(filters.text & filters.private)
async def echo(client, message):
    await message.reply_text(message.text)

app.run()

---

🧮 Multi-Bot (Hemat RAM)

Satu proses, banyak bot, satu pool HTTP.

import asyncio
from pyrogram import Client, filters, idle
from pyrogram.http import close_pool

bot_a = Client("TOKEN_A", name="bot_a")
bot_b = Client("TOKEN_B", name="bot_b")
bot_c = Client("TOKEN_C", name="bot_c")

@bot_a.on_message(filters.command("start"))
async def start_a(client, message):
    await message.reply_text("Halo dari Bot A")

@bot_b.on_message(filters.command("start"))
async def start_b(client, message):
    await message.reply_text("Halo dari Bot B")

@bot_c.on_message(filters.command("start"))
async def start_c(client, message):
    await message.reply_text("Halo dari Bot C")

async def main():
    await asyncio.gather(
        bot_a.start(),
        bot_b.start(),
        bot_c.start(),
    )
    try:
        await idle()
    finally:
        await asyncio.gather(
            bot_a.stop(),
            bot_b.stop(),
            bot_c.stop(),
        )
        await close_pool()

if __name__ == "__main__":
    asyncio.run(main())

Catatan: satu aiohttp.ClientSession dibagi untuk semua bot, satu event loop, satu konektor pool. Untuk 100 bot, footprint tetap rendah.

---

🧩 Handlers

Daftar decorator yang tersedia di Client:

Decorator	Update yang ditangkap
on_message(filter, group)	message
on_edited_message(filter, group)	edited_message
on_channel_post(filter, group)	channel_post
on_edited_channel_post(filter, group)	edited_channel_post
on_callback_query(filter, group)	callback_query
on_inline_query(filter, group)	inline_query
on_chosen_inline_result(filter, group)	chosen_inline_result
on_chat_member_updated(filter, group)	my_chat_member, chat_member
on_chat_join_request(filter, group)	chat_join_request
on_poll(filter, group)	poll
on_poll_answer(filter, group)	poll_answer
on_pre_checkout_query(filter, group)	pre_checkout_query
on_shipping_query(filter, group)	shipping_query
on_message_reaction(filter, group)	message_reaction
on_message_reaction_count(filter, group)	message_reaction_count
on_chat_boost(filter, group)	chat_boost
on_removed_chat_boost(filter, group)	removed_chat_boost
on_business_connection(filter, group)	business_connection
on_business_message(filter, group)	business_message, edited_business_message
on_raw_update(group)	semua update (dict mentah)

---

🎯 Filters

Filter dasar:

filters.text
filters.caption
filters.photo
filters.video
filters.video_note
filters.animation
filters.audio
filters.voice
filters.document
filters.sticker
filters.location
filters.contact
filters.dice
filters.poll

Filter konteks:

filters.reply
filters.forwarded
filters.business
filters.topic
filters.private
filters.group
filters.channel
filters.admin
filters.creator
filters.bot_admin

Filter dinamis:

filters.command("start")            # /start, /start@botname
filters.command(["help", "bantuan"])
filters.regex(r"^/start")
filters.user_id(123456789)
filters.create(lambda c, u: True)   # custom

Kombinasi:

filters.private & filters.text
filters.photo | filters.video
~filters.forwarded
filters.group & filters.admin & filters.command("ban")

---

🎛 Keyboard

from pyrogram.types import (
    InlineKeyboardButton, InlineKeyboardMarkup,
    KeyboardButton, ReplyKeyboardMarkup,
    ReplyKeyboardRemove, ForceReply,
    CopyTextButton,
)

Contoh inline keyboard:

markup = InlineKeyboardMarkup([
    [InlineKeyboardButton("Website", url="https://example.com")],
    [InlineKeyboardButton("Salin", copy_text=CopyTextButton("Kode-123"))],
    [InlineKeyboardButton("Klik saya", callback_data="btn:1")],
])

await message.reply_text("Pilih:", reply_markup=markup)

---

🗂 Contoh Struktur Bot

mybot/
├── bot.py
├── config.py
├── plugins/
│   ├── start.py
│   ├── help.py
│   ├── admin.py
│   └── antispam.py
└── storage.db

bot.py:

import asyncio
from pyrogram import Client, idle
from pyrogram.session import SQLiteStorage
from plugins import start, help, admin, antispam

app = Client(
    bot_token="BOT_TOKEN",
    storage=SQLiteStorage("storage.db"),
)

# Middleware dari aplikasi (bukan bagian library)
app.add_middleware(antispam.middleware, group=-10)

start.register(app)
help.register(app)
admin.register(app)

async def main():
    await app.start()
    try:
        await idle()
    finally:
        await app.stop()

if __name__ == "__main__":
    asyncio.run(main())

---

🧱 Prinsip Desain

Prinsip	Implementasi
Drop-in	Nama modul (pyrogram), kelas, fungsi, dan parameter sama dengan Pyrogram asli
Bot-only	Client(bot_token=...) — tidak butuh api_id/api_hash
Bot API 8.x	Semua endpoint & tipe sinkron dengan dokumentasi resmi Telegram
Hemat RAM	__slots__ di semua tipe, tanpa cache history, tanpa peer cache
Multi-bot	Satu aiohttp.ClientSession per event loop, dibagi ke semua Client
Ringan	Dependency hanya aiohttp
Jelas	Raise error yang jelas jika developer mencoba fitur userbot

---

🚫 Yang Tidak Didukung

Fitur berikut sengaja tidak ada karena hanya relevan untuk userbot:

• Login user (api_id, api_hash, sign_in, session string)
• MTProto raw (raw.functions.*, raw.types.*)
• Secret chat, enkripsi end-to-end
• Panggilan suara/video
• get_chat_history (Bot API tidak menyediakan)
• resolve_peer manual (Bot API resolve otomatis)
• Kontak, 2FA, password akun

Kalau bot Anda butuh salah satu di atas, pakai Pyrogram asli. Kalau tidak, TelePy lebih ringan.

---

🔄 Migrasi dari Pyrogram

Karena nama paket tetap pyrogram, kode Anda tidak perlu diubah sama sekali. Yang berubah hanya sumber instalasi:

- pip install pyrogram
+ pip install git+https://github.com/ArangVolte/TelePy.git

Lalu di kode, cukup pastikan konstruktor Client memakai bot_token:

- app = Client(
-     name="mybot",
-     api_id=12345,
-     api_hash="...",
-     bot_token="BOT_TOKEN",
- )
+ app = Client("BOT_TOKEN")

Sisa kode (from pyrogram import Client, filters, @app.on_message, message.reply_text, send_*) tetap sama.

---

📚 Contoh

Lihat folder examples/ untuk:

• echo.py — bot echo sederhana
• single_bot.py — satu bot dengan beberapa handler
• multi_bot.py — banyak bot dalam satu proses
• inline.py — bot inline query
• callback.py — inline keyboard & callback
• welcome.py — welcomer grup
• antispam.py — contoh middleware antispam

---

🧪 Test

pip install -e ".[dev]"
pytest -q

---

🤝 Kontribusi

Kami menerima pull request. Silakan baca CONTRIBUTING.md untuk panduan gaya kode, struktur commit, dan alur review.

Hal yang kami utamakan:

• Kompatibilitas Pyrogram — jangan ubah signature publik tanpa alasan kuat.
• Hemat RAM — setiap tipe baru wajib memakai __slots__.
• Bot-only — jangan menambahkan fitur userbot.
• Bot API terbaru — sinkron dengan https://core.telegram.org/bots/api.

---

📜 Lisensi

LGPL-3.0-or-later — mengikuti Pyrogram asli.

Karena TelePy adalah fork dari Pyrogram yang dirilis di bawah LGPL-3.0, kode ini juga mengikuti lisensi yang sama. Lihat LICENSE untuk teks lengkap.

---

🙏 Kredit

• Pyrogram — API dan filosofi desain.
• Telegram Bot API — dokumentasi resmi.
• Telegram TL Schema — referensi tipe.
• Semua kontributor TelePy.

---

TelePy — Pyrogram tanpa userbot. Ringan untuk produksi, siap multi-tenant.