LonamiWebs/Telethon
1
1
Fork 0
mirror of https://github.com/LonamiWebs/Telethon.git synced 2025-07-15 02:22:22 +03:00
Code Issues Packages Projects Releases Wiki Activity

Rename entity parameter with something clearer

Browse Source
This commit is contained in:
Lonami Exo 2022-03-02 09:00:39 +01:00
parent 392808b950
commit c3cefef37c
8 changed files with 142 additions and 136 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
readthedocs/misc/v2-migration-guide.rst
View File

@ -985,3 +985,5 @@ send code / sign in now only expect a single phone. resend code with new phone i
sign_up code is also now a kwarg. and no longer noop if already loggedin. sign_up code is also now a kwarg. and no longer noop if already loggedin.
start also mandates phone= or password= as kwarg. start also mandates phone= or password= as kwarg.
qrlogin expires has been replaced with timeout and expired for parity with tos and auth. the goal is to hide the error-prone system clock and instead use asyncio's clock. recreate was removed (just call qr_login again; parity with get_tos). class renamed to QrLogin. now must be used in a contextmgr to prevent misuse. qrlogin expires has been replaced with timeout and expired for parity with tos and auth. the goal is to hide the error-prone system clock and instead use asyncio's clock. recreate was removed (just call qr_login again; parity with get_tos). class renamed to QrLogin. now must be used in a contextmgr to prevent misuse.
"entity" parameters have been renamed to "dialog" (user or chat expected) or "chat" (only chats expected), "profile" (if that makes sense). the goal is to move away from the entity terminology. this is intended to be a documentation change, but because the parameters were renamed, it's breaking. the expected usage of positional arguments is mostly unaffected. this includes the EntityLike hint.
download_media param renamed message to media. iter_download file to media too

8
telethon/_client/bots.py
View File

@ -13,12 +13,12 @@ async def inline_query(
bot: 'hints.EntityLike', bot: 'hints.EntityLike',
query: str, query: str,
*, *,
entity: 'hints.EntityLike' = None, dialog: 'hints.EntityLike' = None,
offset: str = None, offset: str = None,
geo_point: '_tl.GeoPoint' = None) -> _custom.InlineResults: geo_point: '_tl.GeoPoint' = None) -> _custom.InlineResults:
bot = await self.get_input_entity(bot) bot = await self.get_input_entity(bot)
if entity: if dialog:
peer = await self.get_input_entity(entity) peer = await self.get_input_entity(dialog)
else: else:
peer = _tl.InputPeerEmpty() peer = _tl.InputPeerEmpty()
@ -30,4 +30,4 @@ async def inline_query(
geo_point=geo_point geo_point=geo_point
)) ))
return _custom.InlineResults(self, result, entity=peer if entity else None) return _custom.InlineResults(self, result, entity=peer if dialog else None)

36
telethon/_client/chats.py
View File

@ -372,7 +372,7 @@ class _ProfilePhotoIter(requestiter.RequestIter):
def get_participants( def get_participants(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
limit: float = (), limit: float = (),
*, *,
search: str = '', search: str = '',
@ -380,7 +380,7 @@ def get_participants(
return _ParticipantsIter( return _ParticipantsIter(
self, self,
limit, limit,
entity=entity, entity=chat,
filter=filter, filter=filter,
search=search search=search
) )
@ -388,7 +388,7 @@ def get_participants(
def get_admin_log( def get_admin_log(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
limit: float = (), limit: float = (),
*, *,
max_id: int = 0, max_id: int = 0,
@ -413,7 +413,7 @@ def get_admin_log(
return _AdminLogIter( return _AdminLogIter(
self, self,
limit, limit,
entity=entity, entity=chat,
admins=admins, admins=admins,
search=search, search=search,
min_id=min_id, min_id=min_id,
@ -438,7 +438,7 @@ def get_admin_log(
def get_profile_photos( def get_profile_photos(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', profile: 'hints.EntityLike',
limit: int = (), limit: int = (),
*, *,
offset: int = 0, offset: int = 0,
@ -446,7 +446,7 @@ def get_profile_photos(
return _ProfilePhotoIter( return _ProfilePhotoIter(
self, self,
limit, limit,
entity=entity, entity=profile,
offset=offset, offset=offset,
max_id=max_id max_id=max_id
) )
@ -454,7 +454,7 @@ def get_profile_photos(
def action( def action(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
action: 'typing.Union[str, _tl.TypeSendMessageAction]', action: 'typing.Union[str, _tl.TypeSendMessageAction]',
*, *,
delay: float = 4, delay: float = 4,
@ -462,11 +462,11 @@ def action(
action = _ChatAction._parse(action) action = _ChatAction._parse(action)
return _ChatAction( return _ChatAction(
self, entity, action, delay=delay, auto_cancel=auto_cancel) self, dialog, action, delay=delay, auto_cancel=auto_cancel)
async def edit_admin( async def edit_admin(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
user: 'hints.EntityLike', user: 'hints.EntityLike',
*, *,
change_info: bool = None, change_info: bool = None,
@ -481,7 +481,7 @@ async def edit_admin(
anonymous: bool = None, anonymous: bool = None,
is_admin: bool = None, is_admin: bool = None,
title: str = None) -> _tl.Updates: title: str = None) -> _tl.Updates:
entity = await self.get_input_entity(entity) entity = await self.get_input_entity(chat)
user = await self.get_input_entity(user) user = await self.get_input_entity(user)
ty = helpers._entity_type(user) ty = helpers._entity_type(user)
@ -529,7 +529,7 @@ async def edit_admin(
async def edit_permissions( async def edit_permissions(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
user: 'typing.Optional[hints.EntityLike]' = None, user: 'typing.Optional[hints.EntityLike]' = None,
until_date: 'hints.DateLike' = None, until_date: 'hints.DateLike' = None,
*, *,
@ -545,7 +545,7 @@ async def edit_permissions(
change_info: bool = True, change_info: bool = True,
invite_users: bool = True, invite_users: bool = True,
pin_messages: bool = True) -> _tl.Updates: pin_messages: bool = True) -> _tl.Updates:
entity = await self.get_input_entity(entity) entity = await self.get_input_entity(chat)
ty = helpers._entity_type(entity) ty = helpers._entity_type(entity)
rights = _tl.ChatBannedRights( rights = _tl.ChatBannedRights(
@ -583,10 +583,10 @@ async def edit_permissions(
async def kick_participant( async def kick_participant(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
user: 'typing.Optional[hints.EntityLike]' user: 'typing.Optional[hints.EntityLike]'
): ):
entity = await self.get_input_entity(entity) entity = await self.get_input_entity(chat)
user = await self.get_input_entity(user) user = await self.get_input_entity(user)
ty = helpers._entity_type(entity) ty = helpers._entity_type(entity)
@ -617,10 +617,10 @@ async def kick_participant(
async def get_permissions( async def get_permissions(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
user: 'hints.EntityLike' = None user: 'hints.EntityLike' = None
) -> 'typing.Optional[_custom.ParticipantPermissions]': ) -> 'typing.Optional[_custom.ParticipantPermissions]':
entity = await self.get_entity(entity) entity = await self.get_entity(chat)
if not user: if not user:
if helpers._entity_type(entity) != helpers._EntityType.USER: if helpers._entity_type(entity) != helpers._EntityType.USER:
@ -650,10 +650,10 @@ async def get_permissions(
async def get_stats( async def get_stats(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
message: 'typing.Union[int, _tl.Message]' = None, message: 'typing.Union[int, _tl.Message]' = None,
): ):
entity = await self.get_input_entity(entity) entity = await self.get_input_entity(chat)
message = utils.get_message_id(message) message = utils.get_message_id(message)
if message is not None: if message is not None:

16
telethon/_client/dialogs.py
View File

@ -165,20 +165,20 @@ def get_dialogs(
def get_drafts( def get_drafts(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntitiesLike' = None dialog: 'hints.EntitiesLike' = None
) -> _DraftsIter: ) -> _DraftsIter:
limit = None limit = None
if entity: if dialog:
if not utils.is_list_like(entity): if not utils.is_list_like(dialog):
entity = (entity,) dialog = (dialog,)
limit = len(entity) limit = len(dialog)
return _DraftsIter(self, limit, entities=entity) return _DraftsIter(self, limit, entities=dialog)
async def delete_dialog( async def delete_dialog(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
*, *,
revoke: bool = False revoke: bool = False
): ):
@ -189,7 +189,7 @@ async def delete_dialog(
else: else:
deactivated = False deactivated = False
entity = await self.get_input_entity(entity) entity = await self.get_input_entity(dialog)
ty = helpers._entity_type(entity) ty = helpers._entity_type(entity)
if ty == helpers._EntityType.CHANNEL: if ty == helpers._EntityType.CHANNEL:
return await self(_tl.fn.channels.LeaveChannel(entity)) return await self(_tl.fn.channels.LeaveChannel(entity))

10
telethon/_client/downloads.py
View File

@ -178,7 +178,7 @@ class _GenericDownloadIter(_DirectDownloadIter):
async def download_profile_photo( async def download_profile_photo(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', profile: 'hints.EntityLike',
file: 'hints.FileLike' = None, file: 'hints.FileLike' = None,
*, *,
thumb, thumb,
@ -188,6 +188,7 @@ async def download_profile_photo(
ENTITIES = (0x2da17977, 0xc5af5d94, 0x1f4661b9, 0xd49a2697) ENTITIES = (0x2da17977, 0xc5af5d94, 0x1f4661b9, 0xd49a2697)
# ('InputPeer', 'InputUser', 'InputChannel') # ('InputPeer', 'InputUser', 'InputChannel')
INPUTS = (0xc91c90b6, 0xe669bf46, 0x40f202fd) INPUTS = (0xc91c90b6, 0xe669bf46, 0x40f202fd)
entity = profile
if not isinstance(entity, tlobject.TLObject) or entity.SUBCLASS_OF_ID in INPUTS: if not isinstance(entity, tlobject.TLObject) or entity.SUBCLASS_OF_ID in INPUTS:
entity = await self.get_entity(entity) entity = await self.get_entity(entity)
@ -258,7 +259,7 @@ async def download_profile_photo(
async def download_media( async def download_media(
self: 'TelegramClient', self: 'TelegramClient',
message: 'hints.MessageLike', media: 'hints.MessageLike',
file: 'hints.FileLike' = None, file: 'hints.FileLike' = None,
*, *,
size = (), size = (),
@ -269,6 +270,7 @@ async def download_media(
msg_data = None msg_data = None
# TODO This won't work for messageService # TODO This won't work for messageService
message = media
if isinstance(message, _tl.Message): if isinstance(message, _tl.Message):
date = message.date date = message.date
media = message.media media = message.media
@ -405,7 +407,7 @@ async def _download_file(
def iter_download( def iter_download(
self: 'TelegramClient', self: 'TelegramClient',
file: 'hints.FileLike', media: 'hints.FileLike',
*, *,
offset: int = 0, offset: int = 0,
stride: int = None, stride: int = None,
@ -417,7 +419,7 @@ def iter_download(
): ):
return _iter_download( return _iter_download(
self, self,
file, media,
offset=offset, offset=offset,
stride=stride, stride=stride,
limit=limit, limit=limit,

44
telethon/_client/messages.py
View File

@ -332,7 +332,7 @@ async def _get_peer(self: 'TelegramClient', input_peer: 'hints.EntityLike'):
def get_messages( def get_messages(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
limit: float = (), limit: float = (),
*, *,
offset_date: 'hints.DateLike' = None, offset_date: 'hints.DateLike' = None,
@ -358,7 +358,7 @@ def get_messages(
reverse=reverse, reverse=reverse,
wait_time=wait_time, wait_time=wait_time,
limit=len(ids), limit=len(ids),
entity=entity, entity=dialog,
ids=ids ids=ids
) )
@ -367,7 +367,7 @@ def get_messages(
reverse=reverse, reverse=reverse,
wait_time=wait_time, wait_time=wait_time,
limit=limit, limit=limit,
entity=entity, entity=dialog,
offset_id=offset_id, offset_id=offset_id,
min_id=min_id, min_id=min_id,
max_id=max_id, max_id=max_id,
@ -396,7 +396,7 @@ async def _get_comment_data(
async def send_message( async def send_message(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
message: 'hints.MessageLike' = '', message: 'hints.MessageLike' = '',
*, *,
# - Message contents # - Message contents
@ -466,7 +466,7 @@ async def send_message(
elif not isinstance(message, InputMessage): elif not isinstance(message, InputMessage):
raise TypeError(f'message must be either str, Message or InputMessage, but got: {message!r}') raise TypeError(f'message must be either str, Message or InputMessage, but got: {message!r}')
entity = await self.get_input_entity(entity) entity = await self.get_input_entity(dialog)
if comment_to is not None: if comment_to is not None:
entity, reply_to = await _get_comment_data(self, entity, comment_to) entity, reply_to = await _get_comment_data(self, entity, comment_to)
elif reply_to: elif reply_to:
@ -525,9 +525,9 @@ async def send_message(
async def forward_messages( async def forward_messages(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
messages: 'typing.Union[typing.Sequence[hints.MessageIDLike]]', messages: 'typing.Union[typing.Sequence[hints.MessageIDLike]]',
from_peer: 'hints.EntityLike' = None, from_dialog: 'hints.EntityLike' = None,
*, *,
background: bool = None, background: bool = None,
with_my_score: bool = None, with_my_score: bool = None,
@ -540,12 +540,13 @@ async def forward_messages(
if as_album is not None: if as_album is not None:
warnings.warn('the as_album argument is deprecated and no longer has any effect') warnings.warn('the as_album argument is deprecated and no longer has any effect')
entity = await self.get_input_entity(entity) entity = await self.get_input_entity(dialog)
if from_peer: if from_dialog:
from_peer = await self.get_input_entity(from_peer) from_peer = await self.get_input_entity(from_dialog)
from_peer_id = await self.get_peer_id(from_peer) from_peer_id = await self.get_peer_id(from_peer)
else: else:
from_peer = None
from_peer_id = None from_peer_id = None
def get_key(m): def get_key(m):
@ -587,7 +588,7 @@ async def forward_messages(
async def edit_message( async def edit_message(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'typing.Union[hints.EntityLike, _tl.Message]', dialog: 'typing.Union[hints.EntityLike, _tl.Message]',
message: 'hints.MessageLike' = None, message: 'hints.MessageLike' = None,
text: str = None, text: str = None,
*, *,
@ -631,7 +632,7 @@ async def edit_message(
else: else:
return await self(request) return await self(request)
entity = await self.get_input_entity(entity) entity = await self.get_input_entity(dialog)
request = _tl.fn.messages.EditMessage( request = _tl.fn.messages.EditMessage(
peer=entity, peer=entity,
id=utils.get_message_id(message), id=utils.get_message_id(message),
@ -647,7 +648,7 @@ async def edit_message(
async def delete_messages( async def delete_messages(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
messages: 'typing.Union[typing.Sequence[hints.MessageIDLike]]', messages: 'typing.Union[typing.Sequence[hints.MessageIDLike]]',
*, *,
revoke: bool = True) -> 'typing.Sequence[_tl.messages.AffectedMessages]': revoke: bool = True) -> 'typing.Sequence[_tl.messages.AffectedMessages]':
@ -657,11 +658,12 @@ async def delete_messages(
else int(m) for m in messages else int(m) for m in messages
) )
if entity: if dialog:
entity = await self.get_input_entity(entity) entity = await self.get_input_entity(dialog)
ty = helpers._entity_type(entity) ty = helpers._entity_type(entity)
else: else:
# no entity (None), set a value that's not a channel for private delete # no entity (None), set a value that's not a channel for private delete
entity = None
ty = helpers._EntityType.USER ty = helpers._EntityType.USER
if ty == helpers._EntityType.CHANNEL: if ty == helpers._EntityType.CHANNEL:
@ -675,7 +677,7 @@ async def delete_messages(
async def mark_read( async def mark_read(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
message: 'hints.MessageIDLike' = None, message: 'hints.MessageIDLike' = None,
*, *,
clear_mentions: bool = False, clear_mentions: bool = False,
@ -687,7 +689,7 @@ async def mark_read(
else: else:
max_id = message.id max_id = message.id
entity = await self.get_input_entity(entity) entity = await self.get_input_entity(dialog)
if clear_mentions: if clear_mentions:
await self(_tl.fn.messages.ReadMentions(entity)) await self(_tl.fn.messages.ReadMentions(entity))
@ -705,22 +707,22 @@ async def mark_read(
async def pin_message( async def pin_message(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
message: 'typing.Optional[hints.MessageIDLike]', message: 'typing.Optional[hints.MessageIDLike]',
*, *,
notify: bool = False, notify: bool = False,
pm_oneside: bool = False pm_oneside: bool = False
): ):
return await _pin(self, entity, message, unpin=False, notify=notify, pm_oneside=pm_oneside) return await _pin(self, dialog, message, unpin=False, notify=notify, pm_oneside=pm_oneside)
async def unpin_message( async def unpin_message(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
message: 'typing.Optional[hints.MessageIDLike]' = None, message: 'typing.Optional[hints.MessageIDLike]' = None,
*, *,
notify: bool = False notify: bool = False
): ):
return await _pin(self, entity, message, unpin=True, notify=notify) return await _pin(self, dialog, message, unpin=True, notify=notify)
async def _pin(self, entity, message, *, unpin, notify=False, pm_oneside=False): async def _pin(self, entity, message, *, unpin, notify=False, pm_oneside=False):
message = utils.get_message_id(message) or 0 message = utils.get_message_id(message) or 0

158
telethon/_client/telegramclient.py
View File

@ -704,7 +704,7 @@ class TelegramClient:
bot: 'hints.EntityLike', bot: 'hints.EntityLike',
query: str, query: str,
*, *,
entity: 'hints.EntityLike' = None, dialog: 'hints.EntityLike' = None,
offset: str = None, offset: str = None,
geo_point: '_tl.GeoPoint' = None) -> _custom.InlineResults: geo_point: '_tl.GeoPoint' = None) -> _custom.InlineResults:
""" """
@ -712,17 +712,17 @@ class TelegramClient:
Arguments Arguments
bot (`entity`): bot (`entity`):
The bot entity to which the inline query should be made. The bot user to which the inline query should be made.
query (`str`): query (`str`):
The query that should be made to the bot. The query that should be made to the bot.
entity (`entity`, optional): dialog (`entity`, optional):
The entity where the inline query is being made from. Certain The dialog where the inline query is being made from. Certain
bots use this to display different results depending on where bots use this to display different results depending on where
it's used, such as private chats, groups or channels. it's used, such as private chats, groups or channels.
If specified, it will also be the default entity where the If specified, it will also be the default dialog where the
message will be sent after clicked. Otherwise, the "empty message will be sent after clicked. Otherwise, the "empty
peer" will be used, which some bots may not handle correctly. peer" will be used, which some bots may not handle correctly.
@ -754,7 +754,7 @@ class TelegramClient:
@forward_call(chats.get_participants) @forward_call(chats.get_participants)
def get_participants( def get_participants(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
limit: float = (), limit: float = (),
*, *,
search: str = '', search: str = '',
@ -765,8 +765,8 @@ class TelegramClient:
The order is unspecified. The order is unspecified.
Arguments Arguments
entity (`entity`): chat (`entity`):
The entity from which to retrieve the participants list. The chat from which to retrieve the participants list.
limit (`int`): limit (`int`):
Limits amount of participants fetched. Limits amount of participants fetched.
@ -822,7 +822,7 @@ class TelegramClient:
@forward_call(chats.get_admin_log) @forward_call(chats.get_admin_log)
def get_admin_log( def get_admin_log(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
limit: float = (), limit: float = (),
*, *,
max_id: int = 0, max_id: int = 0,
@ -856,8 +856,8 @@ class TelegramClient:
`True`, only those that are true will be returned. `True`, only those that are true will be returned.
Arguments Arguments
entity (`entity`): chat (`entity`):
The channel entity from which to get its admin log. The chat from which to get its admin log.
limit (`int` | `None`, optional): limit (`int` | `None`, optional):
Number of events to be retrieved. Number of events to be retrieved.
@ -957,7 +957,7 @@ class TelegramClient:
@forward_call(chats.get_profile_photos) @forward_call(chats.get_profile_photos)
def get_profile_photos( def get_profile_photos(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', profile: 'hints.EntityLike',
limit: int = (), limit: int = (),
*, *,
offset: int = 0, offset: int = 0,
@ -968,8 +968,8 @@ class TelegramClient:
The order is from the most recent photo to the oldest. The order is from the most recent photo to the oldest.
Arguments Arguments
entity (`entity`): profile (`entity`):
The entity from which to get the profile or chat photos. The user or chat profile from which to get the profile photos.
limit (`int` | `None`, optional): limit (`int` | `None`, optional):
Number of photos to be retrieved. Number of photos to be retrieved.
@ -1005,7 +1005,7 @@ class TelegramClient:
@forward_call(chats.action) @forward_call(chats.action)
def action( def action(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
action: 'typing.Union[str, _tl.TypeSendMessageAction]', action: 'typing.Union[str, _tl.TypeSendMessageAction]',
*, *,
delay: float = 4, delay: float = 4,
@ -1022,8 +1022,8 @@ class TelegramClient:
See the example below for intended usage. See the example below for intended usage.
Arguments Arguments
entity (`entity`): dialog (`entity`):
The entity where the action should be showed in. The dialog where the action should be showed in.
action (`str` | :tl:`SendMessageAction`): action (`str` | :tl:`SendMessageAction`):
The action to show. You can either pass a instance of The action to show. You can either pass a instance of
@ -1083,7 +1083,7 @@ class TelegramClient:
@forward_call(chats.edit_admin) @forward_call(chats.edit_admin)
async def edit_admin( async def edit_admin(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
user: 'hints.EntityLike', user: 'hints.EntityLike',
*, *,
change_info: bool = None, change_info: bool = None,
@ -1107,8 +1107,8 @@ class TelegramClient:
Unless otherwise stated, permissions will work in channels and megagroups. Unless otherwise stated, permissions will work in channels and megagroups.
Arguments Arguments
entity (`entity`): chat (`entity`):
The channel, megagroup or chat where the promotion should happen. The chat where the promotion should happen.
user (`entity`): user (`entity`):
The user to be promoted. The user to be promoted.
@ -1189,7 +1189,7 @@ class TelegramClient:
@forward_call(chats.edit_permissions) @forward_call(chats.edit_permissions)
async def edit_permissions( async def edit_permissions(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
user: 'typing.Optional[hints.EntityLike]' = None, user: 'typing.Optional[hints.EntityLike]' = None,
until_date: 'hints.DateLike' = None, until_date: 'hints.DateLike' = None,
*, *,
@ -1229,8 +1229,8 @@ class TelegramClient:
permissions don't allow it either. permissions don't allow it either.
Arguments Arguments
entity (`entity`): chat (`entity`):
The channel or megagroup where the restriction should happen. The chat where the restriction should happen.
user (`entity`, optional): user (`entity`, optional):
If specified, the permission will be changed for the specific user. If specified, the permission will be changed for the specific user.
@ -1306,7 +1306,7 @@ class TelegramClient:
@forward_call(chats.kick_participant) @forward_call(chats.kick_participant)
async def kick_participant( async def kick_participant(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
user: 'typing.Optional[hints.EntityLike]' user: 'typing.Optional[hints.EntityLike]'
): ):
""" """
@ -1321,8 +1321,8 @@ class TelegramClient:
ban + unban. ban + unban.
Arguments Arguments
entity (`entity`): chat (`entity`):
The channel or chat where the user should be kicked from. The chat where the user should be kicked from.
user (`entity`, optional): user (`entity`, optional):
The user to kick. The user to kick.
@ -1345,7 +1345,7 @@ class TelegramClient:
@forward_call(chats.get_permissions) @forward_call(chats.get_permissions)
async def get_permissions( async def get_permissions(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
user: 'hints.EntityLike' = None user: 'hints.EntityLike' = None
) -> 'typing.Optional[_custom.ParticipantPermissions]': ) -> 'typing.Optional[_custom.ParticipantPermissions]':
""" """
@ -1358,8 +1358,8 @@ class TelegramClient:
which can get somewhat expensive, so use of a cache is advised. which can get somewhat expensive, so use of a cache is advised.
Arguments Arguments
entity (`entity`): chat (`entity`):
The channel or chat the user is participant of. The chat the user is participant of.
user (`entity`, optional): user (`entity`, optional):
Target user. Target user.
@ -1383,7 +1383,7 @@ class TelegramClient:
@forward_call(chats.get_stats) @forward_call(chats.get_stats)
async def get_stats( async def get_stats(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', chat: 'hints.EntityLike',
message: 'typing.Union[int, _tl.Message]' = None, message: 'typing.Union[int, _tl.Message]' = None,
): ):
""" """
@ -1394,22 +1394,22 @@ class TelegramClient:
requires `at least 500 members`_). requires `at least 500 members`_).
Arguments Arguments
entity (`entity`): chat (`entity`):
The channel from which to get statistics. The chat from which to get statistics.
message (`int` | ``Message``, optional): message (`int` | ``Message``, optional):
The message ID from which to get statistics, if your goal is The message ID from which to get statistics, if your goal is
to obtain the statistics of a single message. to obtain the statistics of a single message.
Raises Raises
If the given entity is not a channel (broadcast or megagroup), If the given chat is not a broadcast channel ormegagroup,
a `TypeError` is raised. a `TypeError` is raised.
If there are not enough members (poorly named) errors such as If there are not enough members (poorly named) errors such as
``telethon.errors.ChatAdminRequiredError`` will appear. ``telethon.errors.ChatAdminRequiredError`` will appear.
Returns Returns
If both ``entity`` and ``message`` were provided, returns If both ``chat`` and ``message`` were provided, returns
:tl:`MessageStats`. Otherwise, either :tl:`BroadcastStats` or :tl:`MessageStats`. Otherwise, either :tl:`BroadcastStats` or
:tl:`MegagroupStats`, depending on whether the input belonged to a :tl:`MegagroupStats`, depending on whether the input belonged to a
broadcast channel or megagroup. broadcast channel or megagroup.
@ -1523,7 +1523,7 @@ class TelegramClient:
@forward_call(dialogs.get_drafts) @forward_call(dialogs.get_drafts)
def get_drafts( def get_drafts(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntitiesLike' = None dialog: 'hints.EntitiesLike' = None
) -> dialogs._DraftsIter: ) -> dialogs._DraftsIter:
""" """
Iterator over draft messages. Iterator over draft messages.
@ -1531,8 +1531,8 @@ class TelegramClient:
The order is unspecified. The order is unspecified.
Arguments Arguments
entity (`hints.EntitiesLike`, optional): dialog (`hints.EntitiesLike`, optional):
The entity or entities for which to fetch the draft messages. The dialog or dialogs for which to fetch the draft messages.
If left unspecified, all draft messages will be returned. If left unspecified, all draft messages will be returned.
Yields Yields
@ -1557,7 +1557,7 @@ class TelegramClient:
@forward_call(dialogs.delete_dialog) @forward_call(dialogs.delete_dialog)
async def delete_dialog( async def delete_dialog(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
*, *,
revoke: bool = False revoke: bool = False
): ):
@ -1571,8 +1571,8 @@ class TelegramClient:
See also `Dialog.delete() <telethon.tl._custom.dialog.Dialog.delete>`. See also `Dialog.delete() <telethon.tl._custom.dialog.Dialog.delete>`.
Arguments Arguments
entity (entities): dialog (entities):
The entity of the dialog to delete. If it's a chat or The dialog to delete. If it's a chat or
channel, you will leave it. Note that the chat itself channel, you will leave it. Note that the chat itself
is not deleted, only the dialog, because you left it. is not deleted, only the dialog, because you left it.
@ -1606,7 +1606,7 @@ class TelegramClient:
@forward_call(downloads.download_profile_photo) @forward_call(downloads.download_profile_photo)
async def download_profile_photo( async def download_profile_photo(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', profile: 'hints.EntityLike',
file: 'hints.FileLike' = None, file: 'hints.FileLike' = None,
*, *,
thumb: typing.Union[str, enums.Size] = (), thumb: typing.Union[str, enums.Size] = (),
@ -1615,8 +1615,8 @@ class TelegramClient:
Downloads the profile photo from the given user, chat or channel. Downloads the profile photo from the given user, chat or channel.
Arguments Arguments
entity (`entity`): profile (`entity`):
From who the photo will be downloaded. The profile from which to download its photo.
.. note:: .. note::
@ -1663,7 +1663,7 @@ class TelegramClient:
@forward_call(downloads.download_media) @forward_call(downloads.download_media)
async def download_media( async def download_media(
self: 'TelegramClient', self: 'TelegramClient',
message: 'hints.MessageLike', media: 'hints.MessageLike',
file: 'hints.FileLike' = None, file: 'hints.FileLike' = None,
*, *,
thumb: typing.Union[str, enums.Size] = (), thumb: typing.Union[str, enums.Size] = (),
@ -1678,8 +1678,8 @@ class TelegramClient:
See also `Message.download_media() <telethon.tl._custom.message.Message.download_media>`. See also `Message.download_media() <telethon.tl._custom.message.Message.download_media>`.
Arguments Arguments
message (`Message <telethon.tl._custom.message.Message>` | :tl:`Media`): media (:tl:`Media`):
The media or message containing the media that will be downloaded. The media that will be downloaded.
file (`str` | `file`, optional): file (`str` | `file`, optional):
The output file path, directory, or stream-like object. The output file path, directory, or stream-like object.
@ -1725,7 +1725,7 @@ class TelegramClient:
@forward_call(downloads.iter_download) @forward_call(downloads.iter_download)
def iter_download( def iter_download(
self: 'TelegramClient', self: 'TelegramClient',
file: 'hints.FileLike', media: 'hints.FileLike',
*, *,
offset: int = 0, offset: int = 0,
stride: int = None, stride: int = None,
@ -1826,7 +1826,7 @@ class TelegramClient:
@forward_call(messages.get_messages) @forward_call(messages.get_messages)
def get_messages( def get_messages(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
limit: float = (), limit: float = (),
*, *,
offset_date: 'hints.DateLike' = None, offset_date: 'hints.DateLike' = None,
@ -1859,8 +1859,8 @@ class TelegramClient:
second is the default for this limit (or above). second is the default for this limit (or above).
Arguments Arguments
entity (`entity`): dialog (`entity`):
The entity from whom to retrieve the message history. The dialog from which to retrieve the message history.
It may be `None` to perform a global search, or It may be `None` to perform a global search, or
to get messages by their ID from no particular chat. to get messages by their ID from no particular chat.
@ -1912,7 +1912,7 @@ class TelegramClient:
containing photos. containing photos.
from_user (`entity`): from_user (`entity`):
Only messages from this entity will be returned. Only messages from this user will be returned.
wait_time (`int`): wait_time (`int`):
Wait time (in seconds) between different Wait time (in seconds) between different
@ -1950,7 +1950,7 @@ class TelegramClient:
instead of being `max_id` as well since messages are returned instead of being `max_id` as well since messages are returned
in ascending order. in ascending order.
You cannot use this if both `entity` and `ids` are `None`. You cannot use this if both `dialog` and `ids` are `None`.
reply_to (`int`, optional): reply_to (`int`, optional):
If set to a message ID, the messages that reply to this ID If set to a message ID, the messages that reply to this ID
@ -1974,7 +1974,7 @@ class TelegramClient:
scheduled (`bool`, optional): scheduled (`bool`, optional):
If set to `True`, messages which are scheduled will be returned. If set to `True`, messages which are scheduled will be returned.
All other parameter will be ignored for this, except `entity`. All other parameter will be ignored for this, except `dialog`.
Yields Yields
Instances of `Message <telethon.tl._custom.message.Message>`. Instances of `Message <telethon.tl._custom.message.Message>`.
@ -2025,7 +2025,7 @@ class TelegramClient:
@forward_call(messages.send_message) @forward_call(messages.send_message)
async def send_message( async def send_message(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
message: 'hints.MessageLike' = '', message: 'hints.MessageLike' = '',
*, *,
# - Message contents # - Message contents
@ -2077,7 +2077,7 @@ class TelegramClient:
and `Message.reply() <telethon.tl._custom.message.Message.reply>`. and `Message.reply() <telethon.tl._custom.message.Message.reply>`.
Arguments Arguments
entity (`entity`): dialog (`entity`):
To who will it be sent. To who will it be sent.
message (`str` | `Message <telethon.tl._custom.message.Message>`): message (`str` | `Message <telethon.tl._custom.message.Message>`):
@ -2235,9 +2235,9 @@ class TelegramClient:
@forward_call(messages.forward_messages) @forward_call(messages.forward_messages)
async def forward_messages( async def forward_messages(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
messages: 'typing.Union[typing.Sequence[hints.MessageIDLike]]', messages: 'typing.Union[typing.Sequence[hints.MessageIDLike]]',
from_peer: 'hints.EntityLike' = None, from_dialog: 'hints.EntityLike' = None,
*, *,
background: bool = None, background: bool = None,
with_my_score: bool = None, with_my_score: bool = None,
@ -2246,7 +2246,7 @@ class TelegramClient:
schedule: 'hints.DateLike' = None schedule: 'hints.DateLike' = None
) -> 'typing.Sequence[_tl.Message]': ) -> 'typing.Sequence[_tl.Message]':
""" """
Forwards the given messages to the specified entity. Forwards the given messages to the specified dialog.
If you want to "forward" a message without the forward header If you want to "forward" a message without the forward header
(the "forwarded from" text), you should use `send_message` with (the "forwarded from" text), you should use `send_message` with
@ -2255,17 +2255,17 @@ class TelegramClient:
See also `Message.forward_to() <telethon.tl._custom.message.Message.forward_to>`. See also `Message.forward_to() <telethon.tl._custom.message.Message.forward_to>`.
Arguments Arguments
entity (`entity`): dialog (`entity`):
To which entity the message(s) will be forwarded. The target dialog where the message(s) will be forwarded.
messages (`list`): messages (`list`):
The messages to forward, or their integer IDs. The messages to forward, or their integer IDs.
from_peer (`entity`): from_dialog (`entity`):
If the given messages are integer IDs and not instances If the given messages are integer IDs and not instances
of the ``Message`` class, this *must* be specified in of the ``Message`` class, this *must* be specified in
order for the forward to work. This parameter indicates order for the forward to work. This parameter indicates
the entity from which the messages should be forwarded. the source dialog from which the messages should be forwarded.
silent (`bool`, optional): silent (`bool`, optional):
Whether the message should notify people with sound or not. Whether the message should notify people with sound or not.
@ -2317,7 +2317,7 @@ class TelegramClient:
@forward_call(messages.edit_message) @forward_call(messages.edit_message)
async def edit_message( async def edit_message(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'typing.Union[hints.EntityLike, _tl.Message]', dialog: 'typing.Union[hints.EntityLike, _tl.Message]',
message: 'hints.MessageLike', message: 'hints.MessageLike',
text: str = None, text: str = None,
*, *,
@ -2338,9 +2338,9 @@ class TelegramClient:
See also `Message.edit() <telethon.tl._custom.message.Message.edit>`. See also `Message.edit() <telethon.tl._custom.message.Message.edit>`.
Arguments Arguments
entity (`entity` | `Message <telethon.tl._custom.message.Message>`): dialog (`entity` | `Message <telethon.tl._custom.message.Message>`):
From which chat to edit the message. This can also be From which chat to edit the message. This can also be
the message to be edited, and the entity will be inferred the message to be edited, and the dialog will be inferred
from it, so the next parameter will be assumed to be the from it, so the next parameter will be assumed to be the
message text. message text.
@ -2351,12 +2351,12 @@ class TelegramClient:
message (`int` | `Message <telethon.tl._custom.message.Message>` | `str`): message (`int` | `Message <telethon.tl._custom.message.Message>` | `str`):
The ID of the message (or `Message The ID of the message (or `Message
<telethon.tl._custom.message.Message>` itself) to be edited. <telethon.tl._custom.message.Message>` itself) to be edited.
If the `entity` was a `Message If the `dialog` was a `Message
<telethon.tl._custom.message.Message>`, then this message <telethon.tl._custom.message.Message>`, then this message
will be treated as the new text. will be treated as the new text.
text (`str`, optional): text (`str`, optional):
The new text of the message. Does nothing if the `entity` The new text of the message. Does nothing if the `dialog`
was a `Message <telethon.tl._custom.message.Message>`. was a `Message <telethon.tl._custom.message.Message>`.
parse_mode (`object`, optional): parse_mode (`object`, optional):
@ -2416,7 +2416,7 @@ class TelegramClient:
Returns Returns
The edited `Message <telethon.tl._custom.message.Message>`, The edited `Message <telethon.tl._custom.message.Message>`,
unless `entity` was a :tl:`InputBotInlineMessageID` in which unless `dialog` was a :tl:`InputBotInlineMessageID` in which
case this method returns a boolean. case this method returns a boolean.
Raises Raises
@ -2446,7 +2446,7 @@ class TelegramClient:
@forward_call(messages.delete_messages) @forward_call(messages.delete_messages)
async def delete_messages( async def delete_messages(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
messages: 'typing.Union[typing.Sequence[hints.MessageIDLike]]', messages: 'typing.Union[typing.Sequence[hints.MessageIDLike]]',
*, *,
revoke: bool = True) -> 'typing.Sequence[_tl.messages.AffectedMessages]': revoke: bool = True) -> 'typing.Sequence[_tl.messages.AffectedMessages]':
@ -2463,7 +2463,7 @@ class TelegramClient:
chats at once, so make sure to pass the right IDs. chats at once, so make sure to pass the right IDs.
Arguments Arguments
entity (`entity`): dialog (`entity`):
From who the message will be deleted. This can actually From who the message will be deleted. This can actually
be `None` for normal chats, but **must** be present be `None` for normal chats, but **must** be present
for channels and megagroups. for channels and megagroups.
@ -2498,7 +2498,7 @@ class TelegramClient:
@forward_call(messages.mark_read) @forward_call(messages.mark_read)
async def mark_read( async def mark_read(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
message: 'hints.MessageIDLike' = None, message: 'hints.MessageIDLike' = None,
*, *,
clear_mentions: bool = False) -> bool: clear_mentions: bool = False) -> bool:
@ -2518,7 +2518,7 @@ class TelegramClient:
See also `Message.mark_read() <telethon.tl._custom.message.Message.mark_read>`. See also `Message.mark_read() <telethon.tl._custom.message.Message.mark_read>`.
Arguments Arguments
entity (`entity`): dialog (`entity`):
The chat where these messages are located. The chat where these messages are located.
message (`Message <telethon.tl._custom.message.Message>`): message (`Message <telethon.tl._custom.message.Message>`):
@ -2550,7 +2550,7 @@ class TelegramClient:
@forward_call(messages.pin_message) @forward_call(messages.pin_message)
async def pin_message( async def pin_message(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
message: 'typing.Optional[hints.MessageIDLike]', message: 'typing.Optional[hints.MessageIDLike]',
*, *,
notify: bool = False, notify: bool = False,
@ -2565,7 +2565,7 @@ class TelegramClient:
See also `Message.pin() <telethon.tl._custom.message.Message.pin>`. See also `Message.pin() <telethon.tl._custom.message.Message.pin>`.
Arguments Arguments
entity (`entity`): dialog (`entity`):
The chat where the message should be pinned. The chat where the message should be pinned.
message (`int` | `Message <telethon.tl._custom.message.Message>`): message (`int` | `Message <telethon.tl._custom.message.Message>`):
@ -2591,7 +2591,7 @@ class TelegramClient:
@forward_call(messages.unpin_message) @forward_call(messages.unpin_message)
async def unpin_message( async def unpin_message(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
message: 'typing.Optional[hints.MessageIDLike]' = None, message: 'typing.Optional[hints.MessageIDLike]' = None,
*, *,
notify: bool = False notify: bool = False
@ -2604,8 +2604,8 @@ class TelegramClient:
See also `Message.unpin() <telethon.tl._custom.message.Message.unpin>`. See also `Message.unpin() <telethon.tl._custom.message.Message.unpin>`.
Arguments Arguments
entity (`entity`): dialog (`entity`):
The chat where the message should be pinned. The dialog where the message should be pinned.
message (`int` | `Message <telethon.tl._custom.message.Message>`): message (`int` | `Message <telethon.tl._custom.message.Message>`):
The message or the message ID to unpin. If it's The message or the message ID to unpin. If it's
@ -2968,7 +2968,7 @@ class TelegramClient:
@forward_call(uploads.send_file) @forward_call(uploads.send_file)
async def send_file( async def send_file(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
file: 'typing.Union[hints.FileLike, typing.Sequence[hints.FileLike]]', file: 'typing.Union[hints.FileLike, typing.Sequence[hints.FileLike]]',
*, *,
caption: typing.Union[str, typing.Sequence[str]] = None, caption: typing.Union[str, typing.Sequence[str]] = None,
@ -3006,7 +3006,7 @@ class TelegramClient:
cannot be done if you are sending :tl:`InputFile`, however. cannot be done if you are sending :tl:`InputFile`, however.
Arguments Arguments
entity (`entity`): dialog (`entity`):
Who will receive the file. Who will receive the file.
file (`str` | `bytes` | `file` | `media`): file (`str` | `bytes` | `file` | `media`):

4
telethon/_client/uploads.py
View File

@ -79,7 +79,7 @@ def _resize_photo_if_needed(
async def send_file( async def send_file(
self: 'TelegramClient', self: 'TelegramClient',
entity: 'hints.EntityLike', dialog: 'hints.EntityLike',
file: typing.Optional[hints.FileLike] = None, file: typing.Optional[hints.FileLike] = None,
*, *,
# - Message contents # - Message contents
@ -119,7 +119,7 @@ async def send_file(
comment_to: 'typing.Union[int, _tl.Message]' = None, comment_to: 'typing.Union[int, _tl.Message]' = None,
) -> '_tl.Message': ) -> '_tl.Message':
self.send_message( self.send_message(
entity=entity, dialog=dialog,
message=caption, message=caption,
markdown=markdown, markdown=markdown,
html=html, html=html,