Metadata-Version: 2.4
Name: sayagram
Version: 0.4.3
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: 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'
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
```

Requires Python 3.10 or higher.

## 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)
```

## 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.
- `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`: `auto`, `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.

## 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/)
