Merge branch 'develop' into asyncio

# Conflicts:
#	pyrogram/__init__.py

docs/sitemap.py

@@ -27,6 +27,7 @@ dirs = {
     "start": ("weekly", 0.9),
     "api": ("weekly", 0.8),
     "topics": ("weekly", 0.8),
+    "releases": ("weekly", 0.8),
     "telegram": ("weekly", 0.6)
 }
 

docs/source/topics/advanced-usage.rst

@@ -103,9 +103,9 @@ sending messages with IDs only thanks to cached access hashes.
 There are three different InputPeer types, one for each kind of Telegram entity.
 Whenever an InputPeer is needed you must pass one of these:
 
-    - :class:`~pyrogram.api.types.InputPeerUser` - Users
+- :class:`~pyrogram.api.types.InputPeerUser` - Users
-    - :class:`~pyrogram.api.types.InputPeerChat` -  Basic Chats
+- :class:`~pyrogram.api.types.InputPeerChat` -  Basic Chats
-    - :class:`~pyrogram.api.types.InputPeerChannel` - Either Channels or Supergroups
+- :class:`~pyrogram.api.types.InputPeerChannel` - Either Channels or Supergroups
 
 But you don't necessarily have to manually instantiate each object because, luckily for you, Pyrogram already provides
 :meth:`~pyrogram.Client.resolve_peer` as a convenience utility method that returns the correct InputPeer
@@ -120,9 +120,9 @@ kind of ID.
 
 For example, given the ID *123456789*, here's how Pyrogram can tell entities apart:
 
-    - ``+ID`` User: *123456789*
+- ``+ID`` User: *123456789*
-    - ``-ID`` Chat: *-123456789*
+- ``-ID`` Chat: *-123456789*
-    - ``-100ID`` Channel or Supergroup: *-100123456789*
+- ``-100ID`` Channel or Supergroup: *-100123456789*
 
 So, every time you take a raw ID, make sure to translate it into the correct ID when you want to use it with an
 high-level method.

docs/source/topics/config-file.rst

@@ -1,14 +1,14 @@
 Configuration File
 ==================
 
-As already mentioned in previous sections, Pyrogram can be configured by the use of an INI file.
+As already mentioned in previous pages, Pyrogram can be configured by the use of an INI file.
-This page explains how this file is structured in Pyrogram, how to use it and why.
+This page explains how this file is structured, how to use it and why.
 
 Introduction
 ------------
 
 The idea behind using a configuration file is to help keeping your code free of private settings information such as
-the API Key and Proxy without having you to even deal with how to load such settings. The configuration file, usually
+the API Key and Proxy, without having you to even deal with how to load such settings. The configuration file, usually
 referred as ``config.ini`` file, is automatically loaded from the root of your working directory; all you need to do is
 fill in the necessary parts.
 

docs/source/topics/create-filters.rst

@@ -13,9 +13,10 @@ 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
+:class:`~pyrogram.CallbackQueryHandler`. Note that callback queries updates are only received by bots as result of a
-:doc:`authorize your bot <../start/auth>`, then send a message with an inline keyboard to yourself. This allows you to
+user pressing an inline button attached to the bot's message; create and :doc:`authorize your bot <../start/auth>`,
-test your filter by pressing the inline button:
+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
 
@@ -25,7 +26,7 @@ test your filter by pressing the inline button:
         "username",  # Change this to your username or id
         "Pyrogram's custom filter test",
         reply_markup=InlineKeyboardMarkup(
-            [[InlineKeyboardButton("Press me", b"pyrogram")]]
+            [[InlineKeyboardButton("Press me", "pyrogram")]]
         )
     )
 
@@ -36,13 +37,13 @@ For this basic filter we will be using only the first two parameters of :meth:`~
 
 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"``.
+equals to ``"Pyrogram"``.
 
 .. code-block:: python
 
     static_data = Filters.create(
         name="StaticdData",
-        func=lambda flt, callback_query: callback_query.data == b"Pyrogram"
+        func=lambda flt, query: query.data == "Pyrogram"
     )
 
 The ``lambda`` operator in python is used to create small anonymous functions and is perfect for this example, the same
@@ -50,8 +51,8 @@ could be achieved with a normal function, but we don't really need it as it make
 
 .. code-block:: python
 
-    def func(flt, callback_query):
+    def func(flt, query):
-        return callback_query.data == b"Pyrogram"
+        return query.data == "Pyrogram"
 
     static_data = Filters.create(
         name="StaticData",
@@ -63,8 +64,8 @@ The filter usage remains the same:
 .. code-block:: python
 
     @app.on_callback_query(static_data)
-    def pyrogram_data(client, callback_query):
+    def pyrogram_data(_, query):
-        client.answer_callback_query(callback_query.id, "it works!")
+        query.answer("it works!")
 
 Filters with Arguments
 ----------------------
@@ -79,14 +80,14 @@ This is how a dynamic custom filter looks like:
     def dynamic_data(data):
         return Filters.create(
             name="DynamicData",
-            func=lambda flt, callback_query: flt.data == callback_query.data,
+            func=lambda flt, query: flt.data == query.data,
-            data=data  # "data" kwarg is accessed with "filter.data"
+            data=data  # "data" kwarg is accessed with "flt.data"
         )
 
 And its usage:
 
 .. code-block:: python
 
-    @app.on_callback_query(dynamic_data(b"Pyrogram"))
+    @app.on_callback_query(dynamic_data("Pyrogram"))
-    def pyrogram_data(client, callback_query):
+    def pyrogram_data(_, query):
-        client.answer_callback_query(callback_query.id, "it works!")
+        query.answer("it works!")

docs/source/topics/more-on-updates.rst

@@ -29,7 +29,7 @@ For example, take these two handlers:
         print("Just Text")
 
 Here, ``just_text`` is never executed because ``text_or_sticker``, which has been registered first, already handles
-texts (``Filters.text`` is shared and conflicting). To enable it, register the function using a different group:
+texts (``Filters.text`` is shared and conflicting). To enable it, register the handler using a different group:
 
 .. code-block:: python
 
@@ -37,7 +37,7 @@ texts (``Filters.text`` is shared and conflicting). To enable it, register the f
     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``):
+Or, if you want ``just_text`` to be executed *before* ``text_or_sticker`` (note ``-1``, which is less than ``0``):
 
 .. code-block:: python
 

docs/source/topics/use-filters.rst

@@ -25,7 +25,8 @@ Let's start right away with a simple example:
         def my_handler(client, message):
             print(message)
 
--   or, without decorators. Here filters are passed as the second argument of the handler constructor:
+-   or, without decorators. Here filters are passed as the second argument of the handler constructor; the first is the
+    callback function itself:
 
     .. code-block:: python
         :emphasize-lines: 8

pyrogram/__init__.py

@@ -24,7 +24,7 @@ if sys.version_info[:3] in [(3, 5, 0), (3, 5, 1), (3, 5, 2)]:
     # Monkey patch the standard "typing" module because Python versions from 3.5.0 to 3.5.2 have a broken one.
     sys.modules["typing"] = typing
 
-__version__ = "0.13.0-asyncio"
+__version__ = "0.14.0-asyncio"
 __license__ = "GNU Lesser General Public License v3 or later (LGPLv3+)"
 __copyright__ = "Copyright (C) 2017-2019 Dan <https://github.com/delivrance>"
 

pyrogram/client/methods/decorators/on_callback_query.py

@@ -32,10 +32,11 @@ class OnCallbackQuery(BaseClient):
     ) -> callable:
         """Decorator for handling callback queries.
 
-        This does the same thing as :meth:`~Client.add_handler` using the :obj:`CallbackQueryHandler`.
+        This does the same thing as :meth:`~pyrogram.Client.add_handler` using the
+        :obj:`~pyrogram.CallbackQueryHandler`.
 
         Parameters:
-            filters (:obj:`Filters`):
+            filters (:obj:`~pyrogram.Filters`, *optional*):
                 Pass one or more filters to allow only a subset of callback queries to be passed
                 in your function.
 

pyrogram/client/methods/decorators/on_deleted_messages.py

@@ -32,10 +32,11 @@ class OnDeletedMessages(BaseClient):
     ) -> callable:
         """Decorator for handling deleted messages.
 
-        This does the same thing as :meth:`~Client.add_handler` using the :obj:`DeletedMessagesHandler`.
+        This does the same thing as :meth:`~pyrogram.Client.add_handler` using the
+        :obj:`~pyrogram.DeletedMessagesHandler`.
 
         Parameters:
-            filters (:obj:`Filters`):
+            filters (:obj:`~pyrogram.Filters`, *optional*):
                 Pass one or more filters to allow only a subset of messages to be passed
                 in your function.
 

pyrogram/client/methods/decorators/on_disconnect.py

@@ -25,7 +25,7 @@ class OnDisconnect(BaseClient):
     def on_disconnect(self=None) -> callable:
         """Decorator for handling disconnections.
 
-        This does the same thing as :meth:`~Client.add_handler` using the :obj:`DisconnectHandler`.
+        This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.DisconnectHandler`.
         """
 
         def decorator(func: callable) -> Handler:

pyrogram/client/methods/decorators/on_inline_query.py

@@ -32,10 +32,10 @@ class OnInlineQuery(BaseClient):
     ) -> callable:
         """Decorator for handling inline queries.
 
-        This does the same thing as :meth:`~Client.add_handler` using the :obj:`InlineQueryHandler`.
+        This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.InlineQueryHandler`.
 
         Parameters:
-            filters (:obj:`Filters <pyrogram.Filters>`):
+            filters (:obj:`~pyrogram.Filters`, *optional*):
                 Pass one or more filters to allow only a subset of inline queries to be passed
                 in your function.
 

pyrogram/client/methods/decorators/on_message.py

@@ -32,10 +32,10 @@ class OnMessage(BaseClient):
     ) -> callable:
         """Decorator for handling messages.
 
-        This does the same thing as :meth:`~Client.add_handler` using the :obj:`MessageHandler`.
+        This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.MessageHandler`.
 
         Parameters:
-            filters (:obj:`Filters`):
+            filters (:obj:`~pyrogram.Filters`, *optional*):
                 Pass one or more filters to allow only a subset of messages to be passed
                 in your function.
 

pyrogram/client/methods/decorators/on_poll.py

@@ -32,10 +32,10 @@ class OnPoll(BaseClient):
     ) -> callable:
         """Decorator for handling poll updates.
 
-        This does the same thing as :meth:`~Client.add_handler` using the :obj:`PollHandler`.
+        This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.PollHandler`.
 
         Parameters:
-            filters (:obj:`Filters`):
+            filters (:obj:`~pyrogram.Filters`, *optional*):
                 Pass one or more filters to allow only a subset of polls to be passed
                 in your function.
 

pyrogram/client/methods/decorators/on_raw_update.py

@@ -30,7 +30,7 @@ class OnRawUpdate(BaseClient):
     ) -> callable:
         """Decorator for handling raw updates.
 
-        This does the same thing as :meth:`~Client.add_handler` using the :obj:`RawUpdateHandler`.
+        This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.RawUpdateHandler`.
 
         Parameters:
             group (``int``, *optional*):

pyrogram/client/methods/decorators/on_user_status.py

@@ -31,10 +31,10 @@ class OnUserStatus(BaseClient):
         group: int = 0
     ) -> callable:
         """Decorator for handling user status updates.
-        This does the same thing as :meth:`~Client.add_handler` using the :obj:`UserStatusHandler`.
+        This does the same thing as :meth:`~pyrogram.Client.add_handler` using the :obj:`~pyrogram.UserStatusHandler`.
 
         Parameters:
-            filters (:obj:`Filters`):
+            filters (:obj:`~pyrogram.Filters`, *optional*):
                 Pass one or more filters to allow only a subset of UserStatus updated to be passed in your function.
 
             group (``int``, *optional*):