wizardgram

Async Telegram bot framework for Python.

Works with Python 3.10+. Tracks the current Bot API and documents what's verified.

Installation · Quickstart · Features · Examples · Docs · Contributing

Installation

pip install wizardgram

Quickstart

import wizardgram

bot = wizardgram.Bot(token="YOUR_BOT_TOKEN")


@bot.command("start")
async def start(ctx: wizardgram.Context) -> None:
    await ctx.reply("Hello!")


if __name__ == "__main__":
    bot.run()

Set WIZARDGRAM_TOKEN before running your bot.

Features

Middleware

async def logging_middleware(ctx, next_):
    print(ctx.update_type)
    await next_()


bot.use(logging_middleware)

Bot API Coverage

from wizardgram import status

print(status("sendMessage").value)

FSM

from wizardgram import Scene, Stage

stage = Stage([Scene("signup", [collect_name, collect_city])])
bot.use(stage.middleware())

Keyboards

from wizardgram import Keyboard

keyboard = Keyboard.inline().button("Confirm", callback_data="confirm").build()

Webhooks

async def telegram_webhook(request):
    return await bot.handle_webhook(request)

File Uploads

@bot.command("photo")
async def photo(ctx):
    await ctx.reply_with_photo("photo.jpg", caption="Attached")

Examples

Coverage Confidence

Project Layout

src/wizardgram/
    bot.py
    context.py
    coverage.py
    errors.py
    fsm.py
    keyboard.py
    middleware.py
    router.py
    testing.py
    transport.py
    types.py
examples/
    echo_bot.py
    menu_bot.py
    middleware_bot.py
    scene_bot.py
    webhook_bot.py

Star History

Contributing

See CONTRIBUTING.md for development setup and pull request guidance.

License

Apache-2.0. See LICENSE.