From cffef411b2effaddce2def6bf2c0ece5741b3424 Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Thu, 17 May 2018 12:00:22 +0200 Subject: [PATCH] Enhance documentation --- .../advanced-usage/accessing-the-full-api.rst | 6 +++ readthedocs/extra/basic/getting-started.rst | 2 + readthedocs/extra/basic/telegram-client.rst | 6 ++- .../extra/examples/chats-and-channels.rst | 11 ++--- .../examples/projects-using-telethon.rst | 3 ++ readthedocs/extra/examples/users.rst | 2 +- .../extra/examples/working-with-messages.rst | 22 +++++++--- readthedocs/index.rst | 3 ++ readthedocs/telethon.events.rst | 7 ++++ telethon/events/chataction.py | 15 ++++--- telethon/events/common.py | 3 -- telethon/events/newmessage.py | 42 +++++++++---------- telethon/telegram_client.py | 30 ++++++------- 13 files changed, 94 insertions(+), 58 deletions(-) diff --git a/readthedocs/extra/advanced-usage/accessing-the-full-api.rst b/readthedocs/extra/advanced-usage/accessing-the-full-api.rst index 6f70f480..659af4b7 100644 --- a/readthedocs/extra/advanced-usage/accessing-the-full-api.rst +++ b/readthedocs/extra/advanced-usage/accessing-the-full-api.rst @@ -4,6 +4,12 @@ Accessing the Full API ====================== +.. important:: + + While you have access to this, you should always use the friendly + methods listed on :ref:`telethon-package` unless you have a better + reason not to, like a method not existing or you wanting more control. + The ``TelegramClient`` doesn't offer a method for every single request the Telegram API supports. However, it's very simple to *call* or *invoke* diff --git a/readthedocs/extra/basic/getting-started.rst b/readthedocs/extra/basic/getting-started.rst index 12d8babe..7c3fcad6 100644 --- a/readthedocs/extra/basic/getting-started.rst +++ b/readthedocs/extra/basic/getting-started.rst @@ -65,6 +65,8 @@ Basic Usage **More details**: :ref:`telegram-client` + See :ref:`telethon-package` for all available friendly methods. + Handling Updates **************** diff --git a/readthedocs/extra/basic/telegram-client.rst b/readthedocs/extra/basic/telegram-client.rst index d466646a..706ccfda 100644 --- a/readthedocs/extra/basic/telegram-client.rst +++ b/readthedocs/extra/basic/telegram-client.rst @@ -10,8 +10,10 @@ Introduction .. note:: - Check the :ref:`telethon-package` if you're looking for the methods - reference instead of this tutorial. + Make sure to use the friendly methods described in :ref:`telethon-package`! + This section is just an introduction to using the client, but all the + available methods are in the :ref:`telethon-package` reference, including + detailed descriptions to what they do. The ``TelegramClient`` is the central class of the library, the one you will be using most of the time. For this reason, it's important diff --git a/readthedocs/extra/examples/chats-and-channels.rst b/readthedocs/extra/examples/chats-and-channels.rst index 04d52187..d9e21caf 100644 --- a/readthedocs/extra/examples/chats-and-channels.rst +++ b/readthedocs/extra/examples/chats-and-channels.rst @@ -94,12 +94,13 @@ the hash of said channel or group. Retrieving all chat members (channels too) ****************************************** -You can use -`client.get_participants ` -to retrieve the participants (click it to see the relevant parameters). -Most of the time you will just need ``client.get_participants(entity)``. +.. note:: + + Use the `telethon.telegram_client.TelegramClient.iter_participants` + friendly method instead unless you have a better reason not to! + + This method will handle different chat types for you automatically. -This is what said method is doing behind the scenes as an example. In order to get all the members from a mega-group or channel, you need to use :tl:`GetParticipantsRequest`. As we can see it needs an diff --git a/readthedocs/extra/examples/projects-using-telethon.rst b/readthedocs/extra/examples/projects-using-telethon.rst index d688360c..3c92e660 100644 --- a/readthedocs/extra/examples/projects-using-telethon.rst +++ b/readthedocs/extra/examples/projects-using-telethon.rst @@ -12,6 +12,7 @@ the library. `issue 744 `_ so it can be included in the next revision of the documentation! +.. _projects-telegram-export: telegram-export *************** @@ -22,6 +23,7 @@ telegram-export A tool to download Telegram data (users, chats, messages, and media) into a database (and display the saved data). +.. _projects-mautrix-telegram: mautrix-telegram **************** @@ -31,6 +33,7 @@ mautrix-telegram A Matrix-Telegram hybrid puppeting/relaybot bridge. +.. _projects-telegramtui: TelegramTUI *********** diff --git a/readthedocs/extra/examples/users.rst b/readthedocs/extra/examples/users.rst index 351ce186..1d931ebf 100644 --- a/readthedocs/extra/examples/users.rst +++ b/readthedocs/extra/examples/users.rst @@ -65,6 +65,6 @@ through :tl:`UploadProfilePhoto`: from telethon.tl.functions.photos import UploadProfilePhotoRequest - client(functions.photos.UploadProfilePhotoRequest( + client(UploadProfilePhotoRequest( client.upload_file('/path/to/some/file') )) diff --git a/readthedocs/extra/examples/working-with-messages.rst b/readthedocs/extra/examples/working-with-messages.rst index 36abdf0d..0571beef 100644 --- a/readthedocs/extra/examples/working-with-messages.rst +++ b/readthedocs/extra/examples/working-with-messages.rst @@ -11,11 +11,14 @@ Working with messages Forwarding messages ******************* -This request is available as a friendly method through -`client.forward_messages `, -and can be used like shown below: +.. note:: - .. code-block:: python + Use the `telethon.telegram_client.TelegramClient.forward_messages` + friendly method instead unless you have a better reason not to! + + This method automatically accepts either a single message or many of them. + +.. code-block:: python # If you only have the message IDs client.forward_messages( @@ -51,6 +54,14 @@ too, if that's all you have. Searching Messages ******************* +.. note:: + + Use the `telethon.telegram_client.TelegramClient.iter_messages` + friendly method instead unless you have a better reason not to! + + This method has ``search`` and ``filter`` parameters that will + suit your needs. + Messages are searched through the obvious :tl:`SearchRequest`, but you may run into issues_. A valid example would be: @@ -71,7 +82,8 @@ into issues_. A valid example would be: limit=10, # How many results max_id=0, # Maximum message ID min_id=0, # Minimum message ID - from_id=None # Who must have sent the message (peer) + from_id=None, # Who must have sent the message (peer) + hash=0 # Special number to return nothing on no-change )) It's important to note that the optional parameter ``from_id`` could have diff --git a/readthedocs/index.rst b/readthedocs/index.rst index 01301eaa..f95c4bbb 100644 --- a/readthedocs/index.rst +++ b/readthedocs/index.rst @@ -18,6 +18,9 @@ when you upgrade! If you're new here, you want to read :ref:`getting-started`. If you're looking for the method reference, you should check :ref:`telethon-package`. + The mentioned :ref:`telethon-package` is an important section and it + contains the friendly methods that **you should use** most of the time. + What is this? ************* diff --git a/readthedocs/telethon.events.rst b/readthedocs/telethon.events.rst index 386864fb..5aaa0ba6 100644 --- a/readthedocs/telethon.events.rst +++ b/readthedocs/telethon.events.rst @@ -47,6 +47,13 @@ so all the methods in it can be used from any event builder/event instance. :undoc-members: :show-inheritance: + +.. automodule:: telethon.events.raw + :members: + :undoc-members: + :show-inheritance: + + .. automodule:: telethon.events :members: :undoc-members: diff --git a/telethon/events/chataction.py b/telethon/events/chataction.py index 2927c8d0..cbacba82 100644 --- a/telethon/events/chataction.py +++ b/telethon/events/chataction.py @@ -160,17 +160,19 @@ class ChatAction(EventBuilder): def respond(self, *args, **kwargs): """ - Responds to the chat action message (not as a reply). - Shorthand for ``client.send_message(event.chat, ...)``. + Responds to the chat action message (not as a reply). Shorthand for + `telethon.telegram_client.TelegramClient.send_message` with + ``entity`` already set. """ return self._client.send_message(self.input_chat, *args, **kwargs) def reply(self, *args, **kwargs): """ Replies to the chat action message (as a reply). Shorthand for - ``client.send_message(event.chat, ..., reply_to=event.message.id)``. + `telethon.telegram_client.TelegramClient.send_message` with + both ``entity`` and ``reply_to`` already set. - Has the same effect as ``.respond()`` if there is no message. + Has the same effect as `respond` if there is no message. """ if not self.action_message: return self.respond(*args, **kwargs) @@ -182,8 +184,9 @@ class ChatAction(EventBuilder): """ Deletes the chat action message. You're responsible for checking whether you have the permission to do so, or to except the error - otherwise. This is a shorthand for - ``client.delete_messages(event.chat, event.message, ...)``. + otherwise. Shorthand for + `telethon.telegram_client.TelegramClient.delete_messages` with + ``entity`` and ``message_ids`` already set. Does nothing if no message action triggered this event. """ diff --git a/telethon/events/common.py b/telethon/events/common.py index a5dfc7e7..a7c5db91 100644 --- a/telethon/events/common.py +++ b/telethon/events/common.py @@ -1,12 +1,9 @@ import abc -import datetime import itertools -import re import warnings from .. import utils from ..errors import RPCError -from ..extensions import markdown from ..tl import TLObject, types, functions diff --git a/telethon/events/newmessage.py b/telethon/events/newmessage.py index ec8572cf..ec0133e6 100644 --- a/telethon/events/newmessage.py +++ b/telethon/events/newmessage.py @@ -1,16 +1,9 @@ -import abc -import datetime -import itertools import re -import warnings - -from .. import utils -from ..errors import RPCError -from ..extensions import markdown -from ..tl import TLObject, types, functions - from .common import EventBuilder, EventCommon, name_inner_event +from .. import utils +from ..extensions import markdown +from ..tl import types, functions @name_inner_event @@ -155,23 +148,26 @@ class NewMessage(EventBuilder): def respond(self, *args, **kwargs): """ - Responds to the message (not as a reply). This is a shorthand for - ``client.send_message(event.chat, ...)``. + Responds to the message (not as a reply). Shorthand for + `telethon.telegram_client.TelegramClient.send_message` with + ``entity`` already set. """ return self._client.send_message(self.input_chat, *args, **kwargs) def reply(self, *args, **kwargs): """ - Replies to the message (as a reply). This is a shorthand for - ``client.send_message(event.chat, ..., reply_to=event.message.id)``. + Replies to the message (as a reply). Shorthand for + `telethon.telegram_client.TelegramClient.send_message` with + both ``entity`` and ``reply_to`` already set. """ kwargs['reply_to'] = self.message.id return self._client.send_message(self.input_chat, *args, **kwargs) def forward_to(self, *args, **kwargs): """ - Forwards the message. This is a shorthand for - ``client.forward_messages(entity, event.message, event.chat)``. + Forwards the message. Shorthand for + `telethon.telegram_client.TelegramClient.forward_messages` with + both ``messages`` and ``from_peer`` already set. """ kwargs['messages'] = self.message.id kwargs['from_peer'] = self.input_chat @@ -179,11 +175,12 @@ class NewMessage(EventBuilder): def edit(self, *args, **kwargs): """ - Edits the message iff it's outgoing. This is a shorthand for - ``client.edit_message(event.chat, event.message, ...)``. + Edits the message iff it's outgoing. Shorthand for + `telethon.telegram_client.TelegramClient.edit_message` with + both ``entity`` and ``message`` already set. - Returns ``None`` if the message was incoming, - or the edited message otherwise. + Returns ``None`` if the message was incoming, or the edited + :tl:`Message` otherwise. """ if self.message.fwd_from: return None @@ -202,8 +199,9 @@ class NewMessage(EventBuilder): """ Deletes the message. You're responsible for checking whether you have the permission to do so, or to except the error otherwise. - This is a shorthand for - ``client.delete_messages(event.chat, event.message, ...)``. + Shorthand for + `telethon.telegram_client.TelegramClient.delete_messages` with + ``entity`` and ``message_ids`` already set. """ return self._client.delete_messages(self.input_chat, [self.message], diff --git a/telethon/telegram_client.py b/telethon/telegram_client.py index 4f1ae2aa..a7421241 100644 --- a/telethon/telegram_client.py +++ b/telethon/telegram_client.py @@ -768,6 +768,12 @@ class TelegramClient(TelegramBareClient): other false-y value is provided, the message will be sent with no formatting. + If a ``callable`` is passed, it should be a function accepting + a `str` as an input and return as output a tuple consisting + of ``(parsed message str, [MessageEntity instances])``. + + See :tl:`MessageEntity` for allowed message entities. + link_preview (`bool`, optional): Should the link preview be shown? @@ -1462,9 +1468,6 @@ class TelegramClient(TelegramBareClient): 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 - immediate uploads, unless ``.clear_file_cache()`` is called. - Furthermore the file may be any media (a message, document, photo or similar) so that it can be resent without the need to download and re-upload it again. @@ -1486,7 +1489,7 @@ class TelegramClient(TelegramBareClient): ``(sent bytes, total)``. reply_to (`int` | :tl:`Message`): - Same as reply_to from .send_message(). + Same as `reply_to` from `send_message`. attributes (`list`, optional): Optional attributes that override the inferred ones, like @@ -1761,8 +1764,8 @@ class TelegramClient(TelegramBareClient): progress_callback=None): """ Uploads the specified file and returns a handle (an instance of - InputFile or InputFileBig, as required) which can be later used - before it expires (they are usable during less than a day). + :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 @@ -1775,9 +1778,6 @@ class TelegramClient(TelegramBareClient): 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 - immediate uploads, unless ``.clear_file_cache()`` is called. - part_size_kb (`int`, optional): Chunk size when uploading files. The larger, the less requests will be made (up to 512KB maximum). @@ -1788,8 +1788,8 @@ class TelegramClient(TelegramBareClient): and if this is not a ``str``, it will be ``"unnamed"``. use_cache (`type`, optional): - The type of cache to use (currently either ``InputDocument`` - or ``InputPhoto``). If present and the file is small enough + The type of cache to use (currently either :tl:`InputDocument` + or :tl:`InputPhoto`). If present and the file is small enough to need the MD5, it will be checked against the database, and if a match is found, the upload won't be made. Instead, an instance of type ``use_cache`` will be returned. @@ -1800,7 +1800,8 @@ class TelegramClient(TelegramBareClient): Returns: :tl:`InputFileBig` if the file size is larger than 10MB, - ``InputSizedFile`` (subclass of :tl:`InputFile`) otherwise. + `telethon.tl.custom.input_sized_file.InputSizedFile` + (subclass of :tl:`InputFile`) otherwise. """ if isinstance(file, (InputFile, InputFileBig)): return file # Already uploaded @@ -2357,8 +2358,9 @@ class TelegramClient(TelegramBareClient): The event builder class or instance to be used, for instance ``events.NewMessage``. - If left unspecified, ``events.Raw`` (the ``Update`` objects - with no further processing) will be passed instead. + If left unspecified, `telethon.events.raw.Raw` (the + :tl:`Update` objects with no further processing) will + be passed instead. """ if self.updates.workers is None: warnings.warn(