Clean up some more twirks on RTD and update docstrings

readthedocs/extra/basic/creating-a-client.rst

@@ -98,7 +98,7 @@ Two Factor Authorization (2FA)
 
 If you have Two Factor Authorization (from now on, 2FA) enabled on your
 account, calling :meth:`telethon.TelegramClient.sign_in` will raise a
-`SessionPasswordNeededError`. When this happens, just
+``SessionPasswordNeededError``. When this happens, just
 :meth:`telethon.TelegramClient.sign_in` again with a ``password=``:
 
     .. code-block:: python
@@ -113,7 +113,7 @@ account, calling :meth:`telethon.TelegramClient.sign_in` will raise a
             client.sign_in(password=getpass.getpass())
 
 
-If you don't have 2FA enabled, but you would like to do so through Telethon,
+If you don't have 2FA enabled, but you would like to do so through the library,
 take as example the following code snippet:
 
     .. code-block:: python
@@ -146,4 +146,4 @@ for the tip!
 
 
 __ https://github.com/Anorov/PySocks#installation
-__ https://github.com/Anorov/PySocks#usage-1%3E
+__ https://github.com/Anorov/PySocks#usage-1

readthedocs/extra/basic/entities.rst

@@ -34,22 +34,22 @@ you're able to just do this:
 
     .. code-block:: python
 
-        # dialogs are the "conversations you have open"
+        # Dialogs are the "conversations you have open".
-        # this method returns a list of Dialog, which
+        # This method returns a list of Dialog, which
-        # have the .entity attribute and other information.
+        # has the .entity attribute and other information.
         dialogs = client.get_dialogs(limit=200)
 
-        # all of these work and do the same
+        # All of these work and do the same.
         lonami = client.get_entity('lonami')
         lonami = client.get_entity('t.me/lonami')
         lonami = client.get_entity('https://telegram.dog/lonami')
 
-        # other kind of entities
+        # Other kind of entities.
         channel = client.get_entity('telegram.me/joinchat/AAAAAEkk2WdoDrB4-Q8-gg')
         contact = client.get_entity('+34xxxxxxxxx')
         friend  = client.get_entity(friend_id)
 
-        # using peers/input peers (note that the API may return these)
+        # Using Peer/InputPeer (note that the API may return these)
         # users, chats and channels may all have the same ID, so it's
         # necessary to wrap (at least) chat and channels inside Peer.
         from telethon.tl.types import PeerUser, PeerChat, PeerChannel
@@ -79,7 +79,7 @@ possible, making zero API calls most of the time. When a request is made,
 if you provided the full entity, e.g. an ``User``, the library will convert
 it to the required ``InputPeer`` automatically for you.
 
-**You should always favour ``.get_input_entity()``** over ``.get_entity()``
+**You should always favour** ``.get_input_entity()`` **over** ``.get_entity()``
 for this reason! Calling the latter will always make an API call to get
 the most recent information about said entity, but invoking requests don't
 need this information, just the ``InputPeer``. Only use ``.get_entity()``

readthedocs/extra/basic/getting-started.rst

@@ -50,8 +50,7 @@ Basic Usage
        client.send_file('username', '/home/myself/Pictures/holidays.jpg')
 
        client.download_profile_photo(me)
-       total, messages, senders = client.get_message_history('username')
+       messages = client.get_message_history('username')
        client.download_media(messages[0])
 
    **More details**: :ref:`telegram-client`
-

readthedocs/extra/basic/installation.rst

@@ -65,4 +65,3 @@ __ https://github.com/ricmoo/pyaes
 __ https://pypi.python.org/pypi/pyaes
 __ https://github.com/sybrenstuvel/python-rsa/
 __ https://pypi.python.org/pypi/rsa/3.4.2
-__ https://github.com/LonamiWebs/Telethon/issues/199

readthedocs/extra/developing/api-status.rst

@@ -34,7 +34,7 @@ instance through ``curl``. A JSON response will be returned.
 
     curl https://rpc.pwrtelegram.xyz/?for=messages.sendMessage
 
-**Number of ``RPC_CALL_FAIL``\ 's**:
+**Number of** ``RPC_CALL_FAIL``:
 
 .. code:: bash
 

readthedocs/extra/troubleshooting/rpc-errors.rst

@@ -7,8 +7,8 @@ RPC stands for Remote Procedure Call, and when Telethon raises an
 methods incorrectly (wrong parameters, wrong permissions, or even
 something went wrong on Telegram's server). The most common are:
 
--  ``FloodError`` (420), the same request was repeated many times. Must
+-  ``FloodWaitError`` (420), the same request was repeated many times.
-   wait ``.seconds``.
+   Must wait ``.seconds`` (you can access this parameter).
 -  ``SessionPasswordNeededError``, if you have setup two-steps
    verification on Telegram.
 -  ``CdnFileTamperedError``, if the media you were trying to download

readthedocs/extra/wall-of-shame.rst

@@ -1,3 +1,8 @@
+=============
+Wall of Shame
+=============
+
+
 This project has an
 `issues <https://github.com/LonamiWebs/Telethon/issues>`__ section for
 you to file **issues** whenever you encounter any when working with the

telethon/telegram_client.py

@@ -59,11 +59,66 @@ from .extensions import markdown
 
 
 class TelegramClient(TelegramBareClient):
-    """Full featured TelegramClient meant to extend the basic functionality -
+    """
+    Initializes the Telegram client with the specified API ID and Hash.
 
-       As opposed to the TelegramBareClient, this one  features downloading
+    Args:
-       media from different data centers, starting a second thread to
+        session (:obj:`str` | :obj:`Session` | :obj:`None`):
-       handle updates, and some very common functionality.
+            The file name of the session file to be used if a string is
+            given (it may be a full path), or the Session instance to be
+            used otherwise. If it's ``None``, the session will not be saved,
+            and you should call :meth:`.log_out()` when you're done.
+
+        api_id (:obj:`int` | :obj:`str`):
+            The API ID you obtained from https://my.telegram.org.
+
+        api_hash (:obj:`str`):
+            The API ID you obtained from https://my.telegram.org.
+
+        connection_mode (:obj:`ConnectionMode`, optional):
+            The connection mode to be used when creating a new connection
+            to the servers. Defaults to the ``TCP_FULL`` mode.
+            This will only affect how messages are sent over the network
+            and how much processing is required before sending them.
+
+        use_ipv6 (:obj:`bool`, optional):
+            Whether to connect to the servers through IPv6 or not.
+            By default this is ``False`` as IPv6 support is not
+            too widespread yet.
+
+        proxy (:obj:`tuple` | :obj:`dict`, optional):
+            A tuple consisting of ``(socks.SOCKS5, 'host', port)``.
+            See https://github.com/Anorov/PySocks#usage-1 for more.
+
+        update_workers (:obj:`int`, optional):
+            If specified, represents how many extra threads should
+            be spawned to handle incoming updates, and updates will
+            be kept in memory until they are processed. Note that
+            you must set this to at least ``0`` if you want to be
+            able to process updates through :meth:`updates.poll()`.
+
+        timeout (:obj:`int` | :obj:`float` | :obj:`timedelta`, optional):
+            The timeout to be used when receiving responses from
+            the network. Defaults to 5 seconds.
+
+        spawn_read_thread (:obj:`bool`, optional):
+            Whether to use an extra background thread or not. Defaults
+            to ``True`` so receiving items from the network happens
+            instantly, as soon as they arrive. Can still be disabled
+            if you want to run the library without any additional thread.
+
+    Kwargs:
+        Extra parameters will be forwarded to the ``Session`` file.
+        Most relevant parameters are:
+
+            .. code-block:: python
+
+                 device_model     = platform.node()
+                 system_version   = platform.system()
+                 app_version      = TelegramClient.__version__
+                 lang_code        = 'en'
+                 system_lang_code = lang_code
+                 report_errors    = True
     """
 
     # region Initialization
@@ -76,42 +131,6 @@ class TelegramClient(TelegramBareClient):
                  timeout=timedelta(seconds=5),
                  spawn_read_thread=True,
                  **kwargs):
-        """Initializes the Telegram client with the specified API ID and Hash.
-
-           Session can either be a `str` object (filename for the .session)
-           or it can be a `Session` instance (in which case list_sessions()
-           would probably not work). Pass 'None' for it to be a temporary
-           session - remember to '.log_out()'!
-
-           The 'connection_mode' should be any value under ConnectionMode.
-           This will only affect how messages are sent over the network
-           and how much processing is required before sending them.
-
-           The integer 'update_workers' represents depending on its value:
-             is None: Updates will *not* be stored in memory.
-             = 0: Another thread is responsible for calling self.updates.poll()
-             > 0: 'update_workers' background threads will be spawned, any
-                  any of them will invoke all the self.updates.handlers.
-
-           If 'spawn_read_thread', a background thread will be started once
-           an authorized user has been logged in to Telegram to read items
-           (such as updates and responses) from the network as soon as they
-           occur, which will speed things up.
-
-           If you don't want to spawn any additional threads, pending updates
-           will be read and processed accordingly after invoking a request
-           and not immediately. This is useful if you don't care about updates
-           at all and have set 'update_workers=None'.
-
-           If more named arguments are provided as **kwargs, they will be
-           used to update the Session instance. Most common settings are:
-             device_model     = platform.node()
-             system_version   = platform.system()
-             app_version      = TelegramClient.__version__
-             lang_code        = 'en'
-             system_lang_code = lang_code
-             report_errors    = True
-        """
         super().__init__(
             session, api_id, api_hash,
             connection_mode=connection_mode,
@@ -134,13 +153,17 @@ class TelegramClient(TelegramBareClient):
     # region Authorization requests
 
     def send_code_request(self, phone, force_sms=False):
-        """Sends a code request to the specified phone number.
+        """
+        Sends a code request to the specified phone number.
 
-        :param str | int phone:
+        Args:
-            The phone to which the code will be sent.
+            phone (:obj:`str` | :obj:`int`):
-        :param bool force_sms:
+                The phone to which the code will be sent.
-            Whether to force sending as SMS.
+
-        :return auth.SentCode:
+            force_sms (:obj:`bool`, optional):
+                Whether to force sending as SMS.
+
+        Returns:
             Information about the result of the request.
         """
         phone = utils.parse_phone(phone) or self._phone
@@ -165,23 +188,30 @@ class TelegramClient(TelegramBareClient):
         Starts or completes the sign in process with the given phone number
         or code that Telegram sent.
 
-        :param str | int phone:
+        Args:
-            The phone to send the code to if no code was provided, or to
+            phone (:obj:`str` | :obj:`int`):
-            override the phone that was previously used with these requests.
+                The phone to send the code to if no code was provided,
-        :param str | int code:
+                or to override the phone that was previously used with
-            The code that Telegram sent.
+                these requests.
-        :param str password:
-            2FA password, should be used if a previous call raised
-            SessionPasswordNeededError.
-        :param str bot_token:
-            Used to sign in as a bot. Not all requests will be available.
-            This should be the hash the @BotFather gave you.
-        :param str phone_code_hash:
-            The hash returned by .send_code_request. This can be set to None
-            to use the last hash known.
 
-        :return auth.SentCode | User:
+            code (:obj:`str` | :obj:`int`):
-            The signed in user, or the information about .send_code_request().
+                The code that Telegram sent.
+
+            password (:obj:`str`):
+                2FA password, should be used if a previous call raised
+                SessionPasswordNeededError.
+
+            bot_token (:obj:`str`):
+                Used to sign in as a bot. Not all requests will be available.
+                This should be the hash the @BotFather gave you.
+
+            phone_code_hash (:obj:`str`):
+                The hash returned by .send_code_request. This can be set to None
+                to use the last hash known.
+
+        Returns:
+            The signed in user, or the information about
+            :meth:`.send_code_request()`.
         """
 
         if phone and not code:
@@ -229,10 +259,18 @@ class TelegramClient(TelegramBareClient):
         Signs up to Telegram if you don't have an account yet.
         You must call .send_code_request(phone) first.
 
-        :param str | int code: The code sent by Telegram
+        Args:
-        :param str first_name: The first name to be used by the new account.
+            code (:obj:`str` | :obj:`int`):
-        :param str last_name: Optional last name.
+                The code sent by Telegram
-        :return User: The new created user.
+
+            first_name (:obj:`str`):
+                The first name to be used by the new account.
+
+            last_name (:obj:`str`, optional)
+                Optional last name.
+
+        Returns:
+            The new created user.
         """
         result = self(SignUpRequest(
             phone_number=self._phone,
@@ -246,9 +284,11 @@ class TelegramClient(TelegramBareClient):
         return result.user
 
     def log_out(self):
-        """Logs out Telegram and deletes the current *.session file.
+        """
+        Logs out Telegram and deletes the current *.session file.
 
-        :return bool: True if the operation was successful.
+        Returns:
+            True if the operation was successful.
         """
         try:
             self(LogOutRequest())
@@ -265,7 +305,8 @@ class TelegramClient(TelegramBareClient):
         Gets "me" (the self user) which is currently authenticated,
         or None if the request fails (hence, not authenticated).
 
-        :return User: Your own user.
+        Returns:
+            Your own user.
         """
         try:
             return self(GetUsersRequest([InputUserSelf()]))[0]
@@ -284,19 +325,24 @@ class TelegramClient(TelegramBareClient):
         """
         Gets N "dialogs" (open "chats" or conversations with other people).
 
-        :param limit:
+        Args:
-            How many dialogs to be retrieved as maximum. Can be set to None
+            limit (:obj:`int` | :obj:`None`):
-            to retrieve all dialogs. Note that this may take whole minutes
+                How many dialogs to be retrieved as maximum. Can be set to
-            if you have hundreds of dialogs, as Telegram will tell the library
+                ``None`` to retrieve all dialogs. Note that this may take
-            to slow down through a FloodWaitError.
+                whole minutes if you have hundreds of dialogs, as Telegram
-        :param offset_date:
+                will tell the library to slow down through a
-            The offset date to be used.
+                ``FloodWaitError``.
-        :param offset_id:
-            The message ID to be used as an offset.
-        :param offset_peer:
-            The peer to be used as an offset.
 
-        :return UserList[telethon.tl.custom.Dialog]:
+            offset_date (:obj:`datetime`, optional):
+                The offset date to be used.
+
+            offset_id (:obj:`int`, optional):
+                The message ID to be used as an offset.
+
+            offset_peer (:obj:`InputPeer`, optional):
+                The peer to be used as an offset.
+
+        Returns:
             A list dialogs, with an additional .total attribute on the list.
         """
         limit = float('inf') if limit is None else int(limit)
@@ -351,11 +397,10 @@ class TelegramClient(TelegramBareClient):
         """
         Gets all open draft messages.
 
-        Returns a list of custom `Draft` objects that are easy to work with:
+        Returns:
-          You can call `draft.set_message('text')` to change the message,
+            A list of custom ``Draft`` objects that are easy to work with:
-          or delete it through `draft.delete()`.
+            You can call :meth:`draft.set_message('text')` to change the message,
-
+            or delete it through :meth:`draft.delete()`.
-        :return List[telethon.tl.custom.Draft]: A list of open drafts
         """
         response = self(GetAllDraftsRequest())
         self.session.process_entities(response)
@@ -365,6 +410,7 @@ class TelegramClient(TelegramBareClient):
 
     @staticmethod
     def _get_response_message(request, result):
+        """Extracts the response message known a request and Update result"""
         # Telegram seems to send updateMessageID first, then updateNewMessage,
         # however let's not rely on that just in case.
         msg_id = None
@@ -388,19 +434,26 @@ class TelegramClient(TelegramBareClient):
         """
         Sends the given message to the specified entity (user/chat/channel).
 
-        :param str | int | User | Chat | Channel entity:
+        Args:
-            To who will it be sent.
+            entity (:obj:`entity`):
-        :param str message:
+                To who will it be sent.
-            The message to be sent.
-        :param int | Message reply_to:
-            Whether to reply to a message or not.
-        :param str parse_mode:
-            Can be 'md' or 'markdown' for markdown-like parsing, in a similar
-            fashion how official clients work.
-        :param link_preview:
-            Should the link preview be shown?
 
-        :return Message: the sent message
+            message (:obj:`str`):
+                The message to be sent.
+
+            reply_to (:obj:`int` | :obj:`Message`, optional):
+                Whether to reply to a message or not. If an integer is provided,
+                it should be the ID of the message that it should reply to.
+
+            parse_mode (:obj:`str`, optional):
+                Can be 'md' or 'markdown' for markdown-like parsing, in a similar
+                fashion how official clients work.
+
+            link_preview (:obj:`bool`, optional):
+                Should the link preview be shown?
+
+        Returns:
+            the sent message
         """
         entity = self.get_input_entity(entity)
         if parse_mode:
@@ -435,21 +488,25 @@ class TelegramClient(TelegramBareClient):
 
     def delete_messages(self, entity, message_ids, revoke=True):
         """
-        Deletes a message from a chat, optionally "for everyone" with argument
+        Deletes a message from a chat, optionally "for everyone".
-        `revoke` set to `True`.
 
-        The `revoke` argument has no effect for Channels and Megagroups,
+        Args:
-        where it inherently behaves as being `True`.
+            entity (:obj:`entity`):
+                From who the message will be deleted. This can actually
+                be ``None`` for normal chats, but **must** be present
+                for channels and megagroups.
 
-        Note: The `entity` argument can be `None` for normal chats, but it's
+            message_ids (:obj:`list` | :obj:`int` | :obj:`Message`):
-        mandatory to delete messages from Channels and Megagroups. It is also
+                The IDs (or ID) or messages to be deleted.
-        possible to supply a chat_id which will be automatically resolved to
-        the right type of InputPeer.
 
-        :param entity: ID or Entity of the chat
+            revoke (:obj:`bool`, optional):
-        :param list message_ids: ID(s) or `Message` object(s) of the message(s) to delete
+                Whether the message should be deleted for everyone or not.
-        :param revoke: Delete the message for everyone or just this client
+                By default it has the opposite behaviour of official clients,
-        :returns .messages.AffectedMessages: Messages affected by deletion.
+                and it will delete the message for everyone.
+                This has no effect on channels or megagroups.
+
+        Returns:
+            The affected messages.
         """
 
         if not isinstance(message_ids, list):
@@ -477,34 +534,45 @@ class TelegramClient(TelegramBareClient):
         """
         Gets the message history for the specified entity
 
-        :param entity:
+        Args:
-            The entity from whom to retrieve the message history.
+            entity (:obj:`entity`):
-        :param limit:
+                The entity from whom to retrieve the message history.
-            Number of messages to be retrieved. Due to limitations with the API
-            retrieving more than 3000 messages will take longer than half a
-            minute (or even more based on previous calls). The limit may also
-            be None, which would eventually return the whole history.
-        :param offset_date:
-            Offset date (messages *previous* to this date will be retrieved).
-        :param offset_id:
-            Offset message ID (only messages *previous* to the given ID will
-            be retrieved).
-        :param max_id:
-            All the messages with a higher (newer) ID or equal to this will
-            be excluded
-        :param min_id:
-            All the messages with a lower (older) ID or equal to this will
-            be excluded.
-        :param add_offset:
-            Additional message offset
-            (all of the specified offsets + this offset = older messages).
 
-        :return: A list of messages with extra attributes:
+            limit (:obj:`int` | :obj:`None`, optional):
-                    .total = (on the list) total amount of messages sent
+                Number of messages to be retrieved. Due to limitations with
-                    .sender = entity of the sender
+                the API retrieving more than 3000 messages will take longer
-                    .fwd_from.sender = if fwd_from, who sent it originally
+                than half a minute (or even more based on previous calls).
-                    .fwd_from.channel = if fwd_from, original channel
+                The limit may also be ``None``, which would eventually return
-                    .to = entity to which the message was sent
+                the whole history.
+
+            offset_date (:obj:`datetime`):
+                Offset date (messages *previous* to this date will be
+                retrieved). Exclusive.
+
+            offset_id (:obj:`int`):
+                Offset message ID (only messages *previous* to the given
+                ID will be retrieved). Exclusive.
+
+            max_id (:obj:`int`):
+                All the messages with a higher (newer) ID or equal to this will
+                be excluded
+
+            min_id (:obj:`int`):
+                All the messages with a lower (older) ID or equal to this will
+                be excluded.
+
+            add_offset (:obj:`int`):
+                Additional message offset (all of the specified offsets +
+                this offset = older messages).
+
+        Returns:
+            A list of messages with extra attributes:
+
+                * ``.total`` = (on the list) total amount of messages sent.
+                * ``.sender`` = entity of the sender.
+                * ``.fwd_from.sender`` = if fwd_from, who sent it originally.
+                * ``.fwd_from.channel`` = if fwd_from, original channel.
+                * ``.to`` = entity to which the message was sent.
         """
         entity = self.get_input_entity(entity)
         limit = float('inf') if limit is None else int(limit)
@@ -585,11 +653,16 @@ class TelegramClient(TelegramBareClient):
         Sends a "read acknowledge" (i.e., notifying the given peer that we've
         read their messages, also known as the "double check").
 
-        :param entity: The chat where these messages are located.
+        Args:
-        :param message: Either a list of messages or a single message.
+            entity (:obj:`entity`):
-        :param max_id: Overrides messages, until which message should the
+                The chat where these messages are located.
-                       acknowledge should be sent.
+
-        :return:
+            message (:obj:`list` | :obj:`Message`):
+                Either a list of messages or a single message.
+
+            max_id (:obj:`int`):
+                Overrides messages, until which message should the
+                acknowledge should be sent.
         """
         if max_id is None:
             if not messages:
@@ -636,35 +709,47 @@ class TelegramClient(TelegramBareClient):
         """
         Sends a file to the specified entity.
 
-        :param entity:
+        Args:
-            Who will receive the file.
+            entity (:obj:`entity`):
-        :param file:
+                Who will receive the file.
-            The path of the file, byte array, or stream that will be sent.
-            Note that if a byte array or a stream is given, a filename
-            or its type won't be inferred, and it will be sent as an
-            "unnamed application/octet-stream".
 
-            Subsequent calls with the very same file will result in
+            file (:obj:`str` | :obj:`bytes` | :obj:`file`):
-            immediate uploads, unless .clear_file_cache() is called.
+                The path of the file, byte array, or stream that will be sent.
-        :param caption:
+                Note that if a byte array or a stream is given, a filename
-            Optional caption for the sent media message.
+                or its type won't be inferred, and it will be sent as an
-        :param force_document:
+                "unnamed application/octet-stream".
-            If left to False and the file is a path that ends with .png, .jpg
+
-            and such, the file will be sent as a photo. Otherwise always as
+                Subsequent calls with the very same file will result in
-            a document.
+                immediate uploads, unless ``.clear_file_cache()`` is called.
-        :param progress_callback:
+
-            A callback function accepting two parameters: (sent bytes, total)
+            caption (:obj:`str`, optional):
-        :param reply_to:
+                Optional caption for the sent media message.
-            Same as reply_to from .send_message().
+
-        :param attributes:
+            force_document (:obj:`bool`, optional):
-            Optional attributes that override the inferred ones, like
+                If left to ``False`` and the file is a path that ends with
-            DocumentAttributeFilename and so on.
+                ``.png``, ``.jpg`` and such, the file will be sent as a photo.
-        :param thumb:
+                Otherwise always as a document.
-            Optional thumbnail (for videos).
+
-        :param kwargs:
+            progress_callback (:obj:`callable`, optional):
+                A callback function accepting two parameters:
+                ``(sent bytes, total)``.
+
+            reply_to (:obj:`int` | :obj:`Message`):
+                Same as reply_to from .send_message().
+
+            attributes (:obj:`list`, optional):
+                Optional attributes that override the inferred ones, like
+                ``DocumentAttributeFilename`` and so on.
+
+            thumb (:obj:`str` | :obj:`bytes` | :obj:`file`):
+                Optional thumbnail (for videos).
+
+        Kwargs:
            If "is_voice_note" in kwargs, despite its value, and the file is
            sent as a document, it will be sent as a voice note.
-        :return:
+
+       Returns:
+           The message containing the sent file.
         """
         as_photo = False
         if isinstance(file, str):
@@ -766,15 +851,19 @@ class TelegramClient(TelegramBareClient):
         """
         Downloads the profile photo of the given entity (user/chat/channel).
 
-        :param entity:
+        Args:
-            From who the photo will be downloaded.
+            entity (:obj:`entity`):
-        :param file:
+                From who the photo will be downloaded.
-            The output file path, directory, or stream-like object.
+
-            If the path exists and is a file, it will be overwritten.
+            file (:obj:`str` | :obj:`file`, optional):
-        :param download_big:
+                The output file path, directory, or stream-like object.
-            Whether to use the big version of the available photos.
+                If the path exists and is a file, it will be overwritten.
-        :return:
+
-            None if no photo was provided, or if it was Empty. On success
+            download_big (:obj:`bool`, optional):
+                Whether to use the big version of the available photos.
+
+        Returns:
+            ``None`` if no photo was provided, or if it was Empty. On success
             the file path is returned since it may differ from the one given.
         """
         photo = entity
@@ -843,14 +932,21 @@ class TelegramClient(TelegramBareClient):
     def download_media(self, message, file=None, progress_callback=None):
         """
         Downloads the given media, or the media from a specified Message.
-        :param message:
+
+        message (:obj:`Message` | :obj:`Media`):
             The media or message containing the media that will be downloaded.
-        :param file:
+
+        file (:obj:`str` | :obj:`file`, optional):
             The output file path, directory, or stream-like object.
             If the path exists and is a file, it will be overwritten.
-        :param progress_callback:
+
-            A callback function accepting two parameters: (recv bytes, total)
+        progress_callback (:obj:`callable`, optional):
-        :return:
+            A callback function accepting two parameters:
+            ``(recv bytes, total)``.
+
+        Returns:
+            ``None`` if no media was provided, or if it was Empty. On success
+            the file path is returned since it may differ from the one given.
         """
         # TODO This won't work for messageService
         if isinstance(message, Message):
@@ -1038,7 +1134,7 @@ class TelegramClient(TelegramBareClient):
         """
         Turns the given entity into a valid Telegram user or chat.
 
-        :param entity:
+        entity (:obj:`str` | :obj:`int` | :obj:`Peer` | :obj:`InputPeer`):
             The entity (or iterable of entities) to be transformed.
             If it's a string which can be converted to an integer or starts
             with '+' it will be resolved as if it were a phone number.
@@ -1053,7 +1149,9 @@ class TelegramClient(TelegramBareClient):
             If the entity is neither, and it's not a TLObject, an
             error will be raised.
 
-        :return: User, Chat or Channel corresponding to the input entity.
+        Returns:
+            ``User``, ``Chat`` or ``Channel`` corresponding to the input
+            entity.
         """
         if not isinstance(entity, str) and hasattr(entity, '__iter__'):
             single = False
@@ -1145,19 +1243,20 @@ class TelegramClient(TelegramBareClient):
         use this kind of InputUser, InputChat and so on, so this is the
         most suitable call to make for those cases.
 
-        :param peer:
+        entity (:obj:`str` | :obj:`int` | :obj:`Peer` | :obj:`InputPeer`):
             The integer ID of an user or otherwise either of a
-            PeerUser, PeerChat or PeerChannel, for which to get its
+            ``PeerUser``, ``PeerChat`` or ``PeerChannel``, for
-            Input* version.
+            which to get its ``Input*`` version.
 
-            If this Peer hasn't been seen before by the library, the top
+            If this ``Peer`` hasn't been seen before by the library, the top
             dialogs will be loaded and their entities saved to the session
             file (unless this feature was disabled explicitly).
 
             If in the end the access hash required for the peer was not found,
             a ValueError will be raised.
 
-        :return: InputPeerUser, InputPeerChat or InputPeerChannel.
+        Returns:
+            ``InputPeerUser``, ``InputPeerChat`` or ``InputPeerChannel``.
         """
         try:
             # First try to get the entity from cache, otherwise figure it out