Rename PackedChat type to PeerRef

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.

client/doc/concepts/messages.rst

@@ -96,7 +96,7 @@ and instead favours more standard `HTML elements <https://developer.mozilla.org/
 Both markdown and HTML recognise the following special URLs using the ``tg:`` protocol:
 
 * ``tg://user?id=ab1234cd6789`` for inline mentions.
-  To make sure the mention works, use :attr:`types.PackedChat.hex`.
+  To make sure the mention works, use :attr:`types.PeerRef.hex`.
   You can also use :attr:`types.User.id`, but the mention will fail if the user is not in cache.
 * ``tg://emoji?id=1234567890`` for custom emoji.
   You must use the document identifier as the value.

client/doc/developing/migration-guide.rst

@@ -443,14 +443,14 @@ This doesn't mean the ``.chat`` or ``.sender`` will have all the information.
 Telegram may still choose to send their ``min`` version with only basic details.
 But it means you don't have to remember 5 different ways of using chats.
 
-To replace the concept of "input chats", v2 introduces :class:`types.PackedChat`.
+To replace the concept of "input chats", v2 introduces :class:`types.PeerRef`.
 A "packed chat" is a chat with *just* enough information that you can use it without relying on Telethon's cache.
 This is the most efficient way to call methods like :meth:`Client.send_message` too.
 
 The concept of "marked IDs" also no longer exists.
 This means v2 no longer supports the ``-`` or ``-100`` prefixes on identifiers.
 :tl:`Peer`-wrapping is gone, too.
-Instead, you're strongly encouraged to use :class:`types.PackedChat` instances.
+Instead, you're strongly encouraged to use :class:`types.PeerRef` instances.
 
 The concepts of of "entity" or "peer" are unified to simply :term:`chat`.
 Overall, dealing with users, groups and channels should feel a lot more natural.
@@ -477,7 +477,7 @@ The v1 cache that allowed you to use just chat identifiers to call methods is no
 Sessions now only contain crucial information to have a working client.
 This includes the server address, authorization key, update state, and some very basic details.
 
-To work around this, you can use :class:`types.PackedChat`, which is designed to be easy to store.
+To work around this, you can use :class:`types.PeerRef`, which is designed to be easy to store.
 This means your application can choose the best way to deal with them rather than being forced into Telethon's session.
 
 .. seealso::

client/src/telethon/_impl/client/client/chats.py

@@ -3,7 +3,7 @@ from __future__ import annotations
 import datetime
 from typing import TYPE_CHECKING, Optional, Sequence
 
-from ...session import PackedChat
+from ...session import PeerRef
 from ...tl import abcs, functions, types
 from ..types import (
     AdminRight,
@@ -30,7 +30,7 @@ class ParticipantList(AsyncList[Participant]):
         super().__init__()
         self._client = client
         self._chat = chat
-        self._packed: Optional[PackedChat] = None
+        self._packed: Optional[PeerRef] = None
         self._offset = 0
         self._seen: set[int] = set()
 

client/src/telethon/_impl/client/client/client.py

@@ -13,7 +13,7 @@ from ...session import (
     DataCenter,
     MemorySession,
     MessageBox,
-    PackedChat,
+    PeerRef,
     Session,
     SqliteSession,
     Storage,
@@ -680,7 +680,7 @@ class Client:
         """
         Get the latest basic information about the given chats.
 
-        This method is most commonly used to turn one or more :class:`~types.PackedChat` into the original :class:`~types.Peer`.
+        This method is most commonly used to turn one or more :class:`~types.PeerRef` into the original :class:`~types.Peer`.
         This includes users, groups and broadcast channels.
 
         :param chats:
@@ -2018,7 +2018,7 @@ class Client:
     ) -> 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]:

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:

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:
+) -> PeerRef:
-    if isinstance(chat, PackedChat):
+    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,

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()

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:

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(

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)

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,

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.
 

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,

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",

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"]

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
 

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`.
 

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",
 ]

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)
+        pc = PeerRef(ty, 123, 456789)
-        assert PackedChat.from_bytes(bytes(pc)) == pc
+        assert PeerRef.from_bytes(bytes(pc)) == pc
 
-        pc = PackedChat(ty, 987, None)
+        pc = PeerRef(ty, 987, None)
-        assert PackedChat.from_bytes(bytes(pc)) == pc
+        assert PeerRef.from_bytes(bytes(pc)) == pc