Metadata-Version: 2.4
Name: Telegram-Py-Arang
Version: 0.0.1
Summary: TelePy — Pyrogram-style framework for Telegram bots (bot-only, Bot API 8.x)
Home-page: https://github.com/ArangVolte/TelePy
Author: TelePy Contributors
License: LGPL-3.0-or-later
Project-URL: Homepage, https://github.com/ArangVolte/TelePy
Project-URL: Source, https://github.com/ArangVolte/TelePy
Project-URL: Issues, https://github.com/ArangVolte/TelePy/issues
Requires-Python: >=3.9
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

# 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.

[![Python](https://img.shields.io/badge/python-3.9%2B-blue.svg)](https://www.python.org/)
[![License](https://img.shields.io/badge/license-LGPL--3.0--or--later-green.svg)](LICENSE)
[![Bot API](https://img.shields.io/badge/Bot%20API-8.x-blue.svg)](https://core.telegram.org/bots/api)
[![Dependencies](https://img.shields.io/badge/dependencies-aiohttp-informational.svg)](requirements.txt)

---

## Daftar Isi

- [Apa itu TelePy?](#-apa-itu-telepy)
- [Fitur](#-fitur)
- [Instalasi](#-instalasi)
- [Mulai Cepat — Bot Tunggal](#-mulai-cepat--bot-tunggal)
- [Multi-Bot (Hemat RAM)](#-multi-bot-hemat-ram)
- [Handlers](#-handlers)
- [Filters](#-filters)
- [Keyboard](#-keyboard)
- [Contoh Struktur Bot](#-contoh-struktur-bot)
- [Prinsip Desain](#-prinsip-desain)
- [Yang Tidak Didukung](#-yang-tidak-didukung)
- [Migrasi dari Pyrogram](#-migrasi-dari-pyrogram)
- [Contoh](#-contoh)
- [Test](#-test)
- [Kontribusi](#-kontribusi)
- [Lisensi](#-lisensi)
- [Kredit](#-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](#-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

```bash
# 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:

```txt
aiohttp>=3.9
```

Persyaratan: **Python 3.9+**.

Setelah instalasi, import tetap seperti biasa:

```python
from pyrogram import Client, filters
```

---

## ⚡ Mulai Cepat — Bot Tunggal

```python
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.

```python
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:

```python
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:

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

Filter dinamis:

```python
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:

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

---

## 🎛 Keyboard

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

Contoh inline keyboard:

```python
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`:

```python
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:

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

Lalu di kode, cukup pastikan konstruktor `Client` memakai `bot_token`:

```diff
- 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/`](examples/) untuk:

- [`echo.py`](examples/echo.py) — bot echo sederhana
- [`single_bot.py`](examples/single_bot.py) — satu bot dengan beberapa handler
- [`multi_bot.py`](examples/multi_bot.py) — banyak bot dalam satu proses
- [`inline.py`](examples/inline.py) — bot inline query
- [`callback.py`](examples/callback.py) — inline keyboard & callback
- [`welcome.py`](examples/welcome.py) — welcomer grup
- [`antispam.py`](examples/antispam.py) — contoh middleware antispam

---

## 🧪 Test

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

---

## 🤝 Kontribusi

Kami menerima pull request. Silakan baca [`CONTRIBUTING.md`](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`](LICENSE)
untuk teks lengkap.

---

## 🙏 Kredit

- [Pyrogram](https://github.com/pyrogram/pyrogram) — API dan filosofi desain.
- [Telegram Bot API](https://core.telegram.org/bots/api) — dokumentasi resmi.
- [Telegram TL Schema](https://core.telegram.org/schema) — referensi tipe.
- Semua kontributor **TelePy**.

---

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