Merge branch 'develop' into asyncio

# Conflicts:
#	pyrogram/client/client.py
#	pyrogram/client/methods/messages/send_animation.py
#	pyrogram/client/methods/messages/send_audio.py
#	pyrogram/client/methods/messages/send_document.py
#	pyrogram/client/methods/messages/send_photo.py
#	pyrogram/client/methods/messages/send_sticker.py
#	pyrogram/client/methods/messages/send_video.py
#	pyrogram/client/methods/messages/send_video_note.py
#	pyrogram/client/methods/messages/send_voice.py
#	pyrogram/client/types/messages_and_media/message.py

docs/source/pyrogram/Client.rst

@@ -21,6 +21,7 @@ Utilities
     send
     resolve_peer
     save_file
+    stop_transmission
 
 Decorators
 ----------

pyrogram/client/client.py

@@ -466,6 +466,12 @@ class Client(Methods, BaseClient):
         else:
             self.dispatcher.remove_handler(handler, group)
 
+    def stop_transmission(self):
+        """Use this method to stop downloading or uploading a file.
+        Must be called inside a progress callback function.
+        """
+        raise Client.StopTransmission
+
     async def authorize_bot(self):
         try:
             r = await self.send(
@@ -1376,6 +1382,8 @@ class Client(Methods, BaseClient):
 
                     if progress:
                         await progress(self, min(file_part * part_size, file_size), file_size, *progress_args)
+        except Client.StopTransmission:
+            raise
         except Exception as e:
             log.error(e, exc_info=True)
         else:
@@ -1584,6 +1592,7 @@ class Client(Methods, BaseClient):
                 except Exception as e:
                     raise e
         except Exception as e:
+            if not isinstance(e, Client.StopTransmission):
                 log.error(e, exc_info=True)
 
             try:

pyrogram/client/ext/base_client.py

@@ -26,6 +26,9 @@ from ...session.internals import MsgId
 
 
 class BaseClient:
+    class StopTransmission(StopIteration):
+        pass
+
     APP_VERSION = "Pyrogram \U0001f525 {}".format(__version__)
 
     DEVICE_MODEL = "{} {}".format(

pyrogram/client/methods/messages/download_media.py

@@ -72,6 +72,7 @@ class DownloadMedia(BaseClient):
 
         Returns:
             On success, the absolute path of the downloaded file as string is returned, None otherwise.
+            In case the download is deliberately stopped with :meth:`stop_transmission`, None is returned as well.
 
         Raises:
             :class:`Error <pyrogram.Error>` in case of a Telegram RPC error.

pyrogram/client/methods/messages/send_animation.py

@@ -45,7 +45,7 @@ class SendAnimation(BaseClient):
                                                  "pyrogram.ReplyKeyboardRemove",
                                                  "pyrogram.ForceReply"] = None,
                              progress: callable = None,
-                             progress_args: tuple = ()) -> "pyrogram.Message":
+                             progress_args: tuple = ()) -> Union["pyrogram.Message", None]:
         """Use this method to send animation files (animation or H.264/MPEG-4 AVC video without sound).
 
         Args:
@@ -119,6 +119,7 @@ class SendAnimation(BaseClient):
 
         Returns:
             On success, the sent :obj:`Message <pyrogram.Message>` is returned.
+            In case the upload is deliberately stopped with :meth:`stop_transmission`, None is returned instead.
 
         Raises:
             :class:`Error <pyrogram.Error>` in case of a Telegram RPC error.
@@ -126,6 +127,7 @@ class SendAnimation(BaseClient):
         file = None
         style = self.html if parse_mode.lower() == "html" else self.markdown
 
+        try:
             if os.path.exists(animation):
                 thumb = None if thumb is None else await self.save_file(thumb)
                 file = await self.save_file(animation, progress=progress, progress_args=progress_args)
@@ -195,3 +197,5 @@ class SendAnimation(BaseClient):
                             {i.id: i for i in r.users},
                             {i.id: i for i in r.chats}
                         )
+        except BaseClient.StopTransmission:
+            return None

pyrogram/client/methods/messages/send_audio.py

@@ -44,7 +44,7 @@ class SendAudio(BaseClient):
                                              "pyrogram.ReplyKeyboardRemove",
                                              "pyrogram.ForceReply"] = None,
                          progress: callable = None,
-                         progress_args: tuple = ()) -> "pyrogram.Message":
+                         progress_args: tuple = ()) -> Union["pyrogram.Message", None]:
         """Use this method to send audio files.
 
         For sending voice messages, use the :obj:`send_voice()` method instead.
@@ -120,6 +120,7 @@ class SendAudio(BaseClient):
 
         Returns:
             On success, the sent :obj:`Message <pyrogram.Message>` is returned.
+            In case the upload is deliberately stopped with :meth:`stop_transmission`, None is returned instead.
 
         Raises:
             :class:`Error <pyrogram.Error>` in case of a Telegram RPC error.
@@ -127,6 +128,7 @@ class SendAudio(BaseClient):
         file = None
         style = self.html if parse_mode.lower() == "html" else self.markdown
 
+        try:
             if os.path.exists(audio):
                 thumb = None if thumb is None else self.save_file(thumb)
                 file = await self.save_file(audio, progress=progress, progress_args=progress_args)
@@ -194,3 +196,5 @@ class SendAudio(BaseClient):
                             {i.id: i for i in r.users},
                             {i.id: i for i in r.chats}
                         )
+        except BaseClient.StopTransmission:
+            return None

pyrogram/client/methods/messages/send_document.py

@@ -41,7 +41,7 @@ class SendDocument(BaseClient):
                                                 "pyrogram.ReplyKeyboardRemove",
                                                 "pyrogram.ForceReply"] = None,
                             progress: callable = None,
-                            progress_args: tuple = ()) -> "pyrogram.Message":
+                            progress_args: tuple = ()) -> Union["pyrogram.Message", None]:
         """Use this method to send general files.
 
         Args:
@@ -106,6 +106,7 @@ class SendDocument(BaseClient):
 
         Returns:
             On success, the sent :obj:`Message <pyrogram.Message>` is returned.
+            In case the upload is deliberately stopped with :meth:`stop_transmission`, None is returned instead.
 
         Raises:
             :class:`Error <pyrogram.Error>` in case of a Telegram RPC error.
@@ -113,6 +114,7 @@ class SendDocument(BaseClient):
         file = None
         style = self.html if parse_mode.lower() == "html" else self.markdown
 
+        try:
             if os.path.exists(document):
                 thumb = None if thumb is None else await self.save_file(thumb)
                 file = await self.save_file(document, progress=progress, progress_args=progress_args)
@@ -175,3 +177,5 @@ class SendDocument(BaseClient):
                             {i.id: i for i in r.users},
                             {i.id: i for i in r.chats}
                         )
+        except BaseClient.StopTransmission:
+            return None

pyrogram/client/methods/messages/send_photo.py

@@ -41,7 +41,7 @@ class SendPhoto(BaseClient):
                                              "pyrogram.ReplyKeyboardRemove",
                                              "pyrogram.ForceReply"] = None,
                          progress: callable = None,
-                         progress_args: tuple = ()) -> "pyrogram.Message":
+                         progress_args: tuple = ()) -> Union["pyrogram.Message", None]:
         """Use this method to send photos.
 
         Args:
@@ -105,6 +105,7 @@ class SendPhoto(BaseClient):
 
         Returns:
             On success, the sent :obj:`Message <pyrogram.Message>` is returned.
+            In case the upload is deliberately stopped with :meth:`stop_transmission`, None is returned instead.
 
         Raises:
             :class:`Error <pyrogram.Error>` in case of a Telegram RPC error.
@@ -112,6 +113,7 @@ class SendPhoto(BaseClient):
         file = None
         style = self.html if parse_mode.lower() == "html" else self.markdown
 
+        try:
             if os.path.exists(photo):
                 file = await self.save_file(photo, progress=progress, progress_args=progress_args)
                 media = types.InputMediaUploadedPhoto(
@@ -171,3 +173,5 @@ class SendPhoto(BaseClient):
                             {i.id: i for i in r.users},
                             {i.id: i for i in r.chats}
                         )
+        except BaseClient.StopTransmission:
+            return None

pyrogram/client/methods/messages/send_sticker.py

@@ -38,7 +38,7 @@ class SendSticker(BaseClient):
                                                "pyrogram.ReplyKeyboardRemove",
                                                "pyrogram.ForceReply"] = None,
                            progress: callable = None,
-                           progress_args: tuple = ()) -> "pyrogram.Message":
+                           progress_args: tuple = ()) -> Union["pyrogram.Message", None]:
         """Use this method to send .webp stickers.
 
         Args:
@@ -89,12 +89,14 @@ class SendSticker(BaseClient):
 
         Returns:
             On success, the sent :obj:`Message <pyrogram.Message>` is returned.
+            In case the upload is deliberately stopped with :meth:`stop_transmission`, None is returned instead.
 
         Raises:
             :class:`Error <pyrogram.Error>` in case of a Telegram RPC error.
         """
         file = None
 
+        try:
             if os.path.exists(sticker):
                 file = await self.save_file(sticker, progress=progress, progress_args=progress_args)
                 media = types.InputMediaUploadedDocument(
@@ -155,3 +157,5 @@ class SendSticker(BaseClient):
                             {i.id: i for i in r.users},
                             {i.id: i for i in r.chats}
                         )
+        except BaseClient.StopTransmission:
+            return None

pyrogram/client/methods/messages/send_video.py

@@ -46,7 +46,7 @@ class SendVideo(BaseClient):
                                              "pyrogram.ReplyKeyboardRemove",
                                              "pyrogram.ForceReply"] = None,
                          progress: callable = None,
-                         progress_args: tuple = ()) -> "pyrogram.Message":
+                         progress_args: tuple = ()) -> Union["pyrogram.Message", None]:
         """Use this method to send video files.
 
         Args:
@@ -123,6 +123,7 @@ class SendVideo(BaseClient):
 
         Returns:
             On success, the sent :obj:`Message <pyrogram.Message>` is returned.
+            In case the upload is deliberately stopped with :meth:`stop_transmission`, None is returned instead.
 
         Raises:
             :class:`Error <pyrogram.Error>` in case of a Telegram RPC error.
@@ -130,6 +131,7 @@ class SendVideo(BaseClient):
         file = None
         style = self.html if parse_mode.lower() == "html" else self.markdown
 
+        try:
             if os.path.exists(video):
                 thumb = None if thumb is None else self.save_file(thumb)
                 file = await self.save_file(video, progress=progress, progress_args=progress_args)
@@ -198,3 +200,5 @@ class SendVideo(BaseClient):
                             {i.id: i for i in r.users},
                             {i.id: i for i in r.chats}
                         )
+        except BaseClient.StopTransmission:
+            return None

pyrogram/client/methods/messages/send_video_note.py

@@ -41,7 +41,7 @@ class SendVideoNote(BaseClient):
                                                   "pyrogram.ReplyKeyboardRemove",
                                                   "pyrogram.ForceReply"] = None,
                               progress: callable = None,
-                              progress_args: tuple = ()) -> "pyrogram.Message":
+                              progress_args: tuple = ()) -> Union["pyrogram.Message", None]:
         """Use this method to send video messages.
 
         Args:
@@ -104,12 +104,14 @@ class SendVideoNote(BaseClient):
 
         Returns:
             On success, the sent :obj:`Message <pyrogram.Message>` is returned.
+            In case the upload is deliberately stopped with :meth:`stop_transmission`, None is returned instead.
 
         Raises:
             :class:`Error <pyrogram.Error>` in case of a Telegram RPC error.
         """
         file = None
 
+        try:
             if os.path.exists(video_note):
                 thumb = None if thumb is None else await self.save_file(thumb)
                 file = await self.save_file(video_note, progress=progress, progress_args=progress_args)
@@ -173,3 +175,5 @@ class SendVideoNote(BaseClient):
                             {i.id: i for i in r.users},
                             {i.id: i for i in r.chats}
                         )
+        except BaseClient.StopTransmission:
+            return None

pyrogram/client/methods/messages/send_voice.py

@@ -42,7 +42,7 @@ class SendVoice(BaseClient):
                                              "pyrogram.ReplyKeyboardRemove",
                                              "pyrogram.ForceReply"] = None,
                          progress: callable = None,
-                         progress_args: tuple = ()) -> "pyrogram.Message":
+                         progress_args: tuple = ()) -> Union["pyrogram.Message", None]:
         """Use this method to send audio files.
 
         Args:
@@ -104,6 +104,7 @@ class SendVoice(BaseClient):
 
         Returns:
             On success, the sent :obj:`Message <pyrogram.Message>` is returned.
+            In case the upload is deliberately stopped with :meth:`stop_transmission`, None is returned instead.
 
         Raises:
             :class:`Error <pyrogram.Error>` in case of a Telegram RPC error.
@@ -111,6 +112,7 @@ class SendVoice(BaseClient):
         file = None
         style = self.html if parse_mode.lower() == "html" else self.markdown
 
+        try:
             if os.path.exists(voice):
                 file = await self.save_file(voice, progress=progress, progress_args=progress_args)
                 media = types.InputMediaUploadedDocument(
@@ -174,3 +176,5 @@ class SendVoice(BaseClient):
                             {i.id: i for i in r.users},
                             {i.id: i for i in r.chats}
                         )
+        except BaseClient.StopTransmission:
+            return None

pyrogram/client/types/messages_and_media/message.py

@@ -916,7 +916,7 @@ class Message(PyrogramType, Update):
                        file_name: str = "",
                        block: bool = True,
                        progress: callable = None,
-                       progress_args: tuple = None):
+                       progress_args: tuple = ()):
         """Bound method *download* of :obj:`Message <pyrogram.Message>`.
 
         Use as a shortcut for: