Metadata-Version: 2.4
Name: sayagram
Version: 0.4.4
Summary: High-performance Telegram API framework for Python.
Project-URL: Homepage, https://github.com/SayaGram/sayagram
Project-URL: Repository, https://github.com/SayaGram/sayagram
Project-URL: Issues, https://github.com/SayaGram/sayagram/issues
Author: Sayagram contributors
License-Expression: MIT
License-File: LICENSE
Keywords: async,bot,framework,mtproto,telegram,userbot
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Communications :: Chat
Classifier: Topic :: Internet
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Requires-Python: >=3.10
Provides-Extra: aiogram
Requires-Dist: aiogram<4,>=3.0; extra == 'aiogram'
Provides-Extra: all
Requires-Dist: aiogram<4,>=3.0; extra == 'all'
Requires-Dist: pyrogram<3,>=2.0.106; extra == 'all'
Requires-Dist: srigram<3,>=2.4; extra == 'all'
Requires-Dist: telethon<2,>=1.37; extra == 'all'
Requires-Dist: tgcrypto>=1.2; extra == 'all'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8.0; extra == 'dev'
Requires-Dist: ruff>=0.6; extra == 'dev'
Requires-Dist: twine>=6.0; extra == 'dev'
Provides-Extra: pyrogram
Requires-Dist: pyrogram<3,>=2.0.106; extra == 'pyrogram'
Provides-Extra: speedup
Requires-Dist: tgcrypto>=1.2; extra == 'speedup'
Provides-Extra: srigram
Requires-Dist: srigram<3,>=2.4; extra == 'srigram'
Provides-Extra: telethon
Requires-Dist: telethon<2,>=1.37; extra == 'telethon'
Description-Content-Type: text/markdown

<p align="center">
  <img src="https://raw.githubusercontent.com/SayaGram/sayagram/main/assets/sayagram.png" alt="Sayagram" width="220">
</p>

# Sayagram

High-Performance Telegram API Framework for Python

[![PyPI version](https://img.shields.io/pypi/v/sayagram.svg)](https://pypi.org/project/sayagram/)
[![Python versions](https://img.shields.io/pypi/pyversions/sayagram.svg)](https://pypi.org/project/sayagram/)
[![License](https://img.shields.io/pypi/l/sayagram.svg)](https://github.com/SayaGram/sayagram/blob/main/LICENSE)
[![Telegram Support](https://img.shields.io/badge/Telegram-Sayagram-blue.svg)](https://github.com/SayaGram/sayagram/issues)

Sayagram is an elegant, asynchronous, and deeply customizable Python framework
for Telegram bots, user clients, and MTProto-powered applications. It gives
developers a clean Sayagram API for building scalable Telegram projects with
minimal boilerplate.

## Why Sayagram?

When building production-grade Telegram applications, you need a framework that
stays simple at the surface and powerful underneath.

- Modern Telegram UX: Custom emoji entities, inline keyboard helpers, callback
  data, and clean message reply tools.
- High-concurrency ready: Built around Python asyncio for responsive bot and
  user automation workflows.
- Unified app style: Write intuitive `Client`, `filters`, and `Message` code
  for standard bots and larger Telegram applications.
- Direct escape hatch: Use `app.raw` when you need precise low-level control.
- One install command: Publish, install, and import as Sayagram.

## Installation

Install Sayagram from PyPI:

```bash
pip install -U sayagram
```

Install every supported engine in one command:

```bash
pip install -U "sayagram[all]"
```

Or install only the engine you want:

```bash
pip install -U "sayagram[aiogram]"
pip install -U "sayagram[telethon]"
pip install -U "sayagram[pyrogram]"
pip install -U "sayagram[srigram]"
pip install -U "sayagram[speedup]"
```

Requires Python 3.10 or higher.

## Engine Support

Sayagram supports a native dependency-free Bot API engine and optional adapters
for aiogram, Telethon, Pyrogram, and Srigram. You keep the same Sayagram API and
choose the engine with `backend=...`.

| Backend | Powered by | Best for | Install |
| --- | --- | --- | --- |
| `sayagram` / `native` | Sayagram Bot API | Lean bot projects | `pip install -U sayagram` |
| `aiogram` | aiogram 3.x | Bot API projects that already use aiogram | `pip install -U "sayagram[aiogram]"` |
| `telethon` | Telethon 1.x | MTProto users, userbots, advanced clients | `pip install -U "sayagram[telethon]"` |
| `pyrogram` | Pyrogram 2.x | Pyrogram-style MTProto apps | `pip install -U "sayagram[pyrogram]"` |
| `srigram` | Srigram 2.x | Srigram/Pyrogram-compatible MTProto apps | `pip install -U "sayagram[srigram]"` |

Use `supported_backends()` and `backend_status()` when you want to inspect what
is available in the current Python environment.

## Quick Start

### The Standard Bot

Build a responsive Telegram bot with a small, readable Sayagram app.

```python
from sayagram import Client, filters

app = Client(
    "my_bot",
    bot_token="your_bot_token",
)


@app.on_message(filters.command("start") & filters.private)
async def hello(client, message):
    await message.reply_text("Hello from Sayagram!")


if __name__ == "__main__":
    app.run()
```

### Smart Keyboards and Custom Emojis

Sayagram includes small UI helpers and custom emoji entity builders for richer
Telegram messages.

```python
from sayagram import (
    Client,
    InlineKeyboardButton,
    InlineKeyboardMarkup,
    custom_emoji,
    filters,
    render,
)

app = Client("menu_bot", bot_token="your_bot_token")


@app.on_message(filters.command("menu"))
async def send_menu(client, message):
    keyboard = InlineKeyboardMarkup(
        [
            [
                InlineKeyboardButton(
                    "Confirm Action",
                    callback_data="confirm",
                )
            ]
        ]
    )

    text, entities = render(
        [
            "Please confirm your action ",
            custom_emoji("5368324170671202286", "\U0001F44D"),
        ]
    )

    await message.reply_text(text, entities=entities, reply_markup=keyboard)
```

### Same API, Different Engines

```python
from sayagram import Client, filters

app = Client(
    "my_app",
    backend="pyrogram",  # sayagram, aiogram, telethon, pyrogram, or srigram
    api_id=123456,
    api_hash="your_api_hash",
)


@app.on_message(filters.command("ping"))
async def ping(client, message):
    await message.reply_text("pong from Sayagram")


app.run()
```

## Direct Async Usage

```python
import asyncio

from sayagram import Sayagram


async def main() -> None:
    async with Sayagram(api_id=12345, api_hash="api_hash") as app:
        await app.send_message("me", "Hello from Sayagram")


asyncio.run(main())
```

## Common Framework API

Sayagram gives you a common framework API for everyday Telegram work:

- `Client(...)`: create one Sayagram app for bots or advanced clients.
- `filters.command(...)`, `filters.private`, `filters.group`: route updates
  with readable async filters.
- `Message.reply_text(...)`: reply from a normalized message object.
- `send_message(...)`: send text with entities, keyboards, and extra options.
- `send_custom_emoji_message(...)`: send custom emoji entity markup safely.
- `get_me(...)`: verify the current bot or MTProto account.
- `edit_message(...)`: edit text without changing app style.
- `delete_message(...)`: remove messages with one call.
- `download_media(...)`: download files through the selected engine.
- `InlineKeyboardMarkup` and `InlineKeyboardButton`: build inline keyboards
  directly from Sayagram.
- `app.raw`: access the selected low-level engine when you need advanced
  Telegram control.

## Environment Configuration

`Sayagram.from_env()` reads these variables:

- `SAYAGRAM_BACKEND` or `SAYAGRAM_ENGINE`: `auto`, `sayagram`, `aiogram`,
  `telethon`, `pyrogram`, `srigram`, `bot`, `user`, or `mtproto`.
- `SAYAGRAM_BOT_TOKEN` or `BOT_TOKEN`.
- `SAYAGRAM_API_ID` or `API_ID`.
- `SAYAGRAM_API_HASH` or `API_HASH`.
- `SAYAGRAM_SESSION`.

When `backend="auto"`, Sayagram chooses the right engine from your credentials.

## Local Credential Test

Use the local examples to check real Telegram credentials without saving secrets
in files.

```powershell
$env:SAYAGRAM_BOT_TOKEN="your_bot_token"
$env:SAYAGRAM_API_ID="your_api_id"
$env:SAYAGRAM_API_HASH="your_api_hash"
$env:PYTHONPATH="src"

python examples/check_credentials.py
python examples/local_bot.py
```

## Contributing and Support

Sayagram is actively developed and welcomes feedback, bug reports, and feature
ideas.

- Issue tracker: [GitHub Issues](https://github.com/SayaGram/sayagram/issues)
- Source code: [GitHub Repository](https://github.com/SayaGram/sayagram)
- Package: [PyPI Project](https://pypi.org/project/sayagram/)
