Gpgram
A modern, asynchronous Telegram Bot API library with advanced handler capabilities, inspired by python-telegram-bot and aiogram.
Features
- 🚀 Fully asynchronous using Python's
asyncio - 🧩 Clean, intuitive API design for easy bot development
- 🔄 Advanced routing system for handling updates
- 🔍 Flexible filter system for message handling
- 🔌 Middleware support for pre and post-processing updates
- 🛠️ Utility functions for common tasks
- 📝 Type hints for better IDE support
- 🧪 Pydantic integration for data validation
- 🔒 Error handling with custom exceptions
- 🌟 Simplified syntax for common tasks
Installation
pip install gpgram
Quick Start
Here's a simple echo bot example:
import asyncio
import logging
import os
from gpgram import Bot, Dispatcher, Router, CommandFilter
# Configure logging
logging.basicConfig(level=logging.INFO)
# Create a router for message handlers
router = Router()
@router.message(CommandFilter('start'))
async def start_command(message, bot):
"""Handle the /start command."""
await bot.send_message(
chat_id=message.chat.id,
text=f"Hello, {message.from_user.full_name}! I'm a simple bot."
)
@router.message()
async def echo_message(message, bot):
"""Echo all messages."""
if message.text:
await bot.send_message(
chat_id=message.chat.id,
text=f"You said: {message.text}"
)
async def main():
# Create a bot instance
bot = Bot(token=os.getenv('TELEGRAM_BOT_TOKEN'))
# Create a dispatcher
dp = Dispatcher(bot=bot)
# Register the router
dp.register_router(router)
# Start polling
await dp.run_polling()
if __name__ == '__main__':
asyncio.run(main())
Advanced Usage
Using Filters
from gpgram import TextFilter, RegexFilter, ChatTypeFilter
# Text filter
@router.message(TextFilter("hello", ignore_case=True))
async def hello_message(message, bot):
await bot.send_message(
chat_id=message.chat.id,
text="Hello to you too!"
)
# Regex filter
@router.message(RegexFilter(r"^[0-9]+$"))
async def number_message(message, bot):
await bot.send_message(
chat_id=message.chat.id,
text="That's a number!"
)
# Chat type filter
@router.message(ChatTypeFilter("private"))
async def private_message(message, bot):
await bot.send_message(
chat_id=message.chat.id,
text="This is a private chat"
)
Using Inline Keyboards
from gpgram import InlineKeyboardBuilder
@router.message(CommandFilter('menu'))
async def menu_command(message, bot):
# Create an inline keyboard
keyboard = InlineKeyboardBuilder()
keyboard.add("Option 1", callback_data="option_1")
keyboard.add("Option 2", callback_data="option_2")
keyboard.row()
keyboard.add("Option 3", callback_data="option_3")
await bot.send_message(
chat_id=message.chat.id,
text="Please select an option:",
reply_markup=keyboard.build()
)
@router.callback_query()
async def handle_callback_query(callback_query, bot):
# Answer the callback query
await bot.answer_callback_query(
callback_query_id=callback_query.id,
text=f"You clicked: {callback_query.data}"
)
# Send a response based on the callback data
await bot.send_message(
chat_id=callback_query.message.chat.id,
text=f"You selected: {callback_query.data}"
)
Using Middleware
from gpgram import BaseMiddleware
class LoggingMiddleware(BaseMiddleware):
"""Middleware for logging updates."""
async def on_pre_process_update(self, update, data):
"""Log updates before processing."""
print(f"Received update: {update.update_id}")
async def on_post_process_update(self, update, data, handler_result):
"""Log updates after processing."""
print(f"Processed update: {update.update_id}")
# Register the middleware
dp.register_middleware(LoggingMiddleware())
Error Handling
# Error handler
async def error_handler(exception, update):
"""Handle errors."""
print(f"Error processing update {update.update_id}: {exception}")
# Register the error handler
dp.register_error_handler(error_handler)
Simplified Syntax
Gpgram also provides a simplified syntax for common tasks:
import os
import asyncio
from gpgram import SimpleBot, Handler, Button, InlineButton
async def main():
# Create a bot instance with the simplified interface
bot = SimpleBot(token=os.getenv('TELEGRAM_BOT_TOKEN'))
# Create a handler
handler = Handler(bot=bot)
# Register command handlers
@handler.command("start")
async def start_command(message, bot):
await message.reply(
bot=bot,
text="Hello! I'm a bot created with Gpgram's simplified syntax."
)
# Register message handlers
@handler.message(contains="hello")
async def hello_handler(message, bot):
await message.reply(
bot=bot,
text=f"Hello, {message.from_user_first_name}!"
)
# Create inline buttons
button1 = InlineButton(text="Option 1", callback_data="option1")
button2 = InlineButton(text="Option 2", callback_data="option2")
# Create a keyboard with the buttons
keyboard = Button.row(button1, button2)
# Start polling
await handler.start_polling()
if __name__ == "__main__":
asyncio.run(main())
Examples
Check out the examples directory for more detailed examples:
simple_bot.py- A simple bot with basic commandsadvanced_bot.py- An advanced bot with inline keyboards, middleware, and error handlingecho_bot.py- A basic echo botinline_keyboard_bot.py- A bot demonstrating inline keyboardssimple_syntax_bot.py- A bot using the simplified syntax
Documentation
For more detailed documentation, see the docstrings in the code or visit our documentation website.
Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Metadata
Release files for gpgram 0.2.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| gpgram-0.2.0.tar.gz | 63.5 kB | Without provenance | Details for gpgram-0.2.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| gpgram-0.2.0-py2.py3-none-any.whl | Python 3, Python 2 | none | any | Details for gpgram-0.2.0-py2.py3-none-any.whl |
Total release size: 113.9 kB
Release files / gpgram-0.2.0.tar.gz
| Download URL | gpgram-0.2.0.tar.gz |
|---|---|
| Size | 63.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
565fa93d4df116c770210cde1167b7e7ae7913eead10408b814c4db1aa372a61
|
|
BLAKE2b-256 checksum How to use checksums |
c222f59516dedf4f24f73e46b28f453a55f8c90f0e0872cd3b3fc937013cf60f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.1
|
Release files / gpgram-0.2.0-py2.py3-none-any.whl
| Download URL | gpgram-0.2.0-py2.py3-none-any.whl |
|---|---|
| Size | 50.5 kB |
| Tags | Python 2 Python 3 |
|
SHA-256 checksum How to use checksums |
d6e952920279f85f28a8c8ebef0565ab1568a52cae74851ad22ab79fec732cb2
|
|
BLAKE2b-256 checksum How to use checksums |
ed9591c89138f099ca7e620d3e9d018d8ff304106a72f101d3648d776b61ee3a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.1.0 CPython/3.13.1
|
Security for gpgram 0.2.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.