Asyngram Telegram bot framework

A lightweight, asynchronous Python framework for building Telegram bots. Designed for simplicity, readability, and production use.

Installation

pip install asyngram

Quick Start

from asyngram import Bot, bold

bot = Bot("YOUR_BOT_TOKEN")

@bot.on.message.command("start")
async def start(ctx):
    await ctx.answer(f"Hello, {bold(ctx.user.first_name)}!")

bot.run()

How It Works

Asyngram uses a context-based approach. Every handler receives a ctx object that gives you access to:

• Message data (ctx.text, ctx.user, ctx.message)
• Response methods (ctx.answer(), ctx.reply(), ctx.edit(), ctx.notify())
• State management (ctx.state.set(), ctx.state.get_data(), ctx.state.finish())

Routing is handled via decorators. Handlers are evaluated top-to-bottom, and the first matching handler executes.

Key Features

• Async/Await: Non-blocking architecture built on aiohttp.
• FSM (State Machine): Manage multi-step flows like registrations or surveys. Data is automatically scoped per user/chat.
• Middleware Pipeline: Built-in logging, throttling, and error handling. Easy to extend with custom middleware.
• Keyboard Builders: Create Reply and Inline keyboards with method chaining. No manual JSON formatting.
• Smart Responses: ctx.answer() automatically decides whether to send a new message or edit the existing one.
• Formatting Helpers: Clean functions like bold(), italic(), code(), and link().

Documentation

Full guides, API reference, and troubleshooting are available at: docs.asyngram.dev

Included Examples

Four ready-to-run examples are provided in the repository:

1. echobot.py - Commands, text routing, and fallback handling
2. registration_bot.py - FSM step flow with validation and keyboards
3. inline_menu_bot.py - Callback parsing, prefix routing, and dynamic edits
4. production_bot.py - Environment config, custom middleware, logging, and shutdown handling

Run any example after installing the package and replacing the bot token.

Recommended Project Layout

my_bot/
├── main.py                 # Bot initialization & entry point
├── config.py               # Environment variables & settings
├── handlers/               # Command, message, and callback handlers
├── keyboards/              # Reusable keyboard builders
├── middlewares/            # Custom middleware
└── requirements.txt        # Python dependencies

License

GPL v3. See the LICENSE file for details.

Author

Created by Musa Sadullah Atabek. Musobek Sadullayev Otabek Tomonidan yaratildi Создано Мусобеком Садуллаевым Отабеком أنشأه موسى بن أتابك سعد الله