Update Docs

docs/source/pyrogram/index.rst

@@ -1,11 +1,10 @@
 Pyrogram
 ========
 
-In this section you can find a detailed description of the Pyrogram API.
+In this section you can find a detailed description of the Pyrogram package and its high-level API.
 
-:class:`Client <pyrogram.Client>` is the main class you have to deal with.
+:class:`Client <pyrogram.Client>` is the main class. It exposes easy-to-use methods that are named
-You will notice that methods are named after the well established `Telegram Bot API`_ and that most of them accept
+after the `Telegram Bot API`_ methods, thus offering a familiar look to Bot developers.
-the same parameters as well, thus offering a familiar look to Bot developers.
 
 .. toctree::
     Client

docs/source/resources/TextFormatting.rst

@@ -9,7 +9,7 @@ Markdown Style
 --------------
 
 To use this mode, pass :obj:`MARKDOWN <pyrogram.ParseMode.MARKDOWN>` or "markdown" in the *parse_mode* field when using
-:obj:`send_message <pyrogram.Client.send_message>`. Use the following syntax in your message:
+:obj:`send_message() <pyrogram.Client.send_message>`. Use the following syntax in your message:
 
 .. code::
 
@@ -31,7 +31,7 @@ HTML Style
 ----------
 
 To use this mode, pass :obj:`HTML <pyrogram.ParseMode.HTML>` or "html" in the *parse_mode* field when using
-:obj:`send_message <pyrogram.Client.send_message>`. The following tags are currently supported:
+:obj:`send_message() <pyrogram.Client.send_message>`. The following tags are currently supported:
 
 .. code::
 

docs/source/resources/UpdateHandling.rst

@@ -1,41 +1,118 @@
 Update Handling
 ===============
 
-Updates are events that happen in your Telegram account (incoming messages, new channel posts, user name changes, ...)
+Updates are handled by registering one or more callback functions with an Handler.
-and can be handled by using a callback function, that is, a function called every time an ``Update`` is received from
+There are multiple Handlers to choose from, one for each kind of update.
-Telegram.
 
-To set an update handler simply call :meth:`set_update_handler <pyrogram.Client.set_update_handler>`
+Registering an Handler
-by passing the name of your defined callback function as argument *before* you start the Client.
+----------------------
 
-Here's a complete example on how to set it up:
+We shall examine the :obj:`MessageHandler <pyrogram.MessageHandler>`, which will be in charge for handling
+:obj:`Message <pyrogram.api.types.pyrogram.Message>` objects.
+
+The easiest and nicest way to register a MessageHandler is by decorating your function with the
+:meth:`on_message() <pyrogram.Client.on_message>` decorator. Here's a full example that prints out the content
+of a message as soon as it arrives.
 
 .. code-block:: python
 
     from pyrogram import Client
 
+    app = Client("my_account")
 
-    def update_handler(client, update, users, chats):
-        print(update)
 
-    def main():
+    @app.on_message()
-        client = Client(session_name="example")
+    def my_handler(client, message):
-        client.set_update_handler(update_handler)
+        print(message)
 
-        client.start()
-        client.idle()
 
-    if __name__ == "__main__":
+    app.start()
-        main()
+    app.idle()
 
-The last line of the main function, :meth:`client.idle() <pyrogram.Client.idle>`, is not strictly necessary but highly
+Alternatively, if you prefer not to use decorators, there is an alternative way for registering Handlers.
-recommended when using the update handler; it will block your script execution until you press ``CTRL+C`` and
+This is useful, for example, if you want to keep your callback functions in a separate file.
-automatically call the :meth:`stop <pyrogram.Client.stop>` method which stops the Client and gently close the underlying
-connection.
 
-Examples
+.. code-block:: python
---------
 
-- `Simple Echo <https://github.com/pyrogram/pyrogram/blob/master/examples/simple_echo.py>`_
+    from pyrogram import Client, MessageHandler
-- `Advanced Echo <https://github.com/pyrogram/pyrogram/blob/master/examples/advanced_echo.py>`_
+
-- `Advanced Echo 2 <https://github.com/pyrogram/pyrogram/blob/master/examples/advanced_echo2.py>`_
+    def my_handler(client, message):
+        print(message)
+
+    app = Client("my_account")
+
+    app.add_handler(MessageHandler(my_handler))
+
+    app.start()
+    app.idle()
+
+Using Filters
+-------------
+
+For a finer grained control over what kind of messages will be allowed or not, you can use
+:class:`Filters <pyrogram.Filters>`. The next example will show you how to handler only messages
+containing an :obj:`Audio <pyrogram.api.types.pyrogram.Audio>` object:
+
+.. code-block:: python
+
+    from pyrogram import Filters
+
+    @app.on_message(Filters.audio)
+    def my_handler(client, message):
+        print(message)
+
+or, without decorators:
+
+.. code-block:: python
+
+    from pyrogram import Filters, Messagehandler
+
+    def my_handler(client, message):
+        print(message)
+
+    app.add_handler(MessageHandler(my_handler, Filters.audio))
+
+Advanced Filters
+----------------
+
+Filters can also be used in a more advanced way by combining more filters together using bitwise operators:
+
+-   Use ``~`` to invert a filter (behaves like the ``not`` operator).
+-   Use ``&`` and ``|`` to merge two filters (``and``, ``or`` operators respectively).
+
+Here are some examples:
+
+-   Message is a **text** message **and** is **not edited**.
+
+    .. code-block:: python
+
+        @app.on_message(Filters.text & ~Filters.edited)
+        def my_handler(client, message):
+            print(message)
+
+-   Message is a **sticker** **and** was sent in a **channel** or in a **private** chat.
+
+    .. code-block:: python
+
+        @app.on_message(Filters.sticker & (Filters.channel | Filters.private))
+        def my_handler(client, message):
+            print(message)
+
+Some filters can also accept parameters, like :obj:`command <pyrogram.Filters.command>` or
+:obj:`regex <pyrogram.Filters.regex>`:
+
+-   Message is either a /start or /help **command**.
+
+    .. code-block:: python
+
+        @app.on_message(Filters.command(["start", "help"]))
+        def my_handler(client, message):
+            print(message)
+
+-   Message is a **text** message matching the given regex pattern.
+
+    .. code-block:: python
+
+        @app.on_message(Filters.regex("pyrogram"))
+        def my_handler(client, message):
+            print(message)

docs/source/start/BasicUsage.rst

@@ -9,9 +9,9 @@ Basic Usage
 Simple API Access
 -----------------
 
-The easiest way to interact with the API is via the :class:`Client <pyrogram.Client>` class which exposes bot-like_
+The easiest way to interact with the Telegram API is via the :class:`Client <pyrogram.Client>` class,
-methods. The purpose of this Client class is to make it even simpler to work with Telegram's API by abstracting the
+which exposes bot-like_ methods. The purpose of this Client class is to make it even simpler to work with the
-raw functions listed in the API scheme.
+API by abstracting the raw functions listed in the scheme.
 
 The result is a much cleaner interface that allows you to:
 
@@ -25,10 +25,13 @@ The result is a much cleaner interface that allows you to:
 
     .. code-block:: python
 
-        client.send_message(
+        client.send_message("me", "Hi there! I'm using Pyrogram")
-            chat_id="me",
+
-            text="Hi there! I'm using Pyrogram"
+-   Upload a photo (with caption):
-        )
+
+    .. code-block:: python
+
+        client.send_photo("me", "/home/dan/perla.jpg", "Cute!")
 
 .. seealso:: For a complete list of the available methods have a look at the :class:`Client <pyrogram.Client>` class.
 
@@ -39,7 +42,7 @@ Using Raw Functions
 
 If you want **complete**, low-level access to the Telegram API you have to use the raw
 :mod:`functions <pyrogram.api.functions>` and :mod:`types <pyrogram.api.types>` exposed by the ``pyrogram.api``
-package and call any Telegram API method you wish using the :meth:`send <pyrogram.Client.send>` method provided by
+package and call any Telegram API method you wish using the :meth:`send() <pyrogram.Client.send>` method provided by
 the Client class.
 
 Here some examples:

docs/source/start/ProjectSetup.rst

@@ -8,7 +8,7 @@ API Keys
 --------
 
 The very first step requires you to obtain a valid Telegram API key.
-If you already have one you can skip this, otherwise:
+If you already have one you can skip this step, otherwise:
 
 #. Visit https://my.telegram.org/apps and log in with your Telegram Account.
 #. Fill out the form to register a new Telegram application.
@@ -31,8 +31,8 @@ There are two ways to configure a Pyrogram application project, and you can choo
         api_id = 12345
         api_hash = 0123456789abcdef0123456789abcdef
 
--  Alternatively, you can pass your API key to Pyrogram by simply using the *api_key* parameter of the Client class.
+-  Alternatively, you can pass your API key to Pyrogram by simply using the *api_id* and *api_hash*
-   This way you can have full control on how to store and load your credentials:
+   parameters of the Client class. This way you can have full control on how to store and load your credentials:
 
     .. code-block:: python
 
@@ -40,25 +40,26 @@ There are two ways to configure a Pyrogram application project, and you can choo
 
         client = Client(
             session_name="example",
-            api_key=(12345, "0123456789abcdef0123456789abcdef")
+            api_id=12345
+            api_hash="0123456789abcdef0123456789abcdef"
         )
 
-.. note:: The examples below will assume you have created a *config.ini* file, thus they won't show the *api_key*
+.. note:: The examples below assume you have created a ``config.ini`` file, thus they won't show the *api_id*
-   parameter usage in the :class:`Client <pyrogram.Client>` class.
+    and *api_hash* parameters usage.
 
-Authorization
+User Authorization
--------------
+------------------
 
-Telegram requires that users be authorized in order to use the API.
+In order to use the API, Telegram requires that Users be authorized via their phone numbers.
 Pyrogram automatically manages this access, all you need to do is create an instance of
 the :class:`Client <pyrogram.Client>` class by passing to it a ``<session_name>`` of your choice
-and call the :meth:`start <pyrogram.Client.start>` method:
+(e.g.: "my_account") and call the :meth:`start <pyrogram.Client.start>` method:
 
 .. code-block:: python
 
     from pyrogram import Client
 
-    client = Client(session_name="example")
+    client = Client("my_account")
     client.start()
 
 This starts an interactive shell asking you to input your **phone number** (including your `Country Code`_)
@@ -70,15 +71,26 @@ and the **phone code** you will receive:
     Is "+39**********" correct? (y/n): y
     Enter phone code: 32768
 
-After successfully authorizing yourself, a new file called ``example.session`` will be created allowing
+After successfully authorizing yourself, a new file called ``my_account.session`` will be created allowing
-Pyrogram executing API calls with your identity.
+Pyrogram executing API calls with your identity. This file will be loaded again when you restart your app,
+and as long as you keep the session alive, Pyrogram won't ask you again to enter your phone number.
 
 .. important:: Your *.session file(s) must be kept secret.
 
-.. note::
+Bot Authorization
+-----------------
 
-    The authorization process is executed only once.
+Being written entirely from the ground up, Pyrogram is also able to authorize Bots.
-    However, the code above is always required; as long as a valid session file exists,
+This means that you can use Pyrogram to execute API calls with a Bot identity.
-    Pyrogram will use that and won't ask you to enter your phone number again when you restart your script.
+Instead of phone numbers, Bots are authorized via their tokens which are created by BotFather_:
 
-.. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes
+.. code-block:: python
+
+    from pyrogram import Client
+
+    client = Client("123456:ABC-DEF1234ghIkl-zyx57W2v1u123ew11")
+    client.start()
+
+
+.. _`Country Code`: https://en.wikipedia.org/wiki/List_of_country_calling_codes
+.. _BotFather: https://t.me/botfather

docs/source/start/QuickInstallation.rst

@@ -7,6 +7,12 @@ The most straightforward and recommended way to install or upgrade Pyrogram is b
 
     $ pip3 install --upgrade pyrogram
 
+or, with TgCrypto_ (recommended):
+
+.. code-block:: bash
+
+    $ pip3 install --upgrade pyrogram[tgcrypto]
+
 Bleeding Edge
 -------------
 

pyrogram/client/chat_action.py

@@ -21,7 +21,7 @@ from pyrogram.api import types
 
 class ChatAction:
     """This class provides a convenient access to all Chat Actions available.
-    It is intended to be used with :obj:`pyrogram.Client.send_chat_action`.
+    Chat Actions are intended to be used with :meth:`send_chat_action() <pyrogram.Client.send_chat_action>`.
     """
 
     CANCEL = types.SendMessageCancelAction

pyrogram/client/filters/filters.py

@@ -29,8 +29,8 @@ def build(name: str, func: callable, **kwargs) -> type:
 
 
 class Filters:
-    """This class provides access to all the Filters available in Pyrogram.
+    """This class provides access to all Filters available in Pyrogram.
-    It is intended to be used when adding an handler."""
+    Filters are intended to be used with the :obj:`MessageHandler <pyrogram.MessageHandler>`."""
 
     text = build("Text", lambda _, m: bool(m.text and not m.text.startswith("/")))
     """Filter text messages."""
@@ -48,34 +48,34 @@ class Filters:
     """Filter edited messages."""
 
     audio = build("Audio", lambda _, m: bool(m.audio))
-    """Filter messages that contain an :obj:`Audio <pyrogram.Audio>`."""
+    """Filter messages that contain :obj:`Audio <pyrogram.api.types.pyrogram.Audio>` objects."""
 
     document = build("Document", lambda _, m: bool(m.document))
-    """Filter messages that contain a :obj:`Document <pyrogram.Document>`."""
+    """Filter messages that contain :obj:`Document <pyrogram.api.types.pyrogram.Document>` objects."""
 
     photo = build("Photo", lambda _, m: bool(m.photo))
-    """Filter messages that contain a :obj:`Photo <pyrogram.Photo>`."""
+    """Filter messages that contain :obj:`Photo <pyrogram.api.types.pyrogram.PhotoSize>` objects."""
 
     sticker = build("Sticker", lambda _, m: bool(m.sticker))
-    """Filter messages that contain a :obj:`Sticker <pyrogram.Sticker>`."""
+    """Filter messages that contain :obj:`Sticker <pyrogram.api.types.pyrogram.Sticker>` objects."""
 
     video = build("Video", lambda _, m: bool(m.video))
-    """Filter messages that contain a :obj:`Video <pyrogram.Video>`."""
+    """Filter messages that contain :obj:`Video <pyrogram.api.types.pyrogram.Video>` objects."""
 
     voice = build("Voice", lambda _, m: bool(m.voice))
-    """Filter messages that contain a :obj:`Voice <pyrogram.Voice>` note."""
+    """Filter messages that contain :obj:`Voice <pyrogram.api.types.pyrogram.Voice>` note objects."""
 
     video_note = build("Voice", lambda _, m: bool(m.video_note))
-    """Filter messages that contain a :obj:`VideoNote <pyrogram.VideoNote>`."""
+    """Filter messages that contain :obj:`VideoNote <pyrogram.api.types.pyrogram.VideoNote>` objects."""
 
     contact = build("Contact", lambda _, m: bool(m.contact))
-    """Filter messages that contain a :obj:`Contact <pyrogram.Contact>`."""
+    """Filter messages that contain :obj:`Contact <pyrogram.api.types.pyrogram.Contact>` objects."""
 
     location = build("Location", lambda _, m: bool(m.location))
-    """Filter messages that contain a :obj:`Location <pyrogram.Location>`."""
+    """Filter messages that contain :obj:`Location <pyrogram.api.types.pyrogram.Location>` objects."""
 
     venue = build("Venue", lambda _, m: bool(m.venue))
-    """Filter messages that contain a :obj:`Venue <pyrogram.Venue>`."""
+    """Filter messages that contain :obj:`Venue <pyrogram.api.types.pyrogram.Venue>` objects."""
 
     private = build("Private", lambda _, m: bool(m.chat.type == "private"))
     """Filter messages sent in private chats."""
@@ -166,6 +166,24 @@ class Filters:
             )
         )
 
+    service = build(
+        "Service",
+        lambda _, m: bool(
+            _.new_chat_members(m)
+            or _.left_chat_member(m)
+            or _.new_chat_title(m)
+            or _.new_chat_photo(m)
+            or _.delete_chat_photo(m)
+            or _.group_chat_created(m)
+            or _.supergroup_chat_created(m)
+            or _.channel_chat_created(m)
+            or _.migrate_to_chat_id(m)
+            or _.migrate_from_chat_id(m)
+            or _.pinned_m(m)
+        )
+    )
+    """Filter all service messages"""
+
     new_chat_members = build("NewChatMembers", lambda _, m: bool(m.new_chat_members))
     """Filter service messages for new chat members."""
 
@@ -198,21 +216,3 @@ class Filters:
 
     pinned_message = build("PinnedMessage", lambda _, m: bool(m.pinned_message))
     """Filter service messages for pinned messages."""
-
-    service = build(
-        "Service",
-        lambda _, m: bool(
-            _.new_chat_members(m)
-            or _.left_chat_member(m)
-            or _.new_chat_title(m)
-            or _.new_chat_photo(m)
-            or _.delete_chat_photo(m)
-            or _.group_chat_created(m)
-            or _.supergroup_chat_created(m)
-            or _.channel_chat_created(m)
-            or _.migrate_to_chat_id(m)
-            or _.migrate_from_chat_id(m)
-            or _.pinned_m(m)
-        )
-    )
-    """Filter all service messages"""

pyrogram/client/input_phone_contact.py

@@ -22,16 +22,16 @@ from pyrogram.session.internals import MsgId
 
 class InputPhoneContact:
     """This object represents a Phone Contact to be added in your Telegram address book.
-    It is intended to be used with :meth:`pyrogram.Client.add_contacts`
+    It is intended to be used with :meth:`add_contacts() <pyrogram.Client.add_contacts>`
 
     Args:
-        phone (:obj:`str`):
+        phone (``str``):
             Contact's phone number
 
-        first_name (:obj:`str`):
+        first_name (``str``):
             Contact's first name
 
-        last_name (:obj:`str`, optional):
+        last_name (``str``, optional):
             Contact's last name
     """
 

pyrogram/client/parse_mode.py

@@ -18,8 +18,8 @@
 
 
 class ParseMode:
-    """This class provides a convenient access to parse modes.
+    """This class provides a convenient access to Parse Modes.
-    It is intended to be used with any method that accepts the optional argument **parse_mode**
+    Parse Modes are intended to be used with any method that accepts the optional argument **parse_mode**.
     """
 
     HTML = "html"