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

Completely overhaul the documentation

Browse Source
This commit is contained in:
Lonami Exo
2019-05-09 12:24:37 +02:00
parent 10251f9782
commit 0a3d6106f0
75 changed files with 2410 additions and 2895 deletions
Download Patch File Download Diff File Expand all files Collapse all files

16
telethon/client/account.py
View File

@@ -120,7 +120,7 @@ class AccountMethods(UserMethods):
files: bool = None,
max_file_size: bool = None) -> 'TelegramClient':
"""
Returns a :ref:`TelegramClient` which calls methods behind a takeout session.
Returns a :ref:`telethon-client` which calls methods behind a takeout session.
It does so by creating a proxy object over the current client through
which making requests will use :tl:`InvokeWithTakeoutRequest` to wrap
@@ -190,6 +190,20 @@ class AccountMethods(UserMethods):
max_file_size (`int`):
The maximum file size, in bytes, that you plan
to download for each message with media.
Example:
.. code-block:: python
from telethon import errors
try:
with client.takeout() as takeout:
for message in takeout.iter_messages(chat, wait_time=0):
... # Do something with the message
except errors.TakeoutInitDelayError as e:
print('Must wait', e.seconds, 'before takeout')
"""
request_kwargs = dict(
contacts=contacts,

32
telethon/client/auth.py
View File

@@ -40,13 +40,6 @@ class AuthMethods(MessageParseMethods, UserMethods):
will be banned otherwise.** See https://telegram.org/tos
and https://core.telegram.org/api/terms.
Example usage:
>>> client = ...
>>> client.start(phone)
Please enter the code you received: 12345
Please enter your password: *******
(You are now logged in)
If the event loop is already running, this method returns a
coroutine that you should await on your own code; otherwise
the loop is ran until said coroutine completes.
@@ -91,6 +84,24 @@ class AuthMethods(MessageParseMethods, UserMethods):
Returns:
This `TelegramClient`, so initialization
can be chained with ``.start()``.
Example:
.. code-block:: python
client = TelegramClient('anon', api_id, api_hash)
# Starting as a bot account
client.start(bot_token=bot_token)
# Starting as an user account
client.start(phone)
# Please enter the code you received: 12345
# Please enter your password: *******
# (You are now logged in)
# Starting using a context manager (this calls start()):
with client:
pass
"""
if code_callback is None:
def code_callback():
@@ -452,6 +463,13 @@ class AuthMethods(MessageParseMethods, UserMethods):
Returns:
``True`` if the operation was successful.
Example:
.. code-block:: python
# Note: you will need to login again!
client.log_out()
"""
try:
await self(functions.auth.LogOutRequest())

10
telethon/client/bots.py
View File

@@ -39,6 +39,16 @@ class BotMethods(UserMethods):
Returns:
A list of `custom.InlineResult
<telethon.tl.custom.inlineresult.InlineResult>`.
Example:
.. code-block:: python
# Make an inline query to @like
results = client.inline_query('like', 'Do you like Telethon?')
# Send the first result to some chat
message = results[0].click('TelethonOffTopic')
"""
bot = await self.get_input_entity(bot)
result = await self(functions.messages.GetInlineBotResultsRequest(

35
telethon/client/chats.py
View File

@@ -328,6 +328,23 @@ class ChatMethods(UserMethods):
with an additional ``.participant`` attribute which is the
matched :tl:`ChannelParticipant` type for channels/megagroups
or :tl:`ChatParticipants` for normal chats.
Example:
.. code-block:: python
# Show all user IDs in a chat
for user in client.iter_participants(chat):
print(user.id)
# Search by name
for user in client.iter_participants(chat, search='name'):
print(user.username)
# Filter by admins
from telethon.tl.types import ChannelParticipantsAdmins
for user in client.iter_participants(chat, filter=ChannelParticipantsAdmins):
print(user.first_name)
"""
return _ParticipantsIter(
self,
@@ -343,7 +360,7 @@ class ChatMethods(UserMethods):
*args,
**kwargs) -> 'hints.TotalList':
"""
Same as `iter_participants`, but returns a
Same as `iter_participants()`, but returns a
`TotalList <telethon.helpers.TotalList>` instead.
"""
return await self.iter_participants(*args, **kwargs).collect()
@@ -457,6 +474,20 @@ class ChatMethods(UserMethods):
Yields:
Instances of `telethon.tl.custom.adminlogevent.AdminLogEvent`.
Example:
.. code-block:: python
for event in client.iter_admin_log(channel):
if event.changed_title:
print('The title changed from', event.old, 'to', event.new)
# Get a list of deleted message events which said "heck"
events = client.get_admin_log(channel, search='heck', delete=True)
# Print the old message before it was deleted
print(events[0].old)
"""
return _AdminLogIter(
self,
@@ -487,7 +518,7 @@ class ChatMethods(UserMethods):
*args,
**kwargs) -> 'hints.TotalList':
"""
Same as `iter_admin_log`, but returns a ``list`` instead.
Same as `iter_admin_log()`, but returns a ``list`` instead.
"""
return await self.iter_admin_log(*args, **kwargs).collect()

48
telethon/client/dialogs.py
View File

@@ -138,6 +138,21 @@ class DialogMethods(UserMethods):
Yields:
Instances of `telethon.tl.custom.dialog.Dialog`.
Example:
.. code-block:: python
# Get all open conversation, print the title of the first
dialogs = client.get_dialogs()
first = dialogs[0]
print(first.title)
# Use the dialog somewhere else
client.send_message(first, 'hi')
# Get drafts
drafts = client.get_drafts()
"""
return _DialogsIter(
self,
@@ -150,7 +165,7 @@ class DialogMethods(UserMethods):
async def get_dialogs(self: 'TelegramClient', *args, **kwargs) -> 'hints.TotalList':
"""
Same as `iter_dialogs`, but returns a
Same as `iter_dialogs()`, but returns a
`TotalList <telethon.helpers.TotalList>` instead.
"""
return await self.iter_dialogs(*args, **kwargs).collect()
@@ -169,7 +184,7 @@ class DialogMethods(UserMethods):
async def get_drafts(self: 'TelegramClient') -> 'hints.TotalList':
"""
Same as :meth:`iter_drafts`, but returns a list instead.
Same as `iter_drafts()`, but returns a list instead.
"""
return await self.iter_drafts().collect()
@@ -257,6 +272,35 @@ class DialogMethods(UserMethods):
Returns:
A `Conversation <telethon.tl.custom.conversation.Conversation>`.
Example:
.. code-block:: python
# <you> denotes outgoing messages you sent
# <usr> denotes incoming response messages
with bot.conversation(chat) as conv:
# <you> Hi!
conv.send_message('Hi!')
# <usr> Hello!
hello = conv.get_response()
# <you> Please tell me your name
conv.send_message('Please tell me your name')
# <usr> ?
name = conv.get_response().raw_text
while not any(x.isalpha() for x in name):
# <you> Your name didn't have any letters! Try again
conv.send_message("Your name didn't have any letters! Try again")
# <usr> Lonami
name = conv.get_response().raw_text
# <you> Thanks Lonami!
conv.send_message('Thanks {}!'.format(name))
"""
return custom.Conversation(
self,

18
telethon/client/downloads.py
View File

@@ -56,6 +56,13 @@ class DownloadMethods(UserMethods):
Returns:
``None`` if no photo was provided, or if it was Empty. On success
the file path is returned since it may differ from the one given.
Example:
.. code-block:: python
path = client.download_profile_photo('me')
print(path)
"""
# hex(crc32(x.encode('ascii'))) for x in
# ('User', 'Chat', 'UserFull', 'ChatFull')
@@ -173,6 +180,17 @@ class DownloadMethods(UserMethods):
Returns:
``None`` if no media was provided, or if it was Empty. On success
the file path is returned since it may differ from the one given.
Example:
.. code-block:: python
path = client.download_media(message)
client.download_media(message, filename)
# or
path = message.download_media()
message.download_media(filename)
"""
# TODO This won't work for messageService
if isinstance(message, types.Message):

148
telethon/client/messages.py
View File

@@ -413,6 +413,31 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
Telegram's flood wait limit for :tl:`GetHistoryRequest` seems to
be around 30 seconds per 10 requests, therefore a sleep of 1
second is the default for this limit (or above).
Example:
.. code-block:: python
# From most-recent to oldest
for message in client.iter_messages(chat):
print(message.id, message.text)
# From oldest to most-recent
for message in client.iter_messages(chat, reverse=True):
print(message.id, message.text)
# Filter by sender
for message in client.iter_messages(chat, from_user='me'):
print(message.text)
# Server-side search with fuzzy text
for message in client.iter_messages(chat, search='hello'):
print(message.id)
# Filter by message type:
from telethon.tl.types import InputMessagesFilterPhotos
for message in client.iter_messages(chat, filter=InputMessagesFilterPhotos):
print(message.photo)
"""
if ids is not None:
@@ -436,7 +461,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
async def get_messages(self: 'TelegramClient', *args, **kwargs) -> 'hints.TotalList':
"""
Same as `iter_messages`, but returns a
Same as `iter_messages()`, but returns a
`TotalList <telethon.helpers.TotalList>` instead.
If the `limit` is not set, it will be 1 by default unless both
@@ -450,6 +475,21 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
If `ids` is present in the *named* arguments and is not a list,
a single `Message <telethon.tl.custom.message.Message>` will be
returned for convenience instead of a list.
Example:
.. code-block:: python
# Get 0 photos and print the total to show how many photos there are
from telethon.tl.types import InputMessagesFilterPhotos
photos = client.get_messages(chat, 0, filter=InputMessagesFilterPhotos)
print(photos.total)
# Get all the photos
photos = client.get_messages(chat, None, filter=InputMessagesFilterPhotos)
# Get messages by ID:
message_1337 = client.get_messages(chats, ids=1337)
"""
if len(args) == 1 and 'limit' not in kwargs:
if 'min_id' in kwargs and 'max_id' in kwargs:
@@ -501,6 +541,7 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
the bot.
Args:
entity (`entity`):
To who will it be sent.
@@ -556,7 +597,65 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
notify them. Set it to ``True`` to alter this behaviour.
Returns:
The sent `custom.Message <telethon.tl.custom.message.Message>`.
Example:
.. code-block:: python
client.send_message('lonami', 'Thanks for the Telethon library!')
# Replies and responses
message = client.send_message('me', 'Trying out **markdown**')
message.reply('Trying replies')
message.respond('Trying responses')
# Default to another parse mode
client.parse_mode = 'html'
client.send_message('me', 'Some <b>bold</b> and <i>italic</i> text')
client.send_message('me', 'An <a href="https://example.com">URL</a>')
client.send_message('me', '<code>code</code> and <pre>pre\nblocks</pre>')
client.send_message('me', '<a href="tg://user?id=me">Mentions</a>')
# Explicit parse mode
# No parse mode by default
client.parse_mode = None
# ...but here I want markdown
client.send_message('me', 'Hello, **world**!', parse_mode='md')
# ...and here I need HTML
client.send_message('me', 'Hello, <i>world</i>!', parse_mode='html')
# If you logged in as a bot account, you can send buttons
from telethon import events, Button
@client.on(events.CallbackQuery)
async def callback(event):
await event.edit('Thank you for clicking {}!'.format(event.data))
# Single inline button
client.send_message(chat, 'A single button, with "clk1" as data',
buttons=Button.inline('Click me', b'clk1'))
# Matrix of inline buttons
client.send_message(chat, 'Pick one from this grid', buttons=[
[Button.inline('Left'), Button.inline('Right')],
[Button.url('Check this site!', 'https://lonamiwebs.github.io')]
])
# Reply keyboard
client.send_message(chat, 'Welcome', buttons=[
Button.text('Thanks!', resize=True, single_use=True),
Button.request_phone('Send phone'),
Button.request_location('Send location')
])
# Forcing replies or clearing buttons.
client.send_message(chat, 'Reply to me', buttons=Button.force_reply())
client.send_message(chat, 'Bye Keyboard!', buttons=Button.clear())
"""
if file is not None:
return await self.send_file(
@@ -685,6 +784,25 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
Note that if all messages are invalid (i.e. deleted) the call
will fail with ``MessageIdInvalidError``. If only some are
invalid, the list will have ``None`` instead of those messages.
Example:
.. code-block:: python
# a single one
client.forward_messages(chat, message)
# or
client.forward_messages(chat, message_id, from_chat)
# or
message.forward_to(chat)
# multiple
client.forward_messages(chat, messages)
# or
client.forward_messages(chat, message_ids, from_chat)
# Forwarding as a copy
client.send_message(chat, message)
"""
single = not utils.is_list_like(messages)
if single:
@@ -829,6 +947,16 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
The edited `telethon.tl.custom.message.Message`, unless
`entity` was a :tl:`InputBotInlineMessageID` in which
case this method returns a boolean.
Example:
.. code-block:: python
client.edit_message(message, 'New text')
# or
message.edit('New text')
# or
client.edit_message(chat, message_id, 'New text')
"""
if isinstance(entity, types.InputBotInlineMessageID):
text = message
@@ -900,6 +1028,14 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
Returns:
A list of :tl:`AffectedMessages`, each item being the result
for the delete calls of the messages in chunks of 100 each.
Example:
.. code-block:: python
client.delete_messages(chat, messages)
# or
message.delete()
"""
if not utils.is_list_like(message_ids):
message_ids = (message_ids,)
@@ -955,6 +1091,16 @@ class MessageMethods(UploadMethods, ButtonMethods, MessageParseMethods):
If no message is provided, this will be the only action
taken.
Example:
.. code-block:: python
client.send_read_acknowledge(last_message)
# or
client.send_read_acknowledge(last_message_id)
# or
client.send_read_acknowledge(messages)
"""
if max_id is None:
if not message:

7
telethon/client/telegrambaseclient.py
View File

@@ -396,6 +396,13 @@ class TelegramBaseClient(abc.ABC):
If the event loop is already running, this method returns a
coroutine that you should await on your own code; otherwise
the loop is ran until said coroutine completes.
Example:
.. code-block:: python
# You don't need to use this if you used "with client"
client.disconnect()
"""
if self._loop.is_running():
return self._disconnect_coro()

2
telethon/client/updates.py
View File

@@ -117,7 +117,7 @@ class UpdateMethods(UserMethods):
callback: callable,
event: EventBuilder = None) -> int:
"""
Inverse operation of `add_event_handler`.
Inverse operation of `add_event_handler()`.
If no event is given, all events for this callback are removed.
Returns how many callbacks were removed.

43
telethon/client/uploads.py
View File

@@ -232,6 +232,32 @@ class UploadMethods(ButtonMethods, MessageParseMethods, UserMethods):
Returns:
The `telethon.tl.custom.message.Message` (or messages) containing
the sent file, or messages if a list of them was passed.
Example:
.. code-block:: python
# Normal files like photos
client.send_file(chat, '/my/photos/me.jpg', caption="It's me!")
# or
client.send_message(chat, "It's me!", file='/my/photos/me.jpg')
# Voice notes or round videos
client.send_file(chat, '/my/songs/song.mp3', voice_note=True)
client.send_file(chat, '/my/videos/video.mp4', video_note=True)
# Custom thumbnails
client.send_file(chat, '/my/documents/doc.txt', thumb='photo.jpg')
# Only documents
client.send_file(chat, '/my/photos/photo.png', force_document=True)
# Albums
client.send_file(chat, [
'/my/photos/holiday1.jpg',
'/my/photos/holiday2.jpg',
'/my/drawings/portrait.png'
])
"""
# i.e. ``None`` was used
if not file:
@@ -427,6 +453,23 @@ class UploadMethods(ButtonMethods, MessageParseMethods, UserMethods):
:tl:`InputFileBig` if the file size is larger than 10MB,
`telethon.tl.custom.inputsizedfile.InputSizedFile`
(subclass of :tl:`InputFile`) otherwise.
Example:
.. code-block:: python
# Photos as photo and document
file = client.upload_file('photo.jpg')
client.send_file(chat, file) # sends as photo
client.send_file(chat, file, force_document=True) # sends as document
file.name = 'not a photo.jpg'
client.send_file(chat, file, force_document=True) # document, new name
# As song or as voice note
file = client.upload_file('song.ogg')
client.send_file(chat, file) # sends as song
client.send_file(chat, file, voice_note=True) # sends as voice note
"""
if isinstance(file, (types.InputFile, types.InputFileBig)):
return file # Already uploaded

21
telethon/client/users.py
View File

@@ -191,6 +191,27 @@ class UserMethods(TelegramBaseClient):
Returns:
:tl:`User`, :tl:`Chat` or :tl:`Channel` corresponding to the
input entity. A list will be returned if more than one was given.
Example:
.. code-block:: python
from telethon import utils
me = client.get_entity('me')
print(utils.get_display_name(me))
chat = client.get_input_entity('username')
for message in client.iter_messages(chat):
...
# Note that you could have used the username directly, but it's
# good to use get_input_entity if you will reuse it a lot.
for message in client.iter_messages('username'):
...
# Note that for this to work the phone number must be in your contacts
some_id = client.get_peer_id('+34123456789')
"""
single = not utils.is_list_like(entity)
if single:

2
telethon/events/__init__.py
View File

@@ -42,7 +42,7 @@ class StopPropagation(Exception):
def register(event=None):
"""
Decorator method to *register* event handlers. This is the client-less
`add_event_handler
`add_event_handler()
<telethon.client.updates.UpdateMethods.add_event_handler>` variant.
Note that this method only registers callbacks as handlers,

14
telethon/events/inlinequery.py
View File

@@ -178,6 +178,20 @@ class InlineQuery(EventBuilder):
switch_pm_param (`str`, optional):
Optional parameter to start the bot with if
`switch_pm` was used.
Example:
.. code-block:: python
@bot.on(events.InlineQuery)
async def handler(event):
builder = event.builder
rev_text = event.text[::-1]
await event.answer([
builder.article('Reverse text', text=rev_text),
builder.photo('/path/to/photo.jpg')
])
"""
if self._answered:
return

2
telethon/events/messageread.py
View File

@@ -95,7 +95,7 @@ class MessageRead(EventBuilder):
async def get_messages(self):
"""
Returns the list of `telethon.tl.custom.message.Message`
Returns the list of `Message <telethon.tl.custom.message.Message>`
**which contents'** were read.
Use :meth:`is_read` if you need to check whether a message

10
telethon/events/userupdate.py
View File

@@ -190,23 +190,23 @@ class UserUpdate(EventBuilder):
@property
def user(self):
"""Alias for `sender`."""
"""Alias for `sender <telethon.tl.custom.sendergetter.SenderGetter.sender>`."""
return self.sender
async def get_user(self):
"""Alias for `get_sender`."""
"""Alias for `get_sender <telethon.tl.custom.sendergetter.SenderGetter.get_sender>`."""
return await self.get_sender()
@property
def input_user(self):
"""Alias for `input_sender`."""
"""Alias for `input_sender <telethon.tl.custom.sendergetter.SenderGetter.input_sender>`."""
return self.input_sender
async def get_input_user(self):
"""Alias for `get_input_sender`."""
"""Alias for `get_input_sender <telethon.tl.custom.sendergetter.SenderGetter.get_input_sender>`."""
return await self.get_input_sender()
@property
def user_id(self):
"""Alias for `sender_id`."""
"""Alias for `sender_id <telethon.tl.custom.sendergetter.SenderGetter.sender_id>`."""
return self.sender_id

8
telethon/tl/custom/inlinebuilder.py
View File

@@ -33,11 +33,11 @@ class InlineBuilder:
May be ``True`` to indicate that the game will be sent.
buttons (`list`, `custom.Button <telethon.tl.custom.button.Button>`, :tl:`KeyboardButton`, optional):
Same as ``buttons`` for `client.send_message
Same as ``buttons`` for `client.send_message()
<telethon.client.messages.MessageMethods.send_message>`.
parse_mode (`str`, optional):
Same as ``parse_mode`` for `client.send_message
Same as ``parse_mode`` for `client.send_message()
<telethon.client.messageparse.MessageParseMethods.parse_mode>`.
id (`str`, optional):
@@ -119,7 +119,7 @@ class InlineBuilder:
Args:
file (`obj`, optional):
Same as ``file`` for `client.send_file
Same as ``file`` for `client.send_file()
<telethon.client.uploads.UploadMethods.send_file>`.
"""
try:
@@ -173,7 +173,7 @@ class InlineBuilder:
Args:
file (`obj`):
Same as ``file`` for `client.send_file
Same as ``file`` for `client.send_file()
<telethon.client.uploads.UploadMethods.send_file>`.
title (`str`, optional):

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

@@ -784,6 +784,22 @@ class Message(ChatGetter, SenderGetter, TLObject, abc.ABC):
behave as if it clicked a button with said data. Note
that if the message does not have this data, it will
``raise DataInvalidError``.
Example:
.. code-block:: python
# Click the first button
message.click(0)
# Click some row/column
message.click(row, column)
# Click by text
message.click(text='👍')
# Click by data
message.click(data=b'payload')
"""
if not self._client:
return

9
telethon/utils.py
View File

@@ -937,11 +937,12 @@ def _encode_telegram_base64(string):
def resolve_bot_file_id(file_id):
"""
Given a Bot API-style `file_id`, returns the media it represents.
If the `file_id` is not valid, ``None`` is returned instead.
Given a Bot API-style `file_id <telethon.tl.custom.file.File.id>`,
returns the media it represents. If the `file_id <telethon.tl.custom.file.File.id>`
is not valid, ``None`` is returned instead.
Note that the `file_id` does not have information such as image
dimensions or file size, so these will be zero if present.
Note that the `file_id <telethon.tl.custom.file.File.id>` does not have information
such as image dimensions or file size, so these will be zero if present.
For thumbnails, the photo ID and hash will always be zero.
"""