Reword some method return type docstrings

docs/source/api/handlers.rst

@@ -38,26 +38,10 @@ it.
     RawUpdateHandler
 
 .. autoclass:: MessageHandler()
-    :members:
-
 .. autoclass:: DeletedMessagesHandler()
-    :members:
-
 .. autoclass:: CallbackQueryHandler()
-    :members:
-
 .. autoclass:: InlineQueryHandler()
-    :members:
-
 .. autoclass:: UserStatusHandler()
-    :members:
-
 .. autoclass:: PollHandler()
-    :members:
-
 .. autoclass:: DisconnectHandler()
-    :members:
-
 .. autoclass:: RawUpdateHandler()
-    :members:
-

docs/source/api/methods.rst

@@ -90,7 +90,6 @@ Chats
     pin_chat_message
     unpin_chat_message
     get_chat
-    get_chat_preview
     get_chat_member
     get_chat_members
     get_chat_members_count
@@ -217,7 +216,6 @@ Bots
 .. automethod:: pyrogram.Client.pin_chat_message()
 .. automethod:: pyrogram.Client.unpin_chat_message()
 .. automethod:: pyrogram.Client.get_chat()
-.. automethod:: pyrogram.Client.get_chat_preview()
 .. automethod:: pyrogram.Client.get_chat_member()
 .. automethod:: pyrogram.Client.get_chat_members()
 .. automethod:: pyrogram.Client.get_chat_members_count()

docs/source/api/types.rst

@@ -72,6 +72,7 @@ Keyboards
     ForceReply
     CallbackQuery
     GameHighScore
+    GameHighScores
     CallbackGame
 
 Input Media
@@ -155,6 +156,7 @@ InputMessageContent
 .. autoclass:: ForceReply()
 .. autoclass:: CallbackQuery()
 .. autoclass:: GameHighScore()
+.. autoclass:: GameHighScores()
 .. autoclass:: CallbackGame()
 
 ..  Input Media

docs/source/index.rst

@@ -17,7 +17,7 @@ Welcome to Pyrogram
             GitHub
         </a>
         •
-        <a href="https://t.me/PyrogramChat">
+        <a href="https://t.me/Pyrogram">
             Community
         </a>
 

docs/source/intro/start.rst

@@ -44,5 +44,5 @@ In the next few pages of the introduction, we'll take a much more in-depth look
 
 Feeling eager to continue? You can take a shortcut to `Calling Methods`_ and come back later to learn some more details.
 
-.. _community: //t.me/pyrogramchat
+.. _community: //t.me/Pyrogram
 .. _Calling Methods: ../start/invoking

docs/source/topics/advanced-usage.rst

@@ -130,4 +130,4 @@ high-level method.
 .. _plenty of them: ../api/methods
 .. _raw functions: ../telegram/functions
 .. _raw types: ../telegram/types
-.. _Community: https://t.me/PyrogramChat
+.. _Community: https://t.me/Pyrogram

pyrogram/client/methods/bots/answer_inline_query.py

@@ -73,7 +73,7 @@ class AnswerInlineQuery(BaseClient):
                 where they wanted to use the bot's inline capabilities.
 
         Returns:
-            ``bool``: On success, True is returned.
+            ``bool``: True, on success.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/bots/send_inline_bot_result.py

@@ -58,7 +58,7 @@ class SendInlineBotResult(BaseClient):
                 Sends the message with *via @bot* hidden.
 
         Returns:
-            On success, the sent Message is returned.
+            :obj:`Message`: On success, the sent inline result message is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/bots/set_game_score.py

@@ -32,7 +32,7 @@ class SetGameScore(BaseClient):
         disable_edit_message: bool = None,
         chat_id: Union[int, str] = None,
         message_id: int = None
-    ):
+    ) -> Union["pyrogram.Message", bool]:
         # inline_message_id: str = None):  TODO Add inline_message_id
         """Set the score of the specified user in a game.
 
@@ -63,8 +63,8 @@ class SetGameScore(BaseClient):
                 Required if inline_message_id is not specified.
 
         Returns:
-            On success, if the message was sent by the bot, returns the edited :obj:`Message`,
+            :obj:`Message` | ``bool``: On success, if the message was sent by the bot, the edited message is returned,
-            otherwise returns True.
+            True otherwise.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/chats/get_chat_members_count.py

@@ -34,7 +34,7 @@ class GetChatMembersCount(BaseClient):
                 Unique identifier (int) or username (str) of the target chat.
 
         Returns:
-            On success, an integer is returned.
+            ``int``: On success, the chat members count is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/chats/get_dialogs_count.py

@@ -29,7 +29,7 @@ class GetDialogsCount(BaseClient):
             Defaults to False.
 
         Returns:
-            ``int``: On success, an integer is returned.
+            ``int``: On success, the dialogs count is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/chats/kick_chat_member.py

@@ -54,9 +54,8 @@ class KickChatMember(BaseClient):
                 considered to be banned forever. Defaults to 0 (ban forever).
 
         Returns:
-            :obj:`Message`: On success, a service message will be returned (when applicable).
+            :obj:`Message` | ``bool``: On success, a service message will be returned (when applicable), otherwise, in
-
+            case a message object couldn't be returned, True is returned.
-            ``bool`` -- True, in case a message object couldn't be returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/contacts/get_contacts.py

@@ -30,6 +30,7 @@ log = logging.getLogger(__name__)
 
 class GetContacts(BaseClient):
     def get_contacts(self) -> List["pyrogram.User"]:
+        # TODO: Create a Users object and return that
         """Get contacts from your Telegram address book.
 
         Returns:

pyrogram/client/methods/contacts/get_contacts_count.py

@@ -25,7 +25,7 @@ class GetContactsCount(BaseClient):
         """Get the total count of contacts from your Telegram address book.
 
         Returns:
-            ``int``: On success, an integer is returned.
+            ``int``: On success, the contacts count is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/download_media.py

@@ -73,9 +73,8 @@ class DownloadMedia(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            ``str``: On success, the absolute path of the downloaded file is returned.
+            ``str`` | ``None``: On success, the absolute path of the downloaded file is returned, otherwise, in case
-
+            the download failed or was deliberately stopped with :meth:`stop_transmission`, None is returned.
-            ``None`` --  In case the download is deliberately stopped with :meth:`stop_transmission`.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/edit_message_reply_markup.py

@@ -45,9 +45,8 @@ class EditMessageReplyMarkup(BaseClient):
                 An InlineKeyboardMarkup object.
 
         Returns:
-            :obj:`Message`: In case the edited message is sent by the bot.
+            :obj:`Message` | ``bool``: In case the edited message is sent by the bot, the edited message is returned,
-
+            otherwise, True is returned in case the edited message is send by the user.
-            ``bool`` -- True, in case the edited message is sent by the user.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/forward_messages.py

@@ -64,11 +64,9 @@ class ForwardMessages(BaseClient):
                 Defaults to False.
 
         Returns:
-            :obj:`Message`: In case *message_ids* was an integer, the single forwarded message is
+            :obj:`Message` | :obj:`Messages`: In case *message_ids* was an integer, the single forwarded message is
-            returned.
+            returned, otherwise, in case *message_ids* was an iterable, the returned value will be an object containing
-
+            a list of messages, even if such iterable contained just a single element.
-            :obj:`Messages` -- In case *message_ids* was an iterable, the returned value will be an
-            object containing a list of messages, even if such iterable contained just a single element.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/get_history_count.py

@@ -45,7 +45,7 @@ class GetHistoryCount(BaseClient):
                 Unique identifier (int) or username (str) of the target chat.
 
         Returns:
-            ``int``: On success, an integer is returned.
+            ``int``: On success, the chat history count is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/get_messages.py

@@ -60,11 +60,9 @@ class GetMessages(BaseClient):
                 Defaults to 1.
 
         Returns:
-            :obj:`Message`: In case *message_ids* was an integer, the single forwarded message is
+            :obj:`Message` | :obj:`Messages`: In case *message_ids* was an integer, the single requested message is
-            returned.
+            returned, otherwise, in case *message_ids* was an iterable, the returned value will be an object containing
-
+            a list of messages, even if such iterable contained just a single element.
-            :obj:`Messages` -- In case *message_ids* was an iterable, the returned value will be an
-            object containing a list of messages, even if such iterable contained just a single element.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/send_animation.py

@@ -120,9 +120,8 @@ class SendAnimation(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent animation message is returned.
+            :obj:`Message` | ``None``: On success, the sent animation message is returned, otherwise, in case the upload
-
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/send_audio.py

@@ -122,9 +122,8 @@ class SendAudio(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent audio message is returned.
+            :obj:`Message` | ``None``: On success, the sent audio message is returned, otherwise, in case the upload
-
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/send_document.py

@@ -108,9 +108,8 @@ class SendDocument(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent document message is returned.
+            :obj:`Message` | ``None``: On success, the sent document message is returned, otherwise, in case the upload
-
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/send_photo.py

@@ -107,9 +107,8 @@ class SendPhoto(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent photo message is returned.
+            :obj:`Message` | ``None``: On success, the sent photo message is returned, otherwise, in case the upload
-
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/send_sticker.py

@@ -92,10 +92,8 @@ class SendSticker(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent sticker message is returned.
+            :obj:`Message` | ``None``: On success, the sent sticker message is returned, otherwise, in case the upload
-
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
-
         Raises:
             RPCError: In case of a Telegram RPC error.
         """

pyrogram/client/methods/messages/send_video.py

@@ -124,9 +124,8 @@ class SendVideo(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent video message is returned.
+            :obj:`Message` | ``None``: On success, the sent video message is returned, otherwise, in case the upload
-
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/send_video_note.py

@@ -107,9 +107,8 @@ class SendVideoNote(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent video note message is returned.
+            :obj:`Message` | ``None``: On success, the sent video note message is returned, otherwise, in case the
-
+            pload is deliberately stopped with :meth:`stop_transmission`, None is returned.
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/messages/send_voice.py

@@ -105,9 +105,8 @@ class SendVoice(BaseClient):
                 You can either keep *\*args* or add every single extra argument in your function signature.
 
         Returns:
-            :obj:`Message`: On success, the sent voice message is returned.
+            :obj:`Message` | ``None``: On success, the sent voice message is returned, otherwise, in case the upload
-
+            is deliberately stopped with :meth:`stop_transmission`, None is returned.
-            ``None`` -- In case the upload is deliberately stopped with :meth:`stop_transmission`.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/users/get_user_profile_photos_count.py

@@ -33,7 +33,7 @@ class GetUserProfilePhotosCount(BaseClient):
                 For a contact that exists in your Telegram address book you can use his phone number (str).
 
         Returns:
-            ``int``: On success, an integer is returned.
+            ``int``: On success, the user profile photos count is returned.
 
         Raises:
             RPCError: In case of a Telegram RPC error.

pyrogram/client/methods/users/get_users.py

@@ -24,6 +24,7 @@ from ...ext import BaseClient
 
 
 class GetUsers(BaseClient):
+    # TODO: Add Users type and use that
     def get_users(
         self,
         user_ids: Union[Iterable[Union[int, str]], int, str]
@@ -38,9 +39,9 @@ class GetUsers(BaseClient):
                 Iterators and Generators are also accepted.
 
         Returns:
-            :obj:`User`: In case *user_ids* was an integer or string.
+            :obj:`User` | List of :obj:`User`: In case *user_ids* was an integer or string the single requested user is
-
+            returned, otherwise, in case *user_ids* was an iterable a list of users is returned, even if the iterable
-            List of :obj:`User` -- In case *user_ids* was an iterable, even if the iterable contained one item only.
+            contained one item only.
 
         Raises:
             RPCError: In case of a Telegram RPC error.