LonamiWebs/Telethon
1
1
Fork 0
mirror of https://github.com/LonamiWebs/Telethon.git synced 2024-11-10 19:46:36 +03:00
Code Issues Packages Projects Releases Wiki Activity

Rename PackedChat type to PeerRef

Browse Source
This commit is contained in:
Lonami Exo 2024-03-17 13:21:26 +01:00
parent 7e413e4ee2
commit 46223bcbcc
20 changed files with 65 additions and 65 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
client/doc/concepts/chats.rst
View File

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

2
client/doc/concepts/messages.rst
View File

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

6
client/doc/developing/migration-guide.rst
View File

@ -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::

4
client/src/telethon/_impl/client/client/chats.py
View File

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

6
client/src/telethon/_impl/client/client/client.py
View File

@ -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]:

4
client/src/telethon/_impl/client/client/messages.py
View File

@ -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:

26
client/src/telethon/_impl/client/client/users.py
View File

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

4
client/src/telethon/_impl/client/types/draft.py
View File

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

8
client/src/telethon/_impl/client/types/participant.py
View File

@ -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:

4
client/src/telethon/_impl/client/types/peer/__init__.py
View File

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

6
client/src/telethon/_impl/client/types/peer/channel.py
View File

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

8
client/src/telethon/_impl/client/types/peer/group.py
View File

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

4
client/src/telethon/_impl/client/types/peer/peer.py
View File

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

6
client/src/telethon/_impl/client/types/peer/user.py
View File

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

4
client/src/telethon/_impl/session/__init__.py
View File

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

4
client/src/telethon/_impl/session/chat/__init__.py
View File

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

8
client/src/telethon/_impl/session/chat/hash_cache.py
View File

@ -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

4
client/src/telethon/_impl/session/chat/peer_ref.py
View File

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

4
client/src/telethon/types/__init__.py
View File

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

10
client/tests/packed_chat_test.py
View File

@ -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