From 61613ab6ac475898bbcdc3686c0bcf1be3532f38 Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Mon, 6 May 2019 11:38:26 +0200 Subject: [PATCH] Create a new page with a summary of the method reference --- readthedocs/conf.py | 1 + readthedocs/extra/reference.rst | 187 ++++++++++++++++++++++++++ readthedocs/index.rst | 3 +- telethon/client/account.py | 10 +- telethon/client/auth.py | 27 ++-- telethon/client/bots.py | 3 +- telethon/client/buttons.py | 19 +-- telethon/client/dialogs.py | 9 +- telethon/client/downloads.py | 6 +- telethon/client/messages.py | 18 ++- telethon/client/telegrambaseclient.py | 8 +- telethon/client/updates.py | 24 ++-- telethon/client/uploads.py | 10 +- telethon/client/users.py | 21 +-- telethon/helpers.py | 17 +++ 15 files changed, 303 insertions(+), 60 deletions(-) create mode 100644 readthedocs/extra/reference.rst diff --git a/readthedocs/conf.py b/readthedocs/conf.py index 07fae89b..9c04cc47 100644 --- a/readthedocs/conf.py +++ b/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' ] diff --git a/readthedocs/extra/reference.rst b/readthedocs/extra/reference.rst new file mode 100644 index 00000000..478884d9 --- /dev/null +++ b/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 diff --git a/readthedocs/index.rst b/readthedocs/index.rst index c0978d8e..097ce208 100644 --- a/readthedocs/index.rst +++ b/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 diff --git a/telethon/client/account.py b/telethon/client/account.py index b1c5fa60..3faa366c 100644 --- a/telethon/client/account.py +++ b/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. diff --git a/telethon/client/auth.py b/telethon/client/auth.py index 50a19716..2803ee58 100644 --- a/telethon/client/auth.py +++ b/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, - also taking into consideration that 2FA may be enabled in the account. + Starts the client (connects and logs in if necessary). + + 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 - or code that Telegram sent. + Logs in to Telegram to an existing user or bot account. + + 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. - You must call .send_code_request(phone) first. + Signs up to Telegram as a new user account. + + 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 - passed parameters. Take note of the parameter explanations. + Changes the 2FA settings of the logged in user. + + 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 diff --git a/telethon/client/bots.py b/telethon/client/bots.py index 7b0b9059..00014998 100644 --- a/telethon/client/bots.py +++ b/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 - i.e. ``@vote My New Poll`` would be as follows: + Makes an inline query to the specified bot (e.g. ``@vote New Poll``). >>> client = ... >>> client.inline_query('vote', 'My New Poll') diff --git a/telethon/client/buttons.py b/telethon/client/buttons.py index 4ea2c904..8a6b518b 100644 --- a/telethon/client/buttons.py +++ b/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 - the given buttons, or does nothing if either no buttons are - provided or the provided argument is already a reply markup. + Builds a :tl:`ReplyInlineMarkup` or :tl:`ReplyKeyboardMarkup` for + the given buttons. - This will add any event handlers defined in the - buttons and delete old ones not to call them twice, - so you should probably call this method manually for - serious bots instead re-adding handlers every time you - send a message. Magic can only go so far. + Does nothing if either no buttons are provided or the provided + argument is already a reply markup. + + You should consider using this method if you are going to reuse + 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 diff --git a/telethon/client/dialogs.py b/telethon/client/dialogs.py index 75316169..42e918da 100644 --- a/telethon/client/dialogs.py +++ b/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. - Dialogs are the open "chats" or conversations with other people, - groups you have joined, or channels you are subscribed to. + Iterator over the dialogs (open conversations/subscribed channels). Args: limit (`int` | `None`): @@ -186,7 +184,10 @@ class DialogMethods(UserMethods): replies_are_responses: bool = True) -> custom.Conversation: """ Creates a `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: diff --git a/telethon/client/downloads.py b/telethon/client/downloads.py index ae069516..130b3704 100644 --- a/telethon/client/downloads.py +++ b/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`): diff --git a/telethon/client/messages.py b/telethon/client/messages.py index 404ccead..70fd7114 100644 --- a/telethon/client/messages.py +++ b/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 `): @@ -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 - read their messages, also known as the "double check"). + Marks messages as read and optionally clears mentions. This effectively marks a message as read (or more than one) in the given conversation. diff --git a/telethon/client/telegrambaseclient.py b/telethon/client/telegrambaseclient.py index 4509e627..692a64ec 100644 --- a/telethon/client/telegrambaseclient.py +++ b/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 - ends, either by user action or in the background. + Property with a ``Future`` that resolves upon disconnection. """ 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() diff --git a/telethon/client/updates.py b/telethon/client/updates.py index 66eac4be..cef90aa7 100644 --- a/telethon/client/updates.py +++ b/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 - while connecting/sending/receiving occurs in the background. In - the latter case, said error will ``raise`` so you have a chance + Runs the event loop until the library is disconnected. + + Disconnections can be manual (by calling `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 - consisting of (callback, event). + Lists all registered event handlers. + + Returns a list of pairs consisting of ``(callback, event)``. """ return [(callback, event) for event, callback in self._event_builders] diff --git a/telethon/client/uploads.py b/telethon/client/uploads.py index 45ce94d6..d449557b 100644 --- a/telethon/client/uploads.py +++ b/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 - :tl:`InputFile` or :tl:`InputFileBig`, as required) which can be - later used before it expires (they are usable during less than a day). + Uploads a file to Telegram's servers, without sending it. + + 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 diff --git a/telethon/client/users.py b/telethon/client/users.py index 4bb471c4..1d1c60b8 100644 --- a/telethon/client/users.py +++ b/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, - or None if the request fails (hence, not authenticated). + Gets "me", the current :tl:`User` who is logged in. + + 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 - 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 - 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: + Turns the given entity into its input entity version. + + Most requests 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 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. diff --git a/telethon/helpers.py b/telethon/helpers.py index 38b951ad..f3f8c044 100644 --- a/telethon/helpers.py +++ b/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)