Some fixes to the documentation

delivrance · delivrance · commit 70d5f22e0deb · 2022-04-24T11:56:07.000+02:00
diff --git a/docs/Makefile b/docs/Makefile
@@ -21,4 +21,4 @@ help:
 
 lhtml: # live html
 	sphinx-autobuild --host $(shell ifconfig | grep "inet " | grep -v 127.0.0.1 | cut -d\  -f2) \
-	    --watch ../pyrogram -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
+	    --watch ../pyrogram --watch resources -b html "$(SOURCEDIR)" "$(BUILDDIR)/html" $(SPHINXOPTS)
diff --git a/docs/source/intro/quickstart.rst b/docs/source/intro/quickstart.rst
@@ -50,7 +50,7 @@ Enjoy the API
 That was just a quick overview. In the next few pages of the introduction, we'll take a much more in-depth look of what
 we have just done above.
 
-If you are feeling eager to continue you can take a shortcut to :doc:`Calling Methods <../start/invoking>` and come back
+If you are feeling eager to continue you can take a shortcut to :doc:`Invoking Methods <../start/invoking>` and come back
 later to learn some more details.
 
 .. _community: https://t.me/Pyrogram
diff --git a/docs/source/start/auth.rst b/docs/source/start/auth.rst
@@ -82,8 +82,8 @@ after the session name, which will be ``my_bot.session`` for the example below.
 
 .. note::
 
-    The API key (api_id and api_hash) and the bot_token is not needed anymore after a successful authorization.
-    This means you can now simply use:
+    The API key (api_id and api_hash) and the bot_token are not required anymore after a successful authorization.
+    This means you can now simply use the following:
 
     .. code-block:: python
 
diff --git a/docs/source/start/errors.rst b/docs/source/start/errors.rst
@@ -25,7 +25,7 @@ This error is raised every time a method call against Telegram's API was unsucce
 
     from pyrogram.errors import RPCError
 
-.. note::
+.. warning::
 
     Avoid catching this error everywhere, especially when no feedback is given (i.e. by logging/printing the full error
     traceback), because it makes it impossible to understand what went wrong.
@@ -81,9 +81,6 @@ In case Pyrogram does not know anything about a specific error yet, it raises a
 for example, an unknown error with error code ``400``, will be raised as a ``BadRequest``. This way you can catch the
 whole category of errors and be sure to also handle these unknown errors.
 
-In case a whole class of errors is unknown (that is, an error code that is unknown), Pyrogram will raise a special
-``520 UnknownError`` exception.
-
 Errors with Values
 ------------------
 
diff --git a/docs/source/start/updates.rst b/docs/source/start/updates.rst
@@ -14,7 +14,7 @@ and how to handle new incoming messages or other events in Pyrogram.
 Defining Updates
 ----------------
 
-As hinted already, updates are events that happen in your Telegram account (incoming messages, new members join,
+Updates are events that happen in your Telegram account (incoming messages, new members join,
 bot button presses, etc.), which are meant to notify you about a new specific state that has changed. These updates are
 handled by registering one or more callback functions in your app using :doc:`Handlers <../api/handlers>`.
 
diff --git a/docs/source/topics/advanced-usage.rst b/docs/source/topics/advanced-usage.rst
@@ -50,8 +50,8 @@ Here's some examples:
         from pyrogram import Client
         from pyrogram.raw import functions
 
-        with Client("my_account") as app:
-            app.send(
+        async with Client("my_account") as app:
+            await app.send(
                 functions.account.UpdateProfile(
                     first_name="First Name", last_name="Last Name",
                     about="New bio text"
@@ -65,12 +65,12 @@ Here's some examples:
         from pyrogram import Client
         from pyrogram.raw import functions, types
 
-        with Client("my_account") as app:
+        async with Client("my_account") as app:
             # Set online status
-            app.send(functions.account.UpdateStatus(offline=False))
+            await app.send(functions.account.UpdateStatus(offline=False))
 
             # Set offline status
-            app.send(functions.account.UpdateStatus(offline=True))
+            await app.send(functions.account.UpdateStatus(offline=True))
 
 -   Get chat info:
 
@@ -79,8 +79,8 @@ Here's some examples:
         from pyrogram import Client
         from pyrogram.raw import functions, types
 
-        with Client("my_account") as app:
-            r = app.send(
+        async with Client("my_account") as app:
+            r = await app.send(
                 functions.channels.GetFullChannel(
                     channel=app.resolve_peer("username")
                 )
diff --git a/docs/source/topics/client-settings.rst b/docs/source/topics/client-settings.rst
@@ -18,16 +18,7 @@ settings. By default you will see something like the following:
 Set Custom Values
 -----------------
 
-To set custom values, you can either make use of the ``config.ini`` file, this way:
-
-.. code-block:: ini
-
-    [pyrogram]
-    app_version = 1.2.3
-    device_model = PC
-    system_version = Linux
-
-Or, pass the arguments directly in the Client's constructor.
+To set custom values, you can pass the arguments directly in the Client's constructor.
 
 .. code-block:: python
 
@@ -47,11 +38,6 @@ English).
 
 With the following code we make Telegram know we want it to speak in Italian (it):
 
-.. code-block:: ini
-
-    [pyrogram]
-    lang_code = it
-
 .. code-block:: python
 
     app = Client(
diff --git a/docs/source/topics/create-filters.rst b/docs/source/topics/create-filters.rst
@@ -25,7 +25,7 @@ button:
 
     from pyrogram.types import InlineKeyboardMarkup, InlineKeyboardButton
 
-    app.send_message(
+    await app.send_message(
         "username",  # Change this to your username or id
         "Pyrogram custom filter test",
         reply_markup=InlineKeyboardMarkup(
@@ -48,40 +48,20 @@ queries containing "pyrogram" as data:
 
     from pyrogram import filters
 
-    static_data_filter = filters.create(lambda _, __, query: query.data == "pyrogram")
-
-The first two arguments of the callback function are unused here and because of this we named them using underscores.
-
-The ``lambda`` operator in python is used to create small anonymous functions and is perfect for this example. The same
-can 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
-
-    from pyrogram import filters
-
-    def func(_, __, query):
+    async def func(_, __, query):
         return query.data == "pyrogram"
 
     static_data_filter = filters.create(func)
 
-Asynchronous filters are also possible. Sadly, Python itself doesn't have an ``async lambda``, so we are left with
-using a named function:
-
-.. code-block:: python
-
-    from pyrogram import filters
-
-    async def func(_, __, query):
-        return query.data == "pyrogram"
 
-    static_data_filter = filters.create(func)
+The first two arguments of the callback function are unused here and because of this we named them using underscores.
 
 Finally, the filter usage remains the same:
 
 .. code-block:: python
 
     @app.on_callback_query(static_data_filter)
-    def pyrogram_data(_, query):
+    async def pyrogram_data(_, query):
         query.answer("it works!")
 
 Filters with Arguments
@@ -94,18 +74,6 @@ via named arguments.
 
 This is how a dynamic custom filter looks like:
 
-.. code-block:: python
-
-    from pyrogram import filters
-
-    def dynamic_data_filter(data):
-        return filters.create(
-            lambda flt, _, query: flt.data == query.data,
-            data=data  # "data" kwarg is accessed with "flt.data" above
-        )
-
-And its asynchronous variant:
-
 .. code-block:: python
 
     from pyrogram import filters
@@ -122,7 +90,7 @@ And finally its usage:
 .. code-block:: python
 
     @app.on_callback_query(dynamic_data_filter("pyrogram"))
-    def pyrogram_data(_, query):
+    async def pyrogram_data(_, query):
         query.answer("it works!")
 
 
@@ -133,16 +101,6 @@ The missing piece we haven't covered yet is the second argument of a filter call
 argument. This is a reference to the :obj:`~pyrogram.Client` instance that is running the filter and it is useful in
 case you would like to make some API calls before deciding whether the filter should allow the update or not:
 
-.. code-block:: python
-
-    def func(_, client, query):
-        # r = client.some_api_method()
-        # check response "r" and decide to return True or False
-        ...
-
-Asynchronous filters making API calls work fine as well. Just remember that you need to put ``async`` in front of
-function definitions and ``await`` in front of method calls:
-
 .. code-block:: python
 
     async def func(_, client, query):
diff --git a/docs/source/topics/debugging.rst b/docs/source/topics/debugging.rst
@@ -27,7 +27,7 @@ Consider the following code:
 
 .. code-block:: python
 
-    me = app.get_users("me")
+    me = await app.get_users("me")
     print(me)  # User
 
 This will show a JSON representation of the object returned by :meth:`~pyrogram.Client.get_users`, which is a
diff --git a/docs/source/topics/more-on-updates.rst b/docs/source/topics/more-on-updates.rst
@@ -26,12 +26,12 @@ For example, take these two handlers:
 .. code-block:: python
 
     @app.on_message(filters.text | filters.sticker)
-    def text_or_sticker(client, message):
+    async def text_or_sticker(client, message):
         print("Text or Sticker")
 
 
     @app.on_message(filters.text)
-    def just_text(client, message):
+    async def just_text(client, message):
         print("Just Text")
 
 Here, ``just_text`` is never executed because ``text_or_sticker``, which has been registered first, already handles
@@ -40,15 +40,15 @@ texts (``filters.text`` is shared and conflicting). To enable it, register the h
 .. code-block:: python
 
     @app.on_message(filters.text, group=1)
-    def just_text(client, message):
+    async def just_text(client, message):
         print("Just Text")
 
 Or, if you want ``just_text`` to be executed *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):
+    async def just_text(client, message):
         print("Just Text")
 
 With :meth:`~pyrogram.Client.add_handler` (without decorators) the same can be achieved with:
@@ -68,17 +68,17 @@ continue to propagate the same update to the next groups until all the handlers
 .. code-block:: python
 
     @app.on_message(filters.private)
-    def _(client, message):
+    async def _(client, message):
         print(0)
 
 
     @app.on_message(filters.private, group=1)
-    def _(client, message):
+    async def _(client, message):
         raise Exception("Unhandled exception!")  # Simulate an unhandled exception
 
 
     @app.on_message(filters.private, group=2)
-    def _(client, message):
+    async def _(client, message):
         print(2)
 
 All these handlers will handle the same kind of messages, that are, messages sent or received in private chats.
@@ -110,18 +110,18 @@ Example with ``stop_propagation()``:
 .. code-block:: python
 
     @app.on_message(filters.private)
-    def _(client, message):
+    async def _(client, message):
         print(0)
 
 
     @app.on_message(filters.private, group=1)
-    def _(client, message):
+    async def _(client, message):
         print(1)
         message.stop_propagation()
 
 
     @app.on_message(filters.private, group=2)
-    def _(client, message):
+    async def _(client, message):
         print(2)
 
 Example with ``raise StopPropagation``:
@@ -131,18 +131,18 @@ Example with ``raise StopPropagation``:
     from pyrogram import StopPropagation
 
     @app.on_message(filters.private)
-    def _(client, message):
+    async def _(client, message):
         print(0)
 
 
     @app.on_message(filters.private, group=1)
-    def _(client, message):
+    async ef _(client, message):
         print(1)
         raise StopPropagation
 
 
     @app.on_message(filters.private, group=2)
-    def _(client, message):
+    async def _(client, message):
         print(2)
 
 Each handler is registered in a different group, but the handler in group number 2 will never be executed because the
@@ -178,19 +178,19 @@ Example with ``continue_propagation()``:
 .. code-block:: python
 
     @app.on_message(filters.private)
-    def _(client, message):
+    async def _(client, message):
         print(0)
         message.continue_propagation()
 
 
     @app.on_message(filters.private)
-    def _(client, message):
+    async def _(client, message):
         print(1)
         message.continue_propagation()
 
 
     @app.on_message(filters.private)
-    def _(client, message):
+    async def _(client, message):
         print(2)
 
 Example with ``raise ContinuePropagation``:
@@ -200,19 +200,19 @@ Example with ``raise ContinuePropagation``:
     from pyrogram import ContinuePropagation
 
     @app.on_message(filters.private)
-    def _(client, message):
+    async def _(client, message):
         print(0)
         raise ContinuePropagation
 
 
     @app.on_message(filters.private)
-    def _(client, message):
+    async def _(client, message):
         print(1)
         raise ContinuePropagation
 
 
     @app.on_message(filters.private)
-    def _(client, message):
+    async def _(client, message):
         print(2)
 
 Three handlers are registered in the same group, and all of them will be executed because the propagation was continued
diff --git a/docs/source/topics/serializing.rst b/docs/source/topics/serializing.rst
@@ -21,8 +21,8 @@ If you want a nicely formatted, human readable JSON representation of any object
 
     ...
 
-    with app:
-        r = app.get_chat("me")
+    async with app:
+        r = await app.get_chat("me")
         print(str(r))
 
 .. tip::
@@ -44,8 +44,8 @@ as the process requires the package to be in scope.
 
     ...
 
-    with app:
-        r = app.get_chat("me")
+    async with app:
+        r = await app.get_chat("me")
 
         print(repr(r))
         print(eval(repr(r)) == r)  # True
diff --git a/docs/source/topics/smart-plugins.rst b/docs/source/topics/smart-plugins.rst
diff --git a/docs/source/topics/test-servers.rst b/docs/source/topics/test-servers.rst
diff --git a/docs/source/topics/text-formatting.rst b/docs/source/topics/text-formatting.rst
diff --git a/docs/source/topics/use-filters.rst b/docs/source/topics/use-filters.rst
