# noinspection PyUnresolvedReferences
class Client:
"""Telethon Client，与 Telegram 互动的主要手段。
参数:
session (``str``):
如果给出了字符串（它可以是完整路径）则将会保存 ``.session`` 文件；如果没有，则不会保存会话，并且在程序结束后，您应该调用
`client.log_out()` 。
请注意，如果传递字符串，则文件将保存为当前工作目录下，并且您还可以传递绝对路径。
api_id (``int`` | ``str``):
从 https://my.telegram.org 获取到的 *api_id* 。
api_hash (``str``, *optional*):
从 https://my.telegram.org 获取到的 *api_hash* 。
bot_token （``str``, *可选*):
如果设置了 Bot token，则将直接使用 Bot 身份登录。
app_version (``str``, *可选*):
应用版本号，默认设置为 `telethon.version.__version__` 。
device_model (``str``, *optional*):
设备型号，默认设置为 `·`platform.uname().machine` 。
system_version (``str``, *optional*):
操作系统版本，默认设置为 `platform.uname().release` 。
lang_code (``str``, *optional*):
客户端上使用的 ISO 639-1 标准的语言代码。默认为 “en”。
use_ipv6 (``bool``, *可选*):
如果设置为 `True` ，则将使用 ipv6 连接 Telegram 服务器。默认关闭 (通过 IPv4).
proxy (``tuple``, ``str``, ``dict``, *可选*):
MTProxy: `('hostname', port, 'secret')` ；socks5: `(socks.SOCKS5, "socks.example.com", 1080)` 获取更多
代理配置详情：https://github.com/Anorov/PySocks#usage-1
timeout (``int``, ``float``, *可选*):
设置链接超时所要等待的秒数。
flood_sleep_threshold (``int``, ``float``, *可选*):
设置当出现 `FloodWaitError` 时自动休眠应用程序的时间。
"""
def start(self):
"""启动客户端（在必要时连接和登录）。
此方法将使客户端连接到 Telegram 服务器，如果是一个新的客户端，会自动进行交互式的授权过程。
返回:
:obj:`~telethon.Client`: 启动的 client本身。
Raises:
ConnectionError: 如果您尝试启动已启动客户端。
Example:
.. code-block:: python
:emphasize-lines: 4
from telethon.sync import TelegramClient, events
app = Client("my_account", api_id, api_hash)
app.start()
# Call API methods
app.disconnect()
"""
def disconnect(self):
"""断开客户端与 Telegram 服务器的连接。
此方法将客户端与 Telegram 服务器断开连接，并停止底层任务。
返回:
:obj:`~telethon.Client`: 停止的 client本身。
Raises:
OSError: 如果您尝试停止已停止的客户端。
Example:
.. code-block:: python
:emphasize-lines: 8
from telethon.sync import TelegramClient, events
app = Client("my_account", api_id, api_hash)
app.start()
# Call API methods
app.disconnect()
"""
# Message
def send_message(self):
"""向指定的用户，群组或频道发送消息。
默认文本解析模式与官方应用程序相同（Markdown）
向 bot 发送 start 参数命令 (例如 ``?start=data``) 同样可行，请直接发送 ``/start data`` 。
参数:
entity (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
接收消息的对象
message (``str`` | :obj:`~telethon.tl.types.message`):
要发送的消息或消息对象。
消息的最大长度为 ``35,000`` 字节或 ``4,096`` 个字符。较长的消息不会自动分割，如果要发送的文本长于最大长度，则应手动分割。
reply_to (``int`` | :obj:`~telethon.tl.types.message`, *可选*):
要回复的消息 id 或者消息对象。
parse_mode (``str``, *可选*):
文本格式解析器配置。值支持 `markdown` （`md`)， `html` （`htm`)， `None`。
link_preview (``bool``, *可选*):
配置是否展示消息预览，默认开启。
buttons (``list``), *可选*):
配置消息按钮，参见示例，仅支持 bot 登录时。
限制：
最多可以有 ``100`` 个按钮（更多将被忽略）。
每行最多可以有 ``8`` 个按钮（更多将被忽略）。
按钮的最大回调数据为 ``64`` 字节。
silent (``bool``, *可选*):
配置是否静默消息，默认关闭。
schedule (``float``, *可选*):
配置是否定时消息，默认不配置。
返回:
:obj:`~telethon.tl.types.message`: 成功则将返回已发送的消息。
Example:
.. code-block:: python
# 默认使用 Markdown 解析器解析文本。
await client.send_message('me', 'Hello **world**!')
# 更改客户端的默认解析器。
client.parse_mode = 'html'
await client.send_message('me', 'Some bold and italic text')
await client.send_message('me', 'An URL')
await client.send_message('me', 'Mentions')
# 混合解析
client.parse_mode = None
# 手动配置单条消息的解析器为 Markdown 。
await client.send_message('me', 'Hello, **world**!', parse_mode='md')
# 手动配置单条消息的解析器为 Html 。
await client.send_message('me', 'Hello, world!', parse_mode='html')
# 如果使用 Bot 登录，则您可以使用按钮：
from telethon import events, Button
@client.on(events.CallbackQuery)
async def callback(event):
await event.edit('感谢点击 {}!'.format(event.data))
# 单个按钮
await client.send_message(chat, '只是一个会回调 "clk1" 的按钮。',
buttons=Button.inline('点我', b'clk1'))
# 多个按钮
await client.send_message(chat, '选一个吧！', buttons=[
[Button.inline('回调'), Button.inline('这是回调')],
[Button.url('访问网站', 'https://example.com')]
])
# 消息需要回复
await client.send_message(chat, '欢迎', buttons=[
Button.text('感谢!', resize=True, single_use=True),
Button.request_phone('发送电话号码'),
Button.request_location('发送位置')
])
# 强制回复或清除按钮。
await client.send_message(chat, '回复我', buttons=Button.force_reply())
await client.send_message(chat, '清楚按钮', buttons=Button.clear())
# 定时 5 分钟后发送消息
from datetime import timedelta
await client.send_message(chat, '你好，未来！', schedule=timedelta(minutes=5))
"""
def edit_message(self):
"""编辑指定消息，更改其文本或媒体文件。
参数:
entity (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
接收消息的对象
text (``str``, *可选*):
要编辑的消息文本。
消息的最大长度为 ``35,000`` 字节或 ``4,096`` 个字符。
message (``int`` | ``str`` | :obj:`~telethon.tl.types.message`, *可选*):
要编辑的消息 id 或者消息对象。
parse_mode (``str``, *可选*):
文本格式解析器配置。值支持 `markdown` （`md`)， `html` （`htm`)， `None`。
link_preview (``bool``, *可选*):
配置是否展示消息预览，默认开启。
file (``str``, ``bytes``, *可选*):
如果参数为 ``str`` ，则将再此路径下寻找文件（支持相对/绝对路径）。
请注意：如果原消息为纯文本时，配置此项将会报错。
buttons (``list``), *可选*):
配置消息按钮，参见示例，仅支持 bot 登录时。
限制：
最多可以有 ``100`` 个按钮（更多将被忽略）。
每行最多可以有 ``8`` 个按钮（更多将被忽略）。
按钮的最大回调数据为 ``64`` 字节。
schedule (``float``, *可选*):
配置是否定时消息，默认不配置。
Raises:
MessageAuthorRequiredError: 如果您不是消息的发送者。
MessageNotModifiedError: 如果要编辑的消息和原消息一样。
MessageIdInvalidError: 如果消息的 ID 无效（消息 ID 本身可能是正确的，但无法编辑此 ID 对应的消息。）
Example:
.. code-block:: python
message = await client.send_message(chat, '你好')
await client.edit_message(chat, message, '你好!')
# 或者
await client.edit_message(chat, message.id, '你好!!')
# 或者
await client.edit_message(message, '你好!!!')
"""
def delete_messages(self):
"""删除指定消息。
参数:
entity (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
接收消息的对象
message_ids (``list`` | ``int`` | :obj:`~telethon.tl.types.message`, *可选*):
要删除的消息 id 列表或者单个消息 id 或者消息对象。
Example:
.. code-block:: python
await client.delete_messages(chat, messages)
"""
def forward_messages(self):
"""转发指定消息。
参数:
entity (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
接收消息的对象
message_ids (``list`` | ``int`` | :obj:`~telethon.tl.types.message`, *可选*):
要删除的消息 id 列表或者单个消息 id 或者消息对象。
from_peer (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
指定转发消息的来源。如果 message_ids 传递的参数是数字。
silent (``bool``, *可选*):
配置是否静默消息，默认关闭。
schedule (``float``, *可选*):
配置是否定时消息，默认不配置。
返回:
:obj:`~telethon.tl.types.message`: 成功则将返回已转发的消息。（如果转发的是一组消息，则返回列表）
请注意：批量转发时，如果所有需要转发的消息都无效（即删除）则会抛出 ``MessageIdInvalidError`` 错误；
如果只有一些消息无效，则只是返回的列表中没有这些消息。
Raises:
MessageIdInvalidError: 如果消息的 ID 无效
Example:
.. code-block:: python
# 单条消息
await client.forward_messages(chat, message)
# 或者
await client.forward_messages(chat, message_id, from_chat)
# 或者
await message.forward_to(chat)
# 多条消息
await client.forward_messages(chat, messages)
# 作为一个副本发送（不带转发来源）
await client.send_message(chat, message)
"""
def iter_messages(self):
"""搜索指定对话中的消息。
参数:
entity (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
需要检索的对话的对象
limit (``int`` | ``None``, *可选*):
限制要检索的消息数。由于API的限制，检索超过 ``3000`` 条消息将需要超过半分钟。
配置为 ``None`` ，并不会返回所有历史。
offset_date (``float``, *可选*):
将从此时间之前开始检索消息。
offset_id (``int``, *可选*):
将从此消息 id 之前开始检索消息。
max_id (``int``, *可选*):
配置要检索到的消息的最大 id 值。
min_id (``int``, *可选*):
配置要检索到的消息的最小 id 值。
search (``str``, *可选*):
配置检索的字符串。
filter (``MessagesFilter``, *可选*):
过滤消息类型。
from_user (:obj:`~telethon.tl.types.user`, *可选*)
指定消息发送者。
reverse (``bool``, *可选*):
如果设置为 ``True``，则消息将以相反的顺序返回。这意味着 ``offset_id`` 或者 ``offset_date`` 参数的含义是相反的。
``min_id`` 等同于 ``offset_id`` 。
reply_to (``int``, *可选*):
返回频道消息的所有评论消息。
此功能只能用于链接了某个频道的*讨论组*。在其他对话中使用它将抛出 ``PeridInValiderror`` 错误。
使用此参数时，``filter`` 和 ``search`` 参数无效，因为 Telegram 的 API 不支持搜索回复中的消息。
Yields:
消息对象 :obj:`~telethon.tl.types.message`
Raises:
PeridInValiderror: 此对话不是链接了频道的讨论组。
Example:
.. code-block:: python
# 从最新消息开始检索
async for message in client.iter_messages(chat):
print(message.id, message.text)
# 从第一条消息开始检索
async for message in client.iter_messages(chat, reverse=True):
print(message.id, message.text)
# 只返回我发送的消息
async for message in client.iter_messages(chat, from_user='me'):
print(message.text)
# 通过 Telegram 服务器检索匹配的文本消息
async for message in client.iter_messages(chat, search='hello'):
print(message.id)
# 检索特定类型的消息（例如：图片）
from telethon.tl.types import InputMessagesFilterPhotos
async for message in client.iter_messages(chat, filter=InputMessagesFilterPhotos):
print(message.photo)
# 检索指定频道消息的评论
async for message in client.iter_messages(channel, reply_to=123):
print(message.chat.title, message.text)
"""
def get_messages(self):
"""
和 .. automethod:: telethon.Client.iter_messages() 一样，但是返回的是一个 ``List`` 。
Example:
.. code-block:: python
# 获取对话所有照片数
from telethon.tl.types import InputMessagesFilterPhotos
photos = await client.get_messages(chat, None, filter=InputMessagesFilterPhotos)
print(photos.total)
# 通过消息 id 获取消息
message_1337 = await client.get_messages(chat, ids=1337)
"""
def pin_message(self):
"""置顶指定消息
参数:
entity (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
需要置顶的对话的对象。
message (``int`` | ``None`` | :obj:`~telethon.tl.types.message`, *可选*):
要置顶的消息 id 或者消息对象。如果值为 ``None``，则将取消置顶所有消息。
notify (``bool``, *可选*):
配置是否通知群成员。与官方应用程序不同，默认不通知所有成员。
Example:
.. code-block:: python
# 置顶消息
message = await client.send_message(chat, 'Pinotifying is fun!')
await client.pin_message(chat, message, notify=True)
"""
def unpin_message(self):
"""取消置顶指定消息
参数:
entity (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
需要取消置顶的对话的对象。
message (``int`` | ``None`` | :obj:`~telethon.tl.types.message`, *可选*):
要置顶的消息 id 或者消息对象。如果值为 ``None``，则将取消置顶所有消息。
Example:
.. code-block:: python
# 取消置顶所有消息
await client.unpin_message(chat)
"""
def send_read_acknowledge(self):
"""将消息标记为已读，可选择是否清除提及提示。
如果不提供消息和 ``max_id`` ，则将标记所有消息为已读。
参数:
entity (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
需要标记已读的对话的对象。
message (``list`` | :obj:`~telethon.tl.types.message`, *可选*):
标记此消息及其之前的所有消息为已读。
max_id (``int``, *可选*):
标记此消息 id 及其之前的所有消息为已读。
clear_mentions (``bool``, *可选*):
配置是否清除提及按钮。
Example:
.. code-block:: python
# 使用消息对象
await client.send_read_acknowledge(chat, message)
# 或者使用消息 id
await client.send_read_acknowledge(chat, message_id)
# 或者已读所有消息
await client.send_read_acknowledge(chat, messages)
"""
# Upload
def send_file(self):
"""向指定对话发送文件。
.. note::
安装 ``hachoir3`` 包（``hachoir`` 模块），它可以被用于获取音频和视频元信息。
安装 ``pillow`` 包，它可以自动调整图片尺寸以支持 Telegram 上传，但是，如果使用 ``InputFile`` 发送图片，则无法完成。
参数:
entity (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
需要发送文件的对话的对象。
file (``str`` | ``bytes`` | ``file`` | ``media``):
支持路径、包含文件的 ``bytes``、网络链接、``file_id``、文件句柄（例如 ``message.media``）。
caption (``str``, *可选*):
配置媒体文件的说明文字。
force_document (``bool``, *可选*):
强制以文件方式发送图片等。
reply_to (``int`` | :obj:`~telethon.tl.types.message`, *可选*):
要回复的消息 id 或者消息对象。
parse_mode (``str``, *可选*):
文本格式解析器配置。值支持 `markdown` （`md`)， `html` （`htm`)， `None`。
buttons (``list``), *可选*):
配置消息按钮，参见示例，仅支持 bot 登录时。
限制：
最多可以有 ``100`` 个按钮（更多将被忽略）。
每行最多可以有 ``8`` 个按钮（更多将被忽略）。
按钮的最大回调数据为 ``64`` 字节。
silent (``bool``, *可选*):
配置是否静默消息，默认关闭。
schedule (``float``, *可选*):
配置是否定时消息，默认不配置。
返回:
:obj:`~telethon.tl.types.message`: 如果成功则返回消息对象。
Example:
.. code-block:: python
# 图片文件
await client.send_file(chat, '/my/photos/me.jpg', caption="It's me!")
# 或者
await client.send_message(chat, "It's me!", file='/my/photos/me.jpg')
# 语音文件
await client.send_file(chat, '/my/songs/song.mp3', voice_note=True)
await client.send_file(chat, '/my/videos/video.mp4', video_note=True)
# 自定义缩略图
await client.send_file(chat, '/my/documents/doc.txt', thumb='photo.jpg')
# 文件
await client.send_file(chat, '/my/photos/photo.png', force_document=True)
# 图辑
await client.send_file(chat, [
'/my/photos/holiday1.jpg',
'/my/photos/holiday2.jpg',
'/my/drawings/portrait.png'
])
# 提示上传进度
def callback(current, total):
print('Uploaded', current, 'out of', total,
'bytes: {:.2%}'.format(current / total))
await client.send_file(chat, file, progress_callback=callback)
# 骰子，包括飞镖和其他动态表情符号
from telethon.tl import types
await client.send_file(chat, types.InputMediaDice(''))
await client.send_file(chat, types.InputMediaDice('🎯'))
# 联系人
await client.send_file(chat, types.InputMediaContact(
phone_number='+34 123 456 789',
first_name='Example',
last_name='',
vcard=''
))
"""
# Download
def download_media(self):
"""下载消息对象包含的媒体文件。
.. note::
如果下载太慢，则应考虑安装 ``cryptg`` （``pip3 install cryptg``）
参数:
entity (:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`):
需要发送文件的对话的对象。
file (``str`` | ``file``):
输出文件路径，目录或流等对象。如果该路径存在并且是文件，则将覆盖。
返回:
None: 如果消息中不存在媒体文件，如果为指定路径则将返回文件路径。
Example:
.. code-block:: python
path = await client.download_media(message)
await client.download_media(message, filename)
# 或者
path = await message.download_media()
await message.download_media(filename)
# 提示下载进度
def callback(current, total):
print('Downloaded', current, 'out of', total,
'bytes: {:.2%}'.format(current / total))
await client.download_media(message, progress_callback=callback)
"""
# Users
def get_me(self):
"""获取当前客户端所登录的用户信息。
返回:
:obj:`~telethon.tl.types.user`: 如果成功则返回用户对象。
Example:
.. code-block:: python
me = await client.get_me()
"""
def get_entity(self):
"""获取指定对话信息。
.. note::
使用此方法解析用户名不会自带缓存，对时间内您一般解析 ``50`` 个用户名就会收到请求过快错误。
推荐优先使用 .. automethod:: telethon.Client.get_input_entity() 来请求缓存的用户名数据。
参数:
entity (``str`` | ``int``):
需要获取的对话的对象。
Raise:
ValueError: 指定的对话不存在。
Return:
:obj:`~telethon.tl.types.user` | :obj:`~telethon.tl.types.chat` | :obj:`~telethon.tl.types.channel`: 如果请求成功。
Example:
.. code-block:: python
from telethon import utils
me = await client.get_entity('me')
print(utils.get_display_name(me))
chat = await client.get_input_entity('username')
async for message in client.iter_messages(chat):
...
# 可以直接使用用户名
async for message in client.iter_messages('username'):
...
# 请注意，您的联系人中必须拥有此电话号码才可以请求到数据。
some_id = await client.get_peer_id('+34123456789')
"""
def get_input_entity(self):
"""获取指定对话的对象。
参数:
entity (``str`` | ``int``):
需要获取的对话的对象。
Raise:
ValueError: 指定的对话不存在。
Example:
.. code-block:: python
user = await client.get_input_entity('username')
chat = await client.get_input_entity(-123456789)
"""