mirror of
https://github.com/pyrogram/pyrogram
synced 2025-08-31 22:35:36 +00:00
Update docs with new content
This commit is contained in:
Dan
92
docs/source/topics/create-filters.rst
Normal file
92
docs/source/topics/create-filters.rst
Normal file
@@ -0,0 +1,92 @@
|
||||
Creating Filters
|
||||
================
|
||||
|
||||
Pyrogram already provides lots of built-in :class:`~pyrogram.Filters` to work with, but in case you can't find
|
||||
a specific one for your needs or want to build a custom filter by yourself (to be used in a different kind of handler,
|
||||
for example) you can use :meth:`~pyrogram.Filters.create`.
|
||||
|
||||
.. note::
|
||||
|
||||
At the moment, the built-in filters are intended to be used with the :class:`~pyrogram.MessageHandler` only.
|
||||
|
||||
Custom Filters
|
||||
--------------
|
||||
|
||||
An example to demonstrate how custom filters work is to show how to create and use one for the
|
||||
:class:`~pyrogram.CallbackQueryHandler`. Note that callback queries updates are only received by bots; create and
|
||||
:doc:`authorize your bot <../start/auth>`, then send a message with an inline keyboard to yourself. This allows you to
|
||||
test your filter by pressing the inline button:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import InlineKeyboardMarkup, InlineKeyboardButton
|
||||
|
||||
app.send_message(
|
||||
"username", # Change this to your username or id
|
||||
"Pyrogram's custom filter test",
|
||||
reply_markup=InlineKeyboardMarkup(
|
||||
[[InlineKeyboardButton("Press me", b"pyrogram")]]
|
||||
)
|
||||
)
|
||||
|
||||
Basic Filters
|
||||
-------------
|
||||
|
||||
For this basic filter we will be using only the first two parameters of :meth:`~pyrogram.Filters.create`.
|
||||
|
||||
The code below creates a simple filter for hardcoded, static callback data. This filter will only allow callback queries
|
||||
containing "Pyrogram" as data, that is, the function *func* you pass returns True in case the callback query data
|
||||
equals to ``b"Pyrogram"``.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
static_data = Filters.create(
|
||||
name="StaticdData",
|
||||
func=lambda flt, callback_query: callback_query.data == b"Pyrogram"
|
||||
)
|
||||
|
||||
The ``lambda`` operator in python is used to create small anonymous functions and is perfect for this example, the same
|
||||
could be achieved with a normal function, but we don't really need it as it makes sense only inside the filter's scope:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def func(flt, callback_query):
|
||||
return callback_query.data == b"Pyrogram"
|
||||
|
||||
static_data = Filters.create(
|
||||
name="StaticData",
|
||||
func=func
|
||||
)
|
||||
|
||||
The filter usage remains the same:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@app.on_callback_query(static_data)
|
||||
def pyrogram_data(client, callback_query):
|
||||
client.answer_callback_query(callback_query.id, "it works!")
|
||||
|
||||
Filters with Arguments
|
||||
----------------------
|
||||
|
||||
A much cooler filter would be one that accepts "Pyrogram" or any other data as argument at usage time.
|
||||
A dynamic filter like this will make use of the third parameter of :meth:`~pyrogram.Filters.create`.
|
||||
|
||||
This is how a dynamic custom filter looks like:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def dynamic_data(data):
|
||||
return Filters.create(
|
||||
name="DynamicData",
|
||||
func=lambda flt, callback_query: flt.data == callback_query.data,
|
||||
data=data # "data" kwarg is accessed with "filter.data"
|
||||
)
|
||||
|
||||
And its usage:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@app.on_callback_query(dynamic_data(b"Pyrogram"))
|
||||
def pyrogram_data(client, callback_query):
|
||||
client.answer_callback_query(callback_query.id, "it works!")
|
||||
135
docs/source/topics/debugging.rst
Normal file
135
docs/source/topics/debugging.rst
Normal file
@@ -0,0 +1,135 @@
|
||||
Debugging
|
||||
=========
|
||||
|
||||
When working with the API, chances are you'll stumble upon bugs, get stuck and start wondering how to continue. Nothing
|
||||
to actually worry about -- that's normal -- and luckily for you, Pyrogram provides some commodities to help you in this.
|
||||
|
||||
Caveman Debugging
|
||||
-----------------
|
||||
|
||||
*The most effective debugging tool is still careful thought, coupled with judiciously placed print statements.*
|
||||
|
||||
-- Brian Kernighan, "Unix for Beginners" (1979)
|
||||
|
||||
Adding ``print()`` statements in crucial parts of your code is by far the most ancient, yet efficient technique for
|
||||
debugging programs, especially considering the concurrent nature of the framework itself. Pyrogram goodness in this
|
||||
respect comes with the fact that any object can be nicely printed just by calling ``print(obj)``, thus giving to you
|
||||
an insight of all its inner details.
|
||||
|
||||
Consider the following code:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
dan = app.get_users("haskell")
|
||||
print(dan) # User
|
||||
|
||||
This will show a JSON representation of the object returned by :meth:`~pyrogram.Client.get_users`, which is a
|
||||
:class:`~pyrogram.User` instance, in this case. The output on your terminal will be something similar to this:
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"_": "pyrogram.User",
|
||||
"id": 23122162,
|
||||
"is_self": false,
|
||||
"is_contact": false,
|
||||
"is_mutual_contact": false,
|
||||
"is_deleted": false,
|
||||
"is_bot": false,
|
||||
"is_verified": false,
|
||||
"is_restricted": false,
|
||||
"is_support": false,
|
||||
"is_scam": false,
|
||||
"first_name": "Dan",
|
||||
"status": {
|
||||
"_": "pyrogram.UserStatus",
|
||||
"user_id": 23122162,
|
||||
"recently": true
|
||||
},
|
||||
"username": "haskell",
|
||||
"language_code": "en",
|
||||
"photo": {
|
||||
"_": "pyrogram.ChatPhoto",
|
||||
"small_file_id": "AQADBAAD8tBgAQAEJjCxGgAEo5IBAAIC",
|
||||
"big_file_id": "AQADBAAD8tBgAQAEJjCxGgAEpZIBAAEBAg"
|
||||
}
|
||||
}
|
||||
|
||||
As you've probably guessed already, Pyrogram objects can be nested. That's how compound data are built, and nesting
|
||||
keeps going until we are left with base data types only, such as ``str``, ``int``, ``bool``, etc.
|
||||
|
||||
Accessing Attributes
|
||||
--------------------
|
||||
|
||||
Even though you see a JSON output, it doesn't mean we are dealing with dictionaries; in fact, all Pyrogram types are
|
||||
full-fledged Python objects and the correct way to access any attribute of them is by using the dot notation ``.``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
dan_photo = dan.photo
|
||||
print(dan_photo) # ChatPhoto
|
||||
|
||||
.. code-block:: json
|
||||
|
||||
{
|
||||
"_": "pyrogram.ChatPhoto",
|
||||
"small_file_id": "AQADBAAD8tBgAQAEJjCxGgAEo5IBAAIC",
|
||||
"big_file_id": "AQADBAAD8tBgAQAEJjCxGgAEpZIBAAEBAg"
|
||||
}
|
||||
|
||||
However, the bracket notation ``[]`` is also supported, but its usage is discouraged:
|
||||
|
||||
.. warning::
|
||||
|
||||
Bracket notation in Python is not commonly used for getting/setting object attributes. While it works for Pyrogram
|
||||
objects, it might not work for anything else and you should not rely on this.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
dan_photo_big = dan["photo"]["big_file_id"]
|
||||
print(dan_photo_big) # str
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
AQADBAAD8tBgAQAEJjCxGgAEpZIBAAEBAg
|
||||
|
||||
Checking an Object's Type
|
||||
-------------------------
|
||||
|
||||
Another thing worth talking about is how to tell and check for an object's type.
|
||||
|
||||
As you noticed already, when printing an object you'll see the special attribute ``"_"``. This is just a visual thing
|
||||
useful to show humans the object type, but doesn't really exist anywhere; any attempt in accessing it will lead to an
|
||||
error. The correct way to get the object type is by using the built-in function ``type()``:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
dan_status = dan.status
|
||||
print(type(dan_status))
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
<class 'pyrogram.UserStatus'>
|
||||
|
||||
And to check if an object is an instance of a given class, you use the built-in function ``isinstance()``:
|
||||
|
||||
.. code-block:: python
|
||||
:name: this-py
|
||||
|
||||
from pyrogram import UserStatus
|
||||
|
||||
dan_status = dan.status
|
||||
print(isinstance(dan_status, UserStatus))
|
||||
|
||||
.. code-block:: text
|
||||
|
||||
True
|
||||
|
||||
.. raw:: html
|
||||
|
||||
<script>
|
||||
var e = document.querySelector("blockquote p.attribution");
|
||||
var s = e.innerHTML;
|
||||
|
||||
e.innerHTML = s[0] + " " + s.slice(1);
|
||||
</script>
|
||||
@@ -105,93 +105,3 @@ More handlers using different filters can also live together.
|
||||
@app.on_message(Filters.chat("PyrogramChat"))
|
||||
def from_pyrogramchat(client, message):
|
||||
print("New message in @PyrogramChat")
|
||||
|
||||
Custom Filters
|
||||
--------------
|
||||
|
||||
Pyrogram already provides lots of built-in :class:`~pyrogram.Filters` to work with, but in case you can't find
|
||||
a specific one for your needs or want to build a custom filter by yourself (to be used in a different kind of handler,
|
||||
for example) you can use :meth:`~pyrogram.Filters.create`.
|
||||
|
||||
.. note::
|
||||
|
||||
At the moment, the built-in filters are intended to be used with the :class:`~pyrogram.MessageHandler` only.
|
||||
|
||||
An example to demonstrate how custom filters work is to show how to create and use one for the
|
||||
:class:`~pyrogram.CallbackQueryHandler`. Note that callback queries updates are only received by bots; create and
|
||||
:doc:`authorize your bot <../start/auth>`, then send a message with an inline keyboard to yourself. This allows you to
|
||||
test your filter by pressing the inline button:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
from pyrogram import InlineKeyboardMarkup, InlineKeyboardButton
|
||||
|
||||
app.send_message(
|
||||
"username", # Change this to your username or id
|
||||
"Pyrogram's custom filter test",
|
||||
reply_markup=InlineKeyboardMarkup(
|
||||
[[InlineKeyboardButton("Press me", b"pyrogram")]]
|
||||
)
|
||||
)
|
||||
|
||||
Basic Filters
|
||||
^^^^^^^^^^^^^
|
||||
|
||||
For this basic filter we will be using only the first two parameters of :meth:`~pyrogram.Filters.create`.
|
||||
|
||||
The code below creates a simple filter for hardcoded, static callback data. This filter will only allow callback queries
|
||||
containing "Pyrogram" as data, that is, the function *func* you pass returns True in case the callback query data
|
||||
equals to ``b"Pyrogram"``.
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
static_data = Filters.create(
|
||||
name="StaticdData",
|
||||
func=lambda flt, callback_query: callback_query.data == b"Pyrogram"
|
||||
)
|
||||
|
||||
The ``lambda`` operator in python is used to create small anonymous functions and is perfect for this example, the same
|
||||
could be achieved with a normal function, but we don't really need it as it makes sense only inside the filter's scope:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def func(flt, callback_query):
|
||||
return callback_query.data == b"Pyrogram"
|
||||
|
||||
static_data = Filters.create(
|
||||
name="StaticData",
|
||||
func=func
|
||||
)
|
||||
|
||||
The filter usage remains the same:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@app.on_callback_query(static_data)
|
||||
def pyrogram_data(client, callback_query):
|
||||
client.answer_callback_query(callback_query.id, "it works!")
|
||||
|
||||
Filters with Arguments
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
A much cooler filter would be one that accepts "Pyrogram" or any other data as argument at usage time.
|
||||
A dynamic filter like this will make use of the third parameter of :meth:`~pyrogram.Filters.create`.
|
||||
|
||||
This is how a dynamic custom filter looks like:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
def dynamic_data(data):
|
||||
return Filters.create(
|
||||
name="DynamicData",
|
||||
func=lambda flt, callback_query: flt.data == callback_query.data,
|
||||
data=data # "data" kwarg is accessed with "filter.data"
|
||||
)
|
||||
|
||||
And its usage:
|
||||
|
||||
.. code-block:: python
|
||||
|
||||
@app.on_callback_query(dynamic_data(b"Pyrogram"))
|
||||
def pyrogram_data(client, callback_query):
|
||||
client.answer_callback_query(callback_query.id, "it works!")
|
||||
Reference in New Issue
Block a user