LonamiWebs/Telethon
1
1
Fork 0
mirror of https://github.com/LonamiWebs/Telethon.git synced 2024-11-29 12:53:44 +03:00
Code Issues Packages Projects Releases Wiki Activity

Improve readability for readthedocs/concepts/entities.rst (#3259)

Browse Source
This commit is contained in:
vladislav doster 2022-01-24 06:15:32 -06:00 committed by GitHub
parent f9643bf737
commit 805898c2fd
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 22 additions and 23 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
readthedocs/concepts/entities.rst
View File

@ -39,7 +39,7 @@ A lot of methods and requests require *entities* to work. For example,
you send a message to an *entity*, get the username of an *entity*, and you send a message to an *entity*, get the username of an *entity*, and
so on. so on.
There are a lot of things that work as entities: usernames, phone numbers, There are many things that work as entities: usernames, phone numbers,
chat links, invite links, IDs, and the types themselves. That is, you can chat links, invite links, IDs, and the types themselves. That is, you can
use any of those when you see an "entity" is needed. use any of those when you see an "entity" is needed.
@ -58,16 +58,16 @@ You should use, **from better to worse**:
``entity = await client.get_input_entity(...)``. ``entity = await client.get_input_entity(...)``.
2. Entities. For example, if you had to get someone's 2. Entities. For example, if you had to get someone's
username, you can just use ``user`` or ``channel``. username, you can use ``user`` or ``channel``.
It will work. Only use this option if you already have the entity! It will work. Only use this option if you already have the entity!
3. IDs. This will always look the entity up from the 3. IDs. This will always look the entity up from the
cache (the ``*.session`` file caches seen entities). cache (the ``*.session`` file caches seen entities).
4. Usernames, phone numbers and links. The cache will be 4. Usernames, phone numbers, and links. The cache will be
used too (unless you force a `client.get_entity() used too (unless you force a `client.get_entity()
<telethon.client.users.UserMethods.get_entity>`), <telethon.client.users.UserMethods.get_entity>`),
but may make a request if the username, phone or link but may make a request if the username, phone, or link
has not been found yet. has not been found yet.
In recent versions of the library, the following two are equivalent: In recent versions of the library, the following two are equivalent:
@ -148,7 +148,7 @@ become possible.
Every entity the library encounters (in any response to any call) will by Every entity the library encounters (in any response to any call) will by
default be cached in the ``.session`` file (an SQLite database), to avoid default be cached in the ``.session`` file (an SQLite database), to avoid
performing unnecessary API calls. If the entity cannot be found, additonal performing unnecessary API calls. If the entity cannot be found, additional
calls like :tl:`ResolveUsernameRequest` or :tl:`GetContactsRequest` may be calls like :tl:`ResolveUsernameRequest` or :tl:`GetContactsRequest` may be
made to obtain the required information. made to obtain the required information.
@ -158,24 +158,23 @@ Entities vs. Input Entities
.. note:: .. note::
This section is informative, but worth reading. The library This section is informative but worth reading. The library
will transparently handle all of these details for you. will transparently handle all of these details for you.
On top of the normal types, the API also make use of what they call their On top of the normal types, the API also make use of what they call their
``Input*`` versions of objects. The input version of an entity (e.g. ``Input*`` versions of objects. The input version of an entity (e.g.
:tl:`InputPeerUser`, :tl:`InputChat`, etc.) only contains the minimum :tl:`InputPeerUser`, :tl:`InputChat`, etc.) only contains the minimum
information that's required from Telegram to be able to identify information required from Telegram to identify
who you're referring to: a :tl:`Peer`'s **ID** and **hash**. They who you're referring to: a :tl:`Peer`'s **ID** and **hash**. They
are named like this because they are input parameters in the requests. are named like this because they are input parameters in the requests.
Entities' ID are the same for all user and bot accounts, however, the access Entities' IDs are the same for all user and bot accounts. However, the access
hash is **different for each account**, so trying to reuse the access hash hash is **different for each account**, so trying to reuse the access hash
from one account in another will **not** work. from one account in another will **not** work.
Sometimes, Telegram only needs to indicate the type of the entity along Sometimes, Telegram only needs to indicate the entity type and their ID. For this purpose, :tl:`Peer` versions of the entities also
with their ID. For this purpose, :tl:`Peer` versions of the entities also
exist, which just have the ID. You cannot get the hash out of them since exist, which just have the ID. You cannot get the hash out of them since
you should not be needing it. The library probably has cached it before. you should not need it. The library probably has cached it before.
Peers are enough to identify an entity, but they are not enough to make Peers are enough to identify an entity, but they are not enough to make
a request with them. You need to know their hash before you can a request with them. You need to know their hash before you can
@ -186,15 +185,15 @@ be in your dialogs, participants, message forwards, etc.
You *can* use peers with the library. Behind the scenes, they are You *can* use peers with the library. Behind the scenes, they are
replaced with the input variant. Peers "aren't enough" on their own replaced with the input variant. Peers "aren't enough" on their own
but the library will do some more work to use the right type. , but the library will do some more work to use the right type.
As we just mentioned, API calls don't need to know the whole information As we just mentioned, API calls don't need to know the whole information
about the entities, only their ID and hash. For this reason, another method, about the entities, only their ID and hash. For this reason, another method,
`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>` `client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`
is available. This will always use the cache while possible, making zero API is available. This will always use the cache while possible, making zero API
calls most of the time. When a request is made, if you provided the full calls most of the time. When a request is made, if you provided the full
entity, e.g. an :tl:`User`, the library will convert it to the required entity, e.g. an :tl:`User`, the library will automatically convert it to the required
:tl:`InputPeer` automatically for you. :tl:`InputPeer`.
**You should always favour** **You should always favour**
`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>` `client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`
@ -216,9 +215,9 @@ wherever needed, so you can even do things like:
await client(SendMessageRequest('username', 'hello')) await client(SendMessageRequest('username', 'hello'))
The library will call the ``.resolve()`` method of the request, which will The library will call the request's ``.resolve()`` method, which will
resolve ``'username'`` with the appropriated :tl:`InputPeer`. Don't worry if resolve ``'username'`` with the appropriate :tl:`InputPeer`. Don't worry if
you don't get this yet, but remember some of the details here are important. you don't get this yet, but remember that some of the details here are important.
Full Entities Full Entities
@ -231,8 +230,8 @@ This full variant has additional information such as whether the user is
blocked, its notification settings, the bio or about of the user, etc. blocked, its notification settings, the bio or about of the user, etc.
There is also :tl:`messages.ChatFull` which is the equivalent of full entities There is also :tl:`messages.ChatFull` which is the equivalent of full entities
for chats and channels, with also the about section of the channel. Note that for chats and channels, with the about section of the channel. Note that
the ``users`` field only contains bots for the channel (so that clients can the ``users`` field only contains bots for the channel (so clients can
suggest commands to use). suggest commands to use).
You can get both of these by invoking :tl:`GetFullUser`, :tl:`GetFullChat` You can get both of these by invoking :tl:`GetFullUser`, :tl:`GetFullChat`
@ -282,7 +281,7 @@ Summary
======= =======
TL;DR; If you're here because of *"Could not find the input entity for"*, TL;DR; If you're here because of *"Could not find the input entity for"*,
you must ask yourself "how did I find this entity through official you must ask yourself, "how did I find this entity through official
applications"? Now do the same with the library. Use what applies: applications"? Now do the same with the library. Use what applies:
.. code-block:: python .. code-block:: python
@ -295,13 +294,13 @@ applications"? Now do the same with the library. Use what applies:
# Do you have a conversation open with them? Get dialogs. # Do you have a conversation open with them? Get dialogs.
await client.get_dialogs() await client.get_dialogs()
# Are they participant of some group? Get them. # Are they participants of some group? Get them.
await client.get_participants('username') await client.get_participants('username')
# Is the entity the original sender of a forwarded message? Get it. # Is the entity the original sender of a forwarded message? Get it.
await client.get_messages('username', 100) await client.get_messages('username', 100)
# NOW you can use the ID, anywhere! # NOW you can use the ID anywhere!
await client.send_message(123456, 'Hi!') await client.send_message(123456, 'Hi!')
entity = await client.get_entity(123456) entity = await client.get_entity(123456)
@ -310,4 +309,4 @@ applications"? Now do the same with the library. Use what applies:
Once the library has "seen" the entity, you can use their **integer** ID. Once the library has "seen" the entity, you can use their **integer** ID.
You can't use entities from IDs the library hasn't seen. You must make the You can't use entities from IDs the library hasn't seen. You must make the
library see them *at least once* and disconnect properly. You know where library see them *at least once* and disconnect properly. You know where
the entities are and you must tell the library. It won't guess for you. the entities are, and you must tell the library. It won't guess for you.