LonamiWebs/Telethon
1
1
Fork 0
mirror of https://github.com/LonamiWebs/Telethon.git synced 2024-09-21 03:08:49 +03:00
Code Issues 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
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

38
readthedocs/examples/projects-using-telethon.rst
View File

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

29
readthedocs/quick-references/events-reference.rst
View File

@ -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 <telethon.tl.custom.chatgetter.ChatGetter>`!
.. important::
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
=============

28
readthedocs/quick-references/faq.rst
View File

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

47
readthedocs/quick-references/objects-reference.rst
View File

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

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