Update docs with new content

delivrance · delivrance · commit 1be8ca94cc2a · 2019-06-04T16:10:32.000+02:00
diff --git a/docs/source/faq.rst b/docs/source/faq.rst
@@ -155,6 +155,14 @@ things:
   chats).
 - The chat id argument you passed is in form of a string; you have to convert it into an integer with ``int(chat_id)``.
 
+UnicodeEncodeError: '<encoding>' codec can't encode …
+-----------------------------------------------------
+
+Where ``<encoding>`` might be *ascii*, *cp932*, *charmap* or anything else other than **utf-8**. This error usually
+shows up when you try to print something and has very little to do with Pyrogram itself as it is strictly related to
+your own terminal. To fix it, either find a way to change the encoding settings of your terminal to UTF-8 or switch to a
+better one.
+
 My verification code expires immediately!
 -----------------------------------------
 
@@ -179,8 +187,20 @@ Having said that, here's a list of what Telegram definitely doesn't like:
 - Spam, sending unsolicited messages or adding people to unwanted groups and channels.
 - Virtual/VoIP and cheap real numbers, because they are relatively easy to get and likely used for spam/flood.
 
-However, you might be right, and your account was deactivated/limited without any reason. This could happen because of
-mistakes by either the automatic systems or a moderator. In such cases you can kindly email Telegram at
+And here's a good explanation of how, probably, the system works:
+
+.. raw:: html
+
+    <script
+        async src="https://telegram.org/js/telegram-widget.js?5"
+        data-telegram-post="PyrogramChat/69424"
+        data-width="100%">
+    </script>
+
+.. centered:: Join the discussion at `@PyrogramChat <https://t.me/pyrogramchat>`_
+
+However, you might be right, and your account was deactivated/limited without any good reason. This could happen because
+of mistakes by either the automatic systems or a moderator. In such cases you can kindly email Telegram at
 recover@telegram.org, contact `@smstelegram`_ on Twitter or use `this form`_.
 
 Are there any secret easter eggs?
diff --git a/docs/source/glossary.rst b/docs/source/glossary.rst
@@ -9,7 +9,11 @@ general. Some words may as well link to dedicated articles in case the topic is
     If you think something interesting could be added here, feel free to propose it by opening a `Feature Request`_.
 
 
+Terms
+-----
+
 .. glossary::
+    :sorted:
 
     API
         Application Programming Interface: a set of methods, protocols and tools that make it easier to develop programs
diff --git a/docs/source/index.rst b/docs/source/index.rst
@@ -122,7 +122,8 @@ Meta
     :hidden:
     :caption: Topic Guides
 
-    topics/filters
+    topics/use-filters
+    topics/create-filters
     topics/more-on-updates
     topics/config-file
     topics/smart-plugins
@@ -134,6 +135,7 @@ Meta
     topics/proxy
     topics/bots-interaction
     topics/mtproto-vs-botapi
+    topics/debugging
     topics/test-servers
     topics/advanced-usage
     topics/voice-calls
diff --git a/docs/source/start/invoking.rst b/docs/source/start/invoking.rst
@@ -24,40 +24,40 @@ Making API method calls with Pyrogram is very simple. Here's an example we are g
 
     app.stop()
 
-Let's begin by importing the Client class from the Pyrogram package:
+#.  Let's begin by importing the Client class from the Pyrogram package:
 
-.. code-block:: python
+    .. code-block:: python
 
-    from pyrogram import Client
+        from pyrogram import Client
 
-Now instantiate a new Client object, "my_account" is a session name of your choice:
+#.  Now instantiate a new Client object, "my_account" is a session name of your choice:
 
-.. code-block:: python
+    .. code-block:: python
 
-    app = Client("my_account")
+        app = Client("my_account")
 
-To actually make use of any method, the client has to be started first:
+#.  To actually make use of any method, the client has to be started first:
 
-.. code-block:: python
+    .. code-block:: python
 
-    app.start()
+        app.start()
 
-Now, you can call any method you like:
+#.  Now, you can call any method you like:
 
-.. code-block:: python
+    .. code-block:: python
 
-    print(app.get_me())  # Print information about yourself
+        print(app.get_me())  # Print information about yourself
 
-    # Send messages to yourself:
-    app.send_message("me", "Hi!")  # Text message
-    app.send_location("me", 51.500729, -0.124583)  # Location
-    app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")  # Sticker
+        # Send messages to yourself:
+        app.send_message("me", "Hi!")  # Text message
+        app.send_location("me", 51.500729, -0.124583)  # Location
+        app.send_sticker("me", "CAADBAADyg4AAvLQYAEYD4F7vcZ43AI")  # Sticker
 
-Finally, when done, simply stop the client:
+#.  Finally, when done, simply stop the client:
 
-.. code-block:: python
+    .. code-block:: python
 
-    app.stop()
+        app.stop()
 
 Context Manager
 ---------------
diff --git a/docs/source/start/updates.rst b/docs/source/start/updates.rst
@@ -45,36 +45,37 @@ arrives:
 
     app.run()
 
-Let's examine these four new pieces. First one: a callback function we defined which accepts two arguments -
-*(client, message)*. This will be the function that gets executed every time a new message arrives and Pyrogram will
-call that function by passing the client instance and the new message instance as argument.
+#.  Let's examine these four new pieces. First one: a callback function we defined which accepts two arguments -
+    *(client, message)*. This will be the function that gets executed every time a new message arrives and Pyrogram will
+    call that function by passing the client instance and the new message instance as argument.
 
-.. code-block:: python
+    .. code-block:: python
 
-    def my_function(client, message):
-        print(message)
+        def my_function(client, message):
+            print(message)
 
-Second one: the :class:`~pyrogram.MessageHandler`. This object tells Pyrogram the function we defined above must only
-handle updates that are in form of a :class:`~pyrogram.Message`:
+#.  Second one: the :class:`~pyrogram.MessageHandler`. This object tells Pyrogram the function we defined above must
+    only handle updates that are in form of a :class:`~pyrogram.Message`:
 
-.. code-block:: python
+    .. code-block:: python
 
-    my_handler = MessageHandler(my_function)
+        my_handler = MessageHandler(my_function)
 
-Third: the method :meth:`~pyrogram.Client.add_handler`. This method is used to actually register the handler and let
-Pyrogram know it needs to be taken into consideration when new updates arrive and the internal dispatching phase begins.
+#.  Third: the method :meth:`~pyrogram.Client.add_handler`. This method is used to actually register the handler and let
+    Pyrogram know it needs to be taken into consideration when new updates arrive and the internal dispatching phase
+    begins.
 
-.. code-block:: python
+    .. code-block:: python
 
-    app.add_handler(my_handler)
+        app.add_handler(my_handler)
 
-Last one, the :meth:`~pyrogram.Client.run` method. What this does is simply call :meth:`~pyrogram.Client.start` and a
-special method :meth:`~pyrogram.Client.idle` that keeps your main scripts alive until you press ``CTRL+C``; the client
-will be automatically stopped after that.
+#.  Last one, the :meth:`~pyrogram.Client.run` method. What this does is simply call :meth:`~pyrogram.Client.start` and
+    a special method :meth:`~pyrogram.Client.idle` that keeps your main scripts alive until you press ``CTRL+C``; the
+    client will be automatically stopped after that.
 
-.. code-block:: python
+    .. code-block:: python
 
-    app.run()
+        app.run()
 
 Using Decorators
 ----------------
diff --git a/docs/source/topics/create-filters.rst b/docs/source/topics/create-filters.rst
@@ -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!")
diff --git a/docs/source/topics/debugging.rst b/docs/source/topics/debugging.rst
diff --git a/docs/source/topics/use-filters.rst b/docs/source/topics/use-filters.rst
