Skip to main content

pyroflow

PyPI version Python versions License: MIT

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_query waits for a button press, and both have rich versions. All of them are on Client too. listen_message and listen_callback_query wait without sending anything.
  • Say who and for how long. Pass listen_user_id in groups, or any member can answer. Always pass listen_timeout.
  • Cancel a wait. cancel_listen ends the wait on one key, and cancel_listens every wait with the fields you give, as a /cancel command would.
  • A wait holds a worker. workers_policy decides what happens when the workers run short. See the WorkersPolicy docstring.
  • Your own update types. A ListenerKey class and an UpdateListener class are enough to wait for any update. See the UpdateListener docstring.

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)

Source distribution for pyroflow 1.0.0
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)

Table of built distributions (wheels) for pyroflow 1.0.0
File Interpreter ABI Platform Actions
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 log

Release 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 log

Security 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.

Select from 2 files

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 log

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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page