Metadata-Version: 2.4
Name: DryGram
Version: 1.2.1
Summary: Modern asynchronous Telegram MTProto framework.
Home-page: https://github.com/TG-BOTSNETWORK/drygram
Author: Santhu
Author-email: Santhu <telegramsanthu@gmail.com>
License: GPL-3.0
Project-URL: Homepage, https://github.com/TG-BOTSNETWORK/drygram
Project-URL: Documentation, https://github.com/TG-BOTSNETWORK/drygram/docs
Project-URL: Repository, https://github.com/TG-BOTSNETWORK/drygram
Project-URL: Bug Tracker, https://github.com/TG-BOTSNETWORK/drygram/issues
Keywords: telegram,mtproto,asyncio,telegram-client,telegram-framework
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: License :: OSI Approved :: GNU General Public License v3 (GPLv3)
Classifier: Operating System :: OS Independent
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Development Status :: 5 - Production/Stable
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: COPYING
License-File: NOTICE
Requires-Dist: cryptography>=42.0.0
Requires-Dist: aiosqlite>=0.20.0
Provides-Extra: crypto
Requires-Dist: cryptography>=42.0.0; extra == "crypto"
Provides-Extra: calls
Requires-Dist: py-tgcalls==2.3.3; extra == "calls"
Requires-Dist: ntgcalls==2.2.5; extra == "calls"
Provides-Extra: mongodb
Requires-Dist: motor>=3.3.0; extra == "mongodb"
Provides-Extra: redis
Requires-Dist: redis>=5.0.0; extra == "redis"
Provides-Extra: postgres
Requires-Dist: asyncpg>=0.29.0; extra == "postgres"
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"
Requires-Dist: black>=24.0.0; extra == "dev"
Requires-Dist: isort>=5.13.0; extra == "dev"
Requires-Dist: mypy>=1.10.0; extra == "dev"
Requires-Dist: bandit>=1.7.0; extra == "dev"
Requires-Dist: safety>=3.0.0; extra == "dev"
Requires-Dist: pip-audit>=2.7.0; extra == "dev"
Requires-Dist: build>=1.2.0; extra == "dev"
Requires-Dist: twine>=5.0.0; extra == "dev"
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5.0; extra == "docs"
Requires-Dist: mkdocs-minify-plugin>=0.8.0; extra == "docs"
Requires-Dist: mkdocs-git-revision-date-localized-plugin>=1.2.0; extra == "docs"
Dynamic: author
Dynamic: home-page
Dynamic: license-file
Dynamic: requires-python

<p align="center">
  <img src="assets/logo.png" alt="DryGram Logo" width="280">
</p>

# DryGram

Modern, fully asynchronous, production-ready Telegram MTProto v2.0 client framework built from scratch in Python.

<p align="center">
  <a href="https://www.python.org/"><img src="https://img.shields.io/badge/Python-3.13+-blue.svg" alt="Python Version"></a>
  <a href="LICENSE"><img src="https://img.shields.io/badge/License-GPL--3.0-green.svg" alt="License Badge"></a>
  <a href="https://github.com/TG-BOTSNETWORK/drygram/releases"><img src="https://img.shields.io/github/v/release/TG-BOTSNETWORK/drygram" alt="Latest Release"></a>
  <a href="https://pypi.org/project/drygram/"><img src="https://img.shields.io/pypi/dm/drygram" alt="Downloads"></a>
  <a href="https://github.com/TG-BOTSNETWORK/drygram/docs"><img src="https://img.shields.io/badge/Docs-MkDocs-blue.svg" alt="Documentation Badge"></a>
  <a href="https://github.com/TG-BOTSNETWORK/drygram/stargazers"><img src="https://img.shields.io/github/stars/TG-BOTSNETWORK/drygram?style=flat" alt="GitHub Stars"></a>
  <a href="https://github.com/TG-BOTSNETWORK/drygram/issues"><img src="https://img.shields.io/github/issues/TG-BOTSNETWORK/drygram" alt="GitHub Issues"></a>
  <a href="https://github.com/TG-BOTSNETWORK/drygram/actions"><img src="https://img.shields.io/github/actions/workflow/status/TG-BOTSNETWORK/drygram/test.yml" alt="Build Status"></a>
  <a href="https://pypi.org/project/drygram/"><img src="https://img.shields.io/pypi/v/drygram" alt="PyPI Version"></a>
</p>

---

## Introduction

DryGram is a production-grade, highly-optimized, fully asynchronous Telegram MTProto client framework built from scratch in Python 3.13+. It implements the secure MTProto v2.0 protocol and integrates the latest Telegram features natively.

Designed with architectural originality at its core, DryGram does NOT duplicate or copy Pyrogram, Telethon, or other existing wrappers. It features a decoupled structure, pluggable session stores, extensible middleware chains, and a robust update dispatcher system to achieve maximum performance and scalability.

---

## Features

| Feature | Description |
| :--- | :--- |
| **Authentication** | Support for Bot authorization, User authorization, 2FA password verification, and QR Login flows. |
| **Sessions** | Pluggable, highly-concurrent database storage backends: SQLite, MongoDB, Redis, and PostgreSQL. |
| **Stories** | High-level APIs for publishing stories, reacting to them, archiving stories, and adjusting story privacy. |
| **Business** | Full support for Telegram Business greeting/away responses, custom business links, and short reply templates. |
| **Premium** | Operations for Telegram Star payments, upgradeable gifts, collectibles, and custom Premium Emoji Statuses. |
| **Media** | Chunked uploads, high-speed concurrent downloads, and representations for Photos, Videos, Documents, Audios, and VoiceNotes. |
| **Text Formatting** | Built-in, high-speed parsers for Markdown and HTML messages. |
| **Keyboards** | Declarative markup interfaces for Reply and Inline keyboards, callback button handlers, and interactive menus. |
| **Plugin System & Middleware** | Extensible middleware pipelines, priority-based command watchers, and modular update routing. |
| **Raw MTProto & AsyncIO** | Direct invocation of raw TL schema functions via async loops. |

---

## Installation

### Installation Options

#### 1. Standard Installation (No native compilers required)
Install the core package via PyPI:
```bash
pip install drygram
```

#### 2. Optional Crypto Installation
Install with the optional `crypto` dependency group:
```bash
pip install "drygram[crypto]"
```
*Note: Installs the required standard cryptography package without requiring native compilers or Visual Studio Build Tools.*

#### 3. Optional Voice & Calling Support
Install with integrations for voice and video calling:
```bash
pip install "drygram[calls]"
```

#### 4. Optional Database Support
Install pluggable session database stores:
```bash
# MongoDB support
pip install "drygram[mongodb]"

# Redis support
pip install "drygram[redis]"

# PostgreSQL support
pip install "drygram[postgres]"
```

#### 5. Development Installation
Install for library contribution and testing:
```bash
pip install "drygram[dev]"
```

### Alternative Package Managers
Using **uv**:
```bash
uv pip install drygram
```

Using **Poetry**:
```bash
poetry add drygram
```

### Installation from Source
To install the latest development code from GitHub:
```bash
git clone https://github.com/TG-BOTSNETWORK/drygram.git
cd drygram
pip install -e .
```

To install development and testing dependencies:
```bash
pip install -e .[dev]
```

---

## Quick Start

The following is a complete runnable bot that responds to `/start` messages:

```python
from drygram import (
    DryClient, filters, enums, errors, types, idle, StringSessionGenerator
)

# Initialize bot client
app = DryClient(api_id=12345, api_hash="abcdef", bot_token="YOUR_BOT_TOKEN")

# Register an update observer for /start command with filters
@app.route("/start", gate=filters.private)
async def start_handler(client, msg: types.Message):
    await msg.reply("Hello! Welcome to DryGram.")

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

---

## Top-Level Public API Exports

DryGram provides a clean, Pyrogram/Telethon-friendly top-level import structure:

```python
from drygram import (
    DryClient,              # Main MTProto client engine
    filters,                # Pyrogram/Telethon compatible update filter factory
    enums,                  # Telegram enumerations (ChatType, ParseMode, etc.)
    errors,                 # Framework and MTProto RPC exception module
    types,                  # Type dataclasses (Message, User, Chat, Media)
    idle,                   # Signal-safe event loop blocking helper
    StringSessionGenerator  # Tool for generating DRY1 String Sessions
)
```

---

## Client Authentication Methods

DryGram supports both Bot and User authentication out of the box.

### 1. Bot Authentication (Recommended)
Automatically starts the client in Bot Mode. No session file is created; everything runs in memory.
```python
from drygram import DryClient

app = DryClient(
    api_id=12345,
    api_hash="abcdef",
    bot_token="YOUR_BOT_TOKEN"  # recommended for bots, no session_name required
)
```

### 2. User Authentication
Starts the client in User Mode. Instead of saving `.session` files on disk, DryGram uses stateless **MTProto String Sessions** loaded via the `session_name` parameter.
```python
from drygram import DryClient

# The session_name parameter stores the generated MTProto String Session, not a filename
app = DryClient(
    api_id=12345,
    api_hash="abcdef",
    session_name="DRY1U_..."  # generated string session
)
```

To export the authenticated session to a string:
```python
import asyncio
from drygram import DryClient

async def main():
    # If starting without credentials, log in interactively or import string session
    async with DryClient(api_id=12345, api_hash="abc", session_name="DRY1U_...") as app:
        # Export the active session to a string
        sess_str = await app.export_session()
        print("Exported String Session:", sess_str)

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

---

## Project Structure

```
drygram/
├── drygram/           # Primary package source code
├── docs/              # Detailed guides and manuals
├── examples/          # Complete client usage examples
├── tests/             # Comprehensive testing suite
├── pyproject.toml     # Project metadata and configurations
└── setup.py           # Legacy installer script
```

---

## Documentation

The full documentation is available under the [docs/](docs) directory, containing tutorials and details about the architecture. You can also build it locally using MkDocs:
```bash
pip install mkdocs-material
mkdocs serve
```

---

## Supported Platforms

- **Windows**: x86, x64, ARM64, and WSL.
- **Linux**: Ubuntu, Debian, Arch Linux, Fedora, CentOS, and Alpine.
- **macOS**: Intel and Apple Silicon (M1/M2/M3).
- **Containerization**: Full support for Docker and Kubernetes environments.

---

## Cryptographic Backend & Performance

DryGram dynamically manages cryptographic execution via its built-in Backend Manager:

| Backend | Implementation | Acceleration | Performance Note |
| :--- | :--- | :--- | :--- |
| **Cryptography** | Pure Python Engine | **Disabled** | High compatibility; works out-of-the-box on any platform without compiler tools. |

DryGram operates exclusively on standard Python-compatible cryptography libraries, ensuring compiled C extensions or platform-specific Visual Studio Build Tools are never required.

---

## Optional Voice Support

Voice and video calling functionality are supported through external integrations. Users can utilize third-party WebRTC/calling libraries alongside `DryClient` for streaming capabilities:
- **py-tgcalls** == `2.3.3`
- **ntgcalls** == `2.2.5`

These dependencies can be installed using the optional `calls` extra group:
```bash
pip install "drygram[calls]"
```

---

## Community

- **Support Chat**: [DryGram Support Chat](https://telegram.me/drygramchat)
- **Updates Channel**: [DryGram Updates Channel](https://telegram.me/drygramupdates)
- **GitHub Repository**: [GitHub Issues & Code](https://github.com/TG-BOTSNETWORK/drygram)

---

## Special Thanks

- **Telegram Team** for providing public MTProto documentation and protocol specifications.
- **The Python Open-Source Community** for developing the underlying dependencies and testing systems that power modern async development.
- **Contributors** and community members helping review code and report issues.

---

## Credits

- **Designed and Developed by**: [Santhu](https://github.com/Santhu)
- **Project Name**: DryGram
- **Source Code**: [TG-BOTSNETWORK/drygram](https://github.com/TG-BOTSNETWORK/drygram)

---

## License

This project is licensed under the [GNU General Public License v3.0](LICENSE).
