pyroflow
Conversations for Kurigram (Pyrogram): await the reply, and run one key's updates, such as one chat's, one at a time.
Arabic translation: README.ar.md. If the two differ, this English text is the reference.
pip install pyroflow
import pyroflow patches Pyrogram in place, so your existing code keeps working. Import it before creating any Client.
The supported Python versions are on the badge above, and the Kurigram requirement is in pyproject.toml. The details of every feature below are in its docstring.
Listening
A handler asks a question and awaits the answer, with no state machine. An update taken by a wait never reaches the handlers.
from pyroflow import Client, MessageListener
from pyroflow.enums import WorkersPolicy
from pyroflow.errors import ListenerTimeout
client = Client("my_session").setup_pyroflow(workers_policy=WorkersPolicy.CANCEL_OLDEST)
client.register_listener(MessageListener())
@client.on_message()
async def on_start(client, message):
if message.text != "/start":
return
try:
answer = await message.ask(
"What is your name?", listen_user_id=message.from_user.id, listen_timeout=60
)
except ListenerTimeout:
await message.reply("Timed out.")
return
await answer.reply(f"Hello, {answer.text}!")
client.run()
- More ways to ask.
ask_callback_querywaits for a button press, and both have rich versions. All of them are onClienttoo.listen_messageandlisten_callback_querywait without sending anything. - Say who and for how long. Pass
listen_user_idin groups, or any member can answer. Always passlisten_timeout. - Cancel a wait.
cancel_listenends the wait on one key, andcancel_listensevery wait with the fields you give, as a/cancelcommand would. - A wait holds a worker.
workers_policydecides what happens when the workers run short. See theWorkersPolicydocstring. - Your own update types. A
ListenerKeyclass and anUpdateListenerclass are enough to wait for any update. See theUpdateListenerdocstring.
Coordination
Two rapid messages from one user normally run two handlers at once, and the second can miss the question the first is about to ask. CoordinatedDispatcher runs the updates that share a key, such as a chat, one at a time, while other keys run freely.
from pyroflow import Client, CoordinatedDispatcher, MessageListener
def chat_key(update):
chat = getattr(update, "chat", None)
return None if chat is None else chat.id # None: the update runs free
client = Client("my_session")
client.dispatcher = CoordinatedDispatcher(client, key_functions=[chat_key]) # first
client.register_listener(MessageListener())
@client.on_message()
async def on_order(client, message):
if message.text != "/order":
return
answer = await message.ask(
"What do you want?", listen_user_id=message.from_user.id, listen_timeout=60
)
# A second message from this chat waits its turn, unless the wait takes it as the answer.
await answer.reply(f"Ordered {answer.text}.")
⚠️ Install it first, right after
Client(...): what was registered earlier never runs, with no error.⚠️ Pass
listen_timeout. A wait that never gets a reply, with no timeout, freezes its key.
The full behavior is in the CoordinatedDispatcher docstring. Listeners and coordination live in the client's own process: each client's dispatcher keeps its own lanes, and nothing is shared between clients or sessions.
Also included
Asking until valid. ask_until asks again until parse returns a value.
from pyroflow.models import AskAgain
async def parse_age(answer, kw):
return int(answer.text) if answer.text and answer.text.isdigit() else AskAgain("Digits only. Your age:")
age = await message.ask_until(
"Your age:",
parse=parse_age,
attempts=3,
listen_user_id=message.from_user.id,
listen_timeout=60,
)
Keyboards. CallbackData packs, unpacks and filters callback_data, and arrange splits buttons into rows.
from pyroflow.keyboards import CallbackData, CallbackFields, arrange, parsed
class Product(CallbackFields):
id: int = parsed(int)
action: str
product = CallbackData("product", Product)
buttons = [product.button("Buy", id=7, action="buy")] # callback_data: "product:7:buy"
rows = arrange(buttons, columns=2)
@client.on_callback_query(product.filter(action="buy"))
async def buy(client, query): ...
Pagination. A pagination builds one page of items with a navigation bar, from a sequence or a fetch function.
from pyroflow.keyboards import NumberedPagination
pages = NumberedPagination(
products,
item=lambda item: product.button(item.name, id=item.id, action="buy"),
page_data=lambda number: f"products:{number}",
)
page = await pages.build(2)
await message.reply("Products:", reply_markup=page.markup)
Text filters. pyroflow.filters adds text filters in the style of pyrogram.filters.
from pyroflow import MessageListener, filters
# A registered command ends an open question and reaches its handler.
client.register_listener(MessageListener(strict_filter=~filters.registered_command()))
Repeated presses. filters.too_fast matches an update that arrived within an interval of the last one let through with its key, such as a button pressed again quickly, so on_spam answers it and ~ keeps the handler from running again. Make one filter per update type and use it on all of that type's handlers, not one per handler.
from pyroflow import filters
# A press within 2 seconds of the same user's last press let through on that message
# is answered and skipped.
spam = filters.too_fast(2, on_spam=lambda query: query.answer("Slow down"))
@client.on_callback_query(~spam)
async def on_press(client, query): ...
Bot commands. BotCommandsMixin publishes the commands marked with mark_bot_commands when the client starts.
# bot.py
from pyroflow import BotCommandsMixin, Client
class Bot(BotCommandsMixin, Client): ...
Bot("my_session", plugins=dict(root="plugins")).run()
# plugins/start.py
from pyrogram import filters
from pyrogram.types import BotCommand
from pyroflow import Client
from pyroflow.utils import mark_bot_commands
@mark_bot_commands(BotCommand("start", "Start the bot"))
@Client.on_message(filters.command("start")) # the unbound form, not @client.on_message
async def on_start(client, message): ...
Errors. Every error is in pyroflow.errors and derives from PyroflowError.
Development
See CONTRIBUTING.md. Release notes are on the releases page.
License
MIT
Metadata
Release files for pyroflow 1.0.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 |
|---|---|---|---|---|
| pyroflow-1.0.0.tar.gz | 173.3 kB | With provenance | Details for pyroflow-1.0.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| pyroflow-1.0.0-py3-none-any.whl | Python 3 | none | any | Details for pyroflow-1.0.0-py3-none-any.whl |
Total release size: 267.3 kB
Release files / pyroflow-1.0.0.tar.gz
| Download URL | pyroflow-1.0.0.tar.gz |
|---|---|
| Size | 173.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
70a63cfe61c40eb43ee1d1065ba74263b2b729548376bb7fdb459cb40c35f9a0
|
|
BLAKE2b-256 checksum How to use checksums |
eb717cf9f4e2fd62d3da976aaecdae077e9339173567f08748fa920d34d0e0fe
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logRelease files / pyroflow-1.0.0-py3-none-any.whl
| Download URL | pyroflow-1.0.0-py3-none-any.whl |
|---|---|
| Size | 94.0 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
cc0e514dc2b147ebab08f2f16172770688eb61c3193fecf6660a1551272931d2
|
|
BLAKE2b-256 checksum How to use checksums |
0b66434e82299727cff7581ba88cbbfd6a6e8b240a83127e779333c347d9712a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
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.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logSecurity for pyroflow 1.0.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.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for pyroflow-1.0.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.
Transparency logA 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.