From 4da7df634904e78e9751008500a596d53ef83df0 Mon Sep 17 00:00:00 2001 From: Lonami Exo Date: Sat, 14 Apr 2018 12:03:08 +0200 Subject: [PATCH] Several documentation fixes and additions --- .../advanced-usage/accessing-the-full-api.rst | 2 +- readthedocs/extra/basic/entities.rst | 24 +++++++++++++++++++ readthedocs/telethon.events.rst | 14 +++++------ telethon/telegram_client.py | 18 ++++++++++---- 4 files changed, 45 insertions(+), 13 deletions(-) diff --git a/readthedocs/extra/advanced-usage/accessing-the-full-api.rst b/readthedocs/extra/advanced-usage/accessing-the-full-api.rst index b8d63eb6..6f70f480 100644 --- a/readthedocs/extra/advanced-usage/accessing-the-full-api.rst +++ b/readthedocs/extra/advanced-usage/accessing-the-full-api.rst @@ -137,4 +137,4 @@ This can further be simplified to: __ https://lonamiwebs.github.io/Telethon __ https://lonamiwebs.github.io/Telethon/methods/index.html -__ https://lonamiwebs.github.io/Telethon/?q=message +__ https://lonamiwebs.github.io/Telethon/?q=message&redirect=no diff --git a/readthedocs/extra/basic/entities.rst b/readthedocs/extra/basic/entities.rst index c0473247..2e7d4a9a 100644 --- a/readthedocs/extra/basic/entities.rst +++ b/readthedocs/extra/basic/entities.rst @@ -26,6 +26,12 @@ in response to certain methods, such as :tl:`GetUsersRequest`. If the peer is someone in a group, you would similarly `client.get_participants(group) `. + Once you have encountered an ID, the library will (by default) have saved + their ``access_hash`` for you, which is needed to invoke most methods. + This is why sometimes you might encounter this error when working with + the library. You should ``except ValueError`` and run code that you know + should work to find the entity. + Getting entities **************** @@ -125,3 +131,21 @@ library, the raw requests you make to the API are also able to call The library will call the ``.resolve()`` method of the request, which will resolve ``'username'`` with the appropriated :tl:`InputPeer`. Don't worry if you don't get this yet, but remember some of the details here are important. + + +Full entities +************* + +In addition to :tl:`PeerUser`, :tl:`InputPeerUser`, :tl:`User` (and its +variants for chats and channels), there is also the concept of :tl:`UserFull`. + +This full variant has additional information such as whether the user is +blocked, its notification settings, the bio or about of the user, etc. + +There is also :tl:`messages.ChatFull` which is the equivalent of full entities +for chats and channels, with also the about section of the channel. Note that +the ``users`` field only contains bots for the channel (so that clients can +suggest commands to use). + +You can get both of these by invoking :tl:`GetFullUser`, :tl:`GetFullChat` +and :tl:`GetFullChannel` respectively. diff --git a/readthedocs/telethon.events.rst b/readthedocs/telethon.events.rst index 531427b9..386864fb 100644 --- a/readthedocs/telethon.events.rst +++ b/readthedocs/telethon.events.rst @@ -3,12 +3,6 @@ telethon\.events package ======================== -.. automodule:: telethon.events - :members: - :undoc-members: - :show-inheritance: - - Every event (builder) subclasses `telethon.events.common.EventBuilder`, so all the methods in it can be used from any event builder/event instance. @@ -18,8 +12,6 @@ so all the methods in it can be used from any event builder/event instance. :show-inheritance: -Below all the event types are listed: - .. automodule:: telethon.events.newmessage :members: :undoc-members: @@ -54,3 +46,9 @@ Below all the event types are listed: :members: :undoc-members: :show-inheritance: + +.. automodule:: telethon.events + :members: + :undoc-members: + :show-inheritance: + diff --git a/telethon/telegram_client.py b/telethon/telegram_client.py index 2a3f84be..72b60e61 100644 --- a/telethon/telegram_client.py +++ b/telethon/telegram_client.py @@ -727,6 +727,10 @@ class TelegramClient(TelegramBareClient): ``[mention](tg://user?id=123456789)``) and ``pre`` blocks with three backticks. + Sending a ``/start`` command with a parameter (like ``?start=data``) + is also done through this method. Simply send ``'/start data'`` to + the bot. + Args: entity (`entity`): To who will it be sent. @@ -1119,6 +1123,9 @@ 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"). + This effectively marks a message as read (or more than one) in the + given conversation. + Args: entity (`entity`): The chat where these messages are located. @@ -1868,6 +1875,10 @@ class TelegramClient(TelegramBareClient): """ Downloads the given media, or the media from a specified Message. + Note that if the download is too slow, you should consider installing + ``cryptg`` (through ``pip install cryptg``) so that decrypting the + received data is done in C instead of Python (much faster). + message (:tl:`Message` | :tl:`Media`): The media or message containing the media that will be downloaded. @@ -2489,10 +2500,9 @@ class TelegramClient(TelegramBareClient): return utils.get_input_peer(peer) raise ValueError( - 'Could not find the input entity corresponding to "{}". ' - 'Make sure you have encountered this user/chat/channel before. ' - 'If the peer is in your dialogs call client.get_dialogs().' - 'If the peer belongs to a chat call client.get_participants().' + 'Could not find the input entity for "{}". Please read https://' + 'telethon.readthedocs.io/en/latest/extra/basic/entities.html to' + 'find out more details.' .format(peer) )