diff --git a/client/doc/concepts/chats.rst b/client/doc/concepts/chats.rst index 31e6582a..4de13d4e 100644 --- a/client/doc/concepts/chats.rst +++ b/client/doc/concepts/chats.rst @@ -28,7 +28,7 @@ The following types are chat-like: * An ``'+1 23'`` phone number string. It must be an :class:`str` and start with the plus-sign ``+`` character. * An ``123`` integer identifier. It must be an :class:`int` and cannot be negative. * An existing :class:`~types.User`, :class:`~types.Group` or :class:`~types.Channel`. -* A :class:`~types.PackedChat`. +* A :class:`~types.PeerRef`. Previous versions of Telethon referred to this term as "entity" or "entities" instead. @@ -72,7 +72,7 @@ The Bot API follows a certain convention when it comes to identifiers: * Chat IDs are negative. * Channel IDs are *also* negative, but are prefixed by ``-100``. -Telethon encourages the use of :class:`~types.PackedChat` instead of naked identifiers. +Telethon encourages the use of :class:`~types.PeerRef` instead of naked identifiers. As a reminder, negative identifiers are not supported in Telethon's chat-like parameters. If you got an Bot API-style ID from somewhere else, you will need to explicitly say what type it is: @@ -104,7 +104,7 @@ Chats access hash Users, supergroups and channels all need an :term:`access hash`. -In Telethon, the :class:`~types.PackedChat` is the recommended way to deal with the identifier-hash pairs. +In Telethon, the :class:`~types.PeerRef` is the recommended way to deal with the identifier-hash pairs. This compact type can be used anywhere a chat is expected. It's designed to be easy to store and cache in any way your application chooses. @@ -113,7 +113,7 @@ The same is true for user accounts, although to a lesser extent. When using just the identifier to refer to a chat, Telethon will attempt to retrieve its hash from its in-memory cache. If this fails, an invalid hash will be used. This may or may not make the API call succeed. -For this reason, it is recommended that you always use :class:`~types.PackedChat` instead. +For this reason, it is recommended that you always use :class:`~types.PeerRef` instead. Remember that an :term:`access hash` is account-bound. You cannot obtain an :term:`access hash` in Account-A and use it in Account-B. diff --git a/client/doc/concepts/messages.rst b/client/doc/concepts/messages.rst index a3c23ffc..e0fab4ef 100644 --- a/client/doc/concepts/messages.rst +++ b/client/doc/concepts/messages.rst @@ -96,7 +96,7 @@ and instead favours more standard `HTML elements MessageMap: return build_message_map(self, result, peer) - async def _resolve_to_packed(self, chat: ChatLike) -> PackedChat: + async def _resolve_to_packed(self, chat: ChatLike) -> PeerRef: return await resolve_to_packed(self, chat) def _input_to_peer(self, input: Optional[abcs.InputPeer]) -> Optional[abcs.Peer]: diff --git a/client/src/telethon/_impl/client/client/messages.py b/client/src/telethon/_impl/client/client/messages.py index 3417353f..d606374d 100644 --- a/client/src/telethon/_impl/client/client/messages.py +++ b/client/src/telethon/_impl/client/client/messages.py @@ -4,7 +4,7 @@ import datetime import sys from typing import TYPE_CHECKING, Literal, Optional, Self -from ...session import PackedChat +from ...session import PeerRef from ...tl import abcs, functions, types from ..types import AsyncList, ChatLike, Message, Peer, build_chat_map from ..types import buttons as btns @@ -323,7 +323,7 @@ class CherryPickedList(MessageList): super().__init__() self._client = client self._chat = chat - self._packed: Optional[PackedChat] = None + self._packed: Optional[PeerRef] = None self._ids: list[abcs.InputMessage] = [types.InputMessageId(id=id) for id in ids] async def _fetch_next(self) -> None: diff --git a/client/src/telethon/_impl/client/client/users.py b/client/src/telethon/_impl/client/client/users.py index 6a43da37..c85067d3 100644 --- a/client/src/telethon/_impl/client/client/users.py +++ b/client/src/telethon/_impl/client/client/users.py @@ -3,7 +3,7 @@ from __future__ import annotations from typing import TYPE_CHECKING, Optional from ...mtproto import RpcError -from ...session import PackedChat, PackedType +from ...session import PackedType, PeerRef from ...tl import abcs, functions, types from ..types import ( AsyncList, @@ -77,7 +77,7 @@ async def resolve_username(self: Client, username: str) -> Peer: async def get_chats( self: Client, chats: list[ChatLike] | tuple[ChatLike, ...] ) -> list[Peer]: - packed_chats: list[PackedChat] = [] + packed_chats: list[PeerRef] = [] input_users: list[types.InputUser] = [] input_chats: list[int] = [] input_channels: list[types.InputChannel] = [] @@ -122,8 +122,8 @@ async def get_chats( async def resolve_to_packed( client: Client, chat: ChatLike | abcs.InputPeer | abcs.Peer -) -> PackedChat: - if isinstance(chat, PackedChat): +) -> PeerRef: + if isinstance(chat, PeerRef): return chat if isinstance(chat, (User, Group, Channel)): @@ -139,7 +139,7 @@ async def resolve_to_packed( else: ty = PackedType.BROADCAST - return PackedChat(ty=ty, id=chat.id, access_hash=0) + return PeerRef(ty=ty, id=chat.id, access_hash=0) if isinstance(chat, abcs.InputPeer): if isinstance(chat, types.InputPeerEmpty): @@ -147,25 +147,25 @@ async def resolve_to_packed( elif isinstance(chat, types.InputPeerSelf): if not client._session.user: raise ValueError("Cannot resolve chat") - return PackedChat( + return PeerRef( ty=PackedType.BOT if client._session.user.bot else PackedType.USER, id=client._chat_hashes.self_id, access_hash=0, ) elif isinstance(chat, types.InputPeerChat): - return PackedChat( + return PeerRef( ty=PackedType.CHAT, id=chat.chat_id, access_hash=None, ) elif isinstance(chat, types.InputPeerUser): - return PackedChat( + return PeerRef( ty=PackedType.USER, id=chat.user_id, access_hash=chat.access_hash, ) elif isinstance(chat, types.InputPeerChannel): - return PackedChat( + return PeerRef( ty=PackedType.BROADCAST, id=chat.channel_id, access_hash=chat.access_hash, @@ -182,19 +182,19 @@ async def resolve_to_packed( if packed is not None: return packed if isinstance(chat, types.PeerUser): - return PackedChat( + return PeerRef( ty=PackedType.USER, id=chat.user_id, access_hash=0, ) elif isinstance(chat, types.PeerChat): - return PackedChat( + return PeerRef( ty=PackedType.CHAT, id=chat.chat_id, access_hash=0, ) elif isinstance(chat, types.PeerChannel): - return PackedChat( + return PeerRef( ty=PackedType.BROADCAST, id=chat.channel_id, access_hash=0, @@ -207,7 +207,7 @@ async def resolve_to_packed( resolved = await resolve_phone(client, chat) elif chat == "me": if me := client._session.user: - return PackedChat( + return PeerRef( ty=PackedType.BOT if me.bot else PackedType.USER, id=me.id, access_hash=0, diff --git a/client/src/telethon/_impl/client/types/draft.py b/client/src/telethon/_impl/client/types/draft.py index 7426496c..6de9d9b3 100644 --- a/client/src/telethon/_impl/client/types/draft.py +++ b/client/src/telethon/_impl/client/types/draft.py @@ -3,7 +3,7 @@ from __future__ import annotations import datetime from typing import TYPE_CHECKING, Optional, Self -from ...session import PackedChat +from ...session import PeerRef from ...tl import abcs, functions, types from ..parsers import generate_html_message, generate_markdown_message from .message import Message, generate_random_id @@ -158,7 +158,7 @@ class Draft(metaclass=NoPublicConstructor): reply_to=reply_to, ) - async def _packed_chat(self) -> PackedChat: + async def _packed_chat(self) -> PeerRef: packed = None if chat := self._chat_map.get(peer_id(self._peer)): packed = chat.pack() diff --git a/client/src/telethon/_impl/client/types/participant.py b/client/src/telethon/_impl/client/types/participant.py index 2444a769..864dbde2 100644 --- a/client/src/telethon/_impl/client/types/participant.py +++ b/client/src/telethon/_impl/client/types/participant.py @@ -3,7 +3,7 @@ from __future__ import annotations import datetime from typing import TYPE_CHECKING, Optional, Self, Sequence -from ...session import PackedChat +from ...session import PeerRef from ...tl import abcs, types from .admin_right import AdminRight from .chat_restriction import ChatRestriction @@ -24,7 +24,7 @@ class Participant(metaclass=NoPublicConstructor): def __init__( self, client: Client, - chat: PackedChat, + chat: PeerRef, participant: ( types.ChannelParticipant | types.ChannelParticipantSelf @@ -47,7 +47,7 @@ class Participant(metaclass=NoPublicConstructor): def _from_raw_channel( cls, client: Client, - chat: PackedChat, + chat: PeerRef, participant: abcs.ChannelParticipant, chat_map: dict[int, Peer], ) -> Self: @@ -70,7 +70,7 @@ class Participant(metaclass=NoPublicConstructor): def _from_raw_chat( cls, client: Client, - chat: PackedChat, + chat: PeerRef, participant: abcs.ChatParticipant, chat_map: dict[int, Peer], ) -> Self: diff --git a/client/src/telethon/_impl/client/types/peer/__init__.py b/client/src/telethon/_impl/client/types/peer/__init__.py index 4814f16b..9874f1ab 100644 --- a/client/src/telethon/_impl/client/types/peer/__init__.py +++ b/client/src/telethon/_impl/client/types/peer/__init__.py @@ -5,7 +5,7 @@ import sys from collections import defaultdict from typing import TYPE_CHECKING, Optional, Sequence -from ....session import PackedChat +from ....session import PeerRef from ....tl import abcs, types from .channel import Channel from .group import Group @@ -15,7 +15,7 @@ from .user import User if TYPE_CHECKING: from ...client.client import Client -ChatLike = Peer | PackedChat | int | str +ChatLike = Peer | PeerRef | int | str def build_chat_map( diff --git a/client/src/telethon/_impl/client/types/peer/channel.py b/client/src/telethon/_impl/client/types/peer/channel.py index 2fac4db5..0f331db8 100644 --- a/client/src/telethon/_impl/client/types/peer/channel.py +++ b/client/src/telethon/_impl/client/types/peer/channel.py @@ -1,6 +1,6 @@ from typing import Optional, Self -from ....session import PackedChat, PackedType +from ....session import PackedType, PeerRef from ....tl import abcs, types from ..meta import NoPublicConstructor from .peer import Peer @@ -50,11 +50,11 @@ class Channel(Peer, metaclass=NoPublicConstructor): def username(self) -> Optional[str]: return getattr(self._raw, "username", None) - def pack(self) -> Optional[PackedChat]: + def pack(self) -> Optional[PeerRef]: if self._raw.access_hash is None: return None else: - return PackedChat( + return PeerRef( ty=( PackedType.GIGAGROUP if getattr(self._raw, "gigagroup", False) diff --git a/client/src/telethon/_impl/client/types/peer/group.py b/client/src/telethon/_impl/client/types/peer/group.py index 6b0add8d..1dfcd148 100644 --- a/client/src/telethon/_impl/client/types/peer/group.py +++ b/client/src/telethon/_impl/client/types/peer/group.py @@ -3,7 +3,7 @@ from __future__ import annotations import datetime from typing import TYPE_CHECKING, Optional, Self, Sequence -from ....session import PackedChat, PackedType +from ....session import PackedType, PeerRef from ....tl import abcs, types from ..chat_restriction import ChatRestriction from ..meta import NoPublicConstructor @@ -65,13 +65,13 @@ class Group(Peer, metaclass=NoPublicConstructor): def username(self) -> Optional[str]: return getattr(self._raw, "username", None) - def pack(self) -> Optional[PackedChat]: + def pack(self) -> Optional[PeerRef]: if isinstance(self._raw, (types.ChatEmpty, types.Chat, types.ChatForbidden)): - return PackedChat(ty=PackedType.CHAT, id=self._raw.id, access_hash=None) + return PeerRef(ty=PackedType.CHAT, id=self._raw.id, access_hash=None) elif self._raw.access_hash is None: return None else: - return PackedChat( + return PeerRef( ty=PackedType.MEGAGROUP, id=self._raw.id, access_hash=self._raw.access_hash, diff --git a/client/src/telethon/_impl/client/types/peer/peer.py b/client/src/telethon/_impl/client/types/peer/peer.py index 3c7c80f0..94eb2984 100644 --- a/client/src/telethon/_impl/client/types/peer/peer.py +++ b/client/src/telethon/_impl/client/types/peer/peer.py @@ -1,7 +1,7 @@ import abc from typing import Optional -from ....session import PackedChat +from ....session import PeerRef class Peer(abc.ABC): @@ -45,7 +45,7 @@ class Peer(abc.ABC): """ @abc.abstractmethod - def pack(self) -> Optional[PackedChat]: + def pack(self) -> Optional[PeerRef]: """ Pack the chat into a compact and reusable object. diff --git a/client/src/telethon/_impl/client/types/peer/user.py b/client/src/telethon/_impl/client/types/peer/user.py index 4e1636c1..6ac96afd 100644 --- a/client/src/telethon/_impl/client/types/peer/user.py +++ b/client/src/telethon/_impl/client/types/peer/user.py @@ -1,6 +1,6 @@ from typing import Optional, Self -from ....session import PackedChat, PackedType +from ....session import PackedType, PeerRef from ....tl import abcs, types from ..meta import NoPublicConstructor from .peer import Peer @@ -87,11 +87,11 @@ class User(Peer, metaclass=NoPublicConstructor): def username(self) -> Optional[str]: return self._raw.username - def pack(self) -> Optional[PackedChat]: + def pack(self) -> Optional[PeerRef]: if self._raw.access_hash is None: return None else: - return PackedChat( + return PeerRef( ty=PackedType.BOT if self._raw.bot else PackedType.USER, id=self._raw.id, access_hash=self._raw.access_hash, diff --git a/client/src/telethon/_impl/session/__init__.py b/client/src/telethon/_impl/session/__init__.py index f553a210..848e6abb 100644 --- a/client/src/telethon/_impl/session/__init__.py +++ b/client/src/telethon/_impl/session/__init__.py @@ -1,4 +1,4 @@ -from .chat import ChatHashCache, PackedChat, PackedType +from .chat import ChatHashCache, PackedType, PeerRef from .message_box import ( BOT_CHANNEL_DIFF_LIMIT, NO_UPDATES_TIMEOUT, @@ -15,7 +15,7 @@ from .storage import MemorySession, SqliteSession, Storage __all__ = [ "ChatHashCache", - "PackedChat", + "PeerRef", "PackedType", "BOT_CHANNEL_DIFF_LIMIT", "NO_UPDATES_TIMEOUT", diff --git a/client/src/telethon/_impl/session/chat/__init__.py b/client/src/telethon/_impl/session/chat/__init__.py index 0b4b1fe2..27f29d1c 100644 --- a/client/src/telethon/_impl/session/chat/__init__.py +++ b/client/src/telethon/_impl/session/chat/__init__.py @@ -1,4 +1,4 @@ from .hash_cache import ChatHashCache -from .peer_ref import PackedChat, PackedType +from .peer_ref import PackedType, PeerRef -__all__ = ["ChatHashCache", "PackedChat", "PackedType"] +__all__ = ["ChatHashCache", "PeerRef", "PackedType"] diff --git a/client/src/telethon/_impl/session/chat/hash_cache.py b/client/src/telethon/_impl/session/chat/hash_cache.py index ffe91e45..6e0857f9 100644 --- a/client/src/telethon/_impl/session/chat/hash_cache.py +++ b/client/src/telethon/_impl/session/chat/hash_cache.py @@ -1,7 +1,7 @@ from typing import Any, Optional, Sequence from ...tl import abcs, types -from .peer_ref import PackedChat, PackedType +from .peer_ref import PackedType, PeerRef class ChatHashCache: @@ -21,15 +21,15 @@ class ChatHashCache: def is_self_bot(self) -> bool: return self._self_bot - def set_self_user(self, user: PackedChat) -> None: + def set_self_user(self, user: PeerRef) -> None: assert user.ty in (PackedType.USER, PackedType.BOT) self._self_bot = user.ty == PackedType.BOT self._self_id = user.id - def get(self, id: int) -> Optional[PackedChat]: + def get(self, id: int) -> Optional[PeerRef]: if (entry := self._hash_map.get(id)) is not None: hash, ty = entry - return PackedChat(ty, id, hash) + return PeerRef(ty, id, hash) else: return None diff --git a/client/src/telethon/_impl/session/chat/peer_ref.py b/client/src/telethon/_impl/session/chat/peer_ref.py index 9fe030b4..b05c998f 100644 --- a/client/src/telethon/_impl/session/chat/peer_ref.py +++ b/client/src/telethon/_impl/session/chat/peer_ref.py @@ -7,7 +7,7 @@ from ...tl import abcs, types class PackedType(IntFlag): """ - The type of a :class:`PackedChat`. + The type of a :class:`PeerRef`. """ # bits: zero, has-access-hash, channel, broadcast, group, chat, user, bot @@ -19,7 +19,7 @@ class PackedType(IntFlag): GIGAGROUP = 0b0011_1000 -class PackedChat: +class PeerRef: """ A compact representation of a :term:`chat`. diff --git a/client/src/telethon/types/__init__.py b/client/src/telethon/types/__init__.py index 7c2f43dd..8acac75c 100644 --- a/client/src/telethon/types/__init__.py +++ b/client/src/telethon/types/__init__.py @@ -23,7 +23,7 @@ from .._impl.client.types import ( User, ) from .._impl.client.types.buttons import Button, InlineButton -from .._impl.session import PackedChat, PackedType +from .._impl.session import PackedType, PeerRef __all__ = [ "AdminRight", @@ -46,6 +46,6 @@ __all__ = [ "User", "Button", "InlineButton", - "PackedChat", + "PeerRef", "PackedType", ] diff --git a/client/tests/packed_chat_test.py b/client/tests/packed_chat_test.py index 8a4a98c1..f432a6b5 100644 --- a/client/tests/packed_chat_test.py +++ b/client/tests/packed_chat_test.py @@ -1,10 +1,10 @@ -from telethon._impl.session import PackedChat, PackedType +from telethon._impl.session import PackedType, PeerRef def test_hash_optional() -> None: for ty in PackedType: - pc = PackedChat(ty, 123, 456789) - assert PackedChat.from_bytes(bytes(pc)) == pc + pc = PeerRef(ty, 123, 456789) + assert PeerRef.from_bytes(bytes(pc)) == pc - pc = PackedChat(ty, 987, None) - assert PackedChat.from_bytes(bytes(pc)) == pc + pc = PeerRef(ty, 987, None) + assert PeerRef.from_bytes(bytes(pc)) == pc