Add examples to utility methods

delivrance · delivrance · commit 8f56610c2ca0 · 2019-07-25T11:17:28.000+02:00
diff --git a/pyrogram/client/client.py b/pyrogram/client/client.py
@@ -174,6 +174,17 @@ class Client(Methods, BaseClient):
             download_media, ...) are less prone to throw FloodWait exceptions.
             Only available for users, bots will ignore this parameter.
             Defaults to False (normal session).
+
+    Example:
+        .. code-block:: python
+
+            from pyrogram import Client
+
+            app = Client("my_account")
+
+            with app:
+                app.send_message("me", "Hi!")
+
     """
 
     terms_of_service_displayed = False
@@ -269,11 +280,28 @@ def proxy(self, value):
         self._proxy.update(value)
 
     def start(self):
-        """Start the Client.
+        """Start the client.
+
+        This method connects the client to Telegram and, in case of new sessions, automatically manages the full login
+        process using an interactive prompt (by default).
+
+        Has no parameters.
 
         Raises:
-            RPCError: In case of a Telegram RPC error.
-            ConnectionError: In case you try to start an already started Client.
+            ConnectionError: In case you try to start an already started client.
+
+        Example:
+            .. code-block:: python
+                :emphasize-lines: 4
+
+                from pyrogram import Client
+
+                app = Client("my_account")
+                app.start()
+
+                ...  # Call API methods
+
+                app.stop()
         """
         if self.is_started:
             raise ConnectionError("Client has already been started")
@@ -346,8 +374,25 @@ def start(self):
     def stop(self):
         """Stop the Client.
 
+        This method disconnects the client from Telegram and stops the underlying tasks.
+
+        Has no parameters.
+
         Raises:
-            ConnectionError: In case you try to stop an already stopped Client.
+            ConnectionError: In case you try to stop an already stopped client.
+
+        Example:
+            .. code-block:: python
+                :emphasize-lines: 8
+
+                from pyrogram import Client
+
+                app = Client("my_account")
+                app.start()
+
+                ...  # Call API methods
+
+                app.stop()
         """
         if not self.is_started:
             raise ConnectionError("Client is already stopped")
@@ -388,8 +433,30 @@ def stop(self):
     def restart(self):
         """Restart the Client.
 
+        This method will first call :meth:`~Client.stop` and then :meth:`~Client.start` in a row in order to restart
+        a client using a single method.
+
+        Has no parameters.
+
         Raises:
             ConnectionError: In case you try to restart a stopped Client.
+
+        Example:
+            .. code-block:: python
+                :emphasize-lines: 8
+
+                from pyrogram import Client
+
+                app = Client("my_account")
+                app.start()
+
+                ...  # Call API methods
+
+                app.restart()
+
+                ...  # Call other API methods
+
+                app.stop()
         """
         self.stop()
         self.start()
@@ -451,25 +518,40 @@ def signal_handler(*args):
             time.sleep(1)
 
     def run(self):
-        """Start the Client and automatically idle the main script.
+        """Start the client, idle the main script and finally stop the client.
+
+        This is a convenience method that calls :meth:`~Client.start`, :meth:`~Client.idle` and :meth:`~Client.stop` in
+        sequence. It makes running a client less verbose, but is not suitable in case you want to run more than one
+        client in a single main script, since idle() will block after starting the own client.
 
-        This is a convenience method that literally just calls :meth:`~Client.start` and :meth:`~Client.idle`. It makes
-        running a client less verbose, but is not suitable in case you want to run more than one client in a single main
-        script, since :meth:`~Client.idle` will block.
+        Has no parameters.
 
         Raises:
-            RPCError: In case of a Telegram RPC error.
+            ConnectionError: In case you try to run an already started client.
+
+        Example:
+            .. code-block:: python
+                :emphasize-lines: 7
+
+                from pyrogram import Client
+
+                app = Client("my_account")
+
+                ...  # Set handlers up
+
+                app.run()
         """
         self.start()
-        self.idle()
+        Client.idle()
         self.stop()
 
     def add_handler(self, handler: Handler, group: int = 0):
         """Register an update handler.
 
-        You can register multiple handlers, but at most one handler within a group
-        will be used for a single update. To handle the same update more than once, register
-        your handler using a different group id (lower group id == higher priority).
+        You can register multiple handlers, but at most one handler within a group will be used for a single update.
+        To handle the same update more than once, register your handler using a different group id (lower group id
+        == higher priority). This mechanism is explained in greater details at
+        :doc:`More on Updates <../../topics/more-on-updates>`.
 
         Parameters:
             handler (``Handler``):
@@ -479,7 +561,22 @@ def add_handler(self, handler: Handler, group: int = 0):
                 The group identifier, defaults to 0.
 
         Returns:
-            ``tuple``: A tuple consisting of (handler, group).
+            ``tuple``: A tuple consisting of *(handler, group)*.
+
+        Example:
+            .. code-block:: python
+                :emphasize-lines: 8
+
+                from pyrogram import Client, MessageHandler
+
+                def dump(client, message):
+                    print(message)
+
+                app = Client("my_account")
+
+                app.add_handler(MessageHandler(dump))
+
+                app.run()
         """
         if isinstance(handler, DisconnectHandler):
             self.disconnect_handler = handler.callback
@@ -491,16 +588,33 @@ def add_handler(self, handler: Handler, group: int = 0):
     def remove_handler(self, handler: Handler, group: int = 0):
         """Remove a previously-registered update handler.
 
-        Make sure to provide the right group that the handler was added in. You can use
-        the return value of the :meth:`~Client.add_handler` method, a tuple of (handler, group), and
-        pass it directly.
+        Make sure to provide the right group where the handler was added in. You can use the return value of the
+        :meth:`~Client.add_handler` method, a tuple of *(handler, group)*, and pass it directly.
 
         Parameters:
             handler (``Handler``):
                 The handler to be removed.
 
             group (``int``, *optional*):
                 The group identifier, defaults to 0.
+
+        Example:
+            .. code-block:: python
+                :emphasize-lines: 11
+
+                from pyrogram import Client, MessageHandler
+
+                def dump(client, message):
+                    print(message)
+
+                app = Client("my_account")
+
+                handler = app.add_handler(MessageHandler(dump))
+
+                # Starred expression to unpack (handler, group)
+                app.remove_handler(*handler)
+
+                app.run()
         """
         if isinstance(handler, DisconnectHandler):
             self.disconnect_handler = None
@@ -509,7 +623,28 @@ def remove_handler(self, handler: Handler, group: int = 0):
 
     def stop_transmission(self):
         """Stop downloading or uploading a file.
-        Must be called inside a progress callback function.
+
+        This method must be called inside a progress callback function in order to stop the transmission at the
+        desired time. The progress callback is called every time a file chunk is uploaded/downloaded.
+
+        Has no parameters.
+
+        Example:
+            .. code-block:: python
+                :emphasize-lines: 9
+
+                from pyrogram import Client
+
+                app = Client("my_account")
+
+                # Example to stop transmission once the upload progress reaches 50%
+                # Useless in practice, but shows how to stop on command
+                def progress(client, current, total):
+                    if (current * 100 / total) > 50:
+                        client.stop_transmission()
+
+                with app:
+                    app.send_document("me", "files.zip", progress=progress)
         """
         raise Client.StopTransmission
 
@@ -541,9 +676,9 @@ def export_session_string(self):
     def set_parse_mode(self, parse_mode: Union[str, None] = "combined"):
         """Set the parse mode to be used globally by the client.
 
-        When setting the parse mode with this method, all methods having a *parse_mode* parameter will follow the global
-        value by default. The default value *"combined"* enables both Markdown and HTML styles to be used and combined
-        together.
+        When setting the parse mode with this method, all other methods having a *parse_mode* parameter will follow the
+        global value by default. The default value *"combined"* enables both Markdown and HTML styles to be used and
+        combined together.
 
         Parameters:
             parse_mode (``str``):
@@ -1172,7 +1307,7 @@ def load_session(self):
         ])
 
         if session_empty:
-            self.storage.dc_id = 1
+            self.storage.dc_id = 4
             self.storage.date = 0
 
             self.storage.test_mode = self.test_mode
@@ -1445,23 +1580,22 @@ def save_file(
                 In case a file part expired, pass the file_id and the file_part to retry uploading that specific chunk.
 
             progress (``callable``, *optional*):
-                Pass a callback function to view the upload progress.
-                The function must take *(client, current, total, \*args)* as positional arguments (look at the section
-                below for a detailed description).
+                Pass a callback function to view the file transmission progress.
+                The function must take *(current, total)* as positional arguments (look at Other Parameters below for a
+                detailed description) and will be called back each time a new file chunk has been successfully
+                transmitted.
 
             progress_args (``tuple``, *optional*):
-                Extra custom arguments for the progress callback function. Useful, for example, if you want to pass
-                a chat_id and a message_id in order to edit a message with the updated progress.
+                Extra custom arguments for the progress callback function.
+                You can pass anything you need to be available in the progress callback scope; for example, a Message
+                object or a Client instance in order to edit the message with the updated progress status.
 
         Other Parameters:
-            client (:obj:`Client`):
-                The Client itself, useful when you want to call other API methods inside the callback function.
-
             current (``int``):
-                The amount of bytes uploaded so far.
+                The amount of bytes transmitted so far.
 
             total (``int``):
-                The size of the file.
+                The total size of the file.
 
             *args (``tuple``, *optional*):
                 Extra custom arguments as defined in the *progress_args* parameter.
@@ -1775,11 +1909,3 @@ def guess_extension(self, mime_type: str):
 
         if extensions:
             return extensions.split(" ")[0]
-
-    def export_session_string(self):
-        """Export the current session as serialized string.
-
-        Returns:
-            ``str``: The session serialized into a printable, url-safe string.
-        """
-        return self.storage.export_session_string()
