Metadata-Version: 2.4
Name: sayagram
Version: 0.4.1
Summary: Modern async Telegram framework for bots, user clients, and MTProto apps.
Project-URL: Homepage, https://github.com/shnwazdeveloper/sayagram
Project-URL: Repository, https://github.com/shnwazdeveloper/sayagram
Project-URL: Issues, https://github.com/shnwazdeveloper/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/shnwazdeveloper/sayagram/main/assets/sayagram.png" alt="Sayagram" width="220">
</p>

# Sayagram

High-performance async Telegram framework for Python bots, userbots, and
hybrid applications.

Sayagram gives you one framework API, one package name, and one install
command. It includes a native Sayagram Bot API engine for dependency-free bot
work, plus lazy advanced engines for larger Telegram applications.

Telegram custom emoji support is implemented with official message entities.
Sayagram can send custom emoji where Telegram allows it, but it cannot unlock
Telegram Premium or bypass Telegram platform limits.

## Installation

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

## Quick Start

```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 start(client, message):
    await message.reply_text("Hello 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())
```

## Custom Emoji

Telegram custom emoji entities must wrap a normal fallback emoji. Sayagram
calculates the correct UTF-16 offsets for Bot API and MTProto libraries.

```python
from sayagram import Client, custom_emoji, render

app = Client("emoji-bot", bot_token="123456:BOT_TOKEN")


async def send_approved(chat_id: int) -> None:
    text, entities = render(
        [
            "Approved ",
            custom_emoji("5368324170671202286", "\U0001F44D"),
        ]
    )
    await app.send_message(chat_id, text, entities=entities)
```

Compact markup is supported too:

```python
await app.send_custom_emoji_message(
    123456789,
    "Approved {emoji:5368324170671202286|\U0001F44D}",
)
```

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

## Backend Access

Sayagram gives you a common framework API for common work:

- `start()` and `stop()`
- `run()` and `run_forever()`
- `on_message()` with `sayagram.filters`
- `send_message()`
- `send_custom_emoji_message()`
- `edit_message()`
- `delete_message()`
- `download_media()`

For advanced Telegram features, use `app.raw` and call the selected backend
directly.

## Publishing

Build locally:

```bash
python -m build
```

Upload manually when you have a PyPI token:

```bash
python -m twine upload dist/*
```

The repository also includes a GitHub Actions workflow for PyPI Trusted
Publishing. Configure a PyPI trusted publisher for
`shnwazdeveloper/sayagram`, then create a GitHub release to publish.
