hoelee/Telethon
1
0
Fork 0
mirror of https://github.com/LonamiWebs/Telethon.git synced 2025-08-09 13:29:47 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Clarify some aspects of the documentation

Browse Source
This commit is contained in:
Lonami Exo
2019-06-01 16:27:53 +02:00
parent 27360242b0
commit e47f3ec1d6
15 changed files with 148 additions and 83 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
telethon/client/chats.py
View File

@@ -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

8
telethon/client/dialogs.py
View File

@@ -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.
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 <telethon.tl.custom.draft.Draft>`.
Example
.. code-block:: python

8
telethon/client/messages.py
View File

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

6
telethon/client/uploads.py
View File

@@ -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 <telethon.tl.custom.message.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 <telethon.tl.custom.inputsizedfile.InputSizedFile>`
(subclass of :tl:`InputFile`) otherwise.
Example

4
telethon/events/chataction.py
View File

@@ -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
<telethon.tl.custom.message.Message>` object that was pinned.
"""
if self._pinned_message == 0:
return None

11
telethon/events/newmessage.py
View File

@@ -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 <telethon.tl.custom.message.Message>`,
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
available members and methods.
See `Message <telethon.tl.custom.message.Message>` for
the rest of available members and methods.
pattern_match (`obj`):
The resulting object from calling the passed ``pattern`` function.

23
telethon/tl/custom/chatgetter.py
View File

@@ -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
<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

2
telethon/tl/custom/dialog.py
View File

@@ -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(...)``.

3
telethon/tl/custom/message.py
View File

@@ -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

2
telethon/tl/custom/messagebutton.py
View File

@@ -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.

20
telethon/tl/custom/sendergetter.py
View File

@@ -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
<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