mirror of
https://github.com/TeamPGM/pyrogram.git
synced 2024-11-17 05:08:02 +00:00
149 lines
4.2 KiB
ReStructuredText
149 lines
4.2 KiB
ReStructuredText
More on Updates
|
|
===============
|
|
|
|
Here we'll show some advanced usages when working with updates.
|
|
|
|
.. note::
|
|
This page makes use of Handlers and Filters to show you how to handle updates.
|
|
Learn more at `Update Handling <UpdateHandling.html>`_ and `Using Filters <UsingFilters.html>`_.
|
|
|
|
Handler Groups
|
|
--------------
|
|
|
|
If you register handlers with overlapping filters, only the first one is executed and any other handler will be ignored.
|
|
|
|
In order to process the same update more than once, you can register your handler in a different group.
|
|
Groups are identified by a number (number 0 being the default) and are sorted, that is, a lower group number has a
|
|
higher priority.
|
|
|
|
For example, in:
|
|
|
|
.. code-block:: python
|
|
|
|
@app.on_message(Filters.text | Filters.sticker)
|
|
def text_or_sticker(client, message):
|
|
print("Text or Sticker")
|
|
|
|
|
|
@app.on_message(Filters.text)
|
|
def just_text(client, message):
|
|
print("Just Text")
|
|
|
|
``just_text`` is never executed because ``text_or_sticker`` already handles texts. To enable it, simply register the
|
|
function using a different group:
|
|
|
|
.. code-block:: python
|
|
|
|
@app.on_message(Filters.text, group=1)
|
|
def just_text(client, message):
|
|
print("Just Text")
|
|
|
|
Or, if you want ``just_text`` to be fired *before* ``text_or_sticker`` (note ``-1``, which is less than ``0``):
|
|
|
|
.. code-block:: python
|
|
|
|
@app.on_message(Filters.text, group=-1)
|
|
def just_text(client, message):
|
|
print("Just Text")
|
|
|
|
With :meth:`add_handler() <pyrogram.Client.add_handler>` (without decorators) the same can be achieved with:
|
|
|
|
.. code-block:: python
|
|
|
|
app.add_handler(MessageHandler(just_text, Filters.text), -1)
|
|
|
|
Update propagation
|
|
------------------
|
|
|
|
Registering multiple handlers, each in a different group, becomes useful when you want to handle the same update more
|
|
than once. Any incoming update will be sequentially processed by all of your registered functions by respecting the
|
|
groups priority policy described above. Even in case any handler raises an unhandled exception, Pyrogram will still
|
|
continue to propagate the same update to the next groups until all the handlers are done. Example:
|
|
|
|
.. code-block:: python
|
|
|
|
@app.on_message(Filters.private)
|
|
def _(client, message):
|
|
print(0)
|
|
|
|
|
|
@app.on_message(Filters.private, group=1)
|
|
def _(client, message):
|
|
print(1 / 0) # Unhandled exception: ZeroDivisionError
|
|
|
|
|
|
@app.on_message(Filters.private, group=2)
|
|
def _(client, message):
|
|
print(2)
|
|
|
|
All these handlers will handle the same kind of messages, that are, messages sent or received in private chats.
|
|
The output for each incoming update will therefore be:
|
|
|
|
.. code-block:: text
|
|
|
|
0
|
|
ZeroDivisionError: division by zero
|
|
2
|
|
|
|
Stop Propagation
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
In order to prevent further propagation of an update in the dispatching phase, you can do *one* of the following:
|
|
|
|
- Call the update's bound-method ``.stop_propagation()`` (preferred way).
|
|
- Manually ``raise StopPropagation`` error (more suitable for raw updates only).
|
|
|
|
.. note::
|
|
|
|
Note that ``.stop_propagation()`` is just an elegant and intuitive way to raise a ``StopPropagation`` error;
|
|
this means that any code coming *after* calling it won't be executed as your function just raised a custom exception
|
|
to signal the dispatcher not to propagate the update anymore.
|
|
|
|
Example with ``stop_propagation()``:
|
|
|
|
.. code-block:: python
|
|
|
|
@app.on_message(Filters.private)
|
|
def _(client, message):
|
|
print(0)
|
|
|
|
|
|
@app.on_message(Filters.private, group=1)
|
|
def _(client, message):
|
|
print(1)
|
|
message.stop_propagation()
|
|
|
|
|
|
@app.on_message(Filters.private, group=2)
|
|
def _(client, message):
|
|
print(2)
|
|
|
|
Example with ``raise StopPropagation``:
|
|
|
|
.. code-block:: python
|
|
|
|
from pyrogram import StopPropagation
|
|
|
|
@app.on_message(Filters.private)
|
|
def _(client, message):
|
|
print(0)
|
|
|
|
|
|
@app.on_message(Filters.private, group=1)
|
|
def _(client, message):
|
|
print(1)
|
|
raise StopPropagation
|
|
|
|
|
|
@app.on_message(Filters.private, group=2)
|
|
def _(client, message):
|
|
print(2)
|
|
|
|
The handler in group number 2 will never be executed because the propagation was stopped before. The output of both
|
|
examples will be:
|
|
|
|
.. code-block:: text
|
|
|
|
0
|
|
1
|