kurimod 3.3.0
Kurimod: pyromod fork targeting the Kurigram (Pyrogram) client with conversation helpers
Requires Python: >=3.8

# kurimod

> Fork of [pyromod](https://github.com/usernein/pyromod) that targets the actively maintained
> [kurigram](https://github.com/KurimuzonAkuma/pyrogram) fork of Pyrogram.

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

```bash
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](https://pyromod.pauxis.dev).

Also feel free to ask any kurimod-related questions on our [Telegram group](https://t.me/pyromodchat).

## 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:**

```python
response = await client.listen(chat_id=chat_id)
```

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

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

**Asking the user a question then await for the response:**

```python
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:**

```python
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:**

```python
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:**

```python
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:

```python
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+)](COPYING.lesser)