Clarify some aspects of the documentation

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
+This page lists some **interesting and useful** real world
-the library.
+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
+    Do you have an interesting project that uses the library or know of any
-    listed here? Feel free to leave a comment at
+    that's not listed here? Feel free to leave a comment at
     `issue 744 <https://github.com/LonamiWebs/Telethon/issues/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 <https://github.com/Poolitzer/spotify_telegram_bio_updater>`_ /
-`pooltalks' Telegram <https://t.me/pooltalks>`_
-
-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 <https://github.com/raphielgang/telegram-userbot>`_ /
-`baalajimaestro's site <https://baalajimaestro.ooo>`_
-
-A modular telegram Python UserBot running on python3 with an sqlalchemy database.
-
-kantek
-======
-
-`kantek <https://github.com/mojurasu/kantek>`_ /
-`mojurasu's site <https://mojurasu.com>`_
-
-kantek is a userbot written in Python using Telethon.
-
 tgcloud
 =======
 

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**
+.. important::
-`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`!
+
+    Remember that **all events base** `ChatGetter
+    <telethon.tl.custom.chatgetter.ChatGetter>`! Please see :ref:`faq`
+    if you don't know what this means or the implications of it.
 
 .. contents::
 
 
-ChatGetter
-==========
-
-All events subclass `ChatGetter <telethon.tl.custom.chatgetter.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
 =============
 

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
+<https://ddg.gg/python%20inheritance>`_. What it means is that
+"if a class bases another, you can use the other's methods too".
+
+For example, `Message <telethon.tl.custom.message.Message>` *bases*
+`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`. In turn,
+`ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>` defines
+things like `obj.chat_id <telethon.tl.custom.chatgetter.ChatGetter>`.
+
+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?
 =================================
 

readthedocs/quick-references/objects-reference.rst

@@ -13,6 +13,48 @@ to find out about the attributes.
 .. contents::
 
 
+ChatGetter
+==========
+
+All events base `ChatGetter <telethon.tl.custom.chatgetter.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 <telethon.tl.custom.chatgetter.ChatGetter>`, a
+`SenderGetter <telethon.tl.custom.sendergetter.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 <telethon.tl.custom.chatgetter.ChatGetter>` and
+`SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>`.
+
 Properties
 ----------
 
@@ -115,6 +160,8 @@ is returned by the `client.conversation()
 <telethon.client.dialogs.DialogMethods.conversation>` method to easily
 send and receive responses like a normal conversation.
 
+It bases `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`.
+
 .. currentmodule:: telethon.tl.custom.conversation.Conversation
 
 .. autosummary::

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 <telethon.tl.custom.adminlogevent.AdminLogEvent>`.
 
         Example
             .. code-block:: python

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 <telethon.tl.custom.dialog.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.
+        Yields
-        You can call `telethon.tl.custom.draft.Draft.set_message`
+            Instances of `Draft <telethon.tl.custom.draft.Draft>`.
-        to change the message or `telethon.tl.custom.draft.Draft.delete`
-        among other things.
 
         Example
             .. code-block:: python

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 <telethon.tl.custom.message.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 <telethon.tl.custom.message.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
+            The edited `Message <telethon.tl.custom.message.Message>`,
-            `entity` was a :tl:`InputBotInlineMessageID` in which
+            unless `entity` was a :tl:`InputBotInlineMessageID` in which
             case this method returns a boolean.
 
         Raises

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 `Message <telethon.tl.custom.message.Message>` (or messages)
-            the sent file, or messages if a list of them was passed.
+            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 <telethon.tl.custom.inputsizedfile.InputSizedFile>`
             (subclass of :tl:`InputFile`) otherwise.
 
         Example

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
+            If ``new_pin`` is ``True``, this returns the `Message
-            `telethon.tl.custom.message.Message` object that was pinned.
+            <telethon.tl.custom.message.Message>` object that was pinned.
             """
             if self._pinned_message == 0:
                 return None

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
+        to all effects as a `Message <telethon.tl.custom.message.Message>`,
-        **refer to its documentation** to know what you can do with this event.
+        so please **refer to its documentation** to know what you can do
+        with this event.
 
         Members:
             message (`Message <telethon.tl.custom.message.Message>`):
                 This is the only difference with the received
-                `telethon.tl.custom.message.Message`, and will
+                `Message <telethon.tl.custom.message.Message>`, and will
                 return the `telethon.tl.custom.message.Message` itself,
                 not the text.
 
-                See `telethon.tl.custom.message.Message` for the rest of
+                See `Message <telethon.tl.custom.message.Message>` for
-                available members and methods.
+                the rest of available members and methods.
 
             pattern_match (`obj`):
                 The resulting object from calling the passed ``pattern`` function.

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
+        message was sent. Similarly to `input_sender
-        things like username or similar, but still useful in some cases.
+        <telethon.tl.custom.sendergetter.SenderGetter.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 <chat>`.
         """
         return utils.get_peer_id(self._chat_peer) if self._chat_peer else None
 

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 <telethon.tl.custom.draft.Draft>`):
             The draft object in this dialog. It will not be ``None``,
             so you can call ``draft.set_message(...)``.
 

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 <telethon.tl.custom.messagebutton.MessageButton>`
+                argument.
 
             data (`bytes`):
                 This argument overrides the rest and will not search any

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 <telethon.tl.custom.message.Message>` returned.
 
         If it's an inline :tl:`KeyboardButtonCallback` with text and data,
         it will be "clicked" and the :tl:`BotCallbackAnswer` returned.

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
+        sent the message. Similarly to `input_chat
-        things like username or similar, but still useful in some cases.
+        <telethon.tl.custom.chatgetter.ChatGetter.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 <sender>`.
         """
         return self._sender_id