Getting Started

Get up and running with kurigram-addons in under 5 minutes.

Installation

pip
pip install kurigram-addons
Poetry
poetry add kurigram-addons

Requirements: Python ≥ 3.10, Kurigram ≥ 2.1.35.

Optional Dependencies

Some features require extra packages. Install only what you need, or use [all] for everything:

ExtraInstallsNeeded for
[redis]redis[hiredis]RedisStorage — distributed FSM persistence
[sqlite]aiosqliteSQLiteStorage — local file-based persistence
[all]All of the aboveEverything
Install with extras
# SQLite support
pip install kurigram-addons[sqlite]

# Redis support
pip install kurigram-addons[redis]

# Everything
pip install kurigram-addons[all]

Minimal Bot with Keyboards

Create a bot that responds with an inline keyboard when the user types /start.

main.py
from kurigram_addons import KurigramClient, Router, InlineKeyboard, MemoryStorage

router = Router()

@router.on_command("start")
async def start(client, message):
    kb = InlineKeyboard(row_width=2)
    kb.button("🔍 Search", callback="search")
    kb.button("⚙️ Settings", callback="settings")
    kb.button("📖 Help", callback="help")
    await message.reply("Welcome! Choose an option:", reply_markup=kb)

app = KurigramClient(
    "my_bot",
    bot_token="YOUR_TOKEN",
    storage=MemoryStorage(),
    auto_flood_wait=True,
)
app.include_router(router)
app.run()

Lifecycle Hooks

Run async setup/teardown around the client lifecycle — connect databases, warm caches, etc.

lifecycle.py
@app.on_startup
async def init():
    await database.connect()
    print("✅ Database ready")

@app.on_shutdown
async def cleanup():
    await database.disconnect()
    print("🛑 Disconnected")

First Conversation Flow

Collect user input across multiple steps with a declarative class-based conversation.

registration.py
from kurigram_addons import Conversation, ConversationState

class Registration(Conversation):
    name = ConversationState(initial=True)
    email = ConversationState()

    @name.on_enter
    async def ask_name(self, ctx):
        await ctx.message.reply("What's your name?")

    @name.on_message
    async def save_name(self, ctx):
        await ctx.helper.update_data(name=ctx.message.text)
        await self.goto(ctx, self.email)

    @email.on_enter
    async def ask_email(self, ctx):
        await ctx.message.reply("Great! What's your email?")

    @email.on_message
    async def save_email(self, ctx):
        data = await ctx.helper.get_data()
        name = data["name"]
        await ctx.helper.finish()
        await ctx.message.reply(
            f"Done! Name: {name}, Email: {ctx.message.text}"
        )

# Register with the client
app.include_conversation(Registration)

What's Next?

🤖 KurigramClient
Full client API — middleware, routing, storage, FloodWait, health
💉 Dependency Injection
DIContainer + Depends() for handler DI
📢 Broadcast
Bulk send to user list with FloodWait handling
💬 Conversations
Class-based multi-step FSM flows
🌍 i18n
Auto-detect language and inject translator
🧪 Testing
MockClient and factory functions for unit tests
📦 SQLiteStorage
Persistent FSM with zero infrastructure
⏱️ Rate Limiting
Per-user / per-chat token-bucket rate limiter