diff --git a/readthedocs/examples/projects-using-telethon.rst b/readthedocs/examples/projects-using-telethon.rst index 60c29ceb..bc286350 100644 --- a/readthedocs/examples/projects-using-telethon.rst +++ b/readthedocs/examples/projects-using-telethon.rst @@ -4,16 +4,21 @@ Projects using Telethon ======================= -This page lists some real world examples showcasing what can be built with -the library. +This page lists some **interesting and useful** real world +examples showcasing what can be built with the library. .. note:: - Do you have a project that uses the library or know of any that's not - listed here? Feel free to leave a comment at + Do you have an interesting project that uses the library or know of any + that's not listed here? Feel free to leave a comment at `issue 744 `_ so it can be included in the next revision of the documentation! + You can also advertise your bot and its features, in the issue, although + it should be a big project which can be useful for others before being + included here, so please don't feel offended if it can't be here! + + .. _projects-telegram-export: telethon_examples/ @@ -63,31 +68,6 @@ TelegramTUI A Telegram client on your terminal. -spotify_telegram_bio_updater -============================ - -`spotify_telegram_bio_updater `_ / -`pooltalks' Telegram `_ - -Small project that updates the biography of a telegram user according -to their current Spotify playback, or revert it if no playback is active. - -Telegram-UserBot -================ - -`Telegram-UserBot `_ / -`baalajimaestro's site `_ - -A modular telegram Python UserBot running on python3 with an sqlalchemy database. - -kantek -====== - -`kantek `_ / -`mojurasu's site `_ - -kantek is a userbot written in Python using Telethon. - tgcloud ======= diff --git a/readthedocs/quick-references/events-reference.rst b/readthedocs/quick-references/events-reference.rst index 89c4cee2..ead94a15 100644 --- a/readthedocs/quick-references/events-reference.rst +++ b/readthedocs/quick-references/events-reference.rst @@ -10,34 +10,15 @@ You can access the client that creates this event by doing events to find out what arguments it allows on creation and its **attributes** (the properties will be shown here). -It is important to remember that **all events subclass** -`ChatGetter `! +.. important:: + + Remember that **all events base** `ChatGetter + `! Please see :ref:`faq` + if you don't know what this means or the implications of it. .. contents:: -ChatGetter -========== - -All events subclass `ChatGetter `, -which means all events have (and you can access to): - -.. currentmodule:: telethon.tl.custom.chatgetter.ChatGetter - -.. autosummary:: - :nosignatures: - - chat - input_chat - chat_id - is_private - is_group - is_channel - - get_chat - get_input_chat - - CallbackQuery ============= diff --git a/readthedocs/quick-references/faq.rst b/readthedocs/quick-references/faq.rst index 4bf68bb1..70ab9bfa 100644 --- a/readthedocs/quick-references/faq.rst +++ b/readthedocs/quick-references/faq.rst @@ -1,3 +1,5 @@ +.. _faq: + === FAQ === @@ -177,6 +179,32 @@ won't do unnecessary work unless you need to: sender = await event.get_sender() +What does "bases ChatGetter" mean? +================================== + +In Python, classes can base others. This is called `inheritance +`_. What it means is that +"if a class bases another, you can use the other's methods too". + +For example, `Message ` *bases* +`ChatGetter `. In turn, +`ChatGetter ` defines +things like `obj.chat_id `. + +So if you have a message, you can access that too: + +.. code-block:: python + + # ChatGetter has a chat_id property, and Message bases ChatGetter. + # Thus you can use ChatGetter properties and methods from Message + print(message.chat_id) + + +Telegram has a lot to offer, and inheritance helps the library reduce +boilerplate, so it's important to know this concept. For newcomers, +this may be a problem, so we explain what it means here in the FAQ. + + Can I use Flask with the library? ================================= diff --git a/readthedocs/quick-references/objects-reference.rst b/readthedocs/quick-references/objects-reference.rst index 211b16cf..4a09ff74 100644 --- a/readthedocs/quick-references/objects-reference.rst +++ b/readthedocs/quick-references/objects-reference.rst @@ -13,6 +13,48 @@ to find out about the attributes. .. contents:: +ChatGetter +========== + +All events base `ChatGetter `, +and some of the objects below do too, so it's important to know its methods. + +.. currentmodule:: telethon.tl.custom.chatgetter.ChatGetter + +.. autosummary:: + :nosignatures: + + chat + input_chat + chat_id + is_private + is_group + is_channel + + get_chat + get_input_chat + + +SenderGetter +============ + +Similar to `ChatGetter `, a +`SenderGetter ` is the same, +but it works for senders instead. + +.. currentmodule:: telethon.tl.custom.sendergetter.SenderGetter + +.. autosummary:: + :nosignatures: + + sender + input_sender + sender_id + + get_sender + get_input_sender + + Message ======= @@ -22,6 +64,9 @@ The `Message` type is very important, mostly because we are working with a library for a *messaging* platform, so messages are widely used: in events, when fetching history, replies, etc. +It bases `ChatGetter ` and +`SenderGetter `. + Properties ---------- @@ -115,6 +160,8 @@ is returned by the `client.conversation() ` method to easily send and receive responses like a normal conversation. +It bases `ChatGetter `. + .. currentmodule:: telethon.tl.custom.conversation.Conversation .. autosummary:: diff --git a/telethon/client/chats.py b/telethon/client/chats.py index cd748039..f1bb6040 100644 --- a/telethon/client/chats.py +++ b/telethon/client/chats.py @@ -553,7 +553,7 @@ class ChatMethods(UserMethods): If ``True``, events of message deletions will be returned. Yields - Instances of `telethon.tl.custom.adminlogevent.AdminLogEvent`. + Instances of `AdminLogEvent `. Example .. code-block:: python diff --git a/telethon/client/dialogs.py b/telethon/client/dialogs.py index 12fbe13b..d6552e16 100644 --- a/telethon/client/dialogs.py +++ b/telethon/client/dialogs.py @@ -160,7 +160,7 @@ class DialogMethods(UserMethods): Alias for `folder`. If unspecified, all will be returned, ``False`` implies ``folder=0`` and ``True`` implies ``folder=1``. Yields - Instances of `telethon.tl.custom.dialog.Dialog`. + Instances of `Dialog `. Example .. code-block:: python @@ -212,10 +212,8 @@ class DialogMethods(UserMethods): """ Iterator over all open draft messages. - Instances of `telethon.tl.custom.draft.Draft` are yielded. - You can call `telethon.tl.custom.draft.Draft.set_message` - to change the message or `telethon.tl.custom.draft.Draft.delete` - among other things. + Yields + Instances of `Draft `. Example .. code-block:: python diff --git a/telethon/client/messages.py b/telethon/client/messages.py index 2c26824b..cfb79462 100644 --- a/telethon/client/messages.py +++ b/telethon/client/messages.py @@ -415,7 +415,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods): You cannot use this if both `entity` and `ids` are ``None``. Yields - Instances of `telethon.tl.custom.message.Message`. + Instances of `Message `. Example .. code-block:: python @@ -776,7 +776,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods): images into albums), and ``False`` will never group. Returns - The list of forwarded `telethon.tl.custom.message.Message`, + The list of forwarded `Message `, or a single one if a list wasn't provided as input. Note that if all messages are invalid (i.e. deleted) the call @@ -925,8 +925,8 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods): :tl:`ReplyMarkup` here. Returns - The edited `telethon.tl.custom.message.Message`, unless - `entity` was a :tl:`InputBotInlineMessageID` in which + The edited `Message `, + unless `entity` was a :tl:`InputBotInlineMessageID` in which case this method returns a boolean. Raises diff --git a/telethon/client/uploads.py b/telethon/client/uploads.py index 5fbb6296..1fd5e6ca 100644 --- a/telethon/client/uploads.py +++ b/telethon/client/uploads.py @@ -231,8 +231,8 @@ class UploadMethods(ButtonMethods, MessageParseMethods, UserMethods): Unsupported formats will result in ``VideoContentTypeError``. Returns - The `telethon.tl.custom.message.Message` (or messages) containing - the sent file, or messages if a list of them was passed. + The `Message ` (or messages) + containing the sent file, or messages if a list of them was passed. Example .. code-block:: python @@ -451,7 +451,7 @@ class UploadMethods(ButtonMethods, MessageParseMethods, UserMethods): Returns :tl:`InputFileBig` if the file size is larger than 10MB, - `telethon.tl.custom.inputsizedfile.InputSizedFile` + `InputSizedFile ` (subclass of :tl:`InputFile`) otherwise. Example diff --git a/telethon/events/chataction.py b/telethon/events/chataction.py index ea92dc23..6359cad6 100644 --- a/telethon/events/chataction.py +++ b/telethon/events/chataction.py @@ -212,8 +212,8 @@ class ChatAction(EventBuilder): async def get_pinned_message(self): """ - If ``new_pin`` is ``True``, this returns the - `telethon.tl.custom.message.Message` object that was pinned. + If ``new_pin`` is ``True``, this returns the `Message + ` object that was pinned. """ if self._pinned_message == 0: return None diff --git a/telethon/events/newmessage.py b/telethon/events/newmessage.py index 1c70f7a8..62d5deee 100644 --- a/telethon/events/newmessage.py +++ b/telethon/events/newmessage.py @@ -158,18 +158,19 @@ class NewMessage(EventBuilder): class Event(EventCommon): """ Represents the event of a new message. This event can be treated - to all effects as a `telethon.tl.custom.message.Message`, so please - **refer to its documentation** to know what you can do with this event. + to all effects as a `Message `, + so please **refer to its documentation** to know what you can do + with this event. Members: message (`Message `): This is the only difference with the received - `telethon.tl.custom.message.Message`, and will + `Message `, and will return the `telethon.tl.custom.message.Message` itself, not the text. - See `telethon.tl.custom.message.Message` for the rest of - available members and methods. + See `Message ` for + the rest of available members and methods. pattern_match (`obj`): The resulting object from calling the passed ``pattern`` function. diff --git a/telethon/tl/custom/chatgetter.py b/telethon/tl/custom/chatgetter.py index 78d294db..82d07a0a 100644 --- a/telethon/tl/custom/chatgetter.py +++ b/telethon/tl/custom/chatgetter.py @@ -23,7 +23,12 @@ class ChatGetter(abc.ABC): Returns the :tl:`User`, :tl:`Chat` or :tl:`Channel` where this object belongs to. It may be ``None`` if Telegram didn't send the chat. - If you're using `telethon.events`, use `get_chat` instead. + If you only need the ID, use `chat_id` instead. + + If you need to call a method which needs + this chat, use `input_chat` instead. + + If you're using `telethon.events`, use `get_chat()` instead. """ return self._chat @@ -31,6 +36,11 @@ class ChatGetter(abc.ABC): """ Returns `chat`, but will make an API call to find the chat unless it's already cached. + + If you only need the ID, use `chat_id` instead. + + If you need to call a method which needs + this chat, use `get_input_chat()` instead. """ # See `get_sender` for information about 'min'. if (self._chat is None or getattr(self._chat, 'min', None))\ @@ -46,8 +56,10 @@ class ChatGetter(abc.ABC): def input_chat(self): """ This :tl:`InputPeer` is the input version of the chat where the - message was sent. Similarly to `input_sender`, this doesn't have - things like username or similar, but still useful in some cases. + message was sent. Similarly to `input_sender + `, this + doesn't have things like username or similar, but still useful in + some cases. Note that this might not be available if the library doesn't have enough information available. @@ -83,11 +95,14 @@ class ChatGetter(abc.ABC): def chat_id(self): """ Returns the marked chat integer ID. Note that this value **will - be different** from `to_id` for incoming private messages, since + be different** from ``to_id`` for incoming private messages, since the chat *to* which the messages go is to your own person, but the *chat* itself is with the one who sent the message. TL;DR; this gets the ID that you expect. + + If there is a chat in the object, `chat_id` will *always* be set, + which is why you should use it instead of `chat.id `. """ return utils.get_peer_id(self._chat_peer) if self._chat_peer else None diff --git a/telethon/tl/custom/dialog.py b/telethon/tl/custom/dialog.py index 10510052..8e82feaa 100644 --- a/telethon/tl/custom/dialog.py +++ b/telethon/tl/custom/dialog.py @@ -55,7 +55,7 @@ class Dialog: How many mentions are currently unread in this dialog. Note that this value won't update when new messages arrive. - draft (`telethon.tl.custom.draft.Draft`): + draft (`Draft `): The draft object in this dialog. It will not be ``None``, so you can call ``draft.set_message(...)``. diff --git a/telethon/tl/custom/message.py b/telethon/tl/custom/message.py index fc2a71a5..373feec5 100644 --- a/telethon/tl/custom/message.py +++ b/telethon/tl/custom/message.py @@ -781,7 +781,8 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC): filter (`callable`): Clicks the first button for which the callable returns ``True``. The callable should accept a single - `telethon.tl.custom.messagebutton.MessageButton` argument. + `MessageButton ` + argument. data (`bytes`): This argument overrides the rest and will not search any diff --git a/telethon/tl/custom/messagebutton.py b/telethon/tl/custom/messagebutton.py index 8ac530fe..9d18804c 100644 --- a/telethon/tl/custom/messagebutton.py +++ b/telethon/tl/custom/messagebutton.py @@ -64,7 +64,7 @@ class MessageButton: Emulates the behaviour of clicking this button. If it's a normal :tl:`KeyboardButton` with text, a message will be - sent, and the sent `telethon.tl.custom.message.Message` returned. + sent, and the sent `Message ` returned. If it's an inline :tl:`KeyboardButtonCallback` with text and data, it will be "clicked" and the :tl:`BotCallbackAnswer` returned. diff --git a/telethon/tl/custom/sendergetter.py b/telethon/tl/custom/sendergetter.py index f03c4f92..37ea39fa 100644 --- a/telethon/tl/custom/sendergetter.py +++ b/telethon/tl/custom/sendergetter.py @@ -19,7 +19,12 @@ class SenderGetter(abc.ABC): Returns the :tl:`User` or :tl:`Channel` that sent this object. It may be ``None`` if Telegram didn't send the sender. - If you're using `telethon.events`, use `get_sender` instead. + If you only need the ID, use `sender_id` instead. + + If you need to call a method which needs + this chat, use `input_sender` instead. + + If you're using `telethon.events`, use `get_sender()` instead. """ return self._sender @@ -27,6 +32,11 @@ class SenderGetter(abc.ABC): """ Returns `sender`, but will make an API call to find the sender unless it's already cached. + + If you only need the ID, use `sender_id` instead. + + If you need to call a method which needs + this sender, use `get_input_sender()` instead. """ # ``sender.min`` is present both in :tl:`User` and :tl:`Channel`. # It's a flag that will be set if only minimal information is @@ -47,8 +57,9 @@ class SenderGetter(abc.ABC): def input_sender(self): """ This :tl:`InputPeer` is the input version of the user/channel who - sent the message. Similarly to `input_chat`, this doesn't have - things like username or similar, but still useful in some cases. + sent the message. Similarly to `input_chat + `, this doesn't + have things like username or similar, but still useful in some cases. Note that this might not be available if the library can't find the input chat, or if the message a broadcast on a channel. @@ -74,6 +85,9 @@ class SenderGetter(abc.ABC): def sender_id(self): """ Returns the marked sender integer ID, if present. + + If there is a sender in the object, `sender_id` will *always* be set, + which is why you should use it instead of `sender.id `. """ return self._sender_id