Pytdbot

Pytdbot is an asynchronous TDLib wrapper for Telegram users/bots written in Python.

Features

Pytdbot offers numerous advantages, including:

• Easy to Use: Designed with simplicity in mind, making it accessible for developers
• Performance: Fast and powerful, making it ready to fight
• Asynchronous: Fully asynchronous that allows for non-blocking requests and improved responsiveness
• Scalable: Easily scalable using TDLib Server
• Well-typed: Provides clear and well-defined methods and types to enhance developer experience
• Decorator-Based Updates: Simplifies the implementation of update handlers through a decorator pattern
• Bound Methods: Features types bound methods for improved usability
• Unlimited Support: Supports Plugins, filters, TDLib types/functions and much more

Requirements

• Python 3.10+
• Telegram API key
• tdjson or TDLib
• deepdiff

Installation

For better performance, it’s recommended to install orjson or ujson.

You can install Pytdbot with TDLib included using pip:

pip install --upgrade pytdbot[tdjson]

If the installation fails, then install without pre-built TDLib:

pip install pytdbot

Then you need to build TDLib from source and pass it to Client.lib_path.

You could also install the development version using the following command:

pip install --pre pytdbot

Examples

Basic example:

import asyncio
import logging

from pytdbot import Client, types

logging.basicConfig(
    level=logging.INFO,
    format="[%(levelname)s][p %(process)d %(threadName)s][%(created)f][%(filename)s:%(lineno)d][%(funcName)s][%(name)s]  %(message)s",
)
client = Client(
    token="1088394097:AAQX2DnWiw4ihwiJUhIHOGog8gGOI",  # Your bot token
    api_id=0,
    api_hash="API_HASH",
    files_directory="BotDB",  # Path where to store TDLib files
    database_encryption_key="1234echobot$",
    td_verbosity=2,  # TDLib verbosity level
    td_log=types.LogStreamFile("tdlib.log", 104857600),  # Set TDLib log file path
)

@client.on_updateNewMessage()
async def print_message(c: Client, message: types.UpdateNewMessage):
    print(message)

@client.on_message()
async def say_hello(c: Client, message: types.Message):
    msg = await message.reply_text(f"Hey {await message.mention(parse_mode='html')}! I'm cooking up a surprise... 🍳👨‍🍳", parse_mode="html")

    async with message.action("choose_sticker"):
        await asyncio.sleep(5)

        await msg.edit_text("Boo! 👻 Just kidding.")

# Run the client
asyncio.run(client.run())

For more examples, check the examples folder.

Using AI agents

Pytdbot includes a skill and a local docs CLI so coding agents can use the library correctly (bound methods, helpers, TDLib types, and so on)

1. Install Pytdbot
2. Point your agent at the skill file:
   • In this repo: pytdbot/ai/SKILL.md
   • or using curl -O "https://raw.githubusercontent.com/pytdbot/client/refs/heads/main/pytdbot/ai/SKILL.md"
3. Register it the way your tool expects (project skill, agent rule, or “read this file first”)

The skill explains how Pytdbot is meant to be used; the CLI returns live signatures from your installed version.

Thanks to

• You for viewing or using this project.

• @levlam for maintaining TDLib and for the help to create Pytdbot.

License

MIT License