Create a new page with a summary of the method reference

readthedocs/conf.py

@@ -40,6 +40,7 @@ tl_ref_url = 'https://lonamiwebs.github.io/Telethon'
 # ones.
 extensions = [
     'sphinx.ext.autodoc',
+    'sphinx.ext.autosummary',
     'custom_roles'
 ]
 

readthedocs/extra/reference.rst

@@ -0,0 +1,187 @@
+.. _ref-summary:
+
+=================
+Reference Summary
+=================
+
+This page contains a summary of all the important methods and properties that
+you may need when using Telethon. They are sorted by relevance and are not in
+alphabetical order.
+
+The way you should use this page is by looking up the type you need in the
+table of contents (method index below) and searching for the method or
+property that you are interested in.
+
+.. contents:: Method Index
+
+TelegramClient
+==============
+
+This is a summary of the methods you will find at :ref:`telethon-client`.
+
+Auth
+----
+
+.. currentmodule:: telethon.client.auth.AuthMethods
+
+.. autosummary::
+    :nosignatures:
+
+    start
+    send_code_request
+    sign_in
+    sign_up
+    log_out
+    edit_2fa
+
+Base
+----
+
+.. py:currentmodule:: telethon.client.telegrambaseclient.TelegramBaseClient
+
+.. autosummary::
+    :nosignatures:
+
+    connect
+    disconnect
+    is_connected
+    disconnected
+    loop
+
+Messages
+--------
+
+.. py:currentmodule:: telethon.client.messages.MessageMethods
+
+.. autosummary::
+    :nosignatures:
+
+    send_message
+    edit_message
+    delete_messages
+    forward_messages
+    iter_messages
+    get_messages
+    send_read_acknowledge
+
+Uploads
+-------
+
+.. py:currentmodule:: telethon.client.uploads.UploadMethods
+
+.. autosummary::
+    :nosignatures:
+
+    send_file
+    upload_file
+
+Downloads
+---------
+
+.. currentmodule:: telethon.client.downloads.DownloadMethods
+
+.. autosummary::
+    :nosignatures:
+
+    download_media
+    download_profile_photo
+    download_file
+
+Dialogs
+-------
+
+.. py:currentmodule:: telethon.client.dialogs.DialogMethods
+
+.. autosummary::
+    :nosignatures:
+
+    iter_dialogs
+    get_dialogs
+    iter_drafts
+    get_drafts
+    conversation
+
+Users
+-----
+
+.. py:currentmodule:: telethon.client.users.UserMethods
+
+.. autosummary::
+    :nosignatures:
+
+    get_me
+    is_bot
+    is_user_authorized
+    get_entity
+    get_input_entity
+    get_peer_id
+
+Chats
+-----
+
+.. currentmodule:: telethon.client.chats.ChatMethods
+
+.. autosummary::
+    :nosignatures:
+
+    iter_participants
+    get_participants
+    iter_admin_log
+    get_admin_log
+    action
+
+Parse Mode
+----------
+
+.. py:currentmodule:: telethon.client.messageparse.MessageParseMethods
+
+.. autosummary::
+    :nosignatures:
+
+    parse_mode
+
+Updates
+-------
+
+.. py:currentmodule:: telethon.client.updates.UpdateMethods
+
+.. autosummary::
+    :nosignatures:
+
+    on
+    run_until_disconnected
+    add_event_handler
+    remove_event_handler
+    list_event_handlers
+    catch_up
+
+Bots
+----
+
+.. currentmodule:: telethon.client.bots.BotMethods
+
+.. autosummary::
+    :nosignatures:
+
+    inline_query
+
+Buttons
+-------
+
+.. currentmodule:: telethon.client.buttons.ButtonMethods
+
+.. autosummary::
+    :nosignatures:
+
+    build_reply_markup
+
+Account
+-------
+
+.. currentmodule:: telethon.client.account.AccountMethods
+
+.. autosummary::
+    :nosignatures:
+
+    takeout
+    end_takeout

readthedocs/index.rst

@@ -17,7 +17,7 @@ when you upgrade!
 .. important::
 
     * Are you new here? Jump straight into :ref:`getting-started`!
-    * Looking for available friendly methods? See :ref:`telethon-client`.
+    * Looking for available friendly methods? See :ref:`ref-summary`.
     * Used Telethon before v1.0? See :ref:`compatibility-and-convenience`.
     * Need the full API reference? https://lonamiwebs.github.io/Telethon/.
 
@@ -41,6 +41,7 @@ heavy job for you, so you can focus on developing an application.
    extra/basic/installation
    extra/basic/creating-a-client
    extra/basic/telegram-client
+   extra/reference
    extra/basic/entities
    extra/basic/working-with-updates
    extra/basic/compatibility-and-convenience

telethon/client/account.py

@@ -120,7 +120,9 @@ class AccountMethods(UserMethods):
             files: bool = None,
             max_file_size: bool = None) -> 'TelegramClient':
         """
-        Creates a proxy object over the current :ref:`TelegramClient` through
+        Returns a :ref:`TelegramClient` which calls methods behind a takeout session.
+
+        It does so by creating a proxy object over the current client through
         which making requests will use :tl:`InvokeWithTakeoutRequest` to wrap
         them. In other words, returns the current client modified so that
         requests are done as a takeout:
@@ -210,7 +212,11 @@ class AccountMethods(UserMethods):
 
     async def end_takeout(self: 'TelegramClient', success: bool) -> bool:
         """
-        Finishes a takeout, with specified result sent back to Telegram.
+        Finishes the current takeout session.
+
+        Args:
+            success (`bool`):
+                Whether the takeout completed successfully or not.
 
         Returns:
             ``True`` if the operation was successful, ``False`` otherwise.

telethon/client/auth.py

@@ -29,8 +29,10 @@ class AuthMethods(MessageParseMethods, UserMethods):
             last_name: str = '',
             max_attempts: int = 3) -> 'TelegramClient':
         """
-        Convenience method to interactively connect and sign in if required,
+        Starts the client (connects and logs in if necessary).
-        also taking into consideration that 2FA may be enabled in the account.
+
+        By default, this method will be interactive (asking for
+        user input if needed), and will handle 2FA if enabled too.
 
         If the phone doesn't belong to an existing account (and will hence
         `sign_up` for a new one),  **you are agreeing to Telegram's
@@ -252,8 +254,11 @@ class AuthMethods(MessageParseMethods, UserMethods):
             bot_token: str = None,
             phone_code_hash: str = None) -> types.User:
         """
-        Starts or completes the sign in process with the given phone number
+        Logs in to Telegram to an existing user or bot account.
-        or code that Telegram sent.
+
+        You should only use this if you are not authorized yet.
+
+        This method will send the code if it's not provided.
 
         Args:
             phone (`str` | `int`):
@@ -324,8 +329,11 @@ class AuthMethods(MessageParseMethods, UserMethods):
             phone: str = None,
             phone_code_hash: str = None) -> types.User:
         """
-        Signs up to Telegram if you don't have an account yet.
+        Signs up to Telegram as a new user account.
-        You must call .send_code_request(phone) first.
+
+        Use this if you don't have an account yet.
+
+        You must call `send_code_request` first.
 
         **By using this method you're agreeing to Telegram's
         Terms of Service. This is required and your account
@@ -400,7 +408,7 @@ class AuthMethods(MessageParseMethods, UserMethods):
             *,
             force_sms: bool = False) -> types.auth.SentCode:
         """
-        Sends a code request to the specified phone number.
+        Sends the Telegram code needed to login to the given phone number.
 
         Args:
             phone (`str` | `int`):
@@ -468,8 +476,9 @@ class AuthMethods(MessageParseMethods, UserMethods):
             email: str = None,
             email_code_callback: typing.Callable[[int], str] = None) -> bool:
         """
-        Changes the 2FA settings of the logged in user, according to the
+        Changes the 2FA settings of the logged in user.
-        passed parameters. Take note of the parameter explanations.
+
+        Review carefully the parameter explanations before using this method.
 
         Note that this method may be *incredibly* slow depending on the
         prime numbers that must be used during the process to make sure

telethon/client/bots.py

@@ -17,8 +17,7 @@ class BotMethods(UserMethods):
             offset: str = None,
             geo_point: types.GeoPoint = None) -> custom.InlineResults:
         """
-        Makes the given inline query to the specified bot
+        Makes an inline query to the specified bot (e.g. ``@vote New Poll``).
-        i.e. ``@vote My New Poll`` would be as follows:
 
         >>> client = ...
         >>> client.inline_query('vote', 'My New Poll')

telethon/client/buttons.py

@@ -9,20 +9,21 @@ if typing.TYPE_CHECKING:
 
 
 class ButtonMethods(UpdateMethods):
+    @staticmethod
     def build_reply_markup(
-            self: 'TelegramClient',
             buttons: typing.Optional[hints.MarkupLike],
             inline_only: bool = False) -> typing.Optional[types.TypeReplyMarkup]:
         """
-        Builds a :tl`ReplyInlineMarkup` or :tl:`ReplyKeyboardMarkup` for
+        Builds a :tl:`ReplyInlineMarkup` or :tl:`ReplyKeyboardMarkup` for
-        the given buttons, or does nothing if either no buttons are
+        the given buttons.
-        provided or the provided argument is already a reply markup.
 
-        This will add any event handlers defined in the
+        Does nothing if either no buttons are provided or the provided
-        buttons and delete old ones not to call them twice,
+        argument is already a reply markup.
-        so you should probably call this method manually for
+
-        serious bots instead re-adding handlers every time you
+        You should consider using this method if you are going to reuse
-        send a message. Magic can only go so far.
+        the markup very often. Otherwise, it is not necessary.
+
+        This method is **not** asynchronous (don't use ``await`` on it).
         """
         if buttons is None:
             return None

telethon/client/dialogs.py

@@ -111,9 +111,7 @@ class DialogMethods(UserMethods):
             ignore_migrated: bool = False
     ) -> _DialogsIter:
         """
-        Returns an iterator over the dialogs, yielding 'limit' at most.
+        Iterator over the dialogs (open conversations/subscribed channels).
-        Dialogs are the open "chats" or conversations with other people,
-        groups you have joined, or channels you are subscribed to.
 
         Args:
             limit (`int` | `None`):
@@ -186,7 +184,10 @@ class DialogMethods(UserMethods):
             replies_are_responses: bool = True) -> custom.Conversation:
         """
         Creates a `Conversation <telethon.tl.custom.conversation.Conversation>`
-        with the given entity so you can easily send messages and await for
+        with the given entity.
+
+        This is not the same as just sending a message to create a "dialog"
+        with them, but rather a way to easily send messages and await for
         responses or other reactions. Refer to its documentation for more.
 
         Args:

telethon/client/downloads.py

@@ -28,7 +28,7 @@ class DownloadMethods(UserMethods):
             *,
             download_big: bool = True) -> typing.Optional[str]:
         """
-        Downloads the profile photo of the given entity (user/chat/channel).
+        Downloads the profile photo from the given user, chat or channel.
 
         Args:
             entity (`entity`):
@@ -134,7 +134,7 @@ class DownloadMethods(UserMethods):
             thumb: hints.FileLike = None,
             progress_callback: hints.ProgressCallback = None) -> typing.Optional[str]:
         """
-        Downloads the given media, or the media from a specified Message.
+        Downloads the given media from a message object.
 
         Note that if the download is too slow, you should consider installing
         ``cryptg`` (through ``pip install cryptg``) so that decrypting the
@@ -216,7 +216,7 @@ class DownloadMethods(UserMethods):
             progress_callback: hints.ProgressCallback = None,
             dc_id: int = None) -> None:
         """
-        Downloads the given input location to a file.
+        Low-level method to download files from their input location.
 
         Args:
             input_location (:tl:`InputFileLocation`):

telethon/client/messages.py

@@ -314,7 +314,8 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
             reverse: bool = False
     ) -> typing.Union[_MessagesIter, _IDsIter]:
         """
-        Iterator over the message history for the specified entity.
+        Iterator over the messages for the given chat.
+
         If either `search`, `filter` or `from_user` are provided,
         :tl:`messages.Search` will be used instead of :tl:`messages.getHistory`.
 
@@ -486,7 +487,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
             buttons: hints.MarkupLike = None,
             silent: bool = None) -> types.Message:
         """
-        Sends the given message to the specified entity (user/chat/channel).
+        Sends a message to the specified user, chat or channel.
 
         The default parse mode is the same as the official applications
         (a custom flavour of markdown). ``**bold**, `code` or __italic__``
@@ -642,7 +643,11 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
             silent: bool = None,
             as_album: bool = None) -> typing.Sequence[types.Message]:
         """
-        Forwards the given message(s) to the specified entity.
+        Forwards the given messages to the specified entity.
+
+        If you want to "forward" a message without the forward header
+        (the "forwarded from" text), you should use `send_message` with
+        the original message instead. This will send a copy of it.
 
         Args:
             entity (`entity`):
@@ -759,7 +764,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
             file: hints.FileLike = None,
             buttons: hints.MarkupLike = None) -> types.Message:
         """
-        Edits the given message ID (to change its contents or disable preview).
+        Edits the given message to change its text or media.
 
         Args:
             entity (`entity` | `Message <telethon.tl.custom.message.Message>`):
@@ -867,7 +872,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
             *,
             revoke: bool = True) -> typing.Sequence[types.messages.AffectedMessages]:
         """
-        Deletes a message from a chat, optionally "for everyone".
+        Deletes the given messages, optionally "for everyone".
 
         Args:
             entity (`entity`):
@@ -925,8 +930,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
             max_id: int = None,
             clear_mentions: bool = False) -> bool:
         """
-        Sends a "read acknowledge" (i.e., notifying the given peer that we've
+        Marks messages as read and optionally clears mentions.
-        read their messages, also known as the "double check").
 
         This effectively marks a message as read (or more than one) in the
         given conversation.

telethon/client/telegrambaseclient.py

@@ -344,13 +344,15 @@ class TelegramBaseClient(abc.ABC):
 
     @property
     def loop(self: 'TelegramClient') -> asyncio.AbstractEventLoop:
+        """
+        Property with the ``asyncio`` event loop used by this client.
+        """
         return self._loop
 
     @property
     def disconnected(self: 'TelegramClient') -> asyncio.Future:
         """
-        Future that resolves when the connection to Telegram
+        Property with a ``Future`` that resolves upon disconnection.
-        ends, either by user action or in the background.
         """
         return self._sender.disconnected
 
@@ -381,6 +383,8 @@ class TelegramBaseClient(abc.ABC):
     def is_connected(self: 'TelegramClient') -> bool:
         """
         Returns ``True`` if the user has connected.
+
+        This method is **not** asynchronous (don't use ``await`` on it).
         """
         sender = getattr(self, '_sender', None)
         return sender and sender.is_connected()

telethon/client/updates.py

@@ -27,9 +27,14 @@ class UpdateMethods(UserMethods):
 
     def run_until_disconnected(self: 'TelegramClient'):
         """
-        Runs the event loop until `disconnect` is called or if an error
+        Runs the event loop until the library is disconnected.
-        while connecting/sending/receiving occurs in the background. In
+
-        the latter case, said error will ``raise`` so you have a chance
+        Disconnections can be manual (by calling `disconnect()
+        <telethon.client.telegrambaseclient.TelegramBaseClient.disconnect>`)
+        or not (if the library fails to reconnect automatically).
+
+        If a disconnection error occurs (i.e. not manual disconnect),
+        said error will be raised through here, so you have a chance
         to ``except`` it on your own code.
 
         If the loop is already running, this method returns a coroutine
@@ -47,7 +52,7 @@ class UpdateMethods(UserMethods):
 
     def on(self: 'TelegramClient', event: EventBuilder):
         """
-        Decorator helper method around `add_event_handler`. Example:
+        Decorator used to `add_event_handler` more conveniently.
 
         >>> from telethon import TelegramClient, events
         >>> client = TelegramClient(...)
@@ -74,7 +79,9 @@ class UpdateMethods(UserMethods):
             callback: callable,
             event: EventBuilder = None):
         """
-        Registers the given callback to be called on the specified event.
+        Registers a new event handler callback.
+
+        The callback will be called when the specified event occurs.
 
         Args:
             callback (`callable`):
@@ -110,7 +117,7 @@ class UpdateMethods(UserMethods):
             callback: callable,
             event: EventBuilder = None) -> int:
         """
-        Inverse operation of :meth:`add_event_handler`.
+        Inverse operation of `add_event_handler`.
 
         If no event is given, all events for this callback are removed.
         Returns how many callbacks were removed.
@@ -132,8 +139,9 @@ class UpdateMethods(UserMethods):
     def list_event_handlers(self: 'TelegramClient')\
             -> typing.Sequence[typing.Tuple[callable, EventBuilder]]:
         """
-        Lists all added event handlers, returning a list of pairs
+        Lists all registered event handlers.
-        consisting of (callback, event).
+
+        Returns a list of pairs consisting of ``(callback, event)``.
         """
         return [(callback, event) for event, callback in self._event_builders]
 

telethon/client/uploads.py

@@ -107,7 +107,7 @@ class UploadMethods(ButtonMethods, MessageParseMethods, UserMethods):
             supports_streaming: bool = False,
             **kwargs) -> types.Message:
         """
-        Sends a file to the specified entity.
+        Sends message with the given file to the specified entity.
 
         Args:
             entity (`entity`):
@@ -386,9 +386,11 @@ class UploadMethods(ButtonMethods, MessageParseMethods, UserMethods):
             use_cache: type = None,
             progress_callback: hints.ProgressCallback = None) -> types.TypeInputFile:
         """
-        Uploads the specified file and returns a handle (an instance of
+        Uploads a file to Telegram's servers, without sending it.
-        :tl:`InputFile` or :tl:`InputFileBig`, as required) which can be
+
-        later used before it expires (they are usable during less than a day).
+        This method returns a handle (an instance of :tl:`InputFile` or
+        :tl:`InputFileBig`, as required) which can be later used before
+        it expires (they are usable during less than a day).
 
         Uploading a file will simply return a "handle" to the file stored
         remotely in the Telegram servers, which can be later used on. This

telethon/client/users.py

@@ -104,8 +104,9 @@ class UserMethods(TelegramBaseClient):
     async def get_me(self: 'TelegramClient', input_peer: bool = False) \
             -> typing.Union[types.User, types.InputPeerUser]:
         """
-        Gets "me" (the self user) which is currently authenticated,
+        Gets "me", the current :tl:`User` who is logged in.
-        or None if the request fails (hence, not authenticated).
+
+        If the user has not logged in yet, this method returns ``None``.
 
         Args:
             input_peer (`bool`, optional):
@@ -144,7 +145,7 @@ class UserMethods(TelegramBaseClient):
 
     async def is_user_authorized(self: 'TelegramClient') -> bool:
         """
-        Returns ``True`` if the user is authorized.
+        Returns ``True`` if the user is authorized (i.e. has logged in).
         """
         if self._authorized is None:
             try:
@@ -254,11 +255,13 @@ class UserMethods(TelegramBaseClient):
             self: 'TelegramClient',
             peer: hints.EntityLike) -> types.TypeInputPeer:
         """
-        Turns the given peer into its input entity version. Most requests
+        Turns the given entity into its input entity version.
-        use this kind of :tl:`InputPeer`, so this is the most suitable call
+
-        to make for those cases. **Generally you should let the library do
+        Most requests use this kind of :tl:`InputPeer`, so this is the most
-        its job** and don't worry about getting the input entity first, but
+        suitable call to make for those cases. **Generally you should let the
-        if you're going to use an entity often, consider making the call:
+        library do its job** and don't worry about getting the input entity
+        first, but if you're going to use an entity often, consider making the
+        call:
 
         >>> import asyncio
         >>> rc = asyncio.get_event_loop().run_until_complete
@@ -380,7 +383,7 @@ class UserMethods(TelegramBaseClient):
             peer: hints.EntityLike,
             add_mark: bool = True) -> int:
         """
-        Gets the ID for the given peer, which may be anything entity-like.
+        Gets the ID for the given entity.
 
         This method needs to be ``async`` because `peer` supports usernames,
         invite-links, phone numbers (from people in your contact list), etc.

telethon/helpers.py

@@ -159,6 +159,23 @@ class TotalList(list):
     A list with an extra `total` property, which may not match its `len`
     since the total represents the total amount of items *available*
     somewhere else, not the items *in this list*.
+
+    Examples:
+
+        .. code-block:: python
+
+            # Telethon returns these lists in some cases (for example,
+            # only when a chunk is returned, but the "total" count
+            # is available).
+            result = client.get_messages(chat, limit=10)
+
+            print(result.total)  # large number
+            print(len(result))  # 10
+            print(result[0])  # latest message
+
+            for x in result:  # show the 10 messages
+                print(x.text)
+
     """
     def __init__(self, *args, **kwargs):
         super().__init__(*args, **kwargs)