kurimod 3.3.0

Kurimod: pyromod fork targeting the Kurigram (Pyrogram) client with conversation helpers

kurimod

Fork of pyromod that targets the actively maintained kurigram fork of Pyrogram.

Kurimod keeps the original pyromod conversation helpers while depending on kurigram instead of the archived pyrogram release line. Install it with:

pip install kurimod

The package pulls in the latest kurigram automatically. Although the dependency installs under the name kurigram, it still exposes the pyrogram import path so existing user code can continue to import pyrogram as before.

Kurimod is a versatile Python add-on for the Pyrogram API (through Kurigram), designed to make developing Telegram bots faster and more efficient. It's based on monkeypatching, which means it works together with Pyrogram/Kurigram, rather than being a fork or modified version. It adds features to Pyrogram classes on the go, so you don't need to update it every time Pyrogram/Kurigram is updated.

Whether you're building a simple chatbot or a complex form to get multiple responses from the user, kurimod has you covered. It enhances Pyrogram with a range of advanced features, simplifies conversation handling, and offers a high degree of customizability.

Documentation

You can find the full documentation at pyromod.pauxis.dev.

Also feel free to ask any kurimod-related questions on our Telegram group.

Key Features

• Effortless Bot Development: kurimod streamlines the process of building conversational Telegram bots, saving you time and effort during development.

• Advanced Conversation Management: Managing conversations with users is made easier, allowing you to create dynamic and interactive interactions much easier, without having to save states anywhere, by leveraging the power of async/await syntax.

• Effortless Inline Keyboards Creation: Creating inline keyboards is easier than ever with kurimod's inline keyboard helper functions.

• User-Friendly Pagination: Enhance the user experience by providing easy navigation tools with the kurimod's pagination helpers.

• Highly Customizable: kurimod's configuration options let you customize its behavior to meet your specific project requirements.

Examples

Awaiting a single message from a specific chat:

response = await client.listen(chat_id=chat_id)

Awaiting a single message from a specific user in a specific chat:

response = await client.listen(chat_id=chat_id, user_id=user_id)

Asking the user a question then await for the response:

response = await client.ask(chat_id=chat_id, text='What is your name?')

Asking the user a question then await for the response, with a timeout:

try:
    response = await client.ask(chat_id=chat_id, text='What is your name?', timeout=10)
except ListenerTimeout:
    await message.reply('You took too long to answer.')

Full handler example, getting user's name and age with bound method Chat.ask:

from kurimod import Client, Message
from pyrogram import filters


@Client.on_message(filters.command('form'))
async def on_form(client: Client, message: Message):
    chat = message.chat

    name = await chat.ask('What is your name?', filters=filters.text)
    age = await chat.ask('What is your age?', filters=filters.text)

    await message.reply(f'Your name is {name.text} and you are {age.text} years old.')

Easier inline keyboard creation:

from kurimod.helpers import ikb

keyboard = ikb([
    [('Button 1', 'callback_data_1'), ('Button 2', 'callback_data_2')],
    [('Another button', 't.me/pyromodchat', 'url')]
])

Initialization

To initialize kurimod, on the file that creates the client instance, simply import the Client class from kurimod instead of pyrogram:

from kurimod import Client

And that's all! You can still use the Client class as you would normally do with Pyrogram, but now having all the extra features.

You don't need to change the imports on the plugins files. Even by importing Client from pyrogram, the kurimod features will be available anyway. In order to monkeyatch kurimod features successfully, it's just required that the first Client class imported to your project code should be from kurimod. Then all the other future Client instances will be patched automatically.

You just need to import from kurimod if you want your IDE to recognize and suggest the extra features based on kurimod.Client type.

Contributing

We welcome contributions from the community to make kurimod even better.

Feel free to open issues, submit pull requests, or contribute in any way that aligns with our goals.

Copyright & License

This project may include snippets of Pyrogram code

• Pyrogram - Telegram MTProto API Client Library for Python. Copyright (C) 2017-2023 Dan <https://github.com/delivrance>

Licensed under the terms of the GNU Lesser General Public License v3 or later (LGPLv3+)