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

Merge pull request #1 from LonamiWebs/master

Browse Source 
Hi
This commit is contained in:
D3KRISH 2022-08-14 00:41:58 +05:30 committed by GitHub
commit f3c718ee2b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
204 changed files with 17424 additions and 17187 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
.github/ISSUE_TEMPLATE/bug-report.md vendored
View File

@ -14,7 +14,7 @@ assignees: ''
**Code that causes the issue**
```python
from telethon.sync import TelegramClient
from telethon import TelegramClient
...
```

28
.github/workflows/python.yml vendored
View File

@ -1,28 +0,0 @@
name: Python Library
on: [push, pull_request]
jobs:
build:
runs-on: ubuntu-latest
strategy:
matrix:
python-version: ["3.5", "3.6", "3.7", "3.8"]
steps:
- uses: actions/checkout@v1
- name: Set up Python ${{ matrix.python-version }}
uses: actions/setup-python@v1
with:
python-version: ${{ matrix.python-version }}
- name: Set up env
run: |
python -m pip install --upgrade pip
pip install tox
- name: Lint with flake8
run: |
tox -e flake
- name: Test with pytest
run: |
# use "py", which is the default python version
tox -e py

11
.gitignore vendored
View File

@ -1,11 +1,12 @@
# Generated code
/telethon/tl/functions/
/telethon/tl/types/
/telethon/tl/alltlobjects.py
/telethon/errors/rpcerrorlist.py
/telethon/_tl/fn/
/telethon/_tl/*.py
/telethon/_tl/alltlobjects.py
/telethon/errors/_generated.py
# User session
*.session
sessions/
/usermedia/
# Builds and testing
@ -20,4 +21,4 @@ __pycache__/
/docs/
# File used to manually test new changes, contains sensitive data
/example.py
/example*.py

22
README.rst
View File

@ -35,15 +35,19 @@ Creating a client
.. code-block:: python
from telethon import TelegramClient, events, sync
import asyncio
from telethon import TelegramClient, events
# These example values won't work. You must get your own api_id and
# api_hash from https://my.telegram.org, under API Development.
api_id = 12345
api_hash = '0123456789abcdef0123456789abcdef'
async def main():
client = TelegramClient('session_name', api_id, api_hash)
client.start()
await client.start()
asyncio.run(main())
Doing stuff
@ -51,14 +55,14 @@ Doing stuff
.. code-block:: python
print(client.get_me().stringify())
print((await client.get_me()).stringify())
client.send_message('username', 'Hello! Talking to you from Telethon')
client.send_file('username', '/home/myself/Pictures/holidays.jpg')
await client.send_message('username', 'Hello! Talking to you from Telethon')
await client.send_file('username', '/home/myself/Pictures/holidays.jpg')
client.download_profile_photo('me')
messages = client.get_messages('username')
messages[0].download_media()
await client.download_profile_photo('me')
messages = await client.get_messages('username')
await messages[0].download_media()
@client.on(events.NewMessage(pattern='(?i)hi|hello'))
async def handler(event):
@ -75,7 +79,7 @@ useful information.
.. _asyncio: https://docs.python.org/3/library/asyncio.html
.. _MTProto: https://core.telegram.org/mtproto
.. _Telegram: https://telegram.org
.. _Compatibility and Convenience: https://docs.telethon.dev/en/latest/misc/compatibility-and-convenience.html
.. _Compatibility and Convenience: https://docs.telethon.dev/en/stable/misc/compatibility-and-convenience.html
.. _Read The Docs: https://docs.telethon.dev
.. |logo| image:: logo.svg

2
pyproject.toml
View File

@ -8,7 +8,7 @@ build-backend = "setuptools.build_meta"
[tool.tox]
legacy_tox_ini = """
[tox]
envlist = py35,py36,py37,py38
envlist = py37,py38
# run with tox -e py
[testenv]

18
readthedocs/basic/quick-start.rst
View File

@ -8,14 +8,15 @@ use these if possible.
.. code-block:: python
import asyncio
from telethon import TelegramClient
# Remember to use your own values from my.telegram.org!
api_id = 12345
api_hash = '0123456789abcdef0123456789abcdef'
client = TelegramClient('anon', api_id, api_hash)
async def main():
async with TelegramClient('anon', api_id, api_hash).start() as client:
# Getting information about yourself
me = await client.get_me()
@ -31,7 +32,7 @@ use these if possible.
print(me.phone)
# You can print all the dialogs/conversations that you are part of:
async for dialog in client.iter_dialogs():
async for dialog in client.get_dialogs():
print(dialog.name, 'has ID', dialog.id)
# You can send messages to yourself...
@ -61,7 +62,7 @@ use these if possible.
await client.send_file('me', '/home/me/Pictures/holidays.jpg')
# You can print the message history of any chat:
async for message in client.iter_messages('me'):
async for message in client.get_messages('me'):
print(message.id, message.text)
# You can download media from messages, too!
@ -70,8 +71,7 @@ use these if possible.
path = await message.download_media()
print('File saved to', path) # printed after download is done
with client:
client.loop.run_until_complete(main())
asyncio.run(main())
Here, we show how to sign in, get information about yourself, send
@ -100,12 +100,8 @@ proceeding. We will see all the available methods later on.
# Most of your code should go here.
# You can of course make and use your own async def (do_something).
# They only need to be async if they need to await things.
async with client.start():
me = await client.get_me()
await do_something(me)
with client:
client.loop.run_until_complete(main())
After you understand this, you may use the ``telethon.sync`` hack if you
want do so (see :ref:`compatibility-and-convenience`), but note you may
run into other issues (iPython, Anaconda, etc. have some issues with it).
asyncio.run(main())

40
readthedocs/basic/signing-in.rst
View File

@ -49,15 +49,19 @@ We can finally write some code to log into our account!
.. code-block:: python
import asyncio
from telethon import TelegramClient
# Use your own values from my.telegram.org
api_id = 12345
api_hash = '0123456789abcdef0123456789abcdef'
async def main():
# The first parameter is the .session file name (absolute paths allowed)
with TelegramClient('anon', api_id, api_hash) as client:
client.loop.run_until_complete(client.send_message('me', 'Hello, myself!'))
async with TelegramClient('anon', api_id, api_hash).start() as client:
await client.send_message('me', 'Hello, myself!')
asyncio.run(main())
In the first line, we import the class name so we can create an instance
@ -95,18 +99,19 @@ You will still need an API ID and hash, but the process is very similar:
.. code-block:: python
from telethon.sync import TelegramClient
import asyncio
from telethon import TelegramClient
api_id = 12345
api_hash = '0123456789abcdef0123456789abcdef'
bot_token = '12345:0123456789abcdef0123456789abcdef'
# We have to manually call "start" if we want an explicit bot token
bot = TelegramClient('bot', api_id, api_hash).start(bot_token=bot_token)
async def main():
# But then we can use the client instance as usual
with bot:
...
async with TelegramClient('bot', api_id, api_hash).start(bot_token=bot_token) as bot:
... # bot is your client
asyncio.run(main())
To get a bot account, you need to talk
@ -116,11 +121,9 @@ with `@BotFather <https://t.me/BotFather>`_.
Signing In behind a Proxy
=========================
If you need to use a proxy to access Telegram,
you will need to either:
If you need to use a proxy to access Telegram, you will need to:
* For Python >= 3.6 : `install python-socks[asyncio]`__
* For Python <= 3.5 : `install PySocks`__
`install python-socks[asyncio]`__
and then change
@ -141,16 +144,9 @@ consisting of parameters described `in PySocks usage`__.
The allowed values for the argument ``proxy_type`` are:
* For Python <= 3.5:
* ``socks.SOCKS5`` or ``'socks5'``
* ``socks.SOCKS4`` or ``'socks4'``
* ``socks.HTTP`` or ``'http'``
* For Python >= 3.6:
* All of the above
* ``python_socks.ProxyType.SOCKS5``
* ``python_socks.ProxyType.SOCKS4``
* ``python_socks.ProxyType.HTTP``
* ``python_socks.ProxyType.SOCKS5``
* ``python_socks.ProxyType.SOCKS4``
* ``python_socks.ProxyType.HTTP``
Example:

95
readthedocs/concepts/asyncio.rst
View File

@ -58,84 +58,6 @@ What are asyncio basics?
loop.run_until_complete(main())
What does telethon.sync do?
===========================
The moment you import any of these:
.. code-block:: python
from telethon import sync, ...
# or
from telethon.sync import ...
# or
import telethon.sync
The ``sync`` module rewrites most ``async def``
methods in Telethon to something similar to this:
.. code-block:: python
def new_method():
result = original_method()
if loop.is_running():
# the loop is already running, return the await-able to the user
return result
else:
# the loop is not running yet, so we can run it for the user
return loop.run_until_complete(result)
That means you can do this:
.. code-block:: python
print(client.get_me().username)
Instead of this:
.. code-block:: python
me = client.loop.run_until_complete(client.get_me())
print(me.username)
# or, using asyncio's default loop (it's the same)
import asyncio
loop = asyncio.get_event_loop() # == client.loop
me = loop.run_until_complete(client.get_me())
print(me.username)
As you can see, it's a lot of boilerplate and noise having to type
``run_until_complete`` all the time, so you can let the magic module
to rewrite it for you. But notice the comment above: it won't run
the loop if it's already running, because it can't. That means this:
.. code-block:: python
async def main():
# 3. the loop is running here
print(
client.get_me() # 4. this will return a coroutine!
.username # 5. this fails, coroutines don't have usernames
)
loop.run_until_complete( # 2. run the loop and the ``main()`` coroutine
main() # 1. calling ``async def`` "returns" a coroutine
)
Will fail. So if you're inside an ``async def``, then the loop is
running, and if the loop is running, you must ``await`` things yourself:
.. code-block:: python
async def main():
print((await client.get_me()).username)
loop.run_until_complete(main())
What are async, await and coroutines?
=====================================
@ -153,7 +75,7 @@ loops or use ``async with``:
async with client:
# ^ this is an asynchronous with block
async for message in client.iter_messages(chat):
async for message in client.get_messages(chat):
# ^ this is a for loop over an asynchronous generator
print(message.sender.username)
@ -275,7 +197,7 @@ in it. So if you want to run *other* code, create tasks for it:
loop.create_task(clock())
...
client.run_until_disconnected()
await client.run_until_disconnected()
This creates a task for a clock that prints the time every second.
You don't need to use `client.run_until_disconnected()
@ -344,19 +266,6 @@ When you use a library, you're not limited to use only its methods. You can
combine all the libraries you want. People seem to forget this simple fact!
Why does client.start() work outside async?
===========================================
Because it's so common that it's really convenient to offer said
functionality by default. This means you can set up all your event
handlers and start the client without worrying about loops at all.
Using the client in a ``with`` block, `start
<telethon.client.auth.AuthMethods.start>`, `run_until_disconnected
<telethon.client.updates.UpdateMethods.run_until_disconnected>`, and
`disconnect <telethon.client.telegrambaseclient.TelegramBaseClient.disconnect>`
all support this.
Where can I read more?
======================

2
readthedocs/concepts/botapi-vs-mtproto.rst
View File

@ -145,7 +145,7 @@ After using Telethon:
Key differences:
* The recommended way to do it imports less things.
* The recommended way to do it imports fewer things.
* All handlers trigger by default, so we need ``events.StopPropagation``.
* Adding handlers, responding and running is a lot less verbose.
* Telethon needs ``async def`` and ``await``.

4
readthedocs/concepts/chats-vs-channels.rst
View File

@ -100,12 +100,12 @@ Note that this function can also work with other types, like :tl:`Chat` or
:tl:`Channel` instances.
If you need to convert other types like usernames which might need to perform
API calls to find out the identifier, you can use ``client.get_peer_id``:
API calls to find out the identifier, you can use ``client.get_profile``:
.. code-block:: python
print(await client.get_peer_id('me')) # your id
print((await client.get_profile('me')).id) # your id
If there is no "mark" (no minus sign), Telethon will assume your identifier

395
readthedocs/concepts/entities.rst
View File

@ -1,20 +1,27 @@
.. _entities:
========
Entities
========
===============
Users and Chats
===============
The library widely uses the concept of "entities". An entity will refer
to any :tl:`User`, :tl:`Chat` or :tl:`Channel` object that the API may return
in response to certain methods, such as :tl:`GetUsersRequest`.
The library widely uses the concept of "users" to refer to both real accounts
and bot accounts, as well as the concept of "chats" to refer to groups and
broadcast channels.
The most general term you can use to think about these is "an entity", but
recent versions of the library often prefer to opt for names which better
reflect the intention, such as "dialog" when a previously-existing
conversation is expected, or "profile" when referring to the information about
the user or chat.
.. note::
When something "entity-like" is required, it means that you need to
provide something that can be turned into an entity. These things include,
but are not limited to, usernames, exact titles, IDs, :tl:`Peer` objects,
or even entire :tl:`User`, :tl:`Chat` and :tl:`Channel` objects and even
phone numbers **from people you have in your contact list**.
When something "dialog-like" is required, it means that you need to
provide something that can be used to refer to an open conversation.
These things include, but are not limited to, packed chats, usernames,
integer IDs (identifiers), :tl:`Peer` objects, or even entire :tl:`User`,
:tl:`Chat` and :tl:`Channel` objects and even phone numbers **from people
you have in your contact list**.
To "encounter" an ID, you would have to "find it" like you would in the
normal app. If the peer is in your dialogs, you would need to
@ -23,82 +30,123 @@ in response to certain methods, such as :tl:`GetUsersRequest`.
`client.get_participants(group) <telethon.client.chats.ChatMethods.get_participants>`.
Once you have encountered an ID, the library will (by default) have saved
their ``access_hash`` for you, which is needed to invoke most methods.
its packed version for you, which is needed to invoke most methods.
This is why sometimes you might encounter this error when working with
the library. You should ``except ValueError`` and run code that you know
should work to find the entity.
should work to find the user or chat. You **cannot** use an ID of someone
you haven't interacted with. Because this is more unreliable, packed chats
are recommended instead.
.. contents::
What is an Entity?
==================
What is a User?
===============
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
so on.
A `User <telethon.types._custom.user.User>` can be either a real user account
(some person who has signed up for an account) or a bot account which is
programmed to perform certain actions (created by a developer via
`@BotFather <https://t.me/BotFather>`_).
There are a lot of things that work as entities: usernames, phone numbers,
chat links, invite links, IDs, and the types themselves. That is, you can
use any of those when you see an "entity" is needed.
A lot of methods and requests require user or chats to work. For example,
you can send a message to a *user*, ban a *user* from a group, and so on.
These methods accept more than just `User <telethon.types._custom.user.User>`
as the input parameter. You can also use packed users, usernames, string phone
numbers, or integer IDs, although some have higher cost than others.
When using the username, the library must fetch it first, which can be
expensive. When using the phone number, the library must fetch it first, which
can be expensive. If you plan to use these, it's recommended you manually use
`client.get_profile() <telethon.client.users.UserMethods.get_profile>` to cache
the username or phone number, and then use the value returned instead.
.. note::
Remember that the phone number must be in your contact list before you
can use it.
You should use, **from better to worse**:
The recommended type to use as input parameters to the methods is either a
`User <telethon.types._custom.user.User>` instance or its packed type.
1. Input entities. For example, `event.input_chat
<telethon.tl.custom.chatgetter.ChatGetter.input_chat>`,
`message.input_sender
<telethon.tl.custom.sendergetter.SenderGetter.input_sender>`,
or caching an entity you will use a lot with
``entity = await client.get_input_entity(...)``.
2. Entities. For example, if you had to get someone's
username, you can just use ``user`` or ``channel``.
It will work. Only use this option if you already have the entity!
3. IDs. This will always look the entity up from the
cache (the ``*.session`` file caches seen entities).
4. Usernames, phone numbers and links. The cache will be
used too (unless you force a `client.get_entity()
<telethon.client.users.UserMethods.get_entity>`),
but may make a request if the username, phone or link
has not been found yet.
In recent versions of the library, the following two are equivalent:
.. code-block:: python
async def handler(event):
await client.send_message(event.sender_id, 'Hi')
await client.send_message(event.input_sender, 'Hi')
In the raw API, users are instances of :tl:`User` (or :tl:`UserEmpty`), which
are returned in response to some requests, such as :tl:`GetUsersRequest`.
There are also variants for use as "input parameters", such as :tl:`InputUser`
and :tl:`InputPeerUser`. You generally **do not need** to worry about these
types unless you're using raw API.
If you need to be 99% sure that the code will work (sometimes it's
simply impossible for the library to find the input entity), or if
you will reuse the chat a lot, consider using the following instead:
What is a Chat?
===============
.. code-block:: python
A `Chat <telethon.types._custom.chat.Chat>` can be a small group chat (the
default group type created by users where many users can join and talk), a
megagroup (also known as "supergroup"), a broadcast channel or a broadcast
group.
async def handler(event):
# This method may make a network request to find the input sender.
# Properties can't make network requests, so we need a method.
sender = await event.get_input_sender()
await client.send_message(sender, 'Hi')
await client.send_message(sender, 'Hi')
The term "chat" is really overloaded in Telegram. The library tries to be
explicit and always use "small group chat", "megagroup" and "broadcast" to
differentiate. However, Telegram's API uses "chat" to refer to both "chat"
(small group chat), and "channel" (megagroup, broadcast or "gigagroup" which
is a broadcast group of type channel).
A lot of methods and requests require a chat to work. For example,
you can get the participants from a *chat*, kick users from a *chat*, and so on.
These methods accept more than just `Chat <telethon.types._custom.chat.Chat>`
as the input parameter. You can also use packed chats, the public link, or
integer IDs, although some have higher cost than others.
When using the public link, the library must fetch it first, which can be
expensive. If you plan to use these, it's recommended you manually use
`client.get_profile() <telethon.client.users.UserMethods.get_profile>` to cache
the link, and then use the value returned instead.
.. note::
The link of a public chat has the form "t.me/username", where the username
can belong to either an actual user or a public chat.
The recommended type to use as input parameters to the methods is either a
`Chat <telethon.types._custom.chat.Chat>` instance or its packed type.
In the raw API, chats are instances of :tl:`Chat` and :tl:`Channel` (or
:tl:`ChatEmpty`, :tl:`ChatForbidden` and :tl:`ChannelForbidden`), which
are returned in response to some requests, such as :tl:`messages.GetChats`
and :tl:`channels.GetChannels`. There are also variants for use as "input
parameters", such as :tl:`InputChannel` and :tl:`InputPeerChannel`. You
generally **do not need** to worry about these types unless you're using raw API.
Getting Entities
================
When to use each term?
======================
The term "dialog" is used when the library expects a reference to an open
conversation (from the list the user sees when they open the application).
The term "profile" is used instead of "dialog" when the conversation is not
expected to exist. Because "dialog" is more specific than "profile", "dialog"
is used where possible instead.
In general, you should not use named arguments for neither "dialogs" or
"profiles", since they're the first argument. The parameter name only exists
for documentation purposes.
The term "chat" is used where a group or broadcast channel is expected. This
includes small groups, megagroups, broadcast channels and broadcast groups.
Telegram's API has, in the past, made a difference between which methods can
be used for "small group chats" and everything else. For example, small group
chats cannot have a public link (they automatically convert to megagroups).
Group permissions also used to be different, but because Telegram may unify
these eventually, the library attempts to hide this distinction. In general,
this is not something you should worry about.
Fetching profile information
============================
Through the use of the :ref:`sessions`, the library will automatically
remember the ID and hash pair, along with some extra information, so
you're able to just do this:
remember the packed users and chats, along with some extra information,
so you're able to just do this:
.. code-block:: python
@ -106,146 +154,37 @@ you're able to just do this:
#
# Dialogs are the "conversations you have open".
# This method returns a list of Dialog, which
# has the .entity attribute and other information.
# has the .user and .chat attributes (among others).
#
# This part is IMPORTANT, because it fills the entity cache.
# This part is IMPORTANT, because it fills the cache.
dialogs = await client.get_dialogs()
# All of these work and do the same.
username = await client.get_entity('username')
username = await client.get_entity('t.me/username')
username = await client.get_entity('https://telegram.dog/username')
# All of these work and do the same, but are more expensive to use.
channel = await client.get_profile('username')
channel = await client.get_profile('t.me/username')
channel = await client.get_profile('https://telegram.dog/username')
contact = await client.get_profile('+34xxxxxxxxx')
# Other kind of entities.
channel = await client.get_entity('telegram.me/joinchat/AAAAAEkk2WdoDrB4-Q8-gg')
contact = await client.get_entity('+34xxxxxxxxx')
friend = await client.get_entity(friend_id)
# This will work, but only if the ID is in cache.
friend = await client.get_profile(friend_id)
# Getting entities through their ID (User, Chat or Channel)
entity = await client.get_entity(some_id)
# You can be more explicit about the type for said ID by wrapping
# it inside a Peer instance. This is recommended but not necessary.
from telethon.tl.types import PeerUser, PeerChat, PeerChannel
my_user = await client.get_entity(PeerUser(some_id))
my_chat = await client.get_entity(PeerChat(some_id))
my_channel = await client.get_entity(PeerChannel(some_id))
# This is the most reliable way to fetch a profile.
user = await client.get_profile('U.123.456789')
group = await client.get_profile('G.456.0')
broadcast = await client.get_profile('C.789.123456')
.. note::
You **don't** need to get the entity before using it! Just let the
library do its job. Use a phone from your contacts, username, ID or
input entity (preferred but not necessary), whatever you already have.
All methods in the :ref:`telethon-client` call `.get_input_entity()
<telethon.client.users.UserMethods.get_input_entity>` prior
to sending the request to save you from the hassle of doing so manually.
All methods in the :ref:`telethon-client` accept any of the above
prior to sending the request to save you from the hassle of doing so manually.
That way, convenience calls such as `client.send_message('username', 'hi!')
<telethon.client.messages.MessageMethods.send_message>`
become possible.
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
performing unnecessary API calls. If the entity cannot be found, additonal
calls like :tl:`ResolveUsernameRequest` or :tl:`GetContactsRequest` may be
made to obtain the required information.
Entities vs. Input Entities
===========================
.. note::
This section is informative, but worth reading. The library
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
``Input*`` versions of objects. The input version of an entity (e.g.
:tl:`InputPeerUser`, :tl:`InputChat`, etc.) only contains the minimum
information that's required from Telegram to be able to identify
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.
Entities' ID 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
from one account in another will **not** work.
Sometimes, Telegram only needs to indicate the type of the entity along
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
you should not be needing it. The library probably has cached it before.
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
"use them", and to know the hash you need to "encounter" them, let it
be in your dialogs, participants, message forwards, etc.
.. note::
You *can* use peers with the library. Behind the scenes, they are
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.
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,
`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`
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
entity, e.g. an :tl:`User`, the library will convert it to the required
:tl:`InputPeer` automatically for you.
**You should always favour**
`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`
**over**
`client.get_entity() <telethon.client.users.UserMethods.get_entity>`
for this reason! Calling the latter will always make an API call to get
the most recent information about said entity, but invoking requests don't
need this information, just the :tl:`InputPeer`. Only use
`client.get_entity() <telethon.client.users.UserMethods.get_entity>`
if you need to get actual information, like the username, name, title, etc.
of the entity.
To further simplify the workflow, since the version ``0.16.2`` of the
library, the raw requests you make to the API are also able to call
`client.get_input_entity() <telethon.client.users.UserMethods.get_input_entity>`
wherever needed, so you can even do things like:
.. code-block:: python
await client(SendMessageRequest('username', 'hello'))
The library will call the ``.resolve()`` method of the request, which will
resolve ``'username'`` with the appropriated :tl:`InputPeer`. Don't worry if
you don't get this yet, but remember some of the details here are important.
Full Entities
=============
In addition to :tl:`PeerUser`, :tl:`InputPeerUser`, :tl:`User` (and its
variants for chats and channels), there is also the concept of :tl:`UserFull`.
This full variant has additional information such as whether the user is
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
for chats and channels, with also the about section of the channel. Note that
the ``users`` field only contains bots for the channel (so that clients can
suggest commands to use).
You can get both of these by invoking :tl:`GetFullUser`, :tl:`GetFullChat`
and :tl:`GetFullChannel` respectively.
Accessing Entities
==================
<telethon.client.messages.MessageMethods.send_message>` become possible.
However, it can be expensive to fetch the username every time, so this is
better left for things which are not executed often.
Although it's explicitly noted in the documentation that messages
*subclass* `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`
and `SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>`,
some people still don't get inheritance.
this section will explain what this means.
When the documentation says "Bases: `telethon.tl.custom.chatgetter.ChatGetter`"
it means that the class you're looking at, *also* can act as the class it
@ -258,9 +197,9 @@ That means you can do this:
.. code-block:: python
message.is_private
message.chat_id
await message.get_chat()
message.chat
await event.get_chat()
# ...etc
`SenderGetter <telethon.tl.custom.sendergetter.SenderGetter>` is similar:
@ -268,8 +207,8 @@ That means you can do this:
.. code-block:: python
message.user_id
await message.get_input_user()
message.user
await event.get_input_user()
# ...etc
Quite a few things implement them, so it makes sense to reuse the code.
@ -278,11 +217,51 @@ For example, all events (except raw updates) implement `ChatGetter
in some chat.
Packed User and packed Chat
===========================
A packed `User <telethon.types._custom.user.User>` or a packed
`Chat <telethon.types._custom.chat.Chat>` can be thought of as
"a small string reference to the actual user or chat".
It can easily be saved or embedded in the code for later use,
without having to worry if the user is in the session file cache.
This "packed representation" is a compact way to store the type of the User
or Chat (is it a user account, a bot, a broadcast channel…), the identifier,
and the access hash. This "access hash" is something Telegram uses to ensure
that you can actually use this "User" or "Chat" in requests (so you can't just
create some random user identifier and expect it to work).
In the raw API, this is pretty much "input peers", but the library uses the
term "packed user or chat" to refer to its custom type and string
representation.
The User and Chat 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 from one account in another will **not** work. This also means the packed
representation will only work for the account that created it.
The library needs to have this access hash in some way for it to work.
If it only has an ID and this ID is not in cache, it will not work.
If using the packed representation, the hash is embedded, and will always work.
Every method, including raw API, will automatically convert your types to the
expected input type the API uses, meaning the following will work:
.. code-block:: python
await client(_tl.fn.messages.SendMessage('username', 'hello'))
(This is only a raw API example, there are better ways to send messages.)
Summary
=======
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
TL;DR; If you're here because of *"Could not find the input peer for"*,
you must ask yourself, "how did I find this user or chat through official
applications"? Now do the same with the library. Use what applies:
.. code-block:: python
@ -290,24 +269,28 @@ applications"? Now do the same with the library. Use what applies:
# (These examples assume you are inside an "async def")
async with client:
# Does it have a username? Use it!
entity = await client.get_entity(username)
user = await client.get_profile(username)
# Do you have a conversation open with them? 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')
# Is the entity the original sender of a forwarded message? Get it.
# Is the user the original sender of a forwarded message? Fetch the message.
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!')
entity = await client.get_entity(123456)
print(entity)
user = await client.get_profile(123456)
print(user)
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
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.
Once the library has "seen" the user or chat, you can use their **integer** ID.
You can't use users or chats from IDs the library hasn't seen. You must make
the library see them *at least once* and disconnect properly. You know where
the user or chat are, and you must tell the library. It won't guess for you.
This is why it's recommended to use the packed versions instead. They will
always work (unless Telegram, for some very unlikely reason, changes the way
using users and chats works, of course).

4
readthedocs/concepts/full-api.rst
View File

@ -74,7 +74,7 @@ Or we call `client.get_input_entity()
async def main():
peer = await client.get_input_entity('someone')
client.loop.run_until_complete(main())
asyncio.run(main())
.. note::
@ -129,7 +129,7 @@ as you wish. Remember to use the right types! To sum up:
.. code-block:: python
result = await client(SendMessageRequest(
await client.get_input_entity('username'), 'Hello there!'
await client.get_profile('username'), 'Hello there!'
))

12
readthedocs/concepts/sessions.rst
View File

@ -73,10 +73,10 @@ You can import these ``from telethon.sessions``. For example, using the
.. code-block:: python
from telethon.sync import TelegramClient
from telethon import TelegramClient
from telethon.sessions import StringSession
with TelegramClient(StringSession(string), api_id, api_hash) as client:
async with TelegramClient(StringSession(string), api_id, api_hash) as client:
... # use the client
# Save the string session as a string; you should decide how
@ -129,10 +129,10 @@ The easiest way to generate a string session is as follows:
.. code-block:: python
from telethon.sync import TelegramClient
from telethon import TelegramClient
from telethon.sessions import StringSession
with TelegramClient(StringSession(), api_id, api_hash) as client:
async with TelegramClient(StringSession(), api_id, api_hash) as client:
print(client.session.save())
@ -156,8 +156,8 @@ you can save it in a variable directly:
.. code-block:: python
string = '1aaNk8EX-YRfwoRsebUkugFvht6DUPi_Q25UOCzOAqzc...'
with TelegramClient(StringSession(string), api_id, api_hash) as client:
client.loop.run_until_complete(client.send_message('me', 'Hi'))
async with TelegramClient(StringSession(string), api_id, api_hash).start() as client:
await client.send_message('me', 'Hi')
These strings are really convenient for using in places like Heroku since

2
readthedocs/concepts/strings.rst
View File

@ -8,7 +8,7 @@ does a result have? Well, the easiest thing to do is printing it:
.. code-block:: python
entity = await client.get_entity('username')
entity = await client.get_profile('username')
print(entity)
That will show a huge **string** similar to the following:

2
readthedocs/concepts/updates.rst
View File

@ -28,7 +28,7 @@ In short, you should do this:
buttons = await event.get_buttons()
async def main():
async for message in client.iter_messages('me', 10):
async for message in client.get_messages('me', 10):
# Methods from the client always have these properties ready
chat = message.input_chat
sender = message.sender

10
readthedocs/developing/test-servers.rst
View File

@ -25,13 +25,17 @@ so don't store sensitive data here.
Valid phone numbers are ``99966XYYYY``, where ``X`` is the ``dc_id`` and
``YYYY`` is any number you want, for example, ``1234`` in ``dc_id = 2`` would
be ``9996621234``. The code sent by Telegram will be ``dc_id`` repeated six
times, in this case, ``222222`` so we can hardcode that:
be ``9996621234``. The code sent by Telegram will be ``dc_id`` repeated five
times, in this case, ``22222`` so we can hardcode that:
.. code-block:: python
client = TelegramClient(None, api_id, api_hash)
client.session.set_dc(2, '149.154.167.40', 80)
client.start(
phone='9996621234', code_callback=lambda: '222222'
phone='9996621234', code_callback=lambda: '22222'
)
Note that Telegram has changed the length of login codes multiple times in the
past, so if ``dc_id`` repeated five times does not work, try repeating it six
times.

2
readthedocs/developing/testing.rst
View File

@ -71,7 +71,7 @@ version incompatabilities.
Tox environments are declared in the ``tox.ini`` file. The default
environments, declared at the top, can be simply run with ``tox``. The option
``tox -e py36,flake`` can be used to request specific environments to be run.
``tox -e py37,flake`` can be used to request specific environments to be run.
Brief Introduction to Pytest-cov
================================

6
readthedocs/examples/chats-and-channels.rst
View File

@ -84,6 +84,10 @@ use is very straightforward, or :tl:`InviteToChannelRequest` for channels:
[users_to_add]
))
Note that this method will only really work for friends or bot accounts.
Trying to mass-add users with this approach will not work, and can put both
your account and group to risk, possibly being flagged as spam and limited.
Checking a link without joining
===============================
@ -103,7 +107,7 @@ use :tl:`GetMessagesViewsRequest`, setting ``increment=True``:
.. code-block:: python
# Obtain `channel' through dialogs or through client.get_entity() or anyhow.
# Obtain `channel' through dialogs or through client.get_profile() or anyhow.
# Obtain `msg_ids' through `.get_messages()` or anyhow. Must be a list.
await client(GetMessagesViewsRequest(

2
readthedocs/examples/users.rst
View File

@ -25,7 +25,7 @@ you should use :tl:`GetFullUser`:
# or even
full = await client(GetFullUserRequest('username'))
bio = full.about
bio = full.full_user.about
See :tl:`UserFull` to know what other fields you can access.

16
readthedocs/index.rst
View File

@ -4,17 +4,21 @@ Telethon's Documentation
.. code-block:: python
from telethon.sync import TelegramClient, events
import asyncio
from telethon import TelegramClient, events
with TelegramClient('name', api_id, api_hash) as client:
client.send_message('me', 'Hello, myself!')
print(client.download_profile_photo('me'))
async def main():
async with TelegramClient('name', api_id, api_hash) as client:
await client.send_message('me', 'Hello, myself!')
print(await client.download_profile_photo('me'))
@client.on(events.NewMessage(pattern='(?i).*Hello'))
async def handler(event):
await event.reply('Hey!')
client.run_until_disconnected()
await client.run_until_disconnected()
asyncio.run(main())
* Are you new here? Jump straight into :ref:`installation`!
@ -103,7 +107,7 @@ You can also use the menu on the left to quickly skip over sections.
:caption: Miscellaneous
misc/changelog
misc/wall-of-shame.rst
misc/v2-migration-guide.rst
misc/compatibility-and-convenience
.. toctree::

55
readthedocs/misc/changelog.rst
View File

@ -13,6 +13,61 @@ it can take advantage of new goodies!
.. contents:: List of All Versions
Complete overhaul of the library (v2.0)
=======================================
(inc and link all of migration guide)
properly-typed enums for filters and actions
Rushed release to fix login (v1.24)
===================================
+------------------------+
| Scheme layer used: 133 |
+------------------------+
This is a rushed release. It contains a layer recent enough to not fail with
``UPDATE_APP_TO_LOGIN``, but still not the latest, to avoid breaking more
than necessary.
Breaking Changes
~~~~~~~~~~~~~~~~
* The biggest change is user identifiers (and chat identifiers, and others)
**now use up to 64 bits**, rather than 32. If you were storing them in some
storage with fixed size, you may need to update (such as database tables
storing only integers).
There have been other changes which I currently don't have the time to document.
You can refer to the following link to see them early:
https://github.com/LonamiWebs/Telethon/compare/v1.23.0...v1.24.0
New schema and bug fixes (v1.23)
================================
+------------------------+
| Scheme layer used: 130 |
+------------------------+
`View new and changed raw API methods <https://diff.telethon.dev/?from=129&to=130>`__.
Enhancements
~~~~~~~~~~~~
* `client.pin_message() <telethon.client.messages.MessageMethods.pin_message>`
can now pin on a single side in PMs.
* Iterating participants should now be less expensive floodwait-wise.
Bug fixes
~~~~~~~~~
* The QR login URL was being encoded incorrectly.
* ``force_document`` was being ignored in inline queries for document.
* ``manage_call`` permission was accidentally set to ``True`` by default.
New schema and bug fixes (v1.22)
================================

991
readthedocs/misc/v2-migration-guide.rst Normal file
View File

@ -0,0 +1,991 @@
=========================
Version 2 Migration Guide
=========================
Version 2 represents the second major version change, breaking compatibility
with old code beyond the usual raw API changes in order to clean up a lot of
the technical debt that has grown on the project.
This document documents all the things you should be aware of when migrating from Telethon version
1.x to 2.0 onwards. It is sorted roughly from the "likely most impactful changes" to "there's a
good chance you were not relying on this to begin with".
**Please read this document in full before upgrading your code to Telethon 2.0.**
Python 3.5 is no longer supported
---------------------------------
The library will no longer attempt to support Python 3.5. The minimum version is now Python 3.7.
This also means workarounds for 3.6 and below have been dropped.
User, chat and channel identifiers are now 64-bit numbers
---------------------------------------------------------
`Layer 133 <https://diff.telethon.dev/?from=132&to=133>`__ changed *a lot* of identifiers from
``int`` to ``long``, meaning they will no longer fit in 32 bits, and instead require 64 bits.
If you were storing these identifiers somewhere size did matter (for example, a database), you
will need to migrate that to support the new size requirement of 8 bytes.
For the full list of types changed, please review the above link.
Peer IDs, including chat_id and sender_id, no longer follow bot API conventions
-------------------------------------------------------------------------------
Both the ``utils.get_peer_id`` and ``client.get_peer_id`` methods no longer have an ``add_mark``
parameter. Both will always return the original ID as given by Telegram. This should lead to less
confusion. However, it also means that an integer ID on its own no longer embeds the information
about the type (did it belong to a user, chat, or channel?), so ``utils.get_peer`` can no longer
guess the type from just a number.
Because it's not possible to know what other changes Telegram will do with identifiers, it's
probably best to get used to transparently storing whatever value they send along with the type
separatedly.
As far as I can tell, user, chat and channel identifiers are globally unique, meaning a channel
and a user cannot share the same identifier. The library currently makes this assumption. However,
this is merely an observation (I have never heard of such a collision exist), and Telegram could
change at any time. If you want to be on the safe side, you're encouraged to save a pair of type
and identifier, rather than just the number.
// TODO we DEFINITELY need to provide a way to "upgrade" old ids
// TODO and storing type+number by hand is a pain, provide better alternative
// TODO get_peer_id is gone now too!
Synchronous compatibility mode has been removed
-----------------------------------------------
The "sync hack" (which kicked in as soon as anything from ``telethon.sync`` was imported) has been
removed. This implies:
* The ``telethon.sync`` module is gone.
* Synchronous context-managers (``with`` as opposed to ``async with``) are no longer supported.
Most notably, you can no longer do ``with client``. It must be ``async with client`` now.
* The "smart" behaviour of the following methods has been removed and now they no longer work in
a synchronous context when the ``asyncio`` event loop was not running. This means they now need
to be used with ``await`` (or, alternatively, manually used with ``loop.run_until_complete``):
* ``start``
* ``disconnect``
* ``run_until_disconnected``
// TODO provide standalone alternative for this?
Overhaul of events and updates
------------------------------
Updates produced by the client are now also processed by your event handlers.
Before, if you had some code listening for new outgoing messages, only messages you sent with
another client, such as from Telegram Desktop, would be processed. Now, if your own code uses
``client.send_message``, you will also receive the new message event. Be careful, as this can
easily lead to "loops" (a new outgoing message can trigger ``client.send_message``, which
triggers a new outgoing message and the cycle repeats)!
There are no longer "event builders" and "event" types. Now there are only events, and you
register the type of events you want, not an instance. Because of this, the way filters are
specified have also changed:
.. code-block:: python
# OLD
@client.on(events.NewMessage(chats=...))
async def handler(event):
pass
# NEW
@client.on(events.NewMessage, chats=...)
async def handler(event): # ^^ ^
pass
This also means filters are unified, although not all filters have an effect on all events types.
Type hinting is now done through ``events.NewMessage`` and not ``events.NewMessage.Event``.
The filter rework also enables more features. For example, you can now mutate a ``chats`` filter
to add or remove a chat that needs to be received by a handler, rather than having to remove and
re-add the event handler.
The ``from_users`` filter has been renamed to ``senders``.
The ``inbox`` filter for ``events.MessageRead`` has been removed, in favour of ``outgoing`` and
``incoming``.
``events.register``, ``events.unregister`` and ``events.is_handler`` have been removed. There is
no longer anything special about methods which are handlers, and they are no longer monkey-patched.
Because pre-defining the event type to handle without a client was useful, you can now instead use
the following syntax:
.. code-block:: python
# OLD
@events.register(events.NewMessage)
async def handler(event):
pass
# NEW
async def handler(event: events.NewMessage):
pass # ^^^^^^^^^^^^^^^^^^^^^^^^
As a bonus, you only need to type-hint once, and both your IDE and Telethon will understand what
you meant. This is similar to Python's ``@dataclass`` which uses type hints.
// TODO document filter creation and usage, showcase how to mutate them
Complete overhaul of session files
----------------------------------
If you were using third-party libraries to deal with sessions, you will need to wait for those to
be updated. The library will automatically upgrade the SQLite session files to the new version,
and the ``StringSession`` remains backward-compatible. The sessions can now be async.
In case you were relying on the tables used by SQLite (even though these should have been, and
will still need to be, treated as an implementation detail), here are the changes:
* The ``sessions`` table is now correctly split into ``datacenter`` and ``session``.
``datacenter`` contains information about a Telegram datacenter, along with its corresponding
authorization key, and ``session`` contains information about the update state and user.
* The ``entities`` table is now called ``entity`` and stores the ``type`` separatedly.
* The ``update_state`` table is now split into ``session`` and ``channel``, which can contain
a per-channel ``pts``.
Because **the new version does not cache usernames, phone numbers and display names**, using these
in method calls is now quite expensive. You *should* migrate your code to do the Right Thing and
start using identifiers rather than usernames, phone numbers or invite links. This is both simpler
and more reliable, because while a user identifier won't change, their username could.
You can use the following snippet to make a JSON backup (alternatively, you could just copy the
``.session`` file and keep it around) in case you want to preserve the cached usernames:
.. code-block:: python
import sqlite, json
with sqlite3.connect('your.session') as conn, open('entities.json', 'w', encoding='utf-8') as fp:
json.dump([
{'id': id, 'hash': hash, 'username': username, 'phone': phone, 'name': name, 'date': date}
for (id, hash, username, phone, name, date)
in conn.execute('select id, hash, username, phone, name, date from entities')
], fp)
The following public methods or properties have also been removed from ``SQLiteSession`` because
they no longer make sense:
* ``list_sessions``. You can ``glob.glob('*.session')`` instead.
* ``clone``.
And the following, which were inherited from ``MemorySession``:
* ``delete``. You can ``os.remove`` the file instead (preferably after ``client.log_out()``).
``client.log_out()`` also no longer deletes the session file (it can't as there's no method).
* ``set_dc``.
* ``dc_id``.
* ``server_address``.
* ``port``.
* ``auth_key``.
* ``takeout_id``.
* ``get_update_state``.
* ``set_update_state``.
* ``process_entities``.
* ``get_entity_rows_by_phone``.
* ``get_entity_rows_by_username``.
* ``get_entity_rows_by_name``.
* ``get_entity_rows_by_id``.
* ``get_input_entity``.
* ``cache_file``.
* ``get_file``.
You also can no longer set ``client.session.save_entities = False``. The entities must be saved
for the library to work properly. If you still don't want it, you should subclass the session and
override the methods to do nothing.
Complete overhaul of errors
---------------------------
The following error name have changed to follow a better naming convention (clearer acronyms):
* ``RPCError`` is now ``RpcError``.
* ``InvalidDCError`` is now ``InvalidDcError`` (lowercase ``c``).
The base errors no longer have a ``.message`` field at the class-level. Instead, it is now an
attribute at the instance level (meaning you cannot do ``BadRequestError.message``, it must be
``bad_request_err.message`` where ``isinstance(bad_request_err, BadRequestError)``).
The ``.message`` will gain its value at the time the error is constructed, rather than being
known beforehand.
The parameter order for ``RpcError`` and all its subclasses are now ``(code, message, request)``,
as opposed to ``(message, request, code)``.
Because Telegram errors can be added at any time, the library no longer generate a fixed set of
them. This means you can no longer use ``dir`` to get a full list of them. Instead, the errors
are automatically generated depending on the name you use for the error, with the following rules:
* Numbers are removed from the name. The Telegram error ``FLOOD_WAIT_42`` is transformed into
``FLOOD_WAIT_``.
* Underscores are removed from the name. ``FLOOD_WAIT_`` becomes ``FLOODWAIT``.
* Everything is lowercased. ``FLOODWAIT`` turns into ``floodwait``.
* While the name ends with ``error``, this suffix is removed.
The only exception to this rule is ``2FA_CONFIRM_WAIT_0``, which is transformed as
``twofaconfirmwait`` (read as ``TwoFaConfirmWait``).
What all this means is that, if Telegram raises a ``FLOOD_WAIT_42``, you can write the following:
.. code-block:: python
from telethon.errors import FloodWaitError
try:
await client.send_message(chat, message)
except FloodWaitError as e:
print(f'Flood! wait for {e.seconds} seconds')
Essentially, old code will keep working, but now you have the freedom to define even yet-to-be
discovered errors. This makes use of `PEP 562 <https://www.python.org/dev/peps/pep-0562/>`__ on
Python 3.7 and above and a more-hacky approach below (which your IDE may not love).
Given the above rules, you could also write ``except errors.FLOOD_WAIT`` if you prefer to match
Telegram's naming conventions. We recommend Camel-Case naming with the "Error" suffix, but that's
up to you.
All errors will include a list of ``.values`` (the extracted number) and ``.value`` (the first
number extracted, or ``None`` if ``values`` is empty). In addition to that, certain errors have
a more-recognizable alias (such as ``FloodWait`` which has ``.seconds`` for its ``.value``).
The ``telethon.errors`` module continues to provide certain predefined ``RpcError`` to match on
the *code* of the error and not its message (for instance, match all errors with code 403 with
``ForbiddenError``). Note that a certain error message can appear with different codes too, this
is decided by Telegram.
The ``telethon.errors`` module continues to provide custom errors used by the library such as
``TypeNotFoundError``.
// TODO keep RPCError around? eh idk how much it's used
// TODO should RpcError subclass ValueError? technically the values used in the request somehow were wrong…
// TODO provide a way to see which errors are known in the docs or at tl.telethon.dev
Changes to the default parse mode
---------------------------------
The default markdown parse mode now conforms to the commonmark specification.
The old markdown parser (which was used as the default ``client.parse_mode``) used to emulate
Telegram Desktop's behaviour. Now `<markdown-it-py https://github.com/executablebooks/markdown-it-py>`__
is used instead, which fixes certain parsing bugs but also means the formatting will be different.
Most notably, ``__`` will now make text bold. If you want the old behaviour, use a single
underscore instead (such as ``_``). You can also use a single asterisk (``*``) for italics.
Because now there's proper parsing, you also gain:
* Headings (``# text``) will now be underlined.
* Certain HTML tags will now also be recognized in markdown (including ``<u>`` for underlining text).
* Line breaks behave properly now. For a single-line break, end your line with ``\\``.
* Inline links should no longer behave in a strange manner.
* Pre-blocks can now have a language. Official clients don't syntax highlight code yet, though.
Furthermore, the parse mode is no longer client-dependant. It is now configured through ``Message``.
// TODO provide a way to get back the old behaviour?
The "iter" variant of the client methods have been removed
----------------------------------------------------------
Instead, you can now use the result of the ``get_*`` variant. For instance, where before you had:
.. code-block:: python
async for message in client.iter_messages(...):
pass
You would now do:
.. code-block:: python
async for message in client.get_messages(...):
pass # ^^^ now it's get, not iter
You can still use ``await`` on the ``get_`` methods to retrieve the list.
The removed methods are:
* iter_messages
* iter_dialogs
* iter_participants
* iter_admin_log
* iter_profile_photos
* iter_drafts
The only exception to this rule is ``iter_download``.
Additionally, when using ``await``, if the method was called with a limit of 1 (either through
setting just one value to fetch, or setting the limit to one), either ``None`` or a single item
(outside of a ``list``) will be returned. This used to be the case only for ``get_messages``,
but now all methods behave in the same way for consistency.
When using ``async for``, the default limit will be ``None``, meaning all items will be fetched.
When using ``await``, the default limit will be ``1``, meaning the latest item will be fetched.
If you want to use ``await`` but still get a list, use the ``.collect()`` method to collect the
results into a list:
.. code-block:: python
chat = ...
# will iterate over all (default limit=None)
async for message in client.get_messages(chat):
...
# will return either a single Message or None if there is not any (limit=1)
message = await client.get_messages(chat)
# will collect all messages into a list (default limit=None). will also take long!
all_messages = await client.get_messages(chat).collect()
// TODO keep providing the old ``iter_`` versions? it doesn't really hurt, even if the recommended way changed
// TODO does the download really need to be special? get download is kind of weird though
Raw API has been renamed and is now immutable and considered private
--------------------------------------------------------------------
The subpackage holding the raw API methods has been renamed from ``tl`` to ``_tl`` in order to
signal that these are prone to change across minor version bumps (the ``y`` in version ``x.y.z``).
Because in Python "we're all adults", you *can* use this private module if you need to. However,
you *are* also acknowledging that this is a private module prone to change (and indeed, it will
change on layer upgrades across minor version bumps).
The ``Request`` suffix has been removed from the classes inside ``tl.functions``.
The ``tl.types`` is now simply ``_tl``, and the ``tl.functions`` is now ``_tl.fn``.
Both the raw API types and functions are now immutable. This can enable optimizations in the
future, such as greatly reducing the number of intermediate objects created (something worth
doing for deeply-nested objects).
Some examples:
.. code-block:: python
# Before
from telethon.tl import types, functions
await client(functions.messages.SendMessageRequest(...))
message: types.Message = ...
# After
from telethon import _tl
await client(_tl.fn.messages.SendMessage(...))
message: _tl.Message
This serves multiple goals:
* It removes redundant parts from the names. The "recommended" way of using the raw API is through
the subpackage namespace, which already contains a mention to "functions" in it. In addition,
some requests were awkward, such as ``SendCustomRequestRequest``.
* It makes it easier to search for code that is using the raw API, so that you can quickly
identify which parts are making use of it.
* The name is shorter, but remains recognizable.
Because *a lot* of these objects are created, they now define ``__slots__``. This means you can
no longer monkey-patch them to add new attributes at runtime. You have to create a subclass if you
want to define new attributes.
This also means that the updates from ``events.Raw`` **no longer have** ``update._entities``.
``tlobject.to_dict()`` has changed and is now generated dynamically based on the ``__slots__`.
This may incur a small performance hit (but you shouldn't really be using ``.to_dict()`` when
you can just use attribute access and ``getattr``). In general, this should handle ill-defined
objects more gracefully (for instance, those where you're using a ``tuple`` and not a ``list``
or using a list somewhere it shouldn't be), and have no other observable effects. As an extra
benefit, this slightly cuts down on the amount of bloat.
In ``tlobject.to_dict()``, the special ``_`` key is now also contains the module (so you can
actually distinguish between equally-named classes). If you want the old behaviour, use
``tlobject.__class__.__name__` instead (and add ``Request`` for functions).
Because the string representation of an object used ``tlobject.to_dict()``, it is now also
affected by these changes.
// TODO this definitely generated files mapping from the original name to this new one...
// TODO what's the alternative to update._entities? and update._client??
Many subpackages and modules are now private
--------------------------------------------
There were a lot of things which were public but should not have been. From now on, you should
only rely on things that are either publicly re-exported or defined. That is, as soon as anything
starts with an underscore (``_``) on its name, you're acknowledging that the functionality may
change even across minor version changes, and thus have your code break.
The following subpackages are now considered private:
* ``client`` is now ``_client``.
* ``crypto`` is now ``_crypto``.
* ``extensions`` is now ``_misc``.
* ``tl`` is now ``_tl``.
The following modules have been moved inside ``_misc``:
* ``entitycache.py``
* ``helpers.py``
* ``hints.py``
* ``password.py``
* ``requestiter.py``
* ``statecache.py``
* ``utils.py``
// TODO review telethon/__init__.py isn't exposing more than it should
Using the client in a context-manager no longer calls start automatically
-------------------------------------------------------------------------
The following code no longer automatically calls ``client.start()``:
.. code-block:: python
async with TelegramClient(...) as client:
...
# or
async with client:
...
This means the context-manager will only call ``client.connect()`` and ``client.disconnect()``.
The rationale for this change is that it could be strange for this to ask for the login code if
the session ever was invalid. If you want the old behaviour, you now need to be explicit:
.. code-block:: python
async with TelegramClient(...).start() as client:
... # ++++++++
Note that you do not need to ``await`` the call to ``.start()`` if you are going to use the result
in a context-manager (but it's okay if you put the ``await``).
Changes to sending messages and files
-------------------------------------
When sending messages or files, there is no longer a parse mode. Instead, the ``markdown`` or
``html`` parameters can be used instead of the (plaintext) ``message``.
.. code-block:: python
await client.send_message(chat, 'Default formatting (_markdown_)')
await client.send_message(chat, html='Force <em>HTML</em> formatting')
await client.send_message(chat, markdown='Force **Markdown** formatting')
These 3 parameters are exclusive with each other (you can only use one). The goal here is to make
it consistent with the custom ``Message`` class, which also offers ``.markdown`` and ``.html``
properties to obtain the correctly-formatted text, regardless of the default parse mode, and to
get rid of some implicit behaviour. It's also more convenient to set just one parameter than two
(the message and the parse mode separatedly).
Although the goal is to reduce raw API exposure, ``formatting_entities`` stays, because it's the
only feasible way to manually specify them.
When sending files, you can no longer pass a list of attributes. This was a common workaround to
set video size, audio duration, and so on. Now, proper parameters are available. The goal is to
hide raw API as much as possible (which lets the library hide future breaking changes as much as
possible). One can still use raw API if really needed.
Several methods have been removed from the client
-------------------------------------------------
``client.download_file`` has been removed. Instead, ``client.download_media`` should be used.
The now-removed ``client.download_file`` method was a lower level implementation which should
have not been exposed at all.
``client.build_reply_markup`` has been removed. Manually calling this method was purely an
optimization (the buttons won't need to be transformed into a reply markup every time they're
used). This means you can just remove any calls to this method and things will continue to work.
Support for bot-API style file_id has been removed
--------------------------------------------------
They have been half-broken for a while now, so this is just making an existing reality official.
See `issue #1613 <https://github.com/LonamiWebs/Telethon/issues/1613>`__ for details.
An alternative solution to re-use files may be provided in the future. For the time being, you
should either upload the file as needed, or keep a message with the media somewhere you can
later fetch it (by storing the chat and message identifier).
Additionally, the ``custom.File.id`` property is gone (which used to provide access to this
"bot-API style" file identifier.
// TODO could probably provide an in-memory cache for uploads to temporarily reuse old InputFile.
// this should lessen the impact of the removal of this feature
Removal of several utility methods
----------------------------------
The following ``utils`` methods no longer exist or have been made private:
* ``utils.resolve_bot_file_id``. It was half-broken.
* ``utils.pack_bot_file_id``. It was half-broken.
* ``utils.resolve_invite_link``. It has been broken for a while, so this just makes its removal
official (see `issue #1723 <https://github.com/LonamiWebs/Telethon/issues/1723>`__).
* ``utils.resolve_id``. Marked IDs are no longer used thorough the library. The removal of this
method also means ``utils.get_peer`` can no longer get a ``Peer`` from just a number, as the
type is no longer embedded inside the ID.
// TODO provide the new clean utils
Changes to many friendly methods in the client
----------------------------------------------
Some of the parameters used to initialize the ``TelegramClient`` have been renamed to be clearer:
* ``timeout`` is now ``connect_timeout``.
* ``connection_retries`` is now ``connect_retries``.
* ``retry_delay`` is now ``connect_retry_delay``.
* ``raise_last_call_error`` has been removed and is now the default. This means you won't get a
``ValueError`` if an API call fails multiple times, but rather the original error.
* ``connection`` to change the connection mode has been removed for the time being.
* ``sequential_updates`` has been removed for the time being.
// TODO document new parameters too
``client.send_code_request`` no longer has ``force_sms`` (it was broken and was never reliable).
``client.send_read_acknowledge`` is now ``client.mark_read``, consistent with the method of
``Message``, being shorter and less awkward to type. The method now only supports a single
message, not a list (the list was a lie, because all messages up to the one with the highest
ID were marked as read, meaning one could not leave unread gaps). ``max_id`` is now removed,
since it has the same meaning as the message to mark as read. The method no longer can clear
mentions without marking the chat as read, but this should not be an issue in practice.
Every ``client.action`` can now be directly ``await``-ed, not just ``'cancel'``.
``client.forward_messages`` now requires a list to be specified. The intention is to make it clear
that the method forwards message\ **s** and to reduce the number of strange allowed values, which
needlessly complicate the code. If you still need to forward a single message, manually construct
a list with ``[message]`` or use ``Message.forward_to``.
``client.delete_messages`` now requires a list to be specified, with the same rationale as forward.
``client.get_me`` no longer has an ``input_peer`` parameter. The goal is to hide raw API as much
as possible. Input peers are mostly an implementation detail the library needs to deal with
Telegram's API.
Before, ``client.iter_participants`` (and ``get_participants``) would expect a type or instance
of the raw Telegram definition as a ``filter``. Now, this ``filter`` expects a string.
The supported values are:
* ``'admin'``
* ``'bot'``
* ``'kicked'``
* ``'banned'``
* ``'contact'``
If you prefer to avoid hardcoding strings, you may use ``telethon.enums.Participant``.
The size selector for ``client.download_profile_photo`` and ``client.download_media`` is now using
an enumeration:
.. code-block:: python
from telethon import enums
await client.download_profile_photo(user, thumb=enums.Size.ORIGINAL)
This new selection mode is also smart enough to pick the "next best" size if the specified one
is not available. The parameter is known as ``thumb`` and not ``size`` because documents don't
have a "size", they have thumbnails of different size. For profile photos, the thumbnail size is
also used.
// TODO maintain support for the old way of doing it?
// TODO now that there's a custom filter, filter client-side for small chats?
The custom.Message class and the way it is used has changed
-----------------------------------------------------------
It no longer inherits ``TLObject``, and rather than trying to mimick Telegram's ``Message``
constructor, it now takes two parameters: a ``TelegramClient`` instance and a ``_tl.Message``.
As a benefit, you can now more easily reconstruct instances of this type from a previously-stored
``_tl.Message`` instance.
There are no public attributes. Instead, they are now properties which forward the values into and
from the private ``_message`` field. As a benefit, the documentation will now be easier to follow.
However, you can no longer use ``del`` on these.
The ``_tl.Message.media`` attribute will no longer be ``None`` when using raw API if the media was
``messageMediaEmpty``. As a benefit, you can now actually distinguish between no media and empty
media. The ``Message.media`` property as returned by friendly methods will still be ``None`` on
empty media.
The ``telethon.tl.patched`` hack has been removed.
The message sender no longer is the channel when no sender is provided by Telegram. Telethon used
to patch this value for channels to be the same as the chat, but now it will be faithful to
Telegram's value.
Overhaul of users and chats are no longer raw API types
-------------------------------------------------------
Users and chats are no longer raw API types. The goal is to reduce the amount of raw API exposed
to the user, and to provide less confusing naming. This also means that **the sender and chat of
messages and events is now a different type**. If you were using `isinstance` to check the types,
you will need to update that code. However, if you were accessing things like the ``first_name``
or ``username``, you will be fine.
Raw API is not affected by this change. When using it, the raw :tl:`User`, :tl:`Chat` and
:tl:`Channel` are still returned.
For friendly methods and events, There are now two main entity types, `User` and `Chat`.
`User`\ s are active entities which can send messages and interact with eachother. There is an
account controlling them. `Chat`\ s are passive entities where multiple users can join and
interact with each other. This includes small groups, supergroups, and broadcast channels.
``event.get_sender``, ``event.sender``, ``event.get_chat``, and ``event.chat`` (as well as
the same methods on ``message`` and elsewhere) now return this new type. The ``sender`` and
``chat`` is **now always returned** (where it makes sense, so no sender in channel messages),
even if Telegram did not include information about it in the update. This means you can use
send messages to ``event.chat`` without worrying if Telegram included this information or not,
or even access ``event.chat.id``. This was often a papercut. However, if you need other
information like the title, you might still need to use ``await event.get_chat()``, which is
used to signify an API call might be necessary.
``event.get_input_sender``, ``event.input_sender``, ``message.get_input_sender`` and
``message.input_sender`` (among other variations) have been removed. Instead, a new ``compact``
method has been added to the new `User` and `Chat` types, which can be used to obtain a compact
representation of the sender. The "input" terminology is confusing for end-users, as it's mostly
an implementation detail of friendly methods. Because the return type would've been different
had these methods been kept, one would have had to review code using them regardless.
What this means is that, if you now want a compact way to store a user or chat for later use,
you should use ``compact``:
.. code-block:: python
compacted_user = message.sender.compact()
# store compacted_user in a database or elsewhere for later use
Public methods accept this type as input parameters. This means you can send messages to a
compacted user or chat, for example.
``event.is_private``, ``event.is_group`` and ``event.is_channel`` have **been removed** (among
other variations, such as in ``message``). It didn't make much sense to ask "is this event a
group", and there is no such thing as "group messages" currently either. Instead, it's sensible
to ask if the sender of a message is a group, or the chat of an event is a channel. New properties
have been added to both the `User` and `Chat` classes:
* ``.is_user`` will always be `True` for `User` and `False` for `Chat`.
* ``.is_group`` will be `False` for `User` and be `True` for small group chats and supergroups.
* ``.is_broadcast`` will be `False` for `User` and `True` for broadcast channels and broadcast groups.
Because the properties exist both in `User` and `Chat`, you do not need use `isinstance` to check
if a sender is a channel or if a chat is a user.
Some fields of the new `User` type differ from the naming or value type of its raw API counterpart:
* ``user.restriction_reason`` has been renamed to ``restriction_reasons`` (with a trailing **s**)
and now always returns a list.
* ``user.bot_chat_history`` has been renamed to ``user.bot_info.chat_history_access``.
* ``user.bot_nochats`` has been renamed to ``user.bot_info.private_only``.
* ``user.bot_inline_geo`` has been renamed to ``user.bot_info.inline_geo``.
* ``user.bot_info_version`` has been renamed to ``user.bot_info.version``.
* ``user.bot_inline_placeholder`` has been renamed to ``user.bot_info.inline_placeholder``.
The new ``user.bot_info`` field will be `None` for non-bots. The goal is to unify where this
information is found and reduce clutter in the main ``user`` type.
Some fields of the new `Chat` type differ from the naming or value type of its raw API counterpart:
* ``chat.date`` is currently not available. It's either the chat creation or join date, but due
to this inconsistency, it's not included to allow for a better solution in the future.
* ``chat.has_link`` is currently not available, to allow for a better alternative in the future.
* ``chat.has_geo`` is currently not available, to allow for a better alternative in the future.
* ``chat.call_active`` is currently not available, until it's decided what to do about calls.
* ``chat.call_not_empty`` is currently not available, until it's decided what to do about calls.
* ``chat.version`` was removed. It's an implementation detail.
* ``chat.min`` was removed. It's an implementation detail.
* ``chat.deactivated`` was removed. It's redundant with ``chat.migrated_to``.
* ``chat.forbidden`` has been added as a replacement for ``isinstance(chat, (ChatForbidden, ChannelForbidden))``.
* ``chat.forbidden_until`` has been added as a replacement for ``until_date`` in forbidden chats.
* ``chat.restriction_reason`` has been renamed to ``restriction_reasons`` (with a trailing **s**)
and now always returns a list.
* ``chat.migrated_to`` no longer returns a raw type, and instead returns this new `Chat` type.
If you have a need for these, please step in, and explain your use case, so we can work together
to implement a proper design.
Both the new `User` and `Chat` types offer a ``fetch`` method, which can be used to refetch the
instance with fresh information, including the full information about the user (such as the user's
biography or a chat's about description).
Using a flat list to define buttons will now create rows and not columns
------------------------------------------------------------------------
When sending a message with buttons under a bot account, passing a flat list such as the following:
.. code-block:: python
bot.send_message(chat, message, buttons=[
Button.inline('top'),
Button.inline('middle'),
Button.inline('bottom'),
])
Will now send a message with 3 rows of buttons, instead of a message with 3 columns (old behaviour).
If you still want the old behaviour, wrap the list inside another list:
.. code-block:: python
bot.send_message(chat, message, buttons=[[
# +
Button.inline('left'),
Button.inline('center'),
Button.inline('right'),
]])
#+
Changes to the string and to_dict representation
------------------------------------------------
The string representation of raw API objects will now have its "printing depth" limited, meaning
very large and nested objects will be easier to read.
If you want to see the full object's representation, you should instead use Python's builtin
``repr`` method.
The ``.stringify`` method remains unchanged.
Here's a comparison table for a convenient overview:
+-------------------+---------------------------------------------+---------------------------------------------+
| | Telethon v1.x | Telethon v2.x |
+-------------------+-------------+--------------+----------------+-------------+--------------+----------------+
| | ``__str__`` | ``__repr__`` | ``.stringify`` | ``__str__`` | ``__repr__`` | ``.stringify`` |
+-------------------+-------------+--------------+----------------+-------------+--------------+----------------+
| Useful? | ✅ | ❌ | ✅ | ✅ | ✅ | ✅ |
+-------------------+-------------+--------------+----------------+-------------+--------------+----------------+
| Multiline? | ❌ | ❌ | ✅ | ❌ | ❌ | ✅ |
+-------------------+-------------+--------------+----------------+-------------+--------------+----------------+
| Shows everything? | ✅ | ❌ | ✅ | ❌ | ✅ | ✅ |
+-------------------+-------------+--------------+----------------+-------------+--------------+----------------+
Both of the string representations may still change in the future without warning, as Telegram
adds, changes or removes fields. It should only be used for debugging. If you need a persistent
string representation, it is your job to decide which fields you care about and their format.
The ``Message`` representation now contains different properties, which should be more useful and
less confusing.
Changes on how to configure a different connection mode
-------------------------------------------------------
The ``connection`` parameter of the ``TelegramClient`` now expects a string, and not a type.
The supported values are:
* ``'full'``
* ``'intermediate'``
* ``'abridged'``
* ``'obfuscated'``
* ``'http'``
The value chosen by the library is left as an implementation detail which may change. However,
you can force a certain mode by explicitly configuring it. If you don't want to hardcode the
string, you can import these values from the new ``telethon.enums`` module:
.. code-block:: python
client = TelegramClient(..., connection='tcp')
# or
from telethon.enums import ConnectionMode
client = TelegramClient(..., connection=ConnectionMode.TCP)
You may have noticed there's currently no alternative for ``TcpMTProxy``. This mode has been
broken for some time now (see `issue #1319 <https://github.com/LonamiWebs/Telethon/issues/1319>`__)
anyway, so until there's a working solution, the mode is not supported. Pull Requests are welcome!
The to_json method on objects has been removed
----------------------------------------------
This was not very useful, as most of the time, you'll probably be having other data along with the
object's JSON. It simply saved you an import (and not even always, in case you wanted another
encoder). Use ``json.dumps(obj.to_dict())`` instead.
The Conversation API has been removed
-------------------------------------
This API had certain shortcomings, such as lacking persistence, poor interaction with other event
handlers, and overcomplicated usage for anything beyond the simplest case.
It is not difficult to write your own code to deal with a conversation's state. A simple
`Finite State Machine <https://stackoverflow.com/a/62246569/>`__ inside your handlers will do
just fine This approach can also be easily persisted, and you can adjust it to your needs and
your handlers much more easily.
// TODO provide standalone alternative for this?
Certain client properties and methods are now private or no longer exist
------------------------------------------------------------------------
The ``client.loop`` property has been removed. ``asyncio`` has been moving towards implicit loops,
so this is the next step. Async methods can be launched with the much simpler ``asyncio.run`` (as
opposed to the old ``client.loop.run_until_complete``).
The ``client.upload_file`` method has been removed. It's a low-level method users should not need
to use. Its only purpose could have been to implement a cache of sorts, but this is something the
library needs to do, not the users.
The methods to deal with folders have been removed. The goal is to find and offer a better
interface to deal with both folders and archived chats in the future if there is demand for it.
This includes the removal of ``client.edit_folder``, ``Dialog.archive``, ``Dialog.archived``, and
the ``archived`` parameter of ``client.get_dialogs``. The ``folder`` parameter remains as it's
unlikely to change.
Deleting messages now returns a more useful value
-------------------------------------------------
It used to return a list of :tl:`messages.affectedMessages` which I expect very little people were
actually using. Now it returns an ``int`` value indicating the number of messages that did exist
and were deleted.
Changes to the methods to retrieve participants
-----------------------------------------------
The "aggressive" hack in ``get_participants`` (and ``iter_participants``) is now gone.
It was not reliable, and was a cause of flood wait errors.
The ``search`` parameter is no longer ignored when ``filter`` is specified.
The total value when getting participants has changed
-----------------------------------------------------
Before, it used to always be the total amount of people inside the chat. Now the filter is also
considered. If you were running ``client.get_participants`` with a ``filter`` other than the
default and accessing the ``list.total``, you will now get a different result. You will need to
perform a separate request with no filter to fetch the total without filter (this is what the
library used to do).
Changes to editing messages
---------------------------
Before, calling ``message.edit()`` would completely ignore your attempt to edit a message if the
message had a forward header or was not outgoing. This is no longer the case. It is now the user's
responsibility to check for this.
However, most likely, you were already doing the right thing (or else you would've experienced a
"why is this not being edited", which you would most likely consider a bug rather than a feature).
When using ``client.edit_message``, you now must always specify the chat and the message (or
message identifier). This should be less "magic". As an example, if you were doing this before:
.. code-block:: python
await client.edit_message(message, 'new text')
You now have to do the following:
.. code-block:: python
await client.edit_message(message.input_chat, message.id, 'new text')
# or
await message.edit('new text')
Signing in no longer sends the code
-----------------------------------
``client.sign_in()`` used to run ``client.send_code_request()`` if you only provided the phone and
not the code. It no longer does this. If you need that convenience, use ``client.start()`` instead.
The client.disconnected property has been removed
-------------------------------------------------
``client.run_until_disconnected()`` should be used instead.
The TelegramClient is no longer made out of mixins
--------------------------------------------------
If you were relying on any of the individual mixins that made up the client, such as
``UserMethods`` inside the ``telethon.client`` subpackage, those are now gone.
There is a single ``TelegramClient`` class now, containing everything you need.
The takeout context-manager has changed
---------------------------------------
It no longer has a finalize. All the requests made by the client in the same task will be wrapped,
not only those made through the proxy client returned by the context-manager.
This cleans up the (rather hacky) implementation, making use of Python's ``contextvar``. If you
still need the takeout session to persist, you should manually use the ``begin_takeout`` and
``end_takeout`` method.
If you want to ignore the currently-active takeout session in a task, toggle the following context
variable:
.. code-block:: python
telethon.ignore_takeout.set(True)
CdnDecrypter has been removed
-----------------------------
It was not really working and was more intended to be an implementation detail than anything else.
URL buttons no longer open the web-browser
------------------------------------------
Now the URL is returned. You can still use ``webbrowser.open`` to get the old behaviour.
---
todo update send_message and send_file docs (well review all functions)
album overhaul. use a list of Message instead.
is_connected is now a property (consistent with the rest of ``is_`` properties)
send_code_request now returns a custom type (reducing raw api).
sign_in no longer has phone or phone_hash (these are impl details, and now it's less error prone). also mandatory code=. also no longer is a no-op if already logged in. different error for sign up required.
send code / sign in now only expect a single phone. resend code with new phone is send code, not resend.
sign_up code is also now a kwarg. and no longer noop if already loggedin.
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.
"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
less types are supported to get entity (exact names, private links are undocumented but may work). get_entity is get_profile. get_input_entity is gone. get_peer_id is gone (if the isntance needs to be fetched anyway just use get_profile).

65
readthedocs/misc/wall-of-shame.rst
View File

@ -1,65 +0,0 @@
=============
Wall of Shame
=============
This project has an
`issues <https://github.com/LonamiWebs/Telethon/issues>`__ section for
you to file **issues** whenever you encounter any when working with the
library. Said section is **not** for issues on *your* program but rather
issues with Telethon itself.
If you have not made the effort to 1. read through the docs and 2.
`look for the method you need <https://tl.telethon.dev/>`__,
you will end up on the `Wall of
Shame <https://github.com/LonamiWebs/Telethon/issues?q=is%3Aissue+label%3ARTFM+is%3Aclosed>`__,
i.e. all issues labeled
`"RTFM" <http://www.urbandictionary.com/define.php?term=RTFM>`__:
**rtfm**
Literally "Read The F--king Manual"; a term showing the
frustration of being bothered with questions so trivial that the asker
could have quickly figured out the answer on their own with minimal
effort, usually by reading readily-available documents. People who
say"RTFM!" might be considered rude, but the true rude ones are the
annoying people who take absolutely no self-responibility and expect to
have all the answers handed to them personally.
*"Damn, that's the twelveth time that somebody posted this question
to the messageboard today! RTFM, already!"*
*by Bill M. July 27, 2004*
If you have indeed read the docs, and have tried looking for the method,
and yet you didn't find what you need, **that's fine**. Telegram's API
can have some obscure names at times, and for this reason, there is a
`"question"
label <https://github.com/LonamiWebs/Telethon/issues?utf8=%E2%9C%93&q=is%3Aissue%20is%3Aclosed%20label%3Aquestion%20>`__
with questions that are okay to ask. Just state what you've tried so
that we know you've made an effort, or you'll go to the Wall of Shame.
Of course, if the issue you're going to open is not even a question but
a real issue with the library (thankfully, most of the issues have been
that!), you won't end up here. Don't worry.
Current winner
--------------
The current winner is `issue
213 <https://github.com/LonamiWebs/Telethon/issues/213>`__:
**Issue:**
.. figure:: https://user-images.githubusercontent.com/6297805/29822978-9a9a6ef0-8ccd-11e7-9ec5-934ea0f57681.jpg
:alt: Winner issue
Winner issue
**Answer:**
.. figure:: https://user-images.githubusercontent.com/6297805/29822983-9d523402-8ccd-11e7-9fb1-5783740ee366.jpg
:alt: Winner issue answer
Winner issue answer

4
readthedocs/modules/client.rst
View File

@ -20,10 +20,10 @@ Each mixin has its own methods, which you all can use.
async def main():
# Now you can use all client methods listed below, like for example...
async with client.start():
await client.send_message('me', 'Hello to myself!')
with client:
client.loop.run_until_complete(main())
asyncio.run(main())
You **don't** need to import these `AuthMethods`, `MessageMethods`, etc.

11
readthedocs/modules/custom.rst
View File

@ -46,15 +46,6 @@ ChatGetter
:show-inheritance:
Conversation
============
.. automodule:: telethon.tl.custom.conversation
:members:
:undoc-members:
:show-inheritance:
Dialog
======
@ -145,7 +136,7 @@ ParticipantPermissions
:show-inheritance:
QRLogin
QrLogin
=======
.. automodule:: telethon.tl.custom.qrlogin

7
readthedocs/quick-references/client-reference.rst
View File

@ -103,11 +103,9 @@ Dialogs
iter_dialogs
get_dialogs
edit_folder
iter_drafts
get_drafts
delete_dialog
conversation
Users
-----
@ -120,9 +118,7 @@ Users
get_me
is_bot
is_user_authorized
get_entity
get_input_entity
get_peer_id
get_profile
Chats
-----
@ -169,6 +165,7 @@ Updates
remove_event_handler
list_event_handlers
catch_up
set_receive_updates
Bots
----

23
readthedocs/quick-references/faq.rst
View File

@ -127,14 +127,7 @@ This is basic Python knowledge. You should use the dot operator:
AttributeError: 'coroutine' object has no attribute 'id'
========================================================
You either forgot to:
.. code-block:: python
import telethon.sync
# ^^^^^ import sync
Or:
Telethon is an asynchronous library. This means you need to ``await`` most methods:
.. code-block:: python
@ -218,19 +211,7 @@ Check out `quart_login.py`_ for an example web-application based on Quart.
Can I use Anaconda/Spyder/IPython with the library?
===================================================
Yes, but these interpreters run the asyncio event loop implicitly,
which interferes with the ``telethon.sync`` magic module.
If you use them, you should **not** import ``sync``:
.. code-block:: python
# Change any of these...:
from telethon import TelegramClient, sync, ...
from telethon.sync import TelegramClient, ...
# ...with this:
from telethon import TelegramClient, ...
Yes, but these interpreters run the asyncio event loop implicitly, so be wary of that.
You are also more likely to get "sqlite3.OperationalError: database is locked"
with them. If they cause too much trouble, just write your code in a ``.py``

35
readthedocs/quick-references/objects-reference.rst
View File

@ -155,39 +155,12 @@ its name, bot-API style file ID, etc.
sticker_set
Conversation
============
The `Conversation <telethon.tl.custom.conversation.Conversation>` object
is returned by the `client.conversation()
<telethon.client.dialogs.DialogMethods.conversation>` method to easily
send and receive responses like a normal conversation.
It bases `ChatGetter <telethon.tl.custom.chatgetter.ChatGetter>`.
.. currentmodule:: telethon.tl.custom.conversation.Conversation
.. autosummary::
:nosignatures:
send_message
send_file
mark_read
get_response
get_reply
get_edit
wait_read
wait_event
cancel
cancel_all
AdminLogEvent
=============
The `AdminLogEvent <telethon.tl.custom.adminlogevent.AdminLogEvent>` object
is returned by the `client.iter_admin_log()
<telethon.client.chats.ChatMethods.iter_admin_log>` method to easily iterate
is returned by the `client.get_admin_log()
<telethon.client.chats.ChatMethods.get_admin_log>` method to easily iterate
over past "events" (deleted messages, edits, title changes, leaving members…)
These are all the properties you can find in it:
@ -297,7 +270,7 @@ Dialog
======
The `Dialog <telethon.tl.custom.dialog.Dialog>` object is returned when
you call `client.iter_dialogs() <telethon.client.dialogs.DialogMethods.iter_dialogs>`.
you call `client.get_dialogs() <telethon.client.dialogs.DialogMethods.get_dialogs>`.
.. currentmodule:: telethon.tl.custom.dialog.Dialog
@ -313,7 +286,7 @@ Draft
======
The `Draft <telethon.tl.custom.draft.Draft>` object is returned when
you call `client.iter_drafts() <telethon.client.dialogs.DialogMethods.iter_drafts>`.
you call `client.get_drafts() <telethon.client.dialogs.DialogMethods.get_drafts>`.
.. currentmodule:: telethon.tl.custom.draft.Draft

5
requirements.txt
View File

@ -1,2 +1,3 @@
pyaes
rsa
markdown-it-py~=1.1.0
pyaes~=1.6.1
rsa~=4.7.2

16
setup.py
View File

@ -47,16 +47,16 @@ GENERATOR_DIR = Path('telethon_generator')
LIBRARY_DIR = Path('telethon')
ERRORS_IN = GENERATOR_DIR / 'data/errors.csv'
ERRORS_OUT = LIBRARY_DIR / 'errors/rpcerrorlist.py'
ERRORS_OUT = LIBRARY_DIR / 'errors/_generated.py'
METHODS_IN = GENERATOR_DIR / 'data/methods.csv'
# Which raw API methods are covered by *friendly* methods in the client?
FRIENDLY_IN = GENERATOR_DIR / 'data/friendly.csv'
TLOBJECT_IN_TLS = [Path(x) for x in GENERATOR_DIR.glob('data/*.tl')]
TLOBJECT_OUT = LIBRARY_DIR / 'tl'
IMPORT_DEPTH = 2
TLOBJECT_IN_TLS = [Path(x) for x in sorted(GENERATOR_DIR.glob('data/*.tl'))]
TLOBJECT_OUT = LIBRARY_DIR / '_tl'
TLOBJECT_MOD = 'telethon._tl'
DOCS_IN_RES = GENERATOR_DIR / 'data/html'
DOCS_OUT = Path('docs')
@ -94,7 +94,7 @@ def generate(which, action='gen'):
if clean:
clean_tlobjects(TLOBJECT_OUT)
else:
generate_tlobjects(tlobjects, layer, IMPORT_DEPTH, TLOBJECT_OUT)
generate_tlobjects(tlobjects, layer, TLOBJECT_MOD, TLOBJECT_OUT)
if 'errors' in which:
which.remove('errors')
@ -208,7 +208,7 @@ def main(argv):
# See https://stackoverflow.com/a/40300957/4759433
# -> https://www.python.org/dev/peps/pep-0345/#requires-python
# -> http://setuptools.readthedocs.io/en/latest/setuptools.html
python_requires='>=3.5',
python_requires='>=3.7',
# See https://pypi.python.org/pypi?%3Aaction=list_classifiers
classifiers=[
@ -223,10 +223,10 @@ def main(argv):
'License :: OSI Approved :: MIT License',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.5',
'Programming Language :: Python :: 3.6',
'Programming Language :: Python :: 3.7',
'Programming Language :: Python :: 3.8',
'Programming Language :: Python :: 3.9',
'Programming Language :: Python :: 3.10',
],
keywords='telegram api chat client library messaging mtproto',
packages=find_packages(exclude=[

21
telethon/__init__.py
View File

@ -1,14 +1,11 @@
from .client.telegramclient import TelegramClient
from .network import connection
from .tl import types, functions, custom
from .tl.custom import Button
from .tl import patched as _ # import for its side-effects
from . import version, events, utils, errors
# Note: the import order matters
from ._misc import helpers as _ # no dependencies
from . import _tl # no dependencies
from ._misc import utils as _ # depends on helpers and _tl
from ._misc import hints as _ # depends on types/custom
from ._client.account import ignore_takeout
from ._client.telegramclient import TelegramClient
from . import version, events, errors, enums
__version__ = version.__version__
__all__ = [
'TelegramClient', 'Button',
'types', 'functions', 'custom', 'errors',
'events', 'utils', 'connection'
]

4
telethon/_client/__init__.py Normal file
View File

@ -0,0 +1,4 @@
"""
This package defines the main `telethon._client.telegramclient.TelegramClient` instance
which delegates the work to free-standing functions defined in the rest of files.
"""

75
telethon/_client/account.py Normal file
View File

@ -0,0 +1,75 @@
import functools
import inspect
import typing
import dataclasses
import asyncio
from contextvars import ContextVar
from .._misc import helpers, utils
from .. import _tl
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
ignore_takeout = ContextVar('ignore_takeout', default=False)
# TODO Make use of :tl:`InvokeWithMessagesRange` somehow
# For that, we need to use :tl:`GetSplitRanges` first.
class _Takeout:
def __init__(self, client, kwargs):
self._client = client
self._kwargs = kwargs
async def __aenter__(self):
await self._client.begin_takeout(**self._kwargs)
return self._client
async def __aexit__(self, exc_type, exc_value, traceback):
await self._client.end_takeout(success=exc_type is None)
def takeout(self: 'TelegramClient', **kwargs):
return _Takeout(self, kwargs)
async def begin_takeout(
self: 'TelegramClient',
*,
contacts: bool = None,
users: bool = None,
chats: bool = None,
megagroups: bool = None,
channels: bool = None,
files: bool = None,
max_file_size: bool = None,
) -> 'TelegramClient':
if self.takeout_active:
raise ValueError('a previous takeout session was already active')
takeout = await self(_tl.fn.account.InitTakeoutSession(
contacts=contacts,
message_users=users,
message_chats=chats,
message_megagroups=megagroups,
message_channels=channels,
files=files,
file_max_size=max_file_size
))
await self._replace_session_state(takeout_id=takeout.id)
def takeout_active(self: 'TelegramClient') -> bool:
return self._session_state.takeout_id is not None
async def end_takeout(self: 'TelegramClient', *, success: bool) -> bool:
if not self.takeout_active:
raise ValueError('no previous takeout session was active')
result = await self(_tl.fn.account.FinishTakeoutSession(success))
if not result:
raise ValueError("could not end the active takeout session")
await self._replace_session_state(takeout_id=None)

408
telethon/_client/auth.py Normal file
View File

@ -0,0 +1,408 @@
import asyncio
import getpass
import inspect
import os
import sys
import typing
import warnings
import functools
import time
import dataclasses
from .._misc import utils, helpers, password as pwd_mod
from .. import errors, _tl
from ..types import _custom
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
class StartingClient:
def __init__(self, client, start_fn):
self.client = client
self.start_fn = start_fn
async def __aenter__(self):
await self.start_fn()
return self.client
async def __aexit__(self, *args):
await self.client.__aexit__(*args)
def __await__(self):
return self.__aenter__().__await__()
def start(
self: 'TelegramClient',
phone: typing.Callable[[], str] = lambda: input('Please enter your phone (or bot token): '),
password: typing.Callable[[], str] = lambda: getpass.getpass('Please enter your password: '),
*,
bot_token: str = None,
code_callback: typing.Callable[[], typing.Union[str, int]] = None,
first_name: str = 'New User',
last_name: str = '',
max_attempts: int = 3) -> 'TelegramClient':
if code_callback is None:
def code_callback():
return input('Please enter the code you received: ')
elif not callable(code_callback):
raise ValueError(
'The code_callback parameter needs to be a callable '
'function that returns the code you received by Telegram.'
)
if not phone and not bot_token:
raise ValueError('No phone number or bot token provided.')
if phone and bot_token and not callable(phone):
raise ValueError('Both a phone and a bot token provided, '
'must only provide one of either')
return StartingClient(self, functools.partial(_start,
self=self,
phone=phone,
password=password,
bot_token=bot_token,
code_callback=code_callback,
first_name=first_name,
last_name=last_name,
max_attempts=max_attempts
))
async def _start(
self: 'TelegramClient', phone, password, bot_token,
code_callback, first_name, last_name, max_attempts):
if not self.is_connected:
await self.connect()
# Rather than using `is_user_authorized`, use `get_me`. While this is
# more expensive and needs to retrieve more data from the server, it
# enables the library to warn users trying to login to a different
# account. See #1172.
me = await self.get_me()
if me is not None:
# The warnings here are on a best-effort and may fail.
if bot_token:
# bot_token's first part has the bot ID, but it may be invalid
# so don't try to parse as int (instead cast our ID to string).
if bot_token[:bot_token.find(':')] != str(me.id):
warnings.warn(
'the session already had an authorized user so it did '
'not login to the bot account using the provided '
'bot_token (it may not be using the user you expect)'
)
elif phone and not callable(phone) and utils.parse_phone(phone) != me.phone:
warnings.warn(
'the session already had an authorized user so it did '
'not login to the user account using the provided '
'phone (it may not be using the user you expect)'
)
return self
if not bot_token:
# Turn the callable into a valid phone number (or bot token)
while callable(phone):
value = phone()
if inspect.isawaitable(value):
value = await value
if ':' in value:
# Bot tokens have 'user_id:access_hash' format
bot_token = value
break
phone = utils.parse_phone(value) or phone
if bot_token:
await self.sign_in(bot_token=bot_token)
return self
me = None
attempts = 0
two_step_detected = False
await self.send_code_request(phone)
sign_up = False # assume login
while attempts < max_attempts:
try:
value = code_callback()
if inspect.isawaitable(value):
value = await value
# Since sign-in with no code works (it sends the code)
# we must double-check that here. Else we'll assume we
# logged in, and it will return None as the User.
if not value:
raise errors.PhoneCodeEmptyError(request=None)
if sign_up:
me = await self.sign_up(value, first_name, last_name)
else:
# Raises SessionPasswordNeededError if 2FA enabled
me = await self.sign_in(phone, code=value)
break
except errors.SessionPasswordNeededError:
two_step_detected = True
break
except errors.PhoneNumberOccupiedError:
sign_up = False
except errors.PhoneNumberUnoccupiedError:
sign_up = True
except (errors.PhoneCodeEmptyError,
errors.PhoneCodeExpiredError,
errors.PhoneCodeHashEmptyError,
errors.PhoneCodeInvalidError):
print('Invalid code. Please try again.', file=sys.stderr)
attempts += 1
else:
raise RuntimeError(
'{} consecutive sign-in attempts failed. Aborting'
.format(max_attempts)
)
if two_step_detected:
if not password:
raise ValueError(
"Two-step verification is enabled for this account. "
"Please provide the 'password' argument to 'start()'."
)
if callable(password):
for _ in range(max_attempts):
try:
value = password()
if inspect.isawaitable(value):
value = await value
me = await self.sign_in(phone=phone, password=value)
break
except errors.PasswordHashInvalidError:
print('Invalid password. Please try again',
file=sys.stderr)
else:
raise errors.PasswordHashInvalidError(request=None)
else:
me = await self.sign_in(phone=phone, password=password)
# We won't reach here if any step failed (exit by exception)
signed, name = 'Signed in successfully as', utils.get_display_name(me)
try:
print(signed, name)
except UnicodeEncodeError:
# Some terminals don't support certain characters
print(signed, name.encode('utf-8', errors='ignore')
.decode('ascii', errors='ignore'))
return self
async def sign_in(
self: 'TelegramClient',
*,
code: typing.Union[str, int] = None,
password: str = None,
bot_token: str = None,) -> 'typing.Union[_tl.User, _tl.auth.SentCode]':
if code and bot_token:
raise ValueError('Can only provide one of code or bot_token, not both')
if not code and not bot_token and not password:
raise ValueError('You must provide code, password, or bot_token.')
if code:
if not self._phone_code_hash:
raise ValueError('Must call client.send_code_request before sign in')
# May raise PhoneCodeEmptyError, PhoneCodeExpiredError,
# PhoneCodeHashEmptyError or PhoneCodeInvalidError.
try:
result = await self(_tl.fn.auth.SignIn(*self._phone_code_hash, str(code)))
password = None # user provided a password but it was not needed
except errors.SessionPasswordNeededError:
if not password:
raise
elif bot_token:
result = await self(_tl.fn.auth.ImportBotAuthorization(
flags=0, bot_auth_token=bot_token,
api_id=self._api_id, api_hash=self._api_hash
))
if password:
pwd = await self(_tl.fn.account.GetPassword())
result = await self(_tl.fn.auth.CheckPassword(
pwd_mod.compute_check(pwd, password)
))
if isinstance(result, _tl.auth.AuthorizationSignUpRequired):
# The method must return the User but we don't have it, so raise instead (matches pre-layer 104 behaviour)
self._tos = (result.terms_of_service, None)
raise errors.SignUpRequired()
return await _update_session_state(self, result.user)
async def sign_up(
self: 'TelegramClient',
first_name: str,
last_name: str = '',
*,
code: typing.Union[str, int]) -> '_tl.User':
if not self._phone_code_hash:
# This check is also present in sign_in but we do it here to customize the error message
raise ValueError('Must call client.send_code_request before sign up')
# To prevent abuse, one has to try to sign in before signing up. This
# is the current way in which Telegram validates the code to sign up.
#
# `sign_in` will set `_tos`, so if it's set we don't need to call it
# because the user already tried to sign in.
#
# We're emulating pre-layer 104 behaviour so except the right error:
try:
return await self.sign_in(code=code)
except errors.SignUpRequired:
pass # code is correct and was used, now need to sign in
result = await self(_tl.fn.auth.SignUp(
phone_number=phone,
phone_code_hash=phone_code_hash,
first_name=first_name,
last_name=last_name
))
return await _update_session_state(self, result.user)
async def get_tos(self):
first_time = self._tos is None
no_tos = self._tos and self._tos[0] is None
tos_expired = self._tos and self._tos[1] is not None and asyncio.get_running_loop().time() >= self._tos[1]
if first_time or no_tos or tos_expired:
result = await self(_tl.fn.help.GetTermsOfServiceUpdate())
tos = getattr(result, 'terms_of_service', None)
self._tos = (tos, asyncio.get_running_loop().time() + result.expires.timestamp() - time.time())
# not stored in the client to prevent a cycle
return _custom.TermsOfService._new(self, *self._tos)
async def _update_session_state(self, user, save=True):
"""
Callback called whenever the login or sign up process completes.
Returns the input user parameter.
"""
state = await self(_tl.fn.updates.GetState())
await _replace_session_state(
self,
save=save,
user_id=user.id,
bot=user.bot,
pts=state.pts,
qts=state.qts,
date=int(state.date.timestamp()),
seq=state.seq,
)
self._phone_code_hash = None
return _custom.User._new(self, user)
async def _replace_session_state(self, *, save=True, **changes):
new = dataclasses.replace(self._session_state, **changes)
await self._session.set_state(new)
self._session_state = new
if save:
await self._session.save()
async def send_code_request(
self: 'TelegramClient',
phone: str) -> 'SentCode':
phone = utils.parse_phone(phone)
if self._phone_code_hash and phone == self._phone_code_hash[0]:
result = await self(_tl.fn.auth.ResendCode(*self._phone_code_hash))
else:
try:
result = await self(_tl.fn.auth.SendCode(
phone, self._api_id, self._api_hash, _tl.CodeSettings()))
except errors.AuthRestartError:
return await self.send_code_request(phone)
# phone_code_hash may be empty, if it is, do not save it (#1283)
if not result.phone_code_hash:
# The hash is required to login, so this pretty much means send code failed
raise ValueError('Failed to send code')
self._phone_code_hash = (phone, result.phone_code_hash)
return _custom.SentCode._new(result)
def qr_login(self: 'TelegramClient', ignored_ids: typing.List[int] = None) -> _custom.QrLogin:
return _custom.QrLoginManager(self, ignored_ids)
async def log_out(self: 'TelegramClient') -> bool:
try:
await self(_tl.fn.auth.LogOut())
except errors.RpcError:
return False
await self.disconnect()
return True
async def edit_2fa(
self: 'TelegramClient',
current_password: str = None,
new_password: str = None,
*,
hint: str = '',
email: str = None,
email_code_callback: typing.Callable[[int], str] = None) -> bool:
if new_password is None and current_password is None:
return False
if email and not callable(email_code_callback):
raise ValueError('email present without email_code_callback')
pwd = await self(_tl.fn.account.GetPassword())
pwd.new_algo.salt1 += os.urandom(32)
assert isinstance(pwd, _tl.account.Password)
if not pwd.has_password and current_password:
current_password = None
if current_password:
password = pwd_mod.compute_check(pwd, current_password)
else:
password = _tl.InputCheckPasswordEmpty()
if new_password:
new_password_hash = pwd_mod.compute_digest(
pwd.new_algo, new_password)
else:
new_password_hash = b''
try:
await self(_tl.fn.account.UpdatePasswordSettings(
password=password,
new_settings=_tl.account.PasswordInputSettings(
new_algo=pwd.new_algo,
new_password_hash=new_password_hash,
hint=hint,
email=email,
new_secure_settings=None
)
))
except errors.EmailUnconfirmedError as e:
code = email_code_callback(e.code_length)
if inspect.isawaitable(code):
code = await code
code = str(code)
await self(_tl.fn.account.ConfirmPasswordEmail(code))
return True

37
telethon/_client/bots.py Normal file
View File

@ -0,0 +1,37 @@
import typing
import asyncio
from ..types import _custom
from .._misc import hints
from .. import errors, _tl
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
async def inline_query(
self: 'TelegramClient',
bot: 'hints.DialogLike',
query: str,
*,
dialog: 'hints.DialogLike' = None,
offset: str = None,
geo_point: '_tl.GeoPoint' = None) -> _custom.InlineResults:
bot = await self._get_input_peer(bot)
if dialog:
peer = await self._get_input_peer(dialog)
else:
peer = _tl.InputPeerEmpty()
try:
result = await self(_tl.fn.messages.GetInlineBotResults(
bot=bot,
peer=peer,
query=query,
offset=offset or '',
geo_point=geo_point
))
except errors.BotResponseTimeoutError:
raise asyncio.TimeoutError from None
return _custom.InlineResults(self, result, entity=peer if dialog else None)

690
telethon/_client/chats.py Normal file
View File

@ -0,0 +1,690 @@
import asyncio
import inspect
import itertools
import string
import typing
import dataclasses
from .. import errors, _tl
from .._misc import helpers, utils, requestiter, tlobject, enums, hints
from ..types import _custom
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
_MAX_PARTICIPANTS_CHUNK_SIZE = 200
_MAX_ADMIN_LOG_CHUNK_SIZE = 100
_MAX_PROFILE_PHOTO_CHUNK_SIZE = 100
class _ChatAction:
def __init__(self, client, chat, action, *, delay, auto_cancel):
self._client = client
self._delay = delay
self._auto_cancel = auto_cancel
self._request = _tl.fn.messages.SetTyping(chat, action)
self._task = None
self._running = False
def __await__(self):
return self._once().__await__()
async def __aenter__(self):
self._request = dataclasses.replace(self._request, peer=await self._client._get_input_peer(self._request.peer))
self._running = True
self._task = asyncio.create_task(self._update())
return self
async def __aexit__(self, *args):
self._running = False
if self._task:
self._task.cancel()
try:
await self._task
except asyncio.CancelledError:
pass
self._task = None
async def _once(self):
self._request = dataclasses.replace(self._request, peer=await self._client._get_input_peer(self._request.peer))
await self._client(_tl.fn.messages.SetTyping(self._chat, self._action))
async def _update(self):
try:
while self._running:
await self._client(self._request)
await asyncio.sleep(self._delay)
except ConnectionError:
pass
except asyncio.CancelledError:
if self._auto_cancel:
await self._client(_tl.fn.messages.SetTyping(
self._chat, _tl.SendMessageCancelAction()))
@staticmethod
def _parse(action):
if isinstance(action, tlobject.TLObject) and action.SUBCLASS_OF_ID != 0x20b2cc21:
return action
return {
enums.Action.TYPING: _tl.SendMessageTypingAction(),
enums.Action.CONTACT: _tl.SendMessageChooseContactAction(),
enums.Action.GAME: _tl.SendMessageGamePlayAction(),
enums.Action.LOCATION: _tl.SendMessageGeoLocationAction(),
enums.Action.STICKER: _tl.SendMessageChooseStickerAction(),
enums.Action.RECORD_AUDIO: _tl.SendMessageRecordAudioAction(),
enums.Action.RECORD_ROUND: _tl.SendMessageRecordRoundAction(),
enums.Action.RECORD_VIDEO: _tl.SendMessageRecordVideoAction(),
enums.Action.AUDIO: _tl.SendMessageUploadAudioAction(1),
enums.Action.ROUND: _tl.SendMessageUploadRoundAction(1),
enums.Action.VIDEO: _tl.SendMessageUploadVideoAction(1),
enums.Action.PHOTO: _tl.SendMessageUploadPhotoAction(1),
enums.Action.DOCUMENT: _tl.SendMessageUploadDocumentAction(1),
enums.Action.CANCEL: _tl.SendMessageCancelAction(),
}[enums.Action(action)]
def progress(self, current, total):
if hasattr(self._request.action, 'progress'):
self._request = dataclasses.replace(
self._request,
action=dataclasses.replace(self._request.action, progress=100 * round(current / total))
)
class _ParticipantsIter(requestiter.RequestIter):
async def _init(self, entity, filter, search):
if not filter:
if search:
filter = _tl.ChannelParticipantsSearch(search)
else:
filter = _tl.ChannelParticipantsRecent()
else:
filter = enums.Participant(filter)
if filter == enums.Participant.ADMIN:
filter = _tl.ChannelParticipantsAdmins()
elif filter == enums.Participant.BOT:
filter = _tl.ChannelParticipantsBots()
elif filter == enums.Participant.KICKED:
filter = _tl.ChannelParticipantsKicked(search)
elif filter == enums.Participant.BANNED:
filter = _tl.ChannelParticipantsBanned(search)
elif filter == enums.Participant.CONTACT:
filter = _tl.ChannelParticipantsContacts(search)
else:
raise RuntimeError('unhandled enum variant')
entity = await self.client._get_input_peer(entity)
ty = helpers._entity_type(entity)
if search and (filter or ty != helpers._EntityType.CHANNEL):
# We need to 'search' ourselves unless we have a PeerChannel
search = search.casefold()
self.filter_entity = lambda ent: (
search in utils.get_display_name(ent).casefold() or
search in (getattr(ent, 'username', None) or '').casefold()
)
else:
self.filter_entity = lambda ent: True
if ty == helpers._EntityType.CHANNEL:
if self.limit <= 0:
# May not have access to the channel, but getFull can get the .total.
self.total = (await self.client(
_tl.fn.channels.GetFullChannel(entity)
)).full_chat.participants_count
raise StopAsyncIteration
self.seen = set()
self.request = _tl.fn.channels.GetParticipants(
channel=entity,
filter=filter or _tl.ChannelParticipantsSearch(search),
offset=0,
limit=_MAX_PARTICIPANTS_CHUNK_SIZE,
hash=0
)
elif ty == helpers._EntityType.CHAT:
full = await self.client(
_tl.fn.messages.GetFullChat(entity.chat_id))
if not isinstance(
full.full_chat.participants, _tl.ChatParticipants):
# ChatParticipantsForbidden won't have ``.participants``
self.total = 0
raise StopAsyncIteration
self.total = len(full.full_chat.participants.participants)
users = {user.id: user for user in full.users}
for participant in full.full_chat.participants.participants:
if isinstance(participant, _tl.ChannelParticipantBanned):
user_id = participant.peer.user_id
else:
user_id = participant.user_id
user = users[user_id]
if not self.filter_entity(user):
continue
user = users[user_id]
self.buffer.append(user)
return True
else:
self.total = 1
if self.limit != 0:
user = await self.client.get_profile(entity)
if self.filter_entity(user):
self.buffer.append(user)
return True
async def _load_next_chunk(self):
# Only care about the limit for the first request
# (small amount of people).
#
# Most people won't care about getting exactly 12,345
# members so it doesn't really matter not to be 100%
# precise with being out of the offset/limit here.
self.request = dataclasses.replace(self.request, limit=min(
self.limit - self.request.offset, _MAX_PARTICIPANTS_CHUNK_SIZE))
if self.request.offset > self.limit:
return True
participants = await self.client(self.request)
self.total = participants.count
self.request = dataclasses.replace(self.request, offset=self.request.offset + len(participants.participants))
users = {user.id: user for user in participants.users}
for participant in participants.participants:
if isinstance(participant, _tl.ChannelParticipantBanned):
if not isinstance(participant.peer, _tl.PeerUser):
# May have the entire channel banned. See #3105.
continue
user_id = participant.peer.user_id
else:
user_id = participant.user_id
if isinstance(participant, types.ChannelParticipantLeft):
# These participants should be ignored. See #3231.
continue
user = users[user_id]
if not self.filter_entity(user) or user.id in self.seen:
continue
self.seen.add(user_id)
user = users[user_id]
self.buffer.append(user)
class _AdminLogIter(requestiter.RequestIter):
async def _init(
self, entity, admins, search, min_id, max_id,
join, leave, invite, restrict, unrestrict, ban, unban,
promote, demote, info, settings, pinned, edit, delete,
group_call
):
if any((join, leave, invite, restrict, unrestrict, ban, unban,
promote, demote, info, settings, pinned, edit, delete,
group_call)):
events_filter = _tl.ChannelAdminLogEventsFilter(
join=join, leave=leave, invite=invite, ban=restrict,
unban=unrestrict, kick=ban, unkick=unban, promote=promote,
demote=demote, info=info, settings=settings, pinned=pinned,
edit=edit, delete=delete, group_call=group_call
)
else:
events_filter = None
self.entity = await self.client._get_input_peer(entity)
admin_list = []
if admins:
if not utils.is_list_like(admins):
admins = (admins,)
for admin in admins:
admin_list.append(await self.client._get_input_peer(admin))
self.request = _tl.fn.channels.GetAdminLog(
self.entity, q=search or '', min_id=min_id, max_id=max_id,
limit=0, events_filter=events_filter, admins=admin_list or None
)
async def _load_next_chunk(self):
self.request = dataclasses.replace(self.request, limit=min(self.left, _MAX_ADMIN_LOG_CHUNK_SIZE))
r = await self.client(self.request)
entities = {utils.get_peer_id(x): x
for x in itertools.chain(r.users, r.chats)}
self.request = dataclasses.replace(self.request, max_id=min((e.id for e in r.events), default=0))
for ev in r.events:
if isinstance(ev.action,
_tl.ChannelAdminLogEventActionEditMessage):
ev = dataclasses.replace(ev, action=dataclasses.replace(
ev.action,
prev_message=_custom.Message._new(self.client, ev.action.prev_message, entities, self.entity),
new_message=_custom.Message._new(self.client, ev.action.new_message, entities, self.entity)
))
elif isinstance(ev.action,
_tl.ChannelAdminLogEventActionDeleteMessage):
ev.action.message = _custom.Message._new(
self.client, ev.action.message, entities, self.entity)
self.buffer.append(_custom.AdminLogEvent(ev, entities))
if len(r.events) < self.request.limit:
return True
class _ProfilePhotoIter(requestiter.RequestIter):
async def _init(
self, entity, offset, max_id
):
entity = await self.client._get_input_peer(entity)
ty = helpers._entity_type(entity)
if ty == helpers._EntityType.USER:
self.request = _tl.fn.photos.GetUserPhotos(
entity,
offset=offset,
max_id=max_id,
limit=1
)
else:
self.request = _tl.fn.messages.Search(
peer=entity,
q='',
filter=_tl.InputMessagesFilterChatPhotos(),
min_date=None,
max_date=None,
offset_id=0,
add_offset=offset,
limit=1,
max_id=max_id,
min_id=0,
hash=0
)
if self.limit == 0:
self.request = dataclasses.replace(self.request, limit=1)
result = await self.client(self.request)
if isinstance(result, _tl.photos.Photos):
self.total = len(result.photos)
elif isinstance(result, _tl.messages.Messages):
self.total = len(result.messages)
else:
# Luckily both photosSlice and messages have a count for total
self.total = getattr(result, 'count', None)
async def _load_next_chunk(self):
self.request = dataclasses.replace(self.request, limit=min(self.left, _MAX_PROFILE_PHOTO_CHUNK_SIZE))
result = await self.client(self.request)
if isinstance(result, _tl.photos.Photos):
self.buffer = result.photos
self.left = len(self.buffer)
self.total = len(self.buffer)
elif isinstance(result, _tl.messages.Messages):
self.buffer = [x.action.photo for x in result.messages
if isinstance(x.action, _tl.MessageActionChatEditPhoto)]
self.left = len(self.buffer)
self.total = len(self.buffer)
elif isinstance(result, _tl.photos.PhotosSlice):
self.buffer = result.photos
self.total = result.count
if len(self.buffer) < self.request.limit:
self.left = len(self.buffer)
else:
self.request = dataclasses.replace(self.request, offset=self.request.offset + len(result.photos))
else:
# Some broadcast channels have a photo that this request doesn't
# retrieve for whatever random reason the Telegram server feels.
#
# This means the `total` count may be wrong but there's not much
# that can be done around it (perhaps there are too many photos
# and this is only a partial result so it's not possible to just
# use the len of the result).
self.total = getattr(result, 'count', None)
# Unconditionally fetch the full channel to obtain this photo and
# yield it with the rest (unless it's a duplicate).
seen_id = None
if isinstance(result, _tl.messages.ChannelMessages):
channel = await self.client(_tl.fn.channels.GetFullChannel(self.request.peer))
photo = channel.full_chat.chat_photo
if isinstance(photo, _tl.Photo):
self.buffer.append(photo)
seen_id = photo.id
self.buffer.extend(
x.action.photo for x in result.messages
if isinstance(x.action, _tl.MessageActionChatEditPhoto)
and x.action.photo.id != seen_id
)
if len(result.messages) < self.request.limit:
self.left = len(self.buffer)
elif result.messages:
self.request = dataclasses.replace(
self.request,
add_offset=0,
offset_id=result.messages[-1].id
)
def get_participants(
self: 'TelegramClient',
chat: 'hints.DialogLike',
limit: float = (),
*,
search: str = '',
filter: '_tl.TypeChannelParticipantsFilter' = None) -> _ParticipantsIter:
return _ParticipantsIter(
self,
limit,
entity=chat,
filter=filter,
search=search
)
def get_admin_log(
self: 'TelegramClient',
chat: 'hints.DialogLike',
limit: float = (),
*,
max_id: int = 0,
min_id: int = 0,
search: str = None,
admins: 'hints.DialogsLike' = None,
join: bool = None,
leave: bool = None,
invite: bool = None,
restrict: bool = None,
unrestrict: bool = None,
ban: bool = None,
unban: bool = None,
promote: bool = None,
demote: bool = None,
info: bool = None,
settings: bool = None,
pinned: bool = None,
edit: bool = None,
delete: bool = None,
group_call: bool = None) -> _AdminLogIter:
return _AdminLogIter(
self,
limit,
entity=chat,
admins=admins,
search=search,
min_id=min_id,
max_id=max_id,
join=join,
leave=leave,
invite=invite,
restrict=restrict,
unrestrict=unrestrict,
ban=ban,
unban=unban,
promote=promote,
demote=demote,
info=info,
settings=settings,
pinned=pinned,
edit=edit,
delete=delete,
group_call=group_call
)
def get_profile_photos(
self: 'TelegramClient',
profile: 'hints.DialogLike',
limit: int = (),
*,
offset: int = 0,
max_id: int = 0) -> _ProfilePhotoIter:
return _ProfilePhotoIter(
self,
limit,
entity=profile,
offset=offset,
max_id=max_id
)
def action(
self: 'TelegramClient',
dialog: 'hints.DialogLike',
action: 'typing.Union[str, _tl.TypeSendMessageAction]',
*,
delay: float = 4,
auto_cancel: bool = True) -> 'typing.Union[_ChatAction, typing.Coroutine]':
action = _ChatAction._parse(action)
return _ChatAction(
self, dialog, action, delay=delay, auto_cancel=auto_cancel)
async def edit_admin(
self: 'TelegramClient',
chat: 'hints.DialogLike',
user: 'hints.DialogLike',
*,
change_info: bool = None,
post_messages: bool = None,
edit_messages: bool = None,
delete_messages: bool = None,
ban_users: bool = None,
invite_users: bool = None,
pin_messages: bool = None,
add_admins: bool = None,
manage_call: bool = None,
anonymous: bool = None,
is_admin: bool = None,
title: str = None) -> _tl.Updates:
entity = await self._get_input_peer(chat)
user = await self._get_input_peer(user)
ty = helpers._entity_type(user)
perm_names = (
'change_info', 'post_messages', 'edit_messages', 'delete_messages',
'ban_users', 'invite_users', 'pin_messages', 'add_admins',
'anonymous', 'manage_call',
)
ty = helpers._entity_type(entity)
if ty == helpers._EntityType.CHANNEL:
# If we try to set these permissions in a megagroup, we
# would get a RIGHT_FORBIDDEN. However, it makes sense
# that an admin can post messages, so we want to avoid the error
if post_messages or edit_messages:
# TODO get rid of this once sessions cache this information
if entity.channel_id not in self._megagroup_cache:
full_entity = await self.get_profile(entity)
self._megagroup_cache[entity.channel_id] = full_entity.megagroup
if self._megagroup_cache[entity.channel_id]:
post_messages = None
edit_messages = None
perms = locals()
return await self(_tl.fn.channels.EditAdmin(entity, user, _tl.ChatAdminRights(**{
# A permission is its explicit (not-None) value or `is_admin`.
# This essentially makes `is_admin` be the default value.
name: perms[name] if perms[name] is not None else is_admin
for name in perm_names
}), rank=title or ''))
elif ty == helpers._EntityType.CHAT:
# If the user passed any permission in a small
# group chat, they must be a full admin to have it.
if is_admin is None:
is_admin = any(locals()[x] for x in perm_names)
return await self(_tl.fn.messages.EditChatAdmin(
entity, user, is_admin=is_admin))
else:
raise ValueError(
'You can only edit permissions in groups and channels')
async def edit_permissions(
self: 'TelegramClient',
chat: 'hints.DialogLike',
user: 'typing.Optional[hints.DialogLike]' = None,
until_date: 'hints.DateLike' = None,
*,
view_messages: bool = True,
send_messages: bool = True,
send_media: bool = True,
send_stickers: bool = True,
send_gifs: bool = True,
send_games: bool = True,
send_inline: bool = True,
embed_link_previews: bool = True,
send_polls: bool = True,
change_info: bool = True,
invite_users: bool = True,
pin_messages: bool = True) -> _tl.Updates:
entity = await self._get_input_peer(chat)
ty = helpers._entity_type(entity)
rights = _tl.ChatBannedRights(
until_date=until_date,
view_messages=not view_messages,
send_messages=not send_messages,
send_media=not send_media,
send_stickers=not send_stickers,
send_gifs=not send_gifs,
send_games=not send_games,
send_inline=not send_inline,
embed_links=not embed_link_previews,
send_polls=not send_polls,
change_info=not change_info,
invite_users=not invite_users,
pin_messages=not pin_messages
)
if user is None:
return await self(_tl.fn.messages.EditChatDefaultBannedRights(
peer=entity,
banned_rights=rights
))
user = await self._get_input_peer(user)
if isinstance(user, _tl.InputPeerSelf):
raise ValueError('You cannot restrict yourself')
return await self(_tl.fn.channels.EditBanned(
channel=entity,
participant=user,
banned_rights=rights
))
async def kick_participant(
self: 'TelegramClient',
chat: 'hints.DialogLike',
user: 'typing.Optional[hints.DialogLike]'
):
entity = await self._get_input_peer(chat)
user = await self._get_input_peer(user)
ty = helpers._entity_type(entity)
if ty == helpers._EntityType.CHAT:
resp = await self(_tl.fn.messages.DeleteChatUser(entity.chat_id, user))
elif ty == helpers._EntityType.CHANNEL:
if isinstance(user, _tl.InputPeerSelf):
# Despite no longer being in the channel, the account still
# seems to get the service message.
resp = await self(_tl.fn.channels.LeaveChannel(entity))
else:
resp = await self(_tl.fn.channels.EditBanned(
channel=entity,
participant=user,
banned_rights=_tl.ChatBannedRights(
until_date=None, view_messages=True)
))
await asyncio.sleep(0.5)
await self(_tl.fn.channels.EditBanned(
channel=entity,
participant=user,
banned_rights=_tl.ChatBannedRights(until_date=None)
))
else:
raise ValueError('You must pass either a channel or a chat')
return self._get_response_message(None, resp, entity)
async def get_permissions(
self: 'TelegramClient',
chat: 'hints.DialogLike',
user: 'hints.DialogLike' = None
) -> 'typing.Optional[_custom.ParticipantPermissions]':
entity = await self.get_profile(chat)
if not user:
if helpers._entity_type(entity) != helpers._EntityType.USER:
return entity.default_banned_rights
entity = await self._get_input_peer(entity)
user = await self._get_input_peer(user)
if helpers._entity_type(entity) == helpers._EntityType.CHANNEL:
participant = await self(_tl.fn.channels.GetParticipant(
entity,
user
))
return _custom.ParticipantPermissions(participant.participant, False)
elif helpers._entity_type(entity) == helpers._EntityType.CHAT:
chat = await self(_tl.fn.messages.GetFullChat(
entity
))
if isinstance(user, _tl.InputPeerSelf):
user = _tl.PeerUser(self._session_state.user_id)
for participant in chat.full_chat.participants.participants:
if participant.user_id == user.user_id:
return _custom.ParticipantPermissions(participant, True)
raise errors.USER_NOT_PARTICIPANT(400, 'USER_NOT_PARTICIPANT')
raise ValueError('You must pass either a channel or a chat')
async def get_stats(
self: 'TelegramClient',
chat: 'hints.DialogLike',
message: 'typing.Union[int, _tl.Message]' = None,
):
entity = await self._get_input_peer(chat)
message = utils.get_message_id(message)
if message is not None:
try:
req = _tl.fn.stats.GetMessageStats(entity, message)
return await self(req)
except errors.STATS_MIGRATE as e:
dc = e.dc
else:
# Don't bother fetching the Channel entity (costs a request), instead
# try to guess and if it fails we know it's the other one (best case
# no extra request, worst just one).
try:
req = _tl.fn.stats.GetBroadcastStats(entity)
return await self(req)
except errors.STATS_MIGRATE as e:
dc = e.dc
except errors.BROADCAST_REQUIRED:
req = _tl.fn.stats.GetMegagroupStats(entity)
try:
return await self(req)
except errors.STATS_MIGRATE as e:
dc = e.dc
sender = await self._borrow_exported_sender(dc)
try:
# req will be resolved to use the right types inside by now
return await sender.send(req)
finally:
await self._return_exported_sender(sender)

211
telethon/_client/dialogs.py Normal file
View File

@ -0,0 +1,211 @@
import asyncio
import inspect
import itertools
import typing
import dataclasses
from .. import errors, _tl
from .._misc import helpers, utils, requestiter, hints
from ..types import _custom
_MAX_CHUNK_SIZE = 100
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
def _dialog_message_key(peer, message_id):
"""
Get the key to get messages from a dialog.
We cannot just use the message ID because channels share message IDs,
and the peer ID is required to distinguish between them. But it is not
necessary in small group chats and private chats.
"""
return (peer.channel_id if isinstance(peer, _tl.PeerChannel) else None), message_id
class _DialogsIter(requestiter.RequestIter):
async def _init(
self, offset_date, offset_id, offset_peer, ignore_pinned, ignore_migrated, folder
):
self.request = _tl.fn.messages.GetDialogs(
offset_date=offset_date,
offset_id=offset_id,
offset_peer=offset_peer,
limit=1,
hash=0,
exclude_pinned=ignore_pinned,
folder_id=folder
)
if self.limit <= 0:
# Special case, get a single dialog and determine count
dialogs = await self.client(self.request)
self.total = getattr(dialogs, 'count', len(dialogs.dialogs))
raise StopAsyncIteration
self.seen = set()
self.offset_date = offset_date
self.ignore_migrated = ignore_migrated
async def _load_next_chunk(self):
self.request = dataclasses.replace(self.request, limit=min(self.left, _MAX_CHUNK_SIZE))
r = await self.client(self.request)
self.total = getattr(r, 'count', len(r.dialogs))
entities = {utils.get_peer_id(x): x
for x in itertools.chain(r.users, r.chats)
if not isinstance(x, (_tl.UserEmpty, _tl.ChatEmpty))}
messages = {
_dialog_message_key(m.peer_id, m.id): _custom.Message._new(self.client, m, entities, None)
for m in r.messages
}
for d in r.dialogs:
# We check the offset date here because Telegram may ignore it
message = messages.get(_dialog_message_key(d.peer, d.top_message))
if self.offset_date:
date = getattr(message, 'date', None)
if not date or date.timestamp() > self.offset_date.timestamp():
continue
peer_id = utils.get_peer_id(d.peer)
if peer_id not in self.seen:
self.seen.add(peer_id)
if peer_id not in entities:
# > In which case can a UserEmpty appear in the list of banned members?
# > In a very rare cases. This is possible but isn't an expected behavior.
# Real world example: https://t.me/TelethonChat/271471
continue
cd = _custom.Dialog(self.client, d, entities, message)
if cd.dialog.pts:
self.client._channel_pts[cd.id] = cd.dialog.pts
if not self.ignore_migrated or getattr(
cd.entity, 'migrated_to', None) is None:
self.buffer.append(cd)
if len(r.dialogs) < self.request.limit\
or not isinstance(r, _tl.messages.DialogsSlice):
# Less than we requested means we reached the end, or
# we didn't get a DialogsSlice which means we got all.
return True
# We can't use `messages[-1]` as the offset ID / date.
# Why? Because pinned dialogs will mess with the order
# in this list. Instead, we find the last dialog which
# has a message, and use it as an offset.
last_message = next(filter(None, (
messages.get(_dialog_message_key(d.peer, d.top_message))
for d in reversed(r.dialogs)
)), None)
self.request = dataclasses.replace(
self.request,
exclude_pinned=True,
offset_id=last_message.id if last_message else 0,
offset_date=last_message.date if last_message else None,
offset_peer=self.buffer[-1].input_entity,
)
class _DraftsIter(requestiter.RequestIter):
async def _init(self, entities, **kwargs):
if not entities:
r = await self.client(_tl.fn.messages.GetAllDrafts())
items = r.updates
else:
peers = []
for entity in entities:
peers.append(_tl.InputDialogPeer(
await self.client._get_input_peer(entity)))
r = await self.client(_tl.fn.messages.GetPeerDialogs(peers))
items = r.dialogs
# TODO Maybe there should be a helper method for this?
entities = {utils.get_peer_id(x): x
for x in itertools.chain(r.users, r.chats)}
self.buffer.extend(
_custom.Draft(self.client, entities[utils.get_peer_id(d.peer)], d.draft)
for d in items
)
async def _load_next_chunk(self):
return []
def get_dialogs(
self: 'TelegramClient',
limit: float = (),
*,
offset_date: 'hints.DateLike' = None,
offset_id: int = 0,
offset_peer: 'hints.DialogLike' = _tl.InputPeerEmpty(),
ignore_pinned: bool = False,
ignore_migrated: bool = False,
folder: int = None,
) -> _DialogsIter:
return _DialogsIter(
self,
limit,
offset_date=offset_date,
offset_id=offset_id,
offset_peer=offset_peer,
ignore_pinned=ignore_pinned,
ignore_migrated=ignore_migrated,
folder=folder
)
def get_drafts(
self: 'TelegramClient',
dialog: 'hints.DialogsLike' = None
) -> _DraftsIter:
limit = None
if dialog:
if not utils.is_list_like(dialog):
dialog = (dialog,)
limit = len(dialog)
return _DraftsIter(self, limit, entities=dialog)
async def delete_dialog(
self: 'TelegramClient',
dialog: 'hints.DialogLike',
*,
revoke: bool = False
):
# If we have enough information (`Dialog.delete` gives it to us),
# then we know we don't have to kick ourselves in deactivated chats.
if isinstance(entity, _tl.Chat):
deactivated = entity.deactivated
else:
deactivated = False
entity = await self._get_input_peer(dialog)
ty = helpers._entity_type(entity)
if ty == helpers._EntityType.CHANNEL:
return await self(_tl.fn.channels.LeaveChannel(entity))
if ty == helpers._EntityType.CHAT and not deactivated:
try:
result = await self(_tl.fn.messages.DeleteChatUser(
entity.chat_id, _tl.InputUserSelf(), revoke_history=revoke
))
except errors.PEER_ID_INVALID:
# Happens if we didn't have the deactivated information
result = None
else:
result = None
if not await self.is_bot():
await self(_tl.fn.messages.DeleteHistory(entity, 0, revoke=revoke))
return result

771
telethon/_client/downloads.py Normal file
View File

@ -0,0 +1,771 @@
import datetime
import io
import os
import pathlib
import typing
import inspect
import asyncio
import dataclasses
from .._crypto import AES
from .._misc import utils, helpers, requestiter, tlobject, hints, enums
from .. import errors, _tl
try:
import aiohttp
except ImportError:
aiohttp = None
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
# Chunk sizes for upload.getFile must be multiples of the smallest size
MIN_CHUNK_SIZE = 4096
MAX_CHUNK_SIZE = 512 * 1024
# 2021-01-15, users reported that `errors.TimeoutError` can occur while downloading files.
TIMED_OUT_SLEEP = 1
class _DirectDownloadIter(requestiter.RequestIter):
async def _init(
self, file, dc_id, offset, stride, chunk_size, request_size, file_size, msg_data
):
self.request = _tl.fn.upload.GetFile(
file, offset=offset, limit=request_size)
self.total = file_size
self._stride = stride
self._chunk_size = chunk_size
self._last_part = None
self._msg_data = msg_data
self._timed_out = False
self._exported = dc_id and self.client._session_state.dc_id != dc_id
if not self._exported:
# The used sender will also change if ``FileMigrateError`` occurs
self._sender = self.client._sender
else:
# If this raises DcIdInvalidError, it means we tried exporting the same DC we're in.
# This should not happen, but if it does, it's a bug.
self._sender = await self.client._borrow_exported_sender(dc_id)
async def _load_next_chunk(self):
cur = await self._request()
self.buffer.append(cur)
if len(cur) < self.request.limit:
self.left = len(self.buffer)
await self.close()
else:
self.request = dataclasses.replace(self.request, offset=self.request.offset + self._stride)
async def _request(self):
try:
result = await self.client._call(self._sender, self.request)
self._timed_out = False
if isinstance(result, _tl.upload.FileCdnRedirect):
raise NotImplementedError # TODO Implement
else:
return result.bytes
except errors.TimeoutError as e:
if self._timed_out:
self.client._log[__name__].warning('Got two timeouts in a row while downloading file')
raise
self._timed_out = True
self.client._log[__name__].info('Got timeout while downloading file, retrying once')
await asyncio.sleep(TIMED_OUT_SLEEP)
return await self._request()
except errors.FileMigrateError as e:
self.client._log[__name__].info('File lives in another DC')
self._sender = await self.client._borrow_exported_sender(e.new_dc)
self._exported = True
return await self._request()
except errors.FilerefUpgradeNeededError as e:
# Only implemented for documents which are the ones that may take that long to download
if not self._msg_data \
or not isinstance(self.request.location, _tl.InputDocumentFileLocation) \
or self.request.location.thumb_size != '':
raise
self.client._log[__name__].info('File ref expired during download; refetching message')
chat, msg_id = self._msg_data
msg = await self.client.get_messages(chat, ids=msg_id)
if not isinstance(msg.media, _tl.MessageMediaDocument):
raise
document = msg.media.document
# Message media may have been edited for something else
if document.id != self.request.location.id:
raise
self.request.location = dataclasses.replace(self.request.location, file_reference=document.file_reference)
return await self._request()
async def close(self):
if not self._sender:
return
try:
if self._exported:
await self.client._return_exported_sender(self._sender)
elif self._sender != self.client._sender:
await self._sender.disconnect()
finally:
self._sender = None
async def __aenter__(self):
return self
async def __aexit__(self, *args):
await self.close()
class _GenericDownloadIter(_DirectDownloadIter):
async def _load_next_chunk(self):
# 1. Fetch enough for one chunk
data = b''
# 1.1. ``bad`` is how much into the data we have we need to offset
bad = self.request.offset % self.request.limit
before = self.request.offset
# 1.2. We have to fetch from a valid offset, so remove that bad part
self.request = dataclasses.replace(self.request, offset=self.request.offset - bad)
done = False
while not done and len(data) - bad < self._chunk_size:
cur = await self._request()
self.request = dataclasses.replace(self.request, offset=self.request.offset - self.request.limit)
data += cur
done = len(cur) < self.request.limit
# 1.3 Restore our last desired offset
self.request = dataclasses.replace(self.request, offset=before)
# 2. Fill the buffer with the data we have
# 2.1. Slicing `bytes` is expensive, yield `memoryview` instead
mem = memoryview(data)
# 2.2. The current chunk starts at ``bad`` offset into the data,
# and each new chunk is ``stride`` bytes apart of the other
for i in range(bad, len(data), self._stride):
self.buffer.append(mem[i:i + self._chunk_size])
# 2.3. We will yield this offset, so move to the next one
self.request = dataclasses.replace(self.request, offset=self.request.offset + self._stride)
# 2.4. If we are in the last chunk, we will return the last partial data
if done:
self.left = len(self.buffer)
await self.close()
return
# 2.5. If we are not done, we can't return incomplete chunks.
if len(self.buffer[-1]) != self._chunk_size:
self._last_part = self.buffer.pop().tobytes()
# 3. Be careful with the offsets. Re-fetching a bit of data
# is fine, since it greatly simplifies things.
# TODO Try to not re-fetch data
self.request = dataclasses.replace(self.request, offset=self.request.offset - self._stride)
async def download_profile_photo(
self: 'TelegramClient',
profile: 'hints.DialogLike',
file: 'hints.FileLike' = None,
*,
thumb,
progress_callback) -> typing.Optional[str]:
# hex(crc32(x.encode('ascii'))) for x in
# ('User', 'Chat', 'UserFull', 'ChatFull')
ENTITIES = (0x2da17977, 0xc5af5d94, 0x1f4661b9, 0xd49a2697)
# ('InputPeer', 'InputUser', 'InputChannel')
INPUTS = (0xc91c90b6, 0xe669bf46, 0x40f202fd)
entity = profile
if not isinstance(entity, tlobject.TLObject) or entity.SUBCLASS_OF_ID in INPUTS:
entity = await self.get_profile(entity)
possible_names = []
if entity.SUBCLASS_OF_ID not in ENTITIES:
photo = entity
else:
if not hasattr(entity, 'photo'):
# Special case: may be a ChatFull with photo:Photo
# This is different from a normal UserProfilePhoto and Chat
if not hasattr(entity, 'chat_photo'):
return None
return await _download_photo(
self, entity.chat_photo, file, date=None,
thumb=thumb, progress_callback=progress_callback
)
for attr in ('username', 'first_name', 'title'):
possible_names.append(getattr(entity, attr, None))
photo = entity.photo
if isinstance(photo, (_tl.UserProfilePhoto, _tl.ChatPhoto)):
thumb = enums.Size.ORIGINAL if thumb == () else enums.Size(thumb)
dc_id = photo.dc_id
loc = _tl.InputPeerPhotoFileLocation(
peer=await self._get_input_peer(entity),
photo_id=photo.photo_id,
big=thumb >= enums.Size.LARGE
)
else:
# It doesn't make any sense to check if `photo` can be used
# as input location, because then this method would be able
# to "download the profile photo of a message", i.e. its
# media which should be done with `download_media` instead.
return None
file = _get_proper_filename(
file, 'profile_photo', '.jpg',
possible_names=possible_names
)
try:
result = await _download_file(
self=self,
input_location=loc,
file=file,
dc_id=dc_id
)
return result if file is bytes else file
except errors.LocationInvalidError:
# See issue #500, Android app fails as of v4.6.0 (1155).
# The fix seems to be using the full channel chat photo.
ie = await self._get_input_peer(entity)
ty = helpers._entity_type(ie)
if ty == helpers._EntityType.CHANNEL:
full = await self(_tl.fn.channels.GetFullChannel(ie))
return await _download_photo(
self, full.full_chat.chat_photo, file,
date=None, progress_callback=progress_callback,
thumb=thumb
)
else:
# Until there's a report for chats, no need to.
return None
async def download_media(
self: 'TelegramClient',
media: 'hints.MessageLike',
file: 'hints.FileLike' = None,
*,
size = (),
progress_callback: 'hints.ProgressCallback' = None) -> typing.Optional[typing.Union[str, bytes]]:
# Downloading large documents may be slow enough to require a new file reference
# to be obtained mid-download. Store (input chat, message id) so that the message
# can be re-fetched.
msg_data = None
# TODO This won't work for messageService
message = media
if isinstance(message, _tl.Message):
date = message.date
media = message.media
msg_data = (message.input_chat, message.id) if message.input_chat else None
else:
date = datetime.datetime.now()
media = message
if isinstance(media, _tl.MessageService):
if isinstance(message.action,
_tl.MessageActionChatEditPhoto):
media = media.photo
if isinstance(media, _tl.MessageMediaWebPage):
if isinstance(media.webpage, _tl.WebPage):
media = media.webpage.document or media.webpage.photo
if isinstance(media, (_tl.MessageMediaPhoto, _tl.Photo)):
return await _download_photo(
self, media, file, date, thumb, progress_callback
)
elif isinstance(media, (_tl.MessageMediaDocument, _tl.Document)):
return await _download_document(
self, media, file, date, thumb, progress_callback, msg_data
)
elif isinstance(media, _tl.MessageMediaContact):
return _download_contact(
self, media, file
)
elif isinstance(media, (_tl.WebDocument, _tl.WebDocumentNoProxy)):
return await _download_web_document(
self, media, file, progress_callback
)
async def _download_file(
self: 'TelegramClient',
input_location: 'hints.FileLike',
file: 'hints.OutFileLike' = None,
*,
part_size_kb: float = None,
file_size: int = None,
progress_callback: 'hints.ProgressCallback' = None,
dc_id: int = None,
key: bytes = None,
iv: bytes = None,
msg_data: tuple = None) -> typing.Optional[bytes]:
"""
Low-level method to download files from their input location.
Arguments
input_location (:tl:`InputFileLocation`):
The file location from which the file will be downloaded.
See `telethon.utils.get_input_location` source for a complete
list of supported _tl.
file (`str` | `file`, optional):
The output file path, directory, or stream-like object.
If the path exists and is a file, it will be overwritten.
If the file path is `None` or `bytes`, then the result
will be saved in memory and returned as `bytes`.
part_size_kb (`int`, optional):
Chunk size when downloading files. The larger, the less
requests will be made (up to 512KB maximum).
file_size (`int`, optional):
The file size that is about to be downloaded, if known.
Only used if ``progress_callback`` is specified.
progress_callback (`callable`, optional):
A callback function accepting two parameters:
``(downloaded bytes, total)``. Note that the
``total`` is the provided ``file_size``.
dc_id (`int`, optional):
The data center the library should connect to in order
to download the file. You shouldn't worry about this.
key ('bytes', optional):
In case of an encrypted upload (secret chats) a key is supplied
iv ('bytes', optional):
In case of an encrypted upload (secret chats) an iv is supplied
"""
if not part_size_kb:
if not file_size:
part_size_kb = 64 # Reasonable default
else:
part_size_kb = utils.get_appropriated_part_size(file_size)
part_size = int(part_size_kb * 1024)
if part_size % MIN_CHUNK_SIZE != 0:
raise ValueError(
'The part size must be evenly divisible by 4096.')
if isinstance(file, pathlib.Path):
file = str(file.absolute())
in_memory = file is None or file is bytes
if in_memory:
f = io.BytesIO()
elif isinstance(file, str):
# Ensure that we'll be able to download the media
helpers.ensure_parent_dir_exists(file)
f = open(file, 'wb')
else:
f = file
try:
async for chunk in _iter_download(
self, input_location, request_size=part_size, dc_id=dc_id, msg_data=msg_data):
if iv and key:
chunk = AES.decrypt_ige(chunk, key, iv)
r = f.write(chunk)
if inspect.isawaitable(r):
await r
if progress_callback:
r = progress_callback(f.tell(), file_size)
if inspect.isawaitable(r):
await r
# Not all IO objects have flush (see #1227)
if callable(getattr(f, 'flush', None)):
f.flush()
if in_memory:
return f.getvalue()
finally:
if isinstance(file, str) or in_memory:
f.close()
def iter_download(
self: 'TelegramClient',
media: 'hints.FileLike',
*,
offset: int = 0,
stride: int = None,
limit: int = (),
chunk_size: int = None,
request_size: int = MAX_CHUNK_SIZE,
file_size: int = None,
dc_id: int = None
):
return _iter_download(
self,
media,
offset=offset,
stride=stride,
limit=limit,
chunk_size=chunk_size,
request_size=request_size,
file_size=file_size,
dc_id=dc_id,
)
def _iter_download(
self: 'TelegramClient',
file: 'hints.FileLike',
*,
offset: int = 0,
stride: int = None,
limit: int = None,
chunk_size: int = None,
request_size: int = MAX_CHUNK_SIZE,
file_size: int = None,
dc_id: int = None,
msg_data: tuple = None
):
info = utils._get_file_info(file)
if info.dc_id is not None:
dc_id = info.dc_id
if file_size is None:
file_size = info.size
file = info.location
if chunk_size is None:
chunk_size = request_size
if limit is None and file_size is not None:
limit = (file_size + chunk_size - 1) // chunk_size
if stride is None:
stride = chunk_size
elif stride < chunk_size:
raise ValueError('stride must be >= chunk_size')
request_size -= request_size % MIN_CHUNK_SIZE
if request_size < MIN_CHUNK_SIZE:
request_size = MIN_CHUNK_SIZE
elif request_size > MAX_CHUNK_SIZE:
request_size = MAX_CHUNK_SIZE
if chunk_size == request_size \
and offset % MIN_CHUNK_SIZE == 0 \
and stride % MIN_CHUNK_SIZE == 0 \
and (limit is None or offset % limit == 0):
cls = _DirectDownloadIter
self._log[__name__].info('Starting direct file download in chunks of '
'%d at %d, stride %d', request_size, offset, stride)
else:
cls = _GenericDownloadIter
self._log[__name__].info('Starting indirect file download in chunks of '
'%d at %d, stride %d', request_size, offset, stride)
return cls(
self,
limit,
file=file,
dc_id=dc_id,
offset=offset,
stride=stride,
chunk_size=chunk_size,
request_size=request_size,
file_size=file_size,
msg_data=msg_data,
)
def _get_thumb(thumbs, thumb):
if isinstance(thumb, tlobject.TLObject):
return thumb
thumb = enums.Size(thumb)
return min(
thumbs,
default=None,
key=lambda t: abs(thumb - enums.Size(t.type))
)
def _download_cached_photo_size(self: 'TelegramClient', size, file):
# No need to download anything, simply write the bytes
if isinstance(size, _tl.PhotoStrippedSize):
data = utils.stripped_photo_to_jpg(size.bytes)
else:
data = size.bytes
if file is bytes:
return data
elif isinstance(file, str):
helpers.ensure_parent_dir_exists(file)
f = open(file, 'wb')
else:
f = file
try:
f.write(data)
finally:
if isinstance(file, str):
f.close()
return file
async def _download_photo(self: 'TelegramClient', photo, file, date, thumb, progress_callback):
"""Specialized version of .download_media() for photos"""
# Determine the photo and its largest size
if isinstance(photo, _tl.MessageMediaPhoto):
photo = photo.photo
if not isinstance(photo, _tl.Photo):
return
# Include video sizes here (but they may be None so provide an empty list)
size = _get_thumb(photo.sizes + (photo.video_sizes or []), thumb)
if not size or isinstance(size, _tl.PhotoSizeEmpty):
return
if isinstance(size, _tl.VideoSize):
file = _get_proper_filename(file, 'video', '.mp4', date=date)
else:
file = _get_proper_filename(file, 'photo', '.jpg', date=date)
if isinstance(size, (_tl.PhotoCachedSize, _tl.PhotoStrippedSize)):
return _download_cached_photo_size(self, size, file)
if isinstance(size, _tl.PhotoSizeProgressive):
file_size = max(size.sizes)
else:
file_size = size.size
result = await _download_file(
self=self,
input_location=_tl.InputPhotoFileLocation(
id=photo.id,
access_hash=photo.access_hash,
file_reference=photo.file_reference,
thumb_size=size.type
),
file=file,
file_size=file_size,
progress_callback=progress_callback
)
return result if file is bytes else file
def _get_kind_and_names(attributes):
"""Gets kind and possible names for :tl:`DocumentAttribute`."""
kind = 'document'
possible_names = []
for attr in attributes:
if isinstance(attr, _tl.DocumentAttributeFilename):
possible_names.insert(0, attr.file_name)
elif isinstance(attr, _tl.DocumentAttributeAudio):
kind = 'audio'
if attr.performer and attr.title:
possible_names.append('{} - {}'.format(
attr.performer, attr.title
))
elif attr.performer:
possible_names.append(attr.performer)
elif attr.title:
possible_names.append(attr.title)
elif attr.voice:
kind = 'voice'
return kind, possible_names
async def _download_document(
self, document, file, date, thumb, progress_callback, msg_data):
"""Specialized version of .download_media() for documents."""
if isinstance(document, _tl.MessageMediaDocument):
document = document.document
if not isinstance(document, _tl.Document):
return
if thumb == ():
kind, possible_names = _get_kind_and_names(document.attributes)
file = _get_proper_filename(
file, kind, utils.get_extension(document),
date=date, possible_names=possible_names
)
size = None
else:
file = _get_proper_filename(file, 'photo', '.jpg', date=date)
size = _get_thumb(document.thumbs, thumb)
if isinstance(size, (_tl.PhotoCachedSize, _tl.PhotoStrippedSize)):
return _download_cached_photo_size(self, size, file)
result = await _download_file(
self=self,
input_location=_tl.InputDocumentFileLocation(
id=document.id,
access_hash=document.access_hash,
file_reference=document.file_reference,
thumb_size=size.type if size else ''
),
file=file,
file_size=size.size if size else document.size,
progress_callback=progress_callback,
msg_data=msg_data,
)
return result if file is bytes else file
def _download_contact(cls, mm_contact, file):
"""
Specialized version of .download_media() for contacts.
Will make use of the vCard 4.0 format.
"""
first_name = mm_contact.first_name
last_name = mm_contact.last_name
phone_number = mm_contact.phone_number
# Remove these pesky characters
first_name = first_name.replace(';', '')
last_name = (last_name or '').replace(';', '')
result = (
'BEGIN:VCARD\n'
'VERSION:4.0\n'
'N:{f};{l};;;\n'
'FN:{f} {l}\n'
'TEL;TYPE=cell;VALUE=uri:tel:+{p}\n'
'END:VCARD\n'
).format(f=first_name, l=last_name, p=phone_number).encode('utf-8')
if file is bytes:
return result
elif isinstance(file, str):
file = cls._get_proper_filename(
file, 'contact', '.vcard',
possible_names=[first_name, phone_number, last_name]
)
f = open(file, 'wb')
else:
f = file
try:
f.write(result)
finally:
# Only close the stream if we opened it
if isinstance(file, str):
f.close()
return file
async def _download_web_document(cls, web, file, progress_callback):
"""
Specialized version of .download_media() for web documents.
"""
if not aiohttp:
raise ValueError(
'Cannot download web documents without the aiohttp '
'dependency install it (pip install aiohttp)'
)
# TODO Better way to get opened handles of files and auto-close
in_memory = file is bytes
if in_memory:
f = io.BytesIO()
elif isinstance(file, str):
kind, possible_names = cls._get_kind_and_names(web.attributes)
file = cls._get_proper_filename(
file, kind, utils.get_extension(web),
possible_names=possible_names
)
f = open(file, 'wb')
else:
f = file
try:
async with aiohttp.ClientSession() as session:
# TODO Use progress_callback; get content length from response
# https://github.com/telegramdesktop/tdesktop/blob/c7e773dd9aeba94e2be48c032edc9a78bb50234e/Telegram/SourceFiles/ui/images.cpp#L1318-L1319
async with session.get(web.url) as response:
while True:
chunk = await response.content.read(128 * 1024)
if not chunk:
break
f.write(chunk)
finally:
if isinstance(file, str) or file is bytes:
f.close()
return f.getvalue() if in_memory else file
def _get_proper_filename(file, kind, extension,
date=None, possible_names=None):
"""Gets a proper filename for 'file', if this is a path.
'kind' should be the kind of the output file (photo, document...)
'extension' should be the extension to be added to the file if
the filename doesn't have any yet
'date' should be when this file was originally sent, if known
'possible_names' should be an ordered list of possible names
If no modification is made to the path, any existing file
will be overwritten.
If any modification is made to the path, this method will
ensure that no existing file will be overwritten.
"""
if isinstance(file, pathlib.Path):
file = str(file.absolute())
if file is not None and not isinstance(file, str):
# Probably a stream-like object, we cannot set a filename here
return file
if file is None:
file = ''
elif os.path.isfile(file):
# Make no modifications to valid existing paths
return file
if os.path.isdir(file) or not file:
try:
name = None if possible_names is None else next(
x for x in possible_names if x
)
except StopIteration:
name = None
if not name:
if not date:
date = datetime.datetime.now()
name = '{}_{}-{:02}-{:02}_{:02}-{:02}-{:02}'.format(
kind,
date.year, date.month, date.day,
date.hour, date.minute, date.second,
)
file = os.path.join(file, name)
directory, name = os.path.split(file)
name, ext = os.path.splitext(name)
if not ext:
ext = extension
result = os.path.join(directory, name + ext)
if not os.path.isfile(result):
return result
i = 1
while True:
result = os.path.join(directory, '{} ({}){}'.format(name, i, ext))
if not os.path.isfile(result):
return result
i += 1

175
telethon/_client/messageparse.py Normal file
View File

@ -0,0 +1,175 @@
import itertools
import re
import typing
from .._misc import helpers, utils
from ..types import _custom
from ..types._custom.inputmessage import InputMessage
from .. import _tl
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
async def _replace_with_mention(self: 'TelegramClient', entities, i, user):
"""
Helper method to replace ``entities[i]`` to mention ``user``,
or do nothing if it can't be found.
"""
try:
entities[i] = _tl.InputMessageEntityMentionName(
entities[i].offset, entities[i].length,
await self._get_input_peer(user)
)
return True
except (ValueError, TypeError):
return False
async def _parse_message_text(self: 'TelegramClient', message, parse_mode):
"""
Returns a (parsed message, entities) tuple depending on ``parse_mode``.
"""
if parse_mode == ():
parse, _ = InputMessage._default_parse_mode
else:
parse, _ = utils.sanitize_parse_mode(parse_mode)
original_message = message
message, msg_entities = parse(message)
if original_message and not message and not msg_entities:
raise ValueError("Failed to parse message")
for i in reversed(range(len(msg_entities))):
e = msg_entities[i]
if isinstance(e, _tl.MessageEntityTextUrl):
m = re.match(r'^@|\+|tg://user\?id=(\d+)', e.url)
if m:
user = int(m.group(1)) if m.group(1) else e.url
is_mention = await _replace_with_mention(self, msg_entities, i, user)
if not is_mention:
del msg_entities[i]
elif isinstance(e, (_tl.MessageEntityMentionName,
_tl.InputMessageEntityMentionName)):
is_mention = await _replace_with_mention(self, msg_entities, i, e.user_id)
if not is_mention:
del msg_entities[i]
return message, msg_entities
def _get_response_message(self: 'TelegramClient', request, result, input_chat):
"""
Extracts the response message known a request and Update result.
The request may also be the ID of the message to match.
If ``request is None`` this method returns ``{id: message}``.
If ``request.random_id`` is a list, this method returns a list too.
"""
if isinstance(result, _tl.UpdateShort):
updates = [result.update]
entities = {}
elif isinstance(result, (_tl.Updates, _tl.UpdatesCombined)):
updates = result.updates
entities = {utils.get_peer_id(x): x
for x in
itertools.chain(result.users, result.chats)}
else:
return None
random_to_id = {}
id_to_message = {}
for update in updates:
if isinstance(update, _tl.UpdateMessageID):
random_to_id[update.random_id] = update.id
elif isinstance(update, (
_tl.UpdateNewChannelMessage, _tl.UpdateNewMessage)):
message = _custom.Message._new(self, update.message, entities, input_chat)
# Pinning a message with `updatePinnedMessage` seems to
# always produce a service message we can't map so return
# it directly. The same happens for kicking users.
#
# It could also be a list (e.g. when sending albums).
#
# TODO this method is getting messier and messier as time goes on
if hasattr(request, 'random_id') or utils.is_list_like(request):
id_to_message[message.id] = message
else:
return message
elif (isinstance(update, _tl.UpdateEditMessage)
and helpers._entity_type(request.peer) != helpers._EntityType.CHANNEL):
message = _custom.Message._new(self, update.message, entities, input_chat)
# Live locations use `sendMedia` but Telegram responds with
# `updateEditMessage`, which means we won't have `id` field.
if hasattr(request, 'random_id'):
id_to_message[message.id] = message
elif request.id == message.id:
return message
elif (isinstance(update, _tl.UpdateEditChannelMessage)
and utils.get_peer_id(request.peer) ==
utils.get_peer_id(update.message.peer_id)):
if request.id == update.message.id:
return _custom.Message._new(self, update.message, entities, input_chat)
elif isinstance(update, _tl.UpdateNewScheduledMessage):
# Scheduled IDs may collide with normal IDs. However, for a
# single request there *shouldn't* be a mix between "some
# scheduled and some not".
id_to_message[update.message.id] = _custom.Message._new(self, update.message, entities, input_chat)
elif isinstance(update, _tl.UpdateMessagePoll):
if request.media.poll.id == update.poll_id:
return _custom.Message._new(self, _tl.Message(
id=request.id,
peer_id=utils.get_peer(request.peer),
media=_tl.MessageMediaPoll(
poll=update.poll,
results=update.results
),
date=None,
message=''
), entities, input_chat)
if request is None:
return id_to_message
random_id = request if isinstance(request, (int, list)) else getattr(request, 'random_id', None)
if random_id is None:
# Can happen when pinning a message does not actually produce a service message.
self._log[__name__].warning(
'No random_id in %s to map to, returning None message for %s', request, result)
return None
if not utils.is_list_like(random_id):
msg = id_to_message.get(random_to_id.get(random_id))
if not msg:
self._log[__name__].warning(
'Request %s had missing message mapping %s', request, result)
return msg
try:
return [id_to_message[random_to_id[rnd]] for rnd in random_id]
except KeyError:
# Sometimes forwards fail (`MESSAGE_ID_INVALID` if a message gets
# deleted or `WORKER_BUSY_TOO_LONG_RETRY` if there are issues at
# Telegram), in which case we get some "missing" message mappings.
# Log them with the hope that we can better work around them.
#
# This also happens when trying to forward messages that can't
# be forwarded because they don't exist (0, service, deleted)
# among others which could be (like deleted or existing).
self._log[__name__].warning(
'Request %s had missing message mappings %s', request, result)
return [
id_to_message.get(random_to_id[rnd])
if rnd in random_to_id
else None
for rnd in random_id
]

792
telethon/_client/messages.py Normal file
View File

@ -0,0 +1,792 @@
import inspect
import itertools
import time
import typing
import warnings
import dataclasses
import os
from .._misc import helpers, utils, requestiter, hints
from ..types import _custom
from ..types._custom.inputmessage import InputMessage
from .. import errors, _tl
_MAX_CHUNK_SIZE = 100
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
class _MessagesIter(requestiter.RequestIter):
"""
Common factor for all requests that need to iterate over messages.
"""
async def _init(
self, entity, offset_id, min_id, max_id,
from_user, offset_date, add_offset, filter, search, reply_to,
scheduled
):
# Note that entity being `None` will perform a global search.
if entity:
self.entity = await self.client._get_input_peer(entity)
else:
self.entity = None
if self.reverse:
raise ValueError('Cannot reverse global search')
# Telegram doesn't like min_id/max_id. If these IDs are low enough
# (starting from last_id - 100), the request will return nothing.
#
# We can emulate their behaviour locally by setting offset = max_id
# and simply stopping once we hit a message with ID <= min_id.
if self.reverse:
offset_id = max(offset_id, min_id)
if offset_id and max_id:
if max_id - offset_id <= 1:
raise StopAsyncIteration
if not max_id:
max_id = float('inf')
else:
offset_id = max(offset_id, max_id)
if offset_id and min_id:
if offset_id - min_id <= 1:
raise StopAsyncIteration
if self.reverse:
if offset_id:
offset_id += 1
elif not offset_date:
# offset_id has priority over offset_date, so don't
# set offset_id to 1 if we want to offset by date.
offset_id = 1
if from_user:
from_user = await self.client._get_input_peer(from_user)
self.from_id = await self.client._get_peer_id(from_user)
else:
self.from_id = None
# `messages.searchGlobal` only works with text `search` or `filter` queries.
# If we want to perform global a search with `from_user` we have to perform
# a normal `messages.search`, *but* we can make the entity be `inputPeerEmpty`.
if not self.entity and from_user:
self.entity = _tl.InputPeerEmpty()
if filter is None:
filter = _tl.InputMessagesFilterEmpty()
else:
filter = filter() if isinstance(filter, type) else filter
if not self.entity:
self.request = _tl.fn.messages.SearchGlobal(
q=search or '',
filter=filter,
min_date=None,
max_date=offset_date,
offset_rate=0,
offset_peer=_tl.InputPeerEmpty(),
offset_id=offset_id,
limit=1
)
elif scheduled:
self.request = _tl.fn.messages.GetScheduledHistory(
peer=entity,
hash=0
)
elif reply_to is not None:
self.request = _tl.fn.messages.GetReplies(
peer=self.entity,
msg_id=reply_to,
offset_id=offset_id,
offset_date=offset_date,
add_offset=add_offset,
limit=1,
max_id=0,
min_id=0,
hash=0
)
elif search is not None or not isinstance(filter, _tl.InputMessagesFilterEmpty) or from_user:
# Telegram completely ignores `from_id` in private chats
ty = helpers._entity_type(self.entity)
if ty == helpers._EntityType.USER:
# Don't bother sending `from_user` (it's ignored anyway),
# but keep `from_id` defined above to check it locally.
from_user = None
else:
# Do send `from_user` to do the filtering server-side,
# and set `from_id` to None to avoid checking it locally.
self.from_id = None
self.request = _tl.fn.messages.Search(
peer=self.entity,
q=search or '',
filter=filter,
min_date=None,
max_date=offset_date,
offset_id=offset_id,
add_offset=add_offset,
limit=0, # Search actually returns 0 items if we ask it to
max_id=0,
min_id=0,
hash=0,
from_id=from_user
)
# Workaround issue #1124 until a better solution is found.
# Telegram seemingly ignores `max_date` if `filter` (and
# nothing else) is specified, so we have to rely on doing
# a first request to offset from the ID instead.
#
# Even better, using `filter` and `from_id` seems to always
# trigger `RPC_CALL_FAIL` which is "internal issues"...
if not isinstance(filter, _tl.InputMessagesFilterEmpty) \
and offset_date and not search and not offset_id:
async for m in self.client.get_messages(
self.entity, 1, offset_date=offset_date):
self.request = dataclasses.replace(self.request, offset_id=m.id + 1)
else:
self.request = _tl.fn.messages.GetHistory(
peer=self.entity,
limit=1,
offset_date=offset_date,
offset_id=offset_id,
min_id=0,
max_id=0,
add_offset=add_offset,
hash=0
)
if self.limit <= 0:
# No messages, but we still need to know the total message count
result = await self.client(self.request)
if isinstance(result, _tl.messages.MessagesNotModified):
self.total = result.count
else:
self.total = getattr(result, 'count', len(result.messages))
raise StopAsyncIteration
if self.wait_time is None:
self.wait_time = 1 if self.limit > 3000 else 0
# When going in reverse we need an offset of `-limit`, but we
# also want to respect what the user passed, so add them together.
if self.reverse:
self.request.add_offset -= _MAX_CHUNK_SIZE
self.add_offset = add_offset
self.max_id = max_id
self.min_id = min_id
self.last_id = 0 if self.reverse else float('inf')
async def _load_next_chunk(self):
self.request = dataclasses.replace(self.request, limit=min(self.left, _MAX_CHUNK_SIZE))
if self.reverse and self.request.limit != _MAX_CHUNK_SIZE:
# Remember that we need -limit when going in reverse
self.request = dataclasses.replace(self.request, add_offset=self.add_offset - self.request.limit)
r = await self.client(self.request)
self.total = getattr(r, 'count', len(r.messages))
entities = {utils.get_peer_id(x): x
for x in itertools.chain(r.users, r.chats)}
messages = reversed(r.messages) if self.reverse else r.messages
for message in messages:
if (isinstance(message, _tl.MessageEmpty)
or self.from_id and message.sender_id != self.from_id):
continue
if not self._message_in_range(message):
return True
# There has been reports that on bad connections this method
# was returning duplicated IDs sometimes. Using ``last_id``
# is an attempt to avoid these duplicates, since the message
# IDs are returned in descending order (or asc if reverse).
self.last_id = message.id
self.buffer.append(_custom.Message._new(self.client, message, entities, self.entity))
if len(r.messages) < self.request.limit:
return True
# Get the last message that's not empty (in some rare cases
# it can happen that the last message is :tl:`MessageEmpty`)
if self.buffer:
self._update_offset(self.buffer[-1], r)
else:
# There are some cases where all the messages we get start
# being empty. This can happen on migrated mega-groups if
# the history was cleared, and we're using search. Telegram
# acts incredibly weird sometimes. Messages are returned but
# only "empty", not their contents. If this is the case we
# should just give up since there won't be any new Message.
return True
def _message_in_range(self, message):
"""
Determine whether the given message is in the range or
it should be ignored (and avoid loading more chunks).
"""
# No entity means message IDs between chats may vary
if self.entity:
if self.reverse:
if message.id <= self.last_id or message.id >= self.max_id:
return False
else:
if message.id >= self.last_id or message.id <= self.min_id:
return False
return True
def _update_offset(self, last_message, response):
"""
After making the request, update its offset with the last message.
"""
self.request = dataclasses.replace(self.request, offset_id=last_message.id)
if self.reverse:
# We want to skip the one we already have
self.request = dataclasses.replace(self.request, offset_id=self.request.offset_id + 1)
if isinstance(self.request, _tl.fn.messages.Search):
# Unlike getHistory and searchGlobal that use *offset* date,
# this is *max* date. This means that doing a search in reverse
# will break it. Since it's not really needed once we're going
# (only for the first request), it's safe to just clear it off.
self.request = dataclasses.replace(self.request, max_date=None)
else:
# getHistory, searchGlobal and getReplies call it offset_date
self.request = dataclasses.replace(self.request, offset_date=last_message.date)
if isinstance(self.request, _tl.fn.messages.SearchGlobal):
if last_message.input_chat:
self.request = dataclasses.replace(self.request, offset_peer=last_message.input_chat)
else:
self.request = dataclasses.replace(self.request, offset_peer=_tl.InputPeerEmpty())
self.request = dataclasses.replace(self.request, offset_rate=getattr(response, 'next_rate', 0))
class _IDsIter(requestiter.RequestIter):
async def _init(self, entity, ids):
self.total = len(ids)
self._ids = list(reversed(ids)) if self.reverse else ids
self._offset = 0
self._entity = (await self.client._get_input_peer(entity)) if entity else None
self._ty = helpers._entity_type(self._entity) if self._entity else None
# 30s flood wait every 300 messages (3 requests of 100 each, 30 of 10, etc.)
if self.wait_time is None:
self.wait_time = 10 if self.limit > 300 else 0
async def _load_next_chunk(self):
ids = self._ids[self._offset:self._offset + _MAX_CHUNK_SIZE]
if not ids:
raise StopAsyncIteration
self._offset += _MAX_CHUNK_SIZE
from_id = None # By default, no need to validate from_id
if self._ty == helpers._EntityType.CHANNEL:
try:
r = await self.client(
_tl.fn.channels.GetMessages(self._entity, ids))
except errors.MessageIdsEmptyError:
# All IDs were invalid, use a dummy result
r = _tl.messages.MessagesNotModified(len(ids))
else:
r = await self.client(_tl.fn.messages.GetMessages(ids))
if self._entity:
from_id = await _get_peer(self.client, self._entity)
if isinstance(r, _tl.messages.MessagesNotModified):
self.buffer.extend(None for _ in ids)
return
entities = {utils.get_peer_id(x): x
for x in itertools.chain(r.users, r.chats)}
# Telegram seems to return the messages in the order in which
# we asked them for, so we don't need to check it ourselves,
# unless some messages were invalid in which case Telegram
# may decide to not send them at all.
#
# The passed message IDs may not belong to the desired entity
# since the user can enter arbitrary numbers which can belong to
# arbitrary chats. Validate these unless ``from_id is None``.
for message in r.messages:
if isinstance(message, _tl.MessageEmpty) or (
from_id and message.peer_id != from_id):
self.buffer.append(None)
else:
self.buffer.append(_custom.Message._new(self.client, message, entities, self._entity))
async def _get_peer(self: 'TelegramClient', input_peer: 'hints.DialogLike'):
try:
return utils.get_peer(input_peer)
except TypeError:
# Can only be self by now
return _tl.PeerUser(await self._get_peer_id(input_peer))
def get_messages(
self: 'TelegramClient',
dialog: 'hints.DialogLike',
limit: float = (),
*,
offset_date: 'hints.DateLike' = None,
offset_id: int = 0,
max_id: int = 0,
min_id: int = 0,
add_offset: int = 0,
search: str = None,
filter: 'typing.Union[_tl.TypeMessagesFilter, typing.Type[_tl.TypeMessagesFilter]]' = None,
from_user: 'hints.DialogLike' = None,
wait_time: float = None,
ids: 'typing.Union[int, typing.Sequence[int]]' = None,
reverse: bool = False,
reply_to: int = None,
scheduled: bool = False
) -> 'typing.Union[_MessagesIter, _IDsIter]':
if ids is not None:
if not utils.is_list_like(ids):
ids = [ids]
return _IDsIter(
client=self,
reverse=reverse,
wait_time=wait_time,
limit=len(ids),
entity=dialog,
ids=ids
)
return _MessagesIter(
client=self,
reverse=reverse,
wait_time=wait_time,
limit=limit,
entity=dialog,
offset_id=offset_id,
min_id=min_id,
max_id=max_id,
from_user=from_user,
offset_date=offset_date,
add_offset=add_offset,
filter=filter,
search=search,
reply_to=reply_to,
scheduled=scheduled
)
async def _get_comment_data(
self: 'TelegramClient',
entity: 'hints.DialogLike',
message: 'typing.Union[int, _tl.Message]'
):
r = await self(_tl.fn.messages.GetDiscussionMessage(
peer=entity,
msg_id=utils.get_message_id(message)
))
m = r.messages[0]
chat = next(c for c in r.chats if c.id == m.peer_id.channel_id)
return utils.get_input_peer(chat), m.id
async def send_message(
self: 'TelegramClient',
dialog: 'hints.DialogLike',
message: 'hints.MessageLike' = '',
*,
# - Message contents
# Formatting
markdown: str = None,
html: str = None,
formatting_entities: list = None,
link_preview: bool = (),
# Media
file: typing.Optional[hints.FileLike] = None,
file_name: str = None,
mime_type: str = None,
thumb: str = False,
force_file: bool = False,
file_size: int = None,
# Media attributes
duration: int = None,
width: int = None,
height: int = None,
title: str = None,
performer: str = None,
supports_streaming: bool = False,
video_note: bool = False,
voice_note: bool = False,
waveform: bytes = None,
# Additional parametrization
silent: bool = False,
buttons: list = None,
ttl: int = None,
# - Send options
reply_to: 'typing.Union[int, _tl.Message]' = None,
send_as: 'hints.DialogLike' = None,
clear_draft: bool = False,
background: bool = None,
noforwards: bool = None,
schedule: 'hints.DateLike' = None,
comment_to: 'typing.Union[int, _tl.Message]' = None,
) -> '_tl.Message':
if isinstance(message, str):
message = InputMessage(
text=message,
markdown=markdown,
html=html,
formatting_entities=formatting_entities,
link_preview=link_preview,
file=file,
file_name=file_name,
mime_type=mime_type,
thumb=thumb,
force_file=force_file,
file_size=file_size,
duration=duration,
width=width,
height=height,
title=title,
performer=performer,
supports_streaming=supports_streaming,
video_note=video_note,
voice_note=voice_note,
waveform=waveform,
silent=silent,
buttons=buttons,
ttl=ttl,
)
elif isinstance(message, _custom.Message):
message = message._as_input()
elif not isinstance(message, InputMessage):
raise TypeError(f'message must be either str, Message or InputMessage, but got: {message!r}')
entity = await self._get_input_peer(dialog)
if comment_to is not None:
entity, reply_to = await _get_comment_data(self, entity, comment_to)
elif reply_to:
reply_to = utils.get_message_id(reply_to)
if message._file:
# TODO Properly implement allow_cache to reuse the sha256 of the file
# i.e. `None` was used
# TODO album
if message._file._should_upload_thumb():
message._file._set_uploaded_thumb(await self._upload_file(message._file._thumb))
if message._file._should_upload_file():
message._file._set_uploaded_file(await self._upload_file(message._file._file))
request = _tl.fn.messages.SendMedia(
entity, message._file._media, reply_to_msg_id=reply_to, message=message._text,
entities=message._fmt_entities, reply_markup=message._reply_markup, silent=message._silent,
schedule_date=schedule, clear_draft=clear_draft,
background=background, noforwards=noforwards, send_as=send_as,
random_id=int.from_bytes(os.urandom(8), 'big', signed=True),
)
else:
request = _tl.fn.messages.SendMessage(
peer=entity,
message=message._text,
entities=formatting_entities,
no_webpage=not link_preview,
reply_to_msg_id=utils.get_message_id(reply_to),
clear_draft=clear_draft,
silent=silent,
background=background,
reply_markup=_custom.button.build_reply_markup(buttons),
schedule_date=schedule,
noforwards=noforwards,
send_as=send_as,
random_id=int.from_bytes(os.urandom(8), 'big', signed=True),
)
result = await self(request)
if isinstance(result, _tl.UpdateShortSentMessage):
return _custom.Message._new(self, _tl.Message(
id=result.id,
peer_id=await _get_peer(self, entity),
message=message._text,
date=result.date,
out=result.out,
media=result.media,
entities=result.entities,
reply_markup=request.reply_markup,
ttl_period=result.ttl_period
), {}, entity)
return self._get_response_message(request, result, entity)
async def forward_messages(
self: 'TelegramClient',
dialog: 'hints.DialogLike',
messages: 'typing.Union[typing.Sequence[hints.MessageIDLike]]',
from_dialog: 'hints.DialogLike' = None,
*,
background: bool = None,
with_my_score: bool = None,
silent: bool = None,
as_album: bool = None,
schedule: 'hints.DateLike' = None,
noforwards: bool = None,
send_as: 'hints.DialogLike' = None
) -> 'typing.Sequence[_tl.Message]':
if as_album is not None:
warnings.warn('the as_album argument is deprecated and no longer has any effect')
entity = await self._get_input_peer(dialog)
if from_dialog:
from_peer = await self._get_input_peer(from_dialog)
from_peer_id = await self._get_peer_id(from_peer)
else:
from_peer = None
from_peer_id = None
def get_key(m):
if isinstance(m, int):
if from_peer_id is not None:
return from_peer_id
raise ValueError('from_peer must be given if integer IDs are used')
elif isinstance(m, _tl.Message):
return m.chat_id
else:
raise TypeError('Cannot forward messages of type {}'.format(type(m)))
sent = []
for _chat_id, chunk in itertools.groupby(messages, key=get_key):
chunk = list(chunk)
if isinstance(chunk[0], int):
chat = from_peer
else:
chat = await chunk[0].get_input_chat()
chunk = [m.id for m in chunk]
req = _tl.fn.messages.ForwardMessages(
from_peer=chat,
id=chunk,
to_peer=entity,
silent=silent,
background=background,
with_my_score=with_my_score,
schedule_date=schedule,
noforwards=noforwards,
send_as=send_as,
random_id=[int.from_bytes(os.urandom(8), 'big', signed=True) for _ in chunk],
)
result = await self(req)
sent.extend(self._get_response_message(req, result, entity))
return sent[0] if single else sent
async def edit_message(
self: 'TelegramClient',
dialog: 'typing.Union[hints.DialogLike, _tl.Message]',
message: 'hints.MessageLike' = None,
text: str = None,
*,
parse_mode: str = (),
attributes: 'typing.Sequence[_tl.TypeDocumentAttribute]' = None,
formatting_entities: typing.Optional[typing.List[_tl.TypeMessageEntity]] = None,
link_preview: bool = True,
file: 'hints.FileLike' = None,
thumb: 'hints.FileLike' = None,
force_document: bool = False,
buttons: 'hints.MarkupLike' = None,
supports_streaming: bool = False,
schedule: 'hints.DateLike' = None
) -> '_tl.Message':
if formatting_entities is None:
text, formatting_entities = await self._parse_message_text(text, parse_mode)
file_handle, media, image = await self._file_to_media(file,
supports_streaming=supports_streaming,
thumb=thumb,
attributes=attributes,
force_document=force_document)
if isinstance(message, _tl.InputBotInlineMessageID):
request = _tl.fn.messages.EditInlineBotMessage(
id=message,
message=text,
no_webpage=not link_preview,
entities=formatting_entities,
media=media,
reply_markup=_custom.button.build_reply_markup(buttons)
)
# Invoke `messages.editInlineBotMessage` from the right datacenter.
# Otherwise, Telegram will error with `MESSAGE_ID_INVALID` and do nothing.
exported = self._session_state.dc_id != entity.dc_id
if exported:
try:
sender = await self._borrow_exported_sender(entity.dc_id)
return await self._call(sender, request)
finally:
await self._return_exported_sender(sender)
else:
return await self(request)
entity = await self._get_input_peer(dialog)
request = _tl.fn.messages.EditMessage(
peer=entity,
id=utils.get_message_id(message),
message=text,
no_webpage=not link_preview,
entities=formatting_entities,
media=media,
reply_markup=_custom.button.build_reply_markup(buttons),
schedule_date=schedule
)
msg = self._get_response_message(request, await self(request), entity)
return msg
async def delete_messages(
self: 'TelegramClient',
dialog: 'hints.DialogLike',
messages: 'typing.Union[typing.Sequence[hints.MessageIDLike]]',
*,
revoke: bool = True) -> 'typing.Sequence[_tl.messages.AffectedMessages]':
messages = (
m.id if isinstance(m, (
_tl.Message, _tl.MessageService, _tl.MessageEmpty))
else int(m) for m in messages
)
if dialog:
entity = await self._get_input_peer(dialog)
ty = helpers._entity_type(entity)
else:
# no entity (None), set a value that's not a channel for private delete
entity = None
ty = helpers._EntityType.USER
if ty == helpers._EntityType.CHANNEL:
res = await self([_tl.fn.channels.DeleteMessages(
entity, list(c)) for c in utils.chunks(messages)])
else:
res = await self([_tl.fn.messages.DeleteMessages(
list(c), revoke) for c in utils.chunks(messages)])
return sum(r.pts_count for r in res)
async def mark_read(
self: 'TelegramClient',
dialog: 'hints.DialogLike',
message: 'hints.MessageIDLike' = None,
*,
clear_mentions: bool = False,
clear_reactions: bool = False) -> bool:
if not message:
max_id = 0
elif isinstance(message, int):
max_id = message
else:
max_id = message.id
entity = await self._get_input_peer(dialog)
if clear_mentions:
await self(_tl.fn.messages.ReadMentions(entity))
if clear_reactions:
await self(_tl.fn.messages.ReadReactions(entity))
if helpers._entity_type(entity) == helpers._EntityType.CHANNEL:
return await self(_tl.fn.channels.ReadHistory(
utils.get_input_channel(entity), max_id=max_id))
else:
return await self(_tl.fn.messages.ReadHistory(
entity, max_id=max_id))
return False
async def pin_message(
self: 'TelegramClient',
dialog: 'hints.DialogLike',
message: 'typing.Optional[hints.MessageIDLike]',
*,
notify: bool = False,
pm_oneside: bool = False
):
return await _pin(self, dialog, message, unpin=False, notify=notify, pm_oneside=pm_oneside)
async def unpin_message(
self: 'TelegramClient',
dialog: 'hints.DialogLike',
message: 'typing.Optional[hints.MessageIDLike]' = None,
*,
notify: bool = False
):
return await _pin(self, dialog, message, unpin=True, notify=notify)
async def _pin(self, entity, message, *, unpin, notify=False, pm_oneside=False):
message = utils.get_message_id(message) or 0
entity = await self._get_input_peer(entity)
if message <= 0: # old behaviour accepted negative IDs to unpin
await self(_tl.fn.messages.UnpinAllMessages(entity))
return
request = _tl.fn.messages.UpdatePinnedMessage(
peer=entity,
id=message,
silent=not notify,
unpin=unpin,
pm_oneside=pm_oneside
)
result = await self(request)
# Unpinning does not produce a service message.
# Pinning a message that was already pinned also produces no service message.
# Pinning a message in your own chat does not produce a service message,
# but pinning on a private conversation with someone else does.
if unpin or not result.updates:
return
# Pinning a message that doesn't exist would RPC-error earlier
return self._get_response_message(request, result, entity)
async def send_reaction(
self: 'TelegramClient',
entity: 'hints.DialogLike',
message: 'hints.MessageIDLike',
reaction: typing.Optional[str] = None,
big: bool = False
):
message = utils.get_message_id(message) or 0
if not reaction:
get_default_request = _tl.fn.help.GetAppConfig()
app_config = await self(get_default_request)
reaction = (
next(
(
y for y in app_config.value
if "reactions_default" in y.key
)
)
).value.value
request = _tl.fn.messages.SendReaction(
big=big,
peer=entity,
msg_id=message,
reaction=reaction
)
result = await self(request)
for update in result.updates:
if isinstance(update, _tl.UpdateMessageReactions):
return update.reactions
if isinstance(update, _tl.UpdateEditMessage):
return update.message.reactions
async def set_quick_reaction(
self: 'TelegramClient',
reaction: str
):
request = _tl.fn.messages.SetDefaultReaction(
reaction=reaction
)
return await self(request)

474
telethon/_client/telegrambaseclient.py Normal file
View File

@ -0,0 +1,474 @@
import abc
import re
import asyncio
import collections
import logging
import platform
import time
import typing
import ipaddress
import dataclasses
import functools
from .. import version, __name__ as __base_name__, _tl
from .._crypto import rsa
from .._misc import markdown, enums, helpers
from .._network import MTProtoSender, Connection, transports
from .._sessions import Session, SQLiteSession, MemorySession
from .._sessions.types import DataCenter, SessionState, EntityType, ChannelState
from .._updates import EntityCache, MessageBox
DEFAULT_DC_ID = 2
DEFAULT_IPV4_IP = '149.154.167.51'
DEFAULT_IPV6_IP = '2001:67c:4e8:f002::a'
DEFAULT_PORT = 443
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
_base_log = logging.getLogger(__base_name__)
# In seconds, how long to wait before disconnecting a exported sender.
_DISCONNECT_EXPORTED_AFTER = 60
class _ExportState:
def __init__(self):
# ``n`` is the amount of borrows a given sender has;
# once ``n`` reaches ``0``, disconnect the sender after a while.
self._n = 0
self._zero_ts = 0
self._connected = False
def add_borrow(self):
self._n += 1
self._connected = True
def add_return(self):
self._n -= 1
assert self._n >= 0, 'returned sender more than it was borrowed'
if self._n == 0:
self._zero_ts = time.time()
def should_disconnect(self):
return (self._n == 0
and self._connected
and (time.time() - self._zero_ts) > _DISCONNECT_EXPORTED_AFTER)
def need_connect(self):
return not self._connected
def mark_disconnected(self):
assert self.should_disconnect(), 'marked as disconnected when it was borrowed'
self._connected = False
# TODO How hard would it be to support both `trio` and `asyncio`?
def init(
self: 'TelegramClient',
session: 'typing.Union[str, Session]',
api_id: int,
api_hash: str,
*,
# Logging.
base_logger: typing.Union[str, logging.Logger] = None,
# Connection parameters.
use_ipv6: bool = False,
proxy: typing.Union[tuple, dict] = None,
local_addr: typing.Union[str, tuple] = None,
device_model: str = None,
system_version: str = None,
app_version: str = None,
lang_code: str = 'en',
system_lang_code: str = 'en',
# Nice-to-have.
auto_reconnect: bool = True,
connect_timeout: int = 10,
connect_retries: int = 4,
connect_retry_delay: int = 1,
request_retries: int = 4,
flood_sleep_threshold: int = 60,
# Update handling.
catch_up: bool = False,
receive_updates: bool = True,
max_queued_updates: int = 100,
):
# Logging.
if isinstance(base_logger, str):
base_logger = logging.getLogger(base_logger)
elif not isinstance(base_logger, logging.Logger):
base_logger = _base_log
class _Loggers(dict):
def __missing__(self, key):
if key.startswith("telethon."):
key = key.split('.', maxsplit=1)[1]
return base_logger.getChild(key)
self._log = _Loggers()
# Sessions.
if isinstance(session, str) or session is None:
try:
session = SQLiteSession(session)
except ImportError:
import warnings
warnings.warn(
'The sqlite3 module is not available under this '
'Python installation and no _ session '
'instance was given; using MemorySession.\n'
'You will need to re-login every time unless '
'you use another session storage'
)
session = MemorySession()
elif not isinstance(session, Session):
raise TypeError(
'The given session must be a str or a Session instance.'
)
self._session = session
# In-memory copy of the session's state to avoid a roundtrip as it contains commonly-accessed values.
self._session_state = _default_session_state()
# Nice-to-have.
self._request_retries = request_retries
self._connect_retries = connect_retries
self._connect_retry_delay = connect_retry_delay or 0
self._connect_timeout = connect_timeout
self.flood_sleep_threshold = flood_sleep_threshold
self._flood_waited_requests = {} # prevent calls that would floodwait entirely
self._phone_code_hash = None # used during login to prevent exposing the hash to end users
self._tos = None # used during signup and when fetching tos (tos/expiry)
# Update handling.
self._catch_up = catch_up
self._no_updates = not receive_updates
self._updates_queue = asyncio.Queue(maxsize=max_queued_updates)
self._updates_handle = None
self._update_handlers = [] # sorted list
self._dispatching_update_handlers = False # while dispatching, if add/remove are called, we need to make a copy
self._message_box = MessageBox()
self._entity_cache = EntityCache() # required for proper update handling (to know when to getDifference)
# Connection parameters.
if not api_id or not api_hash:
raise ValueError(
"Your API ID or Hash cannot be empty or None. "
"Refer to docs.telethon.dev for more information.")
if local_addr is not None:
if use_ipv6 is False and ':' in local_addr:
raise TypeError('A local IPv6 address must only be used with `use_ipv6=True`.')
elif use_ipv6 is True and ':' not in local_addr:
raise TypeError('`use_ipv6=True` must only be used with a local IPv6 address.')
self._transport = transports.Full()
self._use_ipv6 = use_ipv6
self._local_addr = local_addr
self._proxy = proxy
self._auto_reconnect = auto_reconnect
self._api_id = int(api_id)
self._api_hash = api_hash
# Used on connection. Capture the variables in a lambda since
# exporting clients need to create this InvokeWithLayer.
system = platform.uname()
if system.machine in ('x86_64', 'AMD64'):
default_device_model = 'PC 64bit'
elif system.machine in ('i386','i686','x86'):
default_device_model = 'PC 32bit'
else:
default_device_model = system.machine
default_system_version = re.sub(r'-.+','',system.release)
self._init_request = functools.partial(
_tl.fn.InitConnection,
api_id=self._api_id,
device_model=device_model or default_device_model or 'Unknown',
system_version=system_version or default_system_version or '1.0',
app_version=app_version or self.__version__,
lang_code=lang_code,
system_lang_code=system_lang_code,
lang_pack='', # "langPacks are for official apps only"
)
self._sender = MTProtoSender(
loggers=self._log,
retries=self._connect_retries,
delay=self._connect_retry_delay,
auto_reconnect=self._auto_reconnect,
connect_timeout=self._connect_timeout,
updates_queue=self._updates_queue,
)
# Cache ``{dc_id: (_ExportState, MTProtoSender)}`` for all borrowed senders.
self._borrowed_senders = {}
self._borrow_sender_lock = asyncio.Lock()
def get_flood_sleep_threshold(self):
return self._flood_sleep_threshold
def set_flood_sleep_threshold(self, value):
# None -> 0, negative values don't really matter
self._flood_sleep_threshold = min(value or 0, 24 * 60 * 60)
def _default_session_state():
return SessionState(
user_id=0,
dc_id=DEFAULT_DC_ID,
bot=False,
pts=0,
qts=0,
date=0,
seq=0,
takeout_id=None,
)
async def connect(self: 'TelegramClient') -> None:
all_dcs = {dc.id: dc for dc in await self._session.get_all_dc()}
self._session_state = await self._session.get_state()
if self._session_state is None:
try_fetch_user = False
self._session_state = _default_session_state()
else:
try_fetch_user = self._session_state.user_id == 0
if self._catch_up:
channel_states = await self._session.get_all_channel_states()
self._message_box.load(self._session_state, channel_states)
for state in channel_states:
entity = await self._session.get_entity(EntityType.CHANNEL, state.channel_id)
if entity:
self._entity_cache.put(entity)
dc = all_dcs.get(self._session_state.dc_id)
if dc is None:
dc = DataCenter(
id=DEFAULT_DC_ID,
ipv4=None if self._use_ipv6 else int(ipaddress.ip_address(DEFAULT_IPV4_IP)),
ipv6=int(ipaddress.ip_address(DEFAULT_IPV6_IP)) if self._use_ipv6 else None,
port=DEFAULT_PORT,
auth=b'',
)
all_dcs[dc.id] = dc
# Use known key, if any
self._sender.auth_key.key = dc.auth
if not await self._sender.connect(Connection(
ip=str(ipaddress.ip_address((self._use_ipv6 and dc.ipv6) or dc.ipv4)),
port=dc.port,
transport=self._transport.recreate_fresh(),
loggers=self._log,
local_addr=self._local_addr,
)):
# We don't want to init or modify anything if we were already connected
return
if self._sender.auth_key.key != dc.auth:
all_dcs[dc.id] = dc = dataclasses.replace(dc, auth=self._sender.auth_key.key)
# Need to send invokeWithLayer for things to work out.
# Make the most out of this opportunity by also refreshing our state.
# During the v1 to v2 migration, this also correctly sets the IPv* columns.
config = await self._sender.send(_tl.fn.InvokeWithLayer(
_tl.LAYER, self._init_request(query=_tl.fn.help.GetConfig())
))
for dc in config.dc_options:
if dc.media_only or dc.tcpo_only or dc.cdn:
continue
ip = int(ipaddress.ip_address(dc.ip_address))
if dc.id in all_dcs:
if dc.ipv6:
all_dcs[dc.id] = dataclasses.replace(all_dcs[dc.id], port=dc.port, ipv6=ip)
else:
all_dcs[dc.id] = dataclasses.replace(all_dcs[dc.id], port=dc.port, ipv4=ip)
elif dc.ipv6:
all_dcs[dc.id] = DataCenter(dc.id, None, ip, dc.port, b'')
else:
all_dcs[dc.id] = DataCenter(dc.id, ip, None, dc.port, b'')
for dc in all_dcs.values():
await self._session.insert_dc(dc)
if try_fetch_user:
# If there was a previous session state, but the current user ID is 0, it means we've
# migrated and not yet populated the current user (or the client connected but never
# logged in). Attempt to fetch the user now. If it works, also get the update state.
me = await self.get_me()
if me:
await self._update_session_state(me, save=False)
await self._session.save()
self._updates_handle = asyncio.create_task(self._update_loop())
def is_connected(self: 'TelegramClient') -> bool:
return self._sender.is_connected()
async def disconnect(self: 'TelegramClient'):
await _disconnect(self)
# Also clean-up all exported senders because we're done with them
async with self._borrow_sender_lock:
for state, sender in self._borrowed_senders.values():
# Note that we're not checking for `state.should_disconnect()`.
# If the user wants to disconnect the client, ALL connections
# to Telegram (including exported senders) should be closed.
#
# Disconnect should never raise, so there's no try/except.
await sender.disconnect()
# Can't use `mark_disconnected` because it may be borrowed.
state._connected = False
# If any was borrowed
self._borrowed_senders.clear()
def set_proxy(self: 'TelegramClient', proxy: typing.Union[tuple, dict]):
init_proxy = None
self._proxy = proxy
# While `await client.connect()` passes new proxy on each new call,
# auto-reconnect attempts use already set up `_connection` inside
# the `_sender`, so the only way to change proxy between those
# is to directly inject parameters.
connection = getattr(self._sender, "_connection", None)
if connection:
if isinstance(connection, conns.TcpMTProxy):
connection._ip = proxy[0]
connection._port = proxy[1]
else:
connection._proxy = proxy
async def _disconnect(self: 'TelegramClient'):
"""
Disconnect only, without closing the session. Used in reconnections
to different data centers, where we don't want to close the session
file; user disconnects however should close it since it means that
their job with the client is complete and we should clean it up all.
"""
await self._sender.disconnect()
await helpers._cancel(self._log[__name__], updates_handle=self._updates_handle)
try:
await self._updates_handle
except asyncio.CancelledError:
pass
await self._session.insert_entities(self._entity_cache.get_all_entities())
session_state, channel_states = self._message_box.session_state()
for channel_id, pts in channel_states.items():
await self._session.insert_channel_state(ChannelState(channel_id=channel_id, pts=pts))
await self._replace_session_state(**session_state)
async def _switch_dc(self: 'TelegramClient', new_dc):
"""
Permanently switches the current connection to the new data center.
"""
self._log[__name__].info('Reconnecting to new data center %s', new_dc)
await self._replace_session_state(dc_id=new_dc)
await _disconnect(self)
return await self.connect()
async def _create_exported_sender(self: 'TelegramClient', dc_id):
"""
Creates a new exported `MTProtoSender` for the given `dc_id` and
returns it. This method should be used by `_borrow_exported_sender`.
"""
# Thanks badoualy/kotlogram on /telegram/api/DefaultTelegramClient.kt
# for clearly showing how to export the authorization
dc = next(dc for dc in await self._session.get_all_dc() if dc.id == dc_id)
# Can't reuse self._sender._connection as it has its own seqno.
#
# If one were to do that, Telegram would reset the connection
# with no further clues.
sender = MTProtoSender(loggers=self._log)
await self._sender.connect(Connection(
ip=str(ipaddress.ip_address((self._use_ipv6 and dc.ipv6) or dc.ipv4)),
port=dc.port,
transport=self._transport.recreate_fresh(),
loggers=self._log,
local_addr=self._local_addr,
))
self._log[__name__].info('Exporting auth for new borrowed sender in %s', dc)
auth = await self(_tl.fn.auth.ExportAuthorization(dc_id))
req = _tl.fn.InvokeWithLayer(_tl.LAYER, self._init_request(
query=_tl.fn.auth.ImportAuthorization(id=auth.id, bytes=auth.bytes)
))
await sender.send(req)
return sender
async def _borrow_exported_sender(self: 'TelegramClient', dc_id):
"""
Borrows a connected `MTProtoSender` for the given `dc_id`.
If it's not cached, creates a new one if it doesn't exist yet,
and imports a freshly exported authorization key for it to be usable.
Once its job is over it should be `_return_exported_sender`.
"""
async with self._borrow_sender_lock:
self._log[__name__].debug('Borrowing sender for dc_id %d', dc_id)
state, sender = self._borrowed_senders.get(dc_id, (None, None))
if state is None:
state = _ExportState()
sender = await _create_exported_sender(self, dc_id)
sender.dc_id = dc_id
self._borrowed_senders[dc_id] = (state, sender)
elif state.need_connect():
dc = next(dc for dc in await self._session.get_all_dc() if dc.id == dc_id)
await self._sender.connect(Connection(
ip=str(ipaddress.ip_address((self._use_ipv6 and dc.ipv6) or dc.ipv4)),
port=dc.port,
transport=self._transport.recreate_fresh(),
loggers=self._log,
local_addr=self._local_addr,
))
state.add_borrow()
return sender
async def _return_exported_sender(self: 'TelegramClient', sender):
"""
Returns a borrowed exported sender. If all borrows have
been returned, the sender is cleanly disconnected.
"""
async with self._borrow_sender_lock:
self._log[__name__].debug('Returning borrowed sender for dc_id %d', sender.dc_id)
state, _ = self._borrowed_senders[sender.dc_id]
state.add_return()
async def _clean_exported_senders(self: 'TelegramClient'):
"""
Cleans-up all unused exported senders by disconnecting them.
"""
async with self._borrow_sender_lock:
for dc_id, (state, sender) in self._borrowed_senders.items():
if state.should_disconnect():
self._log[__name__].info(
'Disconnecting borrowed sender for DC %d', dc_id)
# Disconnect should never raise
await sender.disconnect()
state.mark_disconnected()

3410
telethon/_client/telegramclient.py Normal file
View File

File diff suppressed because it is too large Load Diff

282
telethon/_client/updates.py Normal file
View File

@ -0,0 +1,282 @@
import asyncio
import inspect
import itertools
import random
import sys
import time
import traceback
import typing
import logging
import inspect
import bisect
import warnings
from collections import deque
from ..errors._rpcbase import RpcError
from .._events.raw import Raw
from .._events.base import StopPropagation, EventBuilder, EventHandler
from .._events.filters import make_filter, NotResolved
from .._misc import utils
from .. import _tl
from ..types._custom import User, Chat
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
Callback = typing.Callable[[typing.Any], typing.Any]
async def set_receive_updates(self: 'TelegramClient', receive_updates):
self._no_updates = not receive_updates
if receive_updates:
await self(_tl.fn.updates.GetState())
async def run_until_disconnected(self: 'TelegramClient'):
# Make a high-level request to notify that we want updates
await self(_tl.fn.updates.GetState())
await self._sender.wait_disconnected()
def on(self: 'TelegramClient', *events, priority=0, **filters):
def decorator(f):
for event in events:
self.add_event_handler(f, event, priority=priority, **filters)
return f
return decorator
def add_event_handler(
self: 'TelegramClient',
callback=None,
event=None,
priority=0,
**filters
):
if callback is None:
return functools.partial(add_event_handler, self, event=event, priority=priority, **filters)
if event is None:
for param in inspect.signature(callback).parameters.values():
event = None if param.annotation is inspect.Signature.empty else param.annotation
break # only check the first parameter
if event is None:
event = Raw
if not inspect.iscoroutinefunction(callback):
raise TypeError(f'callback was not an async def function: {callback!r}')
if not isinstance(event, type):
raise TypeError(f'event type was not a type (an instance of something was probably used): {event!r}')
if not isinstance(priority, int):
raise TypeError(f'priority was not an integer: {priority!r}')
if not issubclass(event, EventBuilder):
try:
if event.SUBCLASS_OF_ID != 0x9f89304e:
raise TypeError(f'invalid raw update type for the event handler: {event!r}')
if 'types' in filters:
warnings.warn('"types" filter is ignored when the event type already is a raw update')
filters['types'] = event
event = Raw
except AttributeError:
raise TypeError(f'unrecognized event handler type: {param.annotation!r}')
handler = EventHandler(event, callback, priority, make_filter(**filters))
if self._dispatching_update_handlers:
# Now that there's a copy, we're no longer dispatching from the old update_handlers,
# so we can modify it. This is why we can turn the flag off.
self._update_handlers = self._update_handlers[:]
self._dispatching_update_handlers = False
bisect.insort(self._update_handlers, handler)
return handler
def remove_event_handler(
self: 'TelegramClient',
callback=None,
event=None,
*,
priority=None,
):
if callback is None and event is None and priority is None:
raise ValueError('must specify at least one of callback, event or priority')
if not self._update_handlers:
return [] # won't be removing anything (some code paths rely on non-empty lists)
if self._dispatching_update_handlers:
# May be an unnecessary copy if nothing was removed, but that's not a big deal.
self._update_handlers = self._update_handlers[:]
self._dispatching_update_handlers = False
if isinstance(callback, EventHandler):
if event is not None or priority is not None:
warnings.warn('event and priority are ignored when removing EventHandler instances')
index = bisect.bisect_left(self._update_handlers, callback)
try:
if self._update_handlers[index] == callback:
return [self._update_handlers.pop(index)]
except IndexError:
pass
return []
if priority is not None:
# can binary-search (using a dummy EventHandler)
index = bisect.bisect_right(self._update_handlers, EventHandler(None, None, priority, None))
try:
while self._update_handlers[index].priority == priority:
index += 1
except IndexError:
pass
removed = []
while index > 0 and self._update_handlers[index - 1].priority == priority:
index -= 1
if callback is not None and self._update_handlers[index].callback != callback:
continue
if event is not None and self._update_handlers[index].event != event:
continue
removed.append(self._update_handlers.pop(index))
return removed
# slow-path, remove all matching
removed = []
for index in reversed(range(len(self._update_handlers))):
handler = self._update_handlers[index]
if callback is not None and handler._callback != callback:
continue
if event is not None and handler._event != event:
continue
removed.append(self._update_handlers.pop(index))
return removed
def list_event_handlers(self: 'TelegramClient')\
-> 'typing.Sequence[typing.Tuple[Callback, EventBuilder]]':
return self._update_handlers[:]
async def catch_up(self: 'TelegramClient'):
# The update loop is probably blocked on either timeout or an update to arrive.
# Unblock the loop by pushing a dummy update which will always trigger a gap.
# This, in return, causes the update loop to catch up.
await self._updates_queue.put(_tl.UpdatesTooLong())
async def _update_loop(self: 'TelegramClient'):
try:
updates_to_dispatch = deque()
while self.is_connected:
if updates_to_dispatch:
await _dispatch(self, *updates_to_dispatch.popleft())
continue
get_diff = self._message_box.get_difference()
if get_diff:
self._log[__name__].info('Getting difference for account updates')
diff = await self(get_diff)
updates, users, chats = self._message_box.apply_difference(diff, self._entity_cache)
updates_to_dispatch.extend(_preprocess_updates(self, updates, users, chats))
continue
get_diff = self._message_box.get_channel_difference(self._entity_cache)
if get_diff:
self._log[__name__].info('Getting difference for channel updates')
diff = await self(get_diff)
updates, users, chats = self._message_box.apply_channel_difference(get_diff, diff, self._entity_cache)
updates_to_dispatch.extend(_preprocess_updates(self, updates, users, chats))
continue
deadline = self._message_box.check_deadlines()
try:
updates = await asyncio.wait_for(
self._updates_queue.get(),
deadline - asyncio.get_running_loop().time()
)
except asyncio.TimeoutError:
self._log[__name__].info('Timeout waiting for updates expired')
continue
processed = []
try:
users, chats = self._message_box.process_updates(updates, self._entity_cache, processed)
except GapError:
continue # get(_channel)_difference will start returning requests
updates_to_dispatch.extend(_preprocess_updates(self, processed, users, chats))
except Exception:
self._log[__name__].exception('Fatal error handling updates (this is a bug in Telethon, please report it)')
def _preprocess_updates(self, updates, users, chats):
self._entity_cache.extend(users, chats)
entities = Entities(self, users, chats)
return ((u, entities) for u in updates)
class Entities:
def __init__(self, client, users, chats):
self.self_id = client._session_state.user_id
self._client = client
self._entities = {e.id: e for e in itertools.chain(
(User._new(client, u) for u in users),
(Chat._new(client, c) for u in chats),
)}
def get(self, peer):
if not peer:
return None
id = utils.get_peer_id(peer)
try:
return self._entities[id]
except KeyError:
entity = self._client._entity_cache.get(query.user_id)
if not entity:
raise RuntimeError('Update is missing a hash but did not trigger a gap')
self._entities[entity.id] = User(self._client, entity) if entity.is_user else Chat(self._client, entity)
return self._entities[entity.id]
async def _dispatch(self, update, entities):
self._dispatching_update_handlers = True
try:
event_cache = {}
for handler in self._update_handlers:
event = event_cache.get(handler._event)
if not event:
# build can fail if we're missing an access hash; we want this to crash
event_cache[handler._event] = event = handler._event._build(self, update, entities)
while True:
# filters can be modified at any time, and there can be any amount of them which are not yet resolved
try:
if handler._filter(event):
try:
await handler._callback(event)
except StopPropagation:
return
except Exception:
name = getattr(handler._callback, '__name__', repr(handler._callback))
self._log[__name__].exception('Unhandled exception on %s (this is likely a bug in your code)', name)
except NotResolved as nr:
try:
await nr.unresolved.resolve()
continue
except Exception as e:
# we cannot really do much about this; it might be a temporary network issue
warnings.warn(f'failed to resolve filter, handler will be skipped: {e}: {nr.unresolved!r}')
except Exception as e:
# invalid filter (e.g. types when types were not used as input)
warnings.warn(f'invalid filter applied, handler will be skipped: {e}: {e.filter!r}')
# we only want to continue on unresolved filter (to check if there are more unresolved)
break
finally:
self._dispatching_update_handlers = False

406
telethon/_client/uploads.py Normal file
View File

@ -0,0 +1,406 @@
import hashlib
import io
import itertools
import os
import pathlib
import re
import typing
from io import BytesIO
from .._crypto import AES
from .._misc import utils, helpers, hints
from ..types import _custom
from .. import _tl
try:
import PIL
import PIL.Image
except ImportError:
PIL = None
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
def _resize_photo_if_needed(
file, is_image, width=1280, height=1280, background=(255, 255, 255)):
# https://github.com/telegramdesktop/tdesktop/blob/12905f0dcb9d513378e7db11989455a1b764ef75/Telegram/SourceFiles/boxes/photo_crop_box.cpp#L254
if (not is_image
or PIL is None
or (isinstance(file, io.IOBase) and not file.seekable())):
return file
if isinstance(file, bytes):
file = io.BytesIO(file)
before = file.tell() if isinstance(file, io.IOBase) else None
try:
# Don't use a `with` block for `image`, or `file` would be closed.
# See https://github.com/LonamiWebs/Telethon/issues/1121 for more.
image = PIL.Image.open(file)
try:
kwargs = {'exif': image.info['exif']}
except KeyError:
kwargs = {}
if image.width <= width and image.height <= height:
return file
image.thumbnail((width, height), PIL.Image.ANTIALIAS)
alpha_index = image.mode.find('A')
if alpha_index == -1:
# If the image mode doesn't have alpha
# channel then don't bother masking it away.
result = image
else:
# We could save the resized image with the original format, but
# JPEG often compresses better -> smaller size -> faster upload
# We need to mask away the alpha channel ([3]), since otherwise
# IOError is raised when trying to save alpha channels in JPEG.
result = PIL.Image.new('RGB', image.size, background)
result.paste(image, mask=image.split()[alpha_index])
buffer = io.BytesIO()
result.save(buffer, 'JPEG', **kwargs)
buffer.seek(0)
return buffer
except IOError:
return file
finally:
if before is not None:
file.seek(before, io.SEEK_SET)
async def send_file(
self: 'TelegramClient',
dialog: 'hints.DialogLike',
file: typing.Optional[hints.FileLike] = None,
*,
# - Message contents
# Formatting
caption: 'hints.MessageLike' = '',
markdown: str = None,
html: str = None,
formatting_entities: list = None,
link_preview: bool = (),
# Media
file_name: str = None,
mime_type: str = None,
thumb: str = False,
force_file: bool = False,
file_size: int = None,
# Media attributes
duration: int = None,
width: int = None,
height: int = None,
title: str = None,
performer: str = None,
supports_streaming: bool = False,
video_note: bool = False,
voice_note: bool = False,
waveform: bytes = None,
# Additional parametrization
silent: bool = False,
buttons: list = None,
ttl: int = None,
# - Send options
reply_to: 'typing.Union[int, _tl.Message]' = None,
clear_draft: bool = False,
background: bool = None,
noforwards: bool = None,
send_as: 'hints.DialogLike' = None,
schedule: 'hints.DateLike' = None,
comment_to: 'typing.Union[int, _tl.Message]' = None,
) -> '_tl.Message':
self.send_message(
dialog=dialog,
message=caption,
markdown=markdown,
html=html,
formatting_entities=formatting_entities,
link_preview=link_preview,
file=file,
file_name=file_name,
mime_type=mime_type,
thumb=thumb,
force_file=force_file,
file_size=file_size,
duration=duration,
width=width,
height=height,
title=title,
performer=performer,
supports_streaming=supports_streaming,
video_note=video_note,
voice_note=voice_note,
waveform=waveform,
silent=silent,
buttons=buttons,
ttl=ttl,
reply_to=reply_to,
clear_draft=clear_draft,
background=background,
schedule=schedule,
comment_to=comment_to,
noforwards=noforwards,
send_as=send_as
)
async def _send_album(self: 'TelegramClient', entity, files, caption='',
progress_callback=None, reply_to=None,
parse_mode=(), silent=None, schedule=None,
supports_streaming=None, clear_draft=None,
force_document=False, background=None, ttl=None,
send_as=None, noforwards=None):
"""Specialized version of .send_file for albums"""
# We don't care if the user wants to avoid cache, we will use it
# anyway. Why? The cached version will be exactly the same thing
# we need to produce right now to send albums (uploadMedia), and
# cache only makes a difference for documents where the user may
# want the attributes used on them to change.
#
# In theory documents can be sent inside the albums but they appear
# as different messages (not inside the album), and the logic to set
# the attributes/avoid cache is already written in .send_file().
entity = await self._get_input_peer(entity)
if not utils.is_list_like(caption):
caption = (caption,)
captions = []
for c in reversed(caption): # Pop from the end (so reverse)
captions.append(await self._parse_message_text(c or '', parse_mode))
reply_to = utils.get_message_id(reply_to)
# Need to upload the media first, but only if they're not cached yet
media = []
for file in files:
# Albums want :tl:`InputMedia` which, in theory, includes
# :tl:`InputMediaUploadedPhoto`. However using that will
# make it `raise MediaInvalidError`, so we need to upload
# it as media and then convert that to :tl:`InputMediaPhoto`.
fh, fm, _ = await _file_to_media(
self, file, supports_streaming=supports_streaming,
force_document=force_document, ttl=ttl)
if isinstance(fm, (_tl.InputMediaUploadedPhoto, _tl.InputMediaPhotoExternal)):
r = await self(_tl.fn.messages.UploadMedia(
entity, media=fm
))
fm = utils.get_input_media(r.photo)
elif isinstance(fm, _tl.InputMediaUploadedDocument):
r = await self(_tl.fn.messages.UploadMedia(
entity, media=fm
))
fm = utils.get_input_media(
r.document, supports_streaming=supports_streaming)
if captions:
caption, msg_entities = captions.pop()
else:
caption, msg_entities = '', None
media.append(_tl.InputSingleMedia(
fm,
message=caption,
entities=msg_entities
# random_id is autogenerated
))
# Now we can construct the multi-media request
request = _tl.fn.messages.SendMultiMedia(
entity, reply_to_msg_id=reply_to, multi_media=media,
silent=silent, schedule_date=schedule, clear_draft=clear_draft,
background=background, noforwards=noforwards, send_as=send_as
)
result = await self(request)
random_ids = [m.random_id for m in media]
return self._get_response_message(random_ids, result, entity)
async def upload_file(
self: 'TelegramClient',
file: 'hints.FileLike',
*,
part_size_kb: float = None,
file_size: int = None,
file_name: str = None,
use_cache: type = None,
key: bytes = None,
iv: bytes = None,
progress_callback: 'hints.ProgressCallback' = None) -> '_tl.TypeInputFile':
"""
Uploads a file to Telegram's servers, without sending it.
.. note::
Generally, you want to use `send_file` instead.
This method returns a handle (an instance of :tl:`InputFile` or
:tl:`InputFileBig`, as required) which can be later used before
it expires (they are usable during less than a day).
Uploading a file will simply return a "handle" to the file stored
remotely in the Telegram servers, which can be later used on. This
will **not** upload the file to your own chat or any chat at all.
Arguments
file (`str` | `bytes` | `file`):
The path of the file, byte array, or stream that will be sent.
Note that if a byte array or a stream is given, a filename
or its type won't be inferred, and it will be sent as an
"unnamed application/octet-stream".
part_size_kb (`int`, optional):
Chunk size when uploading files. The larger, the less
requests will be made (up to 512KB maximum).
file_size (`int`, optional):
The size of the file to be uploaded, which will be determined
automatically if not specified.
If the file size can't be determined beforehand, the entire
file will be read in-memory to find out how large it is.
file_name (`str`, optional):
The file name which will be used on the resulting InputFile.
If not specified, the name will be taken from the ``file``
and if this is not a `str`, it will be ``"unnamed"``.
use_cache (`type`, optional):
This parameter currently does nothing, but is kept for
backward-compatibility (and it may get its use back in
the future).
key ('bytes', optional):
In case of an encrypted upload (secret chats) a key is supplied
iv ('bytes', optional):
In case of an encrypted upload (secret chats) an iv is supplied
progress_callback (`callable`, optional):
A callback function accepting two parameters:
``(sent bytes, total)``.
Returns
:tl:`InputFileBig` if the file size is larger than 10MB,
`InputSizedFile <telethon.tl._custom.inputsizedfile.InputSizedFile>`
(subclass of :tl:`InputFile`) otherwise.
Example
.. code-block:: python
# Photos as photo and document
file = await client.upload_file('photo.jpg')
await client.send_file(chat, file) # sends as photo
await client.send_file(chat, file, force_document=True) # sends as document
file.name = 'not a photo.jpg'
await client.send_file(chat, file, force_document=True) # document, new name
# As song or as voice note
file = await client.upload_file('song.ogg')
await client.send_file(chat, file) # sends as song
await client.send_file(chat, file, voice_note=True) # sends as voice note
"""
if isinstance(file, (_tl.InputFile, _tl.InputFileBig)):
return file # Already uploaded
pos = 0
async with helpers._FileStream(file, file_size=file_size) as stream:
# Opening the stream will determine the correct file size
file_size = stream.file_size
if not part_size_kb:
part_size_kb = utils.get_appropriated_part_size(file_size)
if part_size_kb > 512:
raise ValueError('The part size must be less or equal to 512KB')
part_size = int(part_size_kb * 1024)
if part_size % 1024 != 0:
raise ValueError(
'The part size must be evenly divisible by 1024')
# Set a default file name if None was specified
file_id = helpers.generate_random_long()
if not file_name:
file_name = stream.name or str(file_id)
# If the file name lacks extension, add it if possible.
# Else Telegram complains with `PHOTO_EXT_INVALID_ERROR`
# even if the uploaded image is indeed a photo.
if not os.path.splitext(file_name)[-1]:
file_name += utils._get_extension(stream)
# Determine whether the file is too big (over 10MB) or not
# Telegram does make a distinction between smaller or larger files
is_big = file_size > 10 * 1024 * 1024
hash_md5 = hashlib.md5()
part_count = (file_size + part_size - 1) // part_size
self._log[__name__].info('Uploading file of %d bytes in %d chunks of %d',
file_size, part_count, part_size)
pos = 0
for part_index in range(part_count):
# Read the file by in chunks of size part_size
part = await helpers._maybe_await(stream.read(part_size))
if not isinstance(part, bytes):
raise TypeError(
'file descriptor returned {}, not bytes (you must '
'open the file in bytes mode)'.format(type(part)))
# `file_size` could be wrong in which case `part` may not be
# `part_size` before reaching the end.
if len(part) != part_size and part_index < part_count - 1:
raise ValueError(
'read less than {} before reaching the end; either '
'`file_size` or `read` are wrong'.format(part_size))
pos += len(part)
# Encryption part if needed
if key and iv:
part = AES.encrypt_ige(part, key, iv)
if not is_big:
# Bit odd that MD5 is only needed for small files and not
# big ones with more chance for corruption, but that's
# what Telegram wants.
hash_md5.update(part)
# The SavePart is different depending on whether
# the file is too large or not (over or less than 10MB)
if is_big:
request = _tl.fn.upload.SaveBigFilePart(
file_id, part_index, part_count, part)
else:
request = _tl.fn.upload.SaveFilePart(
file_id, part_index, part)
result = await self(request)
if result:
self._log[__name__].debug('Uploaded %d/%d',
part_index + 1, part_count)
if progress_callback:
await helpers._maybe_await(progress_callback(pos, file_size))
else:
raise RuntimeError(
'Failed to upload file part {}.'.format(part_index))
if is_big:
return _tl.InputFileBig(file_id, part_count, file_name)
else:
return _custom.InputSizedFile(
file_id, part_count, file_name, md5=hash_md5, size=file_size
)

398
telethon/_client/users.py Normal file
View File

@ -0,0 +1,398 @@
import asyncio
import datetime
import itertools
import time
import typing
import dataclasses
from ..errors._custom import MultiError
from ..errors._rpcbase import RpcError, ServerError, FloodError, InvalidDcError, UnauthorizedError
from .._misc import helpers, utils, hints
from .._sessions.types import Entity
from .. import errors, _tl
from ..types import _custom
from .account import ignore_takeout
_NOT_A_REQUEST = lambda: TypeError('You can only invoke requests, not types!')
if typing.TYPE_CHECKING:
from .telegramclient import TelegramClient
def _fmt_flood(delay, request, *, early=False, td=datetime.timedelta):
return (
'Sleeping%s for %ds (%s) on %s flood wait',
' early' if early else '',
delay,
td(seconds=delay),
request.__class__.__name__
)
async def call(self: 'TelegramClient', request, ordered=False, flood_sleep_threshold=None):
return await _call(self, self._sender, request, ordered=ordered, flood_sleep_threshold=flood_sleep_threshold)
async def _call(self: 'TelegramClient', sender, request, ordered=False, flood_sleep_threshold=None):
if flood_sleep_threshold is None:
flood_sleep_threshold = self.flood_sleep_threshold
requests = (request if utils.is_list_like(request) else (request,))
new_requests = []
for r in requests:
if not isinstance(r, _tl.TLRequest):
raise _NOT_A_REQUEST()
r = await r._resolve(self, utils)
# Avoid making the request if it's already in a flood wait
if r.CONSTRUCTOR_ID in self._flood_waited_requests:
due = self._flood_waited_requests[r.CONSTRUCTOR_ID]
diff = round(due - time.time())
if diff <= 3: # Flood waits below 3 seconds are "ignored"
self._flood_waited_requests.pop(r.CONSTRUCTOR_ID, None)
elif diff <= flood_sleep_threshold:
self._log[__name__].info(*_fmt_flood(diff, r, early=True))
await asyncio.sleep(diff)
self._flood_waited_requests.pop(r.CONSTRUCTOR_ID, None)
else:
raise errors.FLOOD_WAIT(420, f'FLOOD_WAIT_{diff}', request=r)
if self._session_state.takeout_id and not ignore_takeout.get():
r = _tl.fn.InvokeWithTakeout(self._session_state.takeout_id, r)
if self._no_updates:
r = _tl.fn.InvokeWithoutUpdates(r)
new_requests.append(r)
request = new_requests if utils.is_list_like(request) else new_requests[0]
request_index = 0
last_error = None
self._last_request = time.time()
for attempt in helpers.retry_range(self._request_retries):
try:
future = sender.send(request, ordered=ordered)
if isinstance(future, list):
results = []
exceptions = []
for f in future:
try:
result = await f
except RpcError as e:
exceptions.append(e)
results.append(None)
continue
exceptions.append(None)
results.append(result)
request_index += 1
if any(x is not None for x in exceptions):
raise MultiError(exceptions, results, requests)
else:
return results
else:
result = await future
return result
except ServerError as e:
last_error = e
self._log[__name__].warning(
'Telegram is having internal issues %s: %s',
e.__class__.__name__, e)
await asyncio.sleep(2)
except FloodError as e:
last_error = e
if utils.is_list_like(request):
request = request[request_index]
# SLOWMODE_WAIT is chat-specific, not request-specific
if not isinstance(e, errors.SLOWMODE_WAIT):
self._flood_waited_requests\
[request.CONSTRUCTOR_ID] = time.time() + e.seconds
# In test servers, FLOOD_WAIT_0 has been observed, and sleeping for
# such a short amount will cause retries very fast leading to issues.
if e.seconds == 0:
e.seconds = 1
if e.seconds <= self.flood_sleep_threshold:
self._log[__name__].info(*_fmt_flood(e.seconds, request))
await asyncio.sleep(e.seconds)
else:
raise
except InvalidDcError as e:
last_error = e
self._log[__name__].info('Phone migrated to %d', e.new_dc)
should_raise = isinstance(e, (
errors.PHONE_MIGRATE, errors.NETWORK_MIGRATE
))
if should_raise and await self.is_user_authorized():
raise
await self._switch_dc(e.new_dc)
raise last_error
async def get_me(self: 'TelegramClient') \
-> 'typing.Union[_tl.User, _tl.InputPeerUser]':
try:
return _custom.User._new(self, (await self(_tl.fn.users.GetUsers([_tl.InputUserSelf()])))[0])
except UnauthorizedError:
return None
async def is_bot(self: 'TelegramClient') -> bool:
return self._session_state.bot if self._session_state else False
async def is_user_authorized(self: 'TelegramClient') -> bool:
try:
# Any request that requires authorization will work
await self(_tl.fn.updates.GetState())
return True
except RpcError:
return False
async def get_profile(
self: 'TelegramClient',
profile: 'hints.DialogsLike') -> 'hints.Entity':
entity = profile
single = not utils.is_list_like(entity)
if single:
entity = (entity,)
# Group input entities by string (resolve username),
# input users (get users), input chat (get chats) and
# input channels (get channels) to get the most entities
# in the less amount of calls possible.
inputs = []
for x in entity:
if isinstance(x, str):
inputs.append(x)
else:
inputs.append(await self._get_input_peer(x))
lists = {
helpers._EntityType.USER: [],
helpers._EntityType.CHAT: [],
helpers._EntityType.CHANNEL: [],
}
for x in inputs:
try:
lists[helpers._entity_type(x)].append(x)
except TypeError:
pass
users = lists[helpers._EntityType.USER]
chats = lists[helpers._EntityType.CHAT]
channels = lists[helpers._EntityType.CHANNEL]
if users:
# GetUsers has a limit of 200 per call
tmp = []
while users:
curr, users = users[:200], users[200:]
tmp.extend(await self(_tl.fn.users.GetUsers(curr)))
users = tmp
if chats: # TODO Handle chats slice?
chats = (await self(
_tl.fn.messages.GetChats([x.chat_id for x in chats]))).chats
if channels:
channels = (await self(
_tl.fn.channels.GetChannels(channels))).chats
# Merge users, chats and channels into a single dictionary
id_entity = {
utils.get_peer_id(x): x
for x in itertools.chain(users, chats, channels)
}
# We could check saved usernames and put them into the users,
# chats and channels list from before. While this would reduce
# the amount of ResolveUsername calls, it would fail to catch
# username changes.
result = []
for x in inputs:
if isinstance(x, str):
result.append(await _get_entity_from_string(self, x))
elif not isinstance(x, _tl.InputPeerSelf):
result.append(id_entity[utils.get_peer_id(x)])
else:
result.append(next(
u for u in id_entity.values()
if isinstance(u, _tl.User) and u.is_self
))
return result[0] if single else result
async def _get_input_peer(
self: 'TelegramClient',
peer: 'hints.DialogLike') -> '_tl.TypeInputPeer':
# Short-circuit if the input parameter directly maps to an InputPeer
try:
return utils.get_input_peer(peer)
except TypeError:
pass
# Then come known strings that take precedence
if peer in ('me', 'self'):
return _tl.InputPeerSelf()
# No InputPeer, cached peer, or known string. Fetch from session cache
try:
peer_id = utils.get_peer_id(peer)
except TypeError:
pass
else:
entity = await self._session.get_entity(None, peer_id)
if entity:
if entity.ty in (Entity.USER, Entity.BOT):
return _tl.InputPeerUser(entity.id, entity.hash)
elif entity.ty in (Entity.GROUP):
return _tl.InputPeerChat(peer.chat_id)
elif entity.ty in (Entity.CHANNEL, Entity.MEGAGROUP, Entity.GIGAGROUP):
return _tl.InputPeerChannel(entity.id, entity.hash)
# Only network left to try
if isinstance(peer, str):
return utils.get_input_peer(
await _get_entity_from_string(self, peer))
# If we're a bot and the user has messaged us privately users.getUsers
# will work with access_hash = 0. Similar for channels.getChannels.
# If we're not a bot but the user is in our contacts, it seems to work
# regardless. These are the only two special-cased requests.
peer = utils.get_peer(peer)
if isinstance(peer, _tl.PeerUser):
users = await self(_tl.fn.users.GetUsers([
_tl.InputUser(peer.user_id, access_hash=0)]))
if users and not isinstance(users[0], _tl.UserEmpty):
# If the user passed a valid ID they expect to work for
# channels but would be valid for users, we get UserEmpty.
# Avoid returning the invalid empty input peer for that.
#
# We *could* try to guess if it's a channel first, and if
# it's not, work as a chat and try to validate it through
# another request, but that becomes too much work.
return utils.get_input_peer(users[0])
elif isinstance(peer, _tl.PeerChat):
return _tl.InputPeerChat(peer.chat_id)
elif isinstance(peer, _tl.PeerChannel):
try:
channels = await self(_tl.fn.channels.GetChannels([
_tl.InputChannel(peer.channel_id, access_hash=0)]))
return utils.get_input_peer(channels.chats[0])
except errors.CHANNEL_INVALID:
pass
raise ValueError(
'Could not find the input peer for {} ({}). Please read https://'
'docs.telethon.dev/en/latest/concepts/entities.html to'
' find out more details.'
.format(peer, type(peer).__name__)
)
async def _get_peer_id(
self: 'TelegramClient',
peer: 'hints.DialogLike') -> int:
if isinstance(peer, int):
return utils.get_peer_id(peer)
try:
if peer.SUBCLASS_OF_ID not in (0x2d45687, 0xc91c90b6):
# 0x2d45687, 0xc91c90b6 == crc32(b'Peer') and b'InputPeer'
peer = await self._get_input_peer(peer)
except AttributeError:
peer = await self._get_input_peer(peer)
if isinstance(peer, _tl.InputPeerSelf):
peer = _tl.PeerUser(self._session_state.user_id)
return utils.get_peer_id(peer)
async def _get_entity_from_string(self: 'TelegramClient', string):
"""
Gets a full entity from the given string, which may be a phone or
a username, and processes all the found entities on the session.
The string may also be a user link, or a channel/chat invite link.
This method has the side effect of adding the found users to the
session database, so it can be queried later without API calls,
if this option is enabled on the session.
Returns the found entity, or raises TypeError if not found.
"""
phone = utils.parse_phone(string)
if phone:
try:
for user in (await self(
_tl.fn.contacts.GetContacts(0))).users:
if user.phone == phone:
return user
except errors.BOT_METHOD_INVALID:
raise ValueError('Cannot get entity by phone number as a '
'bot (try using integer IDs, not strings)')
elif string.lower() in ('me', 'self'):
return await self.get_me()
else:
username, is_join_chat = utils.parse_username(string)
if is_join_chat:
invite = await self(
_tl.fn.messages.CheckChatInvite(username))
if isinstance(invite, _tl.ChatInvite):
raise ValueError(
'Cannot get entity from a channel (or group) '
'that you are not part of. Join the group and retry'
)
elif isinstance(invite, _tl.ChatInviteAlready):
return invite.chat
elif username:
try:
result = await self(
_tl.fn.contacts.ResolveUsername(username))
except errors.USERNAME_NOT_OCCUPIED as e:
raise ValueError('No user has "{}" as username'
.format(username)) from e
try:
pid = utils.get_peer_id(result.peer)
if isinstance(result.peer, _tl.PeerUser):
return next(x for x in result.users if x.id == pid)
else:
return next(x for x in result.chats if x.id == pid)
except StopIteration:
pass
raise ValueError(
'Cannot find any entity corresponding to "{}"'.format(string)
)
async def _get_input_dialog(self: 'TelegramClient', dialog):
"""
Returns a :tl:`InputDialogPeer`. This is a bit tricky because
it may or not need access to the client to convert what's given
into an input entity.
"""
try:
if dialog.SUBCLASS_OF_ID == 0xa21c9795: # crc32(b'InputDialogPeer')
return dataclasses.replace(dialog, peer=await self._get_input_peer(dialog.peer))
elif dialog.SUBCLASS_OF_ID == 0xc91c90b6: # crc32(b'InputPeer')
return _tl.InputDialogPeer(dialog)
except AttributeError:
pass
return _tl.InputDialogPeer(await self._get_input_peer(dialog))
async def _get_input_notify(self: 'TelegramClient', notify):
"""
Returns a :tl:`InputNotifyPeer`. This is a bit tricky because
it may or not need access to the client to convert what's given
into an input entity.
"""
try:
if notify.SUBCLASS_OF_ID == 0x58981615:
if isinstance(notify, _tl.InputNotifyPeer):
return dataclasses.replace(notify, peer=await self._get_input_peer(notify.peer))
return notify
except AttributeError:
pass
return _tl.InputNotifyPeer(await self._get_input_peer(notify))

1
telethon/crypto/__init__.py → telethon/_crypto/__init__.py
View File

@ -7,4 +7,3 @@ from .aes import AES
from .aesctr import AESModeCTR
from .authkey import AuthKey
from .factorization import Factorization
from .cdndecrypter import CdnDecrypter

0
telethon/crypto/aes.py → telethon/_crypto/aes.py
View File

0
telethon/crypto/aesctr.py → telethon/_crypto/aesctr.py
View File

2
telethon/crypto/authkey.py → telethon/_crypto/authkey.py
View File

@ -4,7 +4,7 @@ This module holds the AuthKey class.
import struct
from hashlib import sha1
from ..extensions import BinaryReader
from .._misc.binaryreader import BinaryReader
class AuthKey:

0
telethon/crypto/factorization.py → telethon/_crypto/factorization.py
View File

0
telethon/crypto/libssl.py → telethon/_crypto/libssl.py
View File

6
telethon/crypto/rsa.py → telethon/_crypto/rsa.py
View File

@ -11,7 +11,7 @@ except ImportError:
rsa = None
raise ImportError('Missing module "rsa", please install via pip.')
from ..tl import TLObject
from .._misc import tlobject
# {fingerprint: (Crypto.PublicKey.RSA._RSAobj, old)} dictionary
@ -41,8 +41,8 @@ def _compute_fingerprint(key):
:param key: the Crypto.RSA key.
:return: its 8-bytes-long fingerprint.
"""
n = TLObject.serialize_bytes(get_byte_array(key.n))
e = TLObject.serialize_bytes(get_byte_array(key.e))
n = tlobject.TLObject._serialize_bytes(get_byte_array(key.n))
e = tlobject.TLObject._serialize_bytes(get_byte_array(key.e))
# Telegram uses the last 8 bytes as the fingerprint
return struct.unpack('<q', sha1(n + e).digest()[-8:])[0]

0
telethon/_events/__init__.py Normal file
View File

339
telethon/_events/album.py Normal file
View File

@ -0,0 +1,339 @@
import asyncio
import time
import weakref
from .base import EventBuilder
from .._misc import utils
from .. import _tl
from ..types import _custom
_IGNORE_MAX_SIZE = 100 # len()
_IGNORE_MAX_AGE = 5 # seconds
# IDs to ignore, and when they were added. If it grows too large, we will
# remove old entries. Although it should generally not be bigger than 10,
# it may be possible some updates are not processed and thus not removed.
_IGNORE_DICT = {}
_HACK_DELAY = 0.5
class AlbumHack:
"""
When receiving an album from a different data-center, they will come in
separate `Updates`, so we need to temporarily remember them for a while
and only after produce the event.
Of course events are not designed for this kind of wizardy, so this is
a dirty hack that gets the job done.
When cleaning up the code base we may want to figure out a better way
to do this, or just leave the album problem to the users; the update
handling code is bad enough as it is.
"""
def __init__(self, client, event):
# It's probably silly to use a weakref here because this object is
# very short-lived but might as well try to do "the right thing".
self._client = weakref.ref(client)
self._event = event # parent event
self._due = asyncio.get_running_loop().time() + _HACK_DELAY
asyncio.create_task(self.deliver_event())
def extend(self, messages):
client = self._client()
if client: # weakref may be dead
self._event.messages.extend(messages)
self._due = asyncio.get_running_loop().time() + _HACK_DELAY
async def deliver_event(self):
while True:
client = self._client()
if client is None:
return # weakref is dead, nothing to deliver
diff = self._due - asyncio.get_running_loop().time()
if diff <= 0:
# We've hit our due time, deliver event. It won't respect
# sequential updates but fixing that would just worsen this.
await client._dispatch_event(self._event)
return
del client # Clear ref and sleep until our due time
await asyncio.sleep(diff)
class Album(EventBuilder, _custom.chatgetter.ChatGetter, _custom.sendergetter.SenderGetter):
"""
Occurs whenever you receive an album. This event only exists
to ease dealing with an unknown amount of messages that belong
to the same album.
Members:
messages (Sequence[`Message <telethon.tl._custom.message.Message>`]):
The list of messages belonging to the same album.
Example
.. code-block:: python
from telethon import events
@client.on(events.Album)
async def handler(event):
# Counting how many photos or videos the album has
print('Got an album with', len(event), 'items')
# Forwarding the album as a whole to some chat
event.forward_to(chat)
# Printing the caption
print(event.text)
# Replying to the fifth item in the album
await event.messages[4].reply('Cool!')
"""
def __init__(self, messages):
message = messages[0]
if not message.out and isinstance(message.peer_id, _tl.PeerUser):
# Incoming message (e.g. from a bot) has peer_id=us, and
# from_id=bot (the actual "chat" from a user's perspective).
chat_peer = message.from_id
else:
chat_peer = message.peer_id
_custom.chatgetter.ChatGetter.__init__(self, chat_peer=chat_peer, broadcast=bool(message.post))
_custom.sendergetter.SenderGetter.__init__(self, message.sender_id)
self.messages = messages
def _build(cls, client, update, entities):
if not others:
return # We only care about albums which come inside the same Updates
if isinstance(update,
(_tl.UpdateNewMessage, _tl.UpdateNewChannelMessage)):
if not isinstance(update.message, _tl.Message):
return # We don't care about MessageService's here
group = update.message.grouped_id
if group is None:
return # It must be grouped
# Check whether we are supposed to skip this update, and
# if we do also remove it from the ignore list since we
# won't need to check against it again.
if _IGNORE_DICT.pop(id(update), None):
return
# Check if the ignore list is too big, and if it is clean it
# TODO time could technically go backwards; time is not monotonic
now = time.time()
if len(_IGNORE_DICT) > _IGNORE_MAX_SIZE:
for i in [i for i, t in _IGNORE_DICT.items() if now - t > _IGNORE_MAX_AGE]:
del _IGNORE_DICT[i]
# Add the other updates to the ignore list
for u in others:
if u is not update:
_IGNORE_DICT[id(u)] = now
# Figure out which updates share the same group and use those
return cls.Event([
u.message for u in others
if (isinstance(u, (_tl.UpdateNewMessage, _tl.UpdateNewChannelMessage))
and isinstance(u.message, _tl.Message)
and u.message.grouped_id == group)
])
self = cls.__new__(cls)
self._client = client
self._sender = entities.get(_tl.PeerUser(update.user_id))
self._chat = entities.get(_tl.PeerUser(update.user_id))
return self
def _set_client(self, client):
super()._set_client(client)
self._sender, self._input_sender = utils._get_entity_pair(self.sender_id, self._entities)
self.messages = [
_custom.Message._new(client, m, self._entities, None)
for m in self.messages
]
if len(self.messages) == 1:
# This will require hacks to be a proper album event
hack = client._albums.get(self.grouped_id)
if hack is None:
client._albums[self.grouped_id] = AlbumHack(client, self)
else:
hack.extend(self.messages)
@property
def grouped_id(self):
"""
The shared ``grouped_id`` between all the messages.
"""
return self.messages[0].grouped_id
@property
def text(self):
"""
The message text of the first photo with a caption,
formatted using the client's default parse mode.
"""
return next((m.text for m in self.messages if m.text), '')
@property
def raw_text(self):
"""
The raw message text of the first photo
with a caption, ignoring any formatting.
"""
return next((m.raw_text for m in self.messages if m.raw_text), '')
@property
def is_reply(self):
"""
`True` if the album is a reply to some other message.
Remember that you can access the ID of the message
this one is replying to through `reply_to_msg_id`,
and the `Message` object with `get_reply_message()`.
"""
# Each individual message in an album all reply to the same message
return self.messages[0].is_reply
@property
def forward(self):
"""
The `Forward <telethon.tl._custom.forward.Forward>`
information for the first message in the album if it was forwarded.
"""
# Each individual message in an album all reply to the same message
return self.messages[0].forward
# endregion Public Properties
# region Public Methods
async def get_reply_message(self):
"""
The `Message <telethon.tl._custom.message.Message>`
that this album is replying to, or `None`.
The result will be cached after its first use.
"""
return await self.messages[0].get_reply_message()
async def respond(self, *args, **kwargs):
"""
Responds to the album (not as a reply). Shorthand for
`telethon.client.messages.MessageMethods.send_message`
with ``entity`` already set.
"""
return await self.messages[0].respond(*args, **kwargs)
async def reply(self, *args, **kwargs):
"""
Replies to the first photo in the album (as a reply). Shorthand
for `telethon.client.messages.MessageMethods.send_message`
with both ``entity`` and ``reply_to`` already set.
"""
return await self.messages[0].reply(*args, **kwargs)
async def forward_to(self, *args, **kwargs):
"""
Forwards the entire album. Shorthand for
`telethon.client.messages.MessageMethods.forward_messages`
with both ``messages`` and ``from_peer`` already set.
"""
if self._client:
kwargs['messages'] = self.messages
kwargs['from_peer'] = await self.get_input_chat()
return await self._client.forward_messages(*args, **kwargs)
async def edit(self, *args, **kwargs):
"""
Edits the first caption or the message, or the first messages'
caption if no caption is set, iff it's outgoing. Shorthand for
`telethon.client.messages.MessageMethods.edit_message`
with both ``entity`` and ``message`` already set.
Returns `None` if the message was incoming,
or the edited `Message` otherwise.
.. note::
This is different from `client.edit_message
<telethon.client.messages.MessageMethods.edit_message>`
and **will respect** the previous state of the message.
For example, if the message didn't have a link preview,
the edit won't add one by default, and you should force
it by setting it to `True` if you want it.
This is generally the most desired and convenient behaviour,
and will work for link previews and message buttons.
"""
for msg in self.messages:
if msg.raw_text:
return await msg.edit(*args, **kwargs)
return await self.messages[0].edit(*args, **kwargs)
async def delete(self, *args, **kwargs):
"""
Deletes the entire album. You're responsible for checking whether
you have the permission to do so, or to except the error otherwise.
Shorthand for
`telethon.client.messages.MessageMethods.delete_messages` with
``entity`` and ``message_ids`` already set.
"""
if self._client:
return await self._client.delete_messages(
await self.get_input_chat(), self.messages,
*args, **kwargs
)
async def mark_read(self):
"""
Marks the entire album as read. Shorthand for
`client.mark_read()
<telethon.client.messages.MessageMethods.mark_read>`
with both ``entity`` and ``message`` already set.
"""
if self._client:
await self._client.mark_read(
await self.get_input_chat(), max_id=self.messages[-1].id)
async def pin(self, *, notify=False):
"""
Pins the first photo in the album. Shorthand for
`telethon.client.messages.MessageMethods.pin_message`
with both ``entity`` and ``message`` already set.
"""
return await self.messages[0].pin(notify=notify)
def __len__(self):
"""
Return the amount of messages in the album.
Equivalent to ``len(self.messages)``.
"""
return len(self.messages)
def __iter__(self):
"""
Iterate over the messages in the album.
Equivalent to ``iter(self.messages)``.
"""
return iter(self.messages)
def __getitem__(self, n):
"""
Access the n'th message in the album.
Equivalent to ``event.messages[n]``.
"""
return self.messages[n]

63
telethon/_events/base.py Normal file
View File

@ -0,0 +1,63 @@
import abc
import functools
from .filters import Filter
class StopPropagation(Exception):
"""
If this exception is raised in any of the handlers for a given event,
it will stop the execution of all other registered event handlers.
It can be seen as the ``StopIteration`` in a for loop but for events.
Example usage:
>>> from telethon import TelegramClient, events
>>> client = TelegramClient(...)
>>>
>>> @client.on(events.NewMessage)
... async def delete(event):
... await event.delete()
... # No other event handler will have a chance to handle this event
... raise StopPropagation
...
>>> @client.on(events.NewMessage)
... async def _(event):
... # Will never be reached, because it is the second handler
... pass
"""
# For some reason Sphinx wants the silly >>> or
# it will show warnings and look bad when generated.
pass
class EventBuilder(abc.ABC):
@classmethod
@abc.abstractmethod
def _build(cls, client, update, entities):
"""
Builds an event for the given update if possible, or returns None.
`entities` must have `get(Peer) -> User|Chat` and `self_id`,
which must be the current user's ID.
"""
@functools.total_ordering
class EventHandler:
__slots__ = ('_event', '_callback', '_priority', '_filter')
def __init__(self, event: EventBuilder, callback: callable, priority: int, filter: Filter):
self._event = event
self._callback = callback
self._priority = priority
self._filter = filter
def __eq__(self, other):
return self is other
def __lt__(self, other):
return self._priority < other._priority
def __call__(self, *args, **kwargs):
return self._callback(*args, **kwargs)

267
telethon/_events/callbackquery.py Normal file
View File

@ -0,0 +1,267 @@
import re
import struct
import asyncio
import functools
from .base import EventBuilder
from .._misc import utils
from .. import _tl
from ..types import _custom
def auto_answer(func):
@functools.wraps(func)
async def wrapped(self, *args, **kwargs):
if self._answered:
return await func(*args, **kwargs)
else:
return (await asyncio.gather(
self._answer(),
func(*args, **kwargs),
))[1]
return wrapped
class CallbackQuery(EventBuilder, _custom.chatgetter.ChatGetter, _custom.sendergetter.SenderGetter):
"""
Occurs whenever you sign in as a bot and a user
clicks one of the inline buttons on your messages.
Note that the `chats` parameter will **not** work with normal
IDs or peers if the clicked inline button comes from a "via bot"
message. The `chats` parameter also supports checking against the
`chat_instance` which should be used for inline callbacks.
Members:
query (:tl:`UpdateBotCallbackQuery`):
The original :tl:`UpdateBotCallbackQuery`.
data_match (`obj`, optional):
The object returned by the ``data=`` parameter
when creating the event builder, if any. Similar
to ``pattern_match`` for the new message event.
pattern_match (`obj`, optional):
Alias for ``data_match``.
Example
.. code-block:: python
from telethon import events, Button
# Handle all callback queries and check data inside the handler
@client.on(events.CallbackQuery)
async def handler(event):
if event.data == b'yes':
await event.answer('Correct answer!')
# Handle only callback queries with data being b'no'
@client.on(events.CallbackQuery(data=b'no'))
async def handler(event):
# Pop-up message with alert
await event.answer('Wrong answer!', alert=True)
# Send a message with buttons users can click
async def main():
await client.send_message(user, 'Yes or no?', buttons=[
Button.inline('Yes!', b'yes'),
Button.inline('Nope', b'no')
])
"""
@classmethod
def _build(cls, client, update, entities):
query = update
if isinstance(update, _tl.UpdateBotCallbackQuery):
peer = update.peer
msg_id = update.msg_id
elif isinstance(update, _tl.UpdateInlineBotCallbackQuery):
# See https://github.com/LonamiWebs/Telethon/pull/1005
# The long message ID is actually just msg_id + peer_id
msg_id, pid = struct.unpack('<ii', struct.pack('<q', update.msg_id.id))
peer = _tl.PeerChannel(-pid) if pid < 0 else _tl.PeerUser(pid)
else:
return None
self = cls.__new__(cls)
self._client = client
self._sender = entities.get(_tl.PeerUser(query.user_id))
self._chat = entities.get(peer)
self.query = query
self.data_match = None
self.pattern_match = None
self._message = None
self._answered = False
return self
@property
def id(self):
"""
Returns the query ID. The user clicking the inline
button is the one who generated this random ID.
"""
return self.query.query_id
@property
def message_id(self):
"""
Returns the message ID to which the clicked inline button belongs.
"""
return self._message_id
@property
def data(self):
"""
Returns the data payload from the original inline button.
"""
return self.query.data
@property
def chat_instance(self):
"""
Unique identifier for the chat where the callback occurred.
Useful for high scores in games.
"""
return self.query.chat_instance
async def get_message(self):
"""
Returns the message to which the clicked inline button belongs.
"""
if self._message is not None:
return self._message
try:
self._message = await self._client.get_messages(self.chat, ids=self._message_id)
except ValueError:
return
return self._message
async def answer(
self, message=None, cache_time=0, *, url=None, alert=False):
"""
Answers the callback query (and stops the loading circle).
Args:
message (`str`, optional):
The toast message to show feedback to the user.
cache_time (`int`, optional):
For how long this result should be cached on
the user's client. Defaults to 0 for no cache.
url (`str`, optional):
The URL to be opened in the user's client. Note that
the only valid URLs are those of games your bot has,
or alternatively a 't.me/your_bot?start=xyz' parameter.
alert (`bool`, optional):
Whether an alert (a pop-up dialog) should be used
instead of showing a toast. Defaults to `False`.
"""
if self._answered:
return
res = await self._client(_tl.fn.messages.SetBotCallbackAnswer(
query_id=self.query.query_id,
cache_time=cache_time,
alert=alert,
message=message,
url=url,
))
self._answered = True
return res
@property
def via_inline(self):
"""
Whether this callback was generated from an inline button sent
via an inline query or not. If the bot sent the message itself
with buttons, and one of those is clicked, this will be `False`.
If a user sent the message coming from an inline query to the
bot, and one of those is clicked, this will be `True`.
If it's `True`, it's likely that the bot is **not** in the
chat, so methods like `respond` or `delete` won't work (but
`edit` will always work).
"""
return isinstance(self.query, _tl.UpdateInlineBotCallbackQuery)
@auto_answer
async def respond(self, *args, **kwargs):
"""
Responds to the message (not as a reply). Shorthand for
`telethon.client.messages.MessageMethods.send_message` with
``entity`` already set.
This method will also `answer` the callback if necessary.
This method will likely fail if `via_inline` is `True`.
"""
return await self._client.send_message(
await self.get_input_chat(), *args, **kwargs)
@auto_answer
async def reply(self, *args, **kwargs):
"""
Replies to the message (as a reply). Shorthand for
`telethon.client.messages.MessageMethods.send_message` with
both ``entity`` and ``reply_to`` already set.
This method will also `answer` the callback if necessary.
This method will likely fail if `via_inline` is `True`.
"""
kwargs['reply_to'] = self.query.msg_id
return await self._client.send_message(
await self.get_input_chat(), *args, **kwargs)
@auto_answer
async def edit(self, *args, **kwargs):
"""
Edits the message. Shorthand for
`telethon.client.messages.MessageMethods.edit_message` with
the ``entity`` set to the correct :tl:`InputBotInlineMessageID`.
Returns `True` if the edit was successful.
This method will also `answer` the callback if necessary.
.. note::
This method won't respect the previous message unlike
`Message.edit <telethon.tl._custom.message.Message.edit>`,
since the message object is normally not present.
"""
if isinstance(self.query.msg_id, _tl.InputBotInlineMessageID):
return await self._client.edit_message(
None, self.query.msg_id, *args, **kwargs
)
else:
return await self._client.edit_message(
await self.get_input_chat(), self.query.msg_id,
*args, **kwargs
)
@auto_answer
async def delete(self, *args, **kwargs):
"""
Deletes the message. Shorthand for
`telethon.client.messages.MessageMethods.delete_messages` with
``entity`` and ``message_ids`` already set.
If you need to delete more than one message at once, don't use
this `delete` method. Use a
`telethon.client.telegramclient.TelegramClient` instance directly.
This method will also `answer` the callback if necessary.
This method will likely fail if `via_inline` is `True`.
"""
return await self._client.delete_messages(
await self.get_input_chat(), [self.query.msg_id],
*args, **kwargs
)

451
telethon/_events/chataction.py Normal file
View File

@ -0,0 +1,451 @@
from .base import EventBuilder
from .._misc import utils
from .. import _tl
from ..types import _custom
class ChatAction(EventBuilder):
"""
Occurs on certain chat actions:
* Whenever a new chat is created.
* Whenever a chat's title or photo is changed or removed.
* Whenever a new message is pinned.
* Whenever a user scores in a game.
* Whenever a user joins or is added to the group.
* Whenever a user is removed or leaves a group if it has
less than 50 members or the removed user was a bot.
Note that "chat" refers to "small group, megagroup and broadcast
channel", whereas "group" refers to "small group and megagroup" only.
Members:
action_message (`MessageAction <https://tl.telethon.dev/types/message_action.html>`_):
The message invoked by this Chat Action.
new_pin (`bool`):
`True` if there is a new pin.
new_photo (`bool`):
`True` if there's a new chat photo (or it was removed).
photo (:tl:`Photo`, optional):
The new photo (or `None` if it was removed).
user_added (`bool`):
`True` if the user was added by some other.
user_joined (`bool`):
`True` if the user joined on their own.
user_left (`bool`):
`True` if the user left on their own.
user_kicked (`bool`):
`True` if the user was kicked by some other.
user_approved (`bool`):
`True` if the user's join request was approved.
along with `user_joined` will be also True.
created (`bool`, optional):
`True` if this chat was just created.
new_title (`str`, optional):
The new title string for the chat, if applicable.
new_score (`str`, optional):
The new score string for the game, if applicable.
unpin (`bool`):
`True` if the existing pin gets unpinned.
Example
.. code-block:: python
from telethon import events
@client.on(events.ChatAction)
async def handler(event):
# Welcome every new user
if event.user_joined:
await event.reply('Welcome to the group!')
"""
@classmethod
def _build(cls, client, update, entities):
where = None
new_photo = None
added_by = None
kicked_by = None
created = None
from_approval = None
users = None
new_title = None
pin_ids = None
pin = None
new_score = None
# Rely on specific pin updates for unpins, but otherwise ignore them
# for new pins (we'd rather handle the new service message with pin,
# so that we can act on that message').
if isinstance(update, _tl.UpdatePinnedChannelMessages) and not update.pinned:
where = _tl.PeerChannel(update.channel_id)
pin_ids = update.messages
pin = update.pinned
elif isinstance(update, _tl.UpdatePinnedMessages) and not update.pinned:
where = update.peer
pin_ids = update.messages
pin = update.pinned
elif isinstance(update, _tl.UpdateChatParticipantAdd):
where = _tl.PeerChat(update.chat_id)
added_by = update.inviter_id or True
users = update.user_id
elif isinstance(update, _tl.UpdateChatParticipantDelete):
where = _tl.PeerChat(update.chat_id)
kicked_by = True
users = update.user_id
# UpdateChannel is sent if we leave a channel, and the update._entities
# set by _process_update would let us make some guesses. However it's
# better not to rely on this. Rely only in MessageActionChatDeleteUser.
elif (isinstance(update, (
_tl.UpdateNewMessage, _tl.UpdateNewChannelMessage))
and isinstance(update.message, _tl.MessageService)):
msg = update.message
action = update.message.action
if isinstance(action, _tl.MessageActionChatJoinedByLink):
where = msg
added_by = True
users = msg.from_id
elif isinstance(action, _tl.MessageActionChatAddUser):
# If a user adds itself, it means they joined via the public chat username
added_by = ([msg.sender_id] == action.users) or msg.from_id
where = msg
added_by = added_by
users = action.users
elif isinstance(action, _tl.MessageActionChatJoinedByRequest):
# user joined from join request (after getting admin approval)
where = msg
from_approval = True
users = msg.from_id
elif isinstance(action, _tl.MessageActionChatDeleteUser):
where = msg
kicked_by = utils.get_peer_id(msg.from_id) if msg.from_id else True
users = action.user_id
elif isinstance(action, _tl.MessageActionChatCreate):
where = msg
users = action.users
created = True
new_title = action.title
elif isinstance(action, _tl.MessageActionChannelCreate):
where = msg
created = True
users = msg.from_id
new_title = action.title
elif isinstance(action, _tl.MessageActionChatEditTitle):
where = msg
users = msg.from_id
new_title = action.title
elif isinstance(action, _tl.MessageActionChatEditPhoto):
where = msg
users = msg.from_id
new_photo = action.photo
elif isinstance(action, _tl.MessageActionChatDeletePhoto):
where = msg
users = msg.from_id
new_photo = True
elif isinstance(action, _tl.MessageActionPinMessage) and msg.reply_to:
where = msg
pin_ids=[msg.reply_to_msg_id]
elif isinstance(action, _tl.MessageActionGameScore):
where = msg
new_score = action.score
self = cls.__new__(cls)
self._client = client
if isinstance(where, _tl.MessageService):
self.action_message = where
where = where.peer_id
else:
self.action_message = None
self._chat = entities.get(where)
self.new_pin = pin_ids is not None
self._pin_ids = pin_ids
self._pinned_messages = None
self.new_photo = new_photo is not None
self.photo = \
new_photo if isinstance(new_photo, _tl.Photo) else None
self._added_by = None
self._kicked_by = None
self.user_added = self.user_joined = self.user_left = \
self.user_kicked = self.unpin = False
if added_by is True or from_approval is True:
self.user_joined = True
elif added_by:
self.user_added = True
self._added_by = added_by
self.user_approved = from_approval
# If `from_id` was not present (it's `True`) or the affected
# user was "kicked by itself", then it left. Else it was kicked.
if kicked_by is True or (users is not None and kicked_by == users):
self.user_left = True
elif kicked_by:
self.user_kicked = True
self._kicked_by = kicked_by
self.created = bool(created)
if isinstance(users, list):
self._user_ids = [utils.get_peer_id(u) for u in users]
elif users:
self._user_ids = [utils.get_peer_id(users)]
else:
self._user_ids = []
self._users = None
self._input_users = None
self.new_title = new_title
self.new_score = new_score
self.unpin = not pin
return self
async def respond(self, *args, **kwargs):
"""
Responds to the chat action message (not as a reply). Shorthand for
`telethon.client.messages.MessageMethods.send_message` with
``entity`` already set.
"""
return await self._client.send_message(
await self.get_input_chat(), *args, **kwargs)
async def reply(self, *args, **kwargs):
"""
Replies to the chat action message (as a reply). Shorthand for
`telethon.client.messages.MessageMethods.send_message` with
both ``entity`` and ``reply_to`` already set.
Has the same effect as `respond` if there is no message.
"""
if not self.action_message:
return await self.respond(*args, **kwargs)
kwargs['reply_to'] = self.action_message.id
return await self._client.send_message(
await self.get_input_chat(), *args, **kwargs)
async def delete(self, *args, **kwargs):
"""
Deletes the chat action message. You're responsible for checking
whether you have the permission to do so, or to except the error
otherwise. Shorthand for
`telethon.client.messages.MessageMethods.delete_messages` with
``entity`` and ``message_ids`` already set.
Does nothing if no message action triggered this event.
"""
if not self.action_message:
return
return await self._client.delete_messages(
await self.get_input_chat(), [self.action_message],
*args, **kwargs
)
async def get_pinned_message(self):
"""
If ``new_pin`` is `True`, this returns the `Message
<telethon.tl.custom.message.Message>` object that was pinned.
"""
if self._pinned_messages is None:
await self.get_pinned_messages()
if self._pinned_messages:
return self._pinned_messages[0]
async def get_pinned_messages(self):
"""
If ``new_pin`` is `True`, this returns a `list` of `Message
<telethon.tl.custom.message.Message>` objects that were pinned.
"""
if not self._pin_ids:
return self._pin_ids # either None or empty list
chat = await self.get_input_chat()
if chat:
self._pinned_messages = await self._client.get_messages(
self._input_chat, ids=self._pin_ids)
return self._pinned_messages
@property
def added_by(self):
"""
The user who added ``users``, if applicable (`None` otherwise).
"""
if self._added_by and not isinstance(self._added_by, _tl.User):
aby = self._entities.get(utils.get_peer_id(self._added_by))
if aby:
self._added_by = aby
return self._added_by
async def get_added_by(self):
"""
Returns `added_by` but will make an API call if necessary.
"""
if not self.added_by and self._added_by:
self._added_by = await self._client.get_profile(self._added_by)
return self._added_by
@property
def kicked_by(self):
"""
The user who kicked ``users``, if applicable (`None` otherwise).
"""
if self._kicked_by and not isinstance(self._kicked_by, _tl.User):
kby = self._entities.get(utils.get_peer_id(self._kicked_by))
if kby:
self._kicked_by = kby
return self._kicked_by
async def get_kicked_by(self):
"""
Returns `kicked_by` but will make an API call if necessary.
"""
if not self.kicked_by and self._kicked_by:
self._kicked_by = await self._client.get_profile(self._kicked_by)
return self._kicked_by
@property
def user(self):
"""
The first user that takes part in this action. For example, who joined.
Might be `None` if the information can't be retrieved or
there is no user taking part.
"""
if self.users:
return self._users[0]
async def get_user(self):
"""
Returns `user` but will make an API call if necessary.
"""
if self.users or await self.get_users():
return self._users[0]
@property
def input_user(self):
"""
Input version of the ``self.user`` property.
"""
if self.input_users:
return self._input_users[0]
async def get_input_user(self):
"""
Returns `input_user` but will make an API call if necessary.
"""
if self.input_users or await self.get_input_users():
return self._input_users[0]
@property
def user_id(self):
"""
Returns the marked signed ID of the first user, if any.
"""
if self._user_ids:
return self._user_ids[0]
@property
def users(self):
"""
A list of users that take part in this action. For example, who joined.
Might be empty if the information can't be retrieved or there
are no users taking part.
"""
if not self._user_ids:
return []
if self._users is None:
self._users = [
self._entities[user_id]
for user_id in self._user_ids
if user_id in self._entities
]
return self._users
async def get_users(self):
"""
Returns `users` but will make an API call if necessary.
"""
if not self._user_ids:
return []
# Note: we access the property first so that it fills if needed
if (self.users is None or len(self._users) != len(self._user_ids)) and self.action_message:
await self.action_message._reload_message()
self._users = [
u for u in self.action_message.action_entities
if isinstance(u, (_tl.User, _tl.UserEmpty))]
return self._users
@property
def input_users(self):
"""
Input version of the ``self.users`` property.
"""
if self._input_users is None and self._user_ids:
self._input_users = []
for user_id in self._user_ids:
# Try to get it from our entities
try:
self._input_users.append(utils.get_input_peer(self._entities[user_id]))
continue
except (KeyError, TypeError):
pass
return self._input_users or []
async def get_input_users(self):
"""
Returns `input_users` but will make an API call if necessary.
"""
if not self._user_ids:
return []
# Note: we access the property first so that it fills if needed
if (self.input_users is None or len(self._input_users) != len(self._user_ids)) and self.action_message:
self._input_users = [
utils.get_input_peer(u)
for u in self.action_message.action_entities
if isinstance(u, (_tl.User, _tl.UserEmpty))]
return self._input_users or []
@property
def user_ids(self):
"""
Returns the marked signed ID of the users, if any.
"""
if self._user_ids:
return self._user_ids[:]

150
telethon/_events/filters/__init__.py Normal file
View File

@ -0,0 +1,150 @@
from .base import Filter, And, Or, Not, Identity, Always, Never
from .generic import Types
from .entities import Chats, Senders
from .messages import Incoming, Outgoing, Pattern, Data
_sentinel = object()
def make_filter(
chats=_sentinel,
blacklist_chats=_sentinel,
func=_sentinel,
types=_sentinel,
incoming=_sentinel,
outgoing=_sentinel,
senders=_sentinel,
blacklist_senders=_sentinel,
forwards=_sentinel,
pattern=_sentinel,
data=_sentinel,
):
"""
Create a new `And` filter joining all the filters specified as input parameters.
Not all filters may have an effect on all events.
chats (`entity`, optional):
May be one or more entities (username/peer/etc.), preferably IDs.
By default, only matching chats will be handled.
blacklist_chats (`bool`, optional):
Whether to treat the chats as a blacklist instead of
as a whitelist (default). This means that every chat
will be handled *except* those specified in ``chats``
which will be ignored if ``blacklist_chats=True``.
func (`callable`, optional):
A callable (async or not) function that should accept the event as input
parameter, and return a value indicating whether the event
should be dispatched or not (any truthy value will do, it
does not need to be a `bool`). It works like a custom filter:
.. code-block:: python
@client.on(events.NewMessage(func=lambda e: e.is_private))
async def handler(event):
pass # code here
incoming (`bool`, optional):
If set to `True`, only **incoming** messages will be handled.
If set to `False`, incoming messages will be ignored.
If both incoming are outgoing are set, whichever is true will be handled.
outgoing (`bool`, optional):
If set to `True`, only **outgoing** messages will be handled.
If set to `False`, outgoing messages will be ignored.
If both incoming are outgoing are set, whichever is true will be handled.
senders (`entity`, optional):
Unlike `chats`, this parameter filters the *senders* of the
message. That is, only messages *sent by these users* will be
handled. Use `chats` if you want private messages with this/these
users. `senders` lets you filter by messages sent by *one or
more* users across the desired chats (doesn't need a list).
blacklist_senders (`bool`):
Whether to treat the senders as a blacklist instead of
as a whitelist (default). This means that every sender
will be handled *except* those specified in ``senders``
which will be ignored if ``blacklist_senders=True``.
forwards (`bool`, optional):
Whether forwarded messages should be handled or not. By default,
both forwarded and normal messages are included. If it's `True`
*only* forwards will be handled. If it's `False` only messages
that are *not* forwards will be handled.
pattern (`str`, `callable`, `Pattern`, optional):
If set, only messages matching this pattern will be handled.
You can specify a regex-like string which will be matched
against the message, a callable function that returns `True`
if a message is acceptable, or a compiled regex pattern.
data (`bytes`, `str`, `callable`, optional):
If set, the inline button payload data must match this data.
A UTF-8 string can also be given, a regex or a callable. For
instance, to check against ``'data_1'`` and ``'data_2'`` you
can use ``re.compile(b'data_')``.
types (`list` | `tuple` | `type`, optional):
The type or types that the :tl:`Update` instance must be.
Equivalent to ``if not isinstance(update, types): return``.
"""
filters = []
if chats is not _sentinel:
f = Chats(chats)
if blacklist_chats is not _sentinel and blacklist_chats:
f = Not(f)
filters.append(f)
if func is not _sentinel:
filters.append(Identity(func))
if types is not _sentinel:
filters.append(Types(types))
if incoming is not _sentinel:
if outgoing is not _sentinel:
if incoming and outgoing:
pass # no need to filter
elif incoming:
filters.append(Incoming())
elif outgoing:
filters.append(Outgoing())
else:
return Never() # why?
elif incoming:
filters.append(Incoming())
else:
filters.append(Outgoing())
elif outgoing is not _sentinel:
if outgoing:
filters.append(Outgoing())
else:
filters.append(Incoming())
if senders is not _sentinel:
f = Senders(senders)
if blacklist_senders is not _sentinel and blacklist_senders:
f = Not(f)
filters.append(f)
if forwards is not _sentinel:
filters.append(Forward())
if pattern is not _sentinel:
filters.append(Pattern(pattern))
if data is not _sentinel:
filters.append(Data(data))
return And(*filters) if filters else Always()
class NotResolved(ValueError):
def __init__(self, unresolved):
super().__init__()
self.unresolved = unresolved

78
telethon/_events/filters/base.py Normal file
View File

@ -0,0 +1,78 @@
import abc
class Filter(abc.ABC):
@abc.abstractmethod
def __call__(self, event):
return True
def __and__(self, other):
return And(self, other)
def __or__(self, other):
return Or(self, other)
def __invert__(self):
return Not(self)
class And(Filter):
"""
All underlying filters must return `True` for this filter to be `True`.
"""
def __init__(self, *filters):
self._filters = filters
def __call__(self, event):
return all(f(event) for f in self._filters)
class Or(Filter):
"""
At least one underlying filter must return `True` for this filter to be `True`.
"""
def __init__(self, *filters):
self._filters = filters
def __call__(self, event):
return any(f(event) for f in self._filters)
class Not(Filter):
"""
The underlying filter must return `False` for this filter to be `True`.
"""
def __init__(self, filter):
self._filter = filter
def __call__(self, event):
return not self._filter(event)
class Identity(Filter):
"""
Return the value of the underlying filter (or callable) without any modifications.
"""
def __init__(self, filter):
self._filter = filter
def __call__(self, event):
return self._filter(event)
class Always(Filter):
"""
This filter always returns `True`, and is used as the "empty filter".
"""
def __call__(self, event):
return True
class Never(Filter):
"""
This filter always returns `False`, and is used when an impossible filter is made
(for example, neither outgoing nor incoming is always false). This can be used to
"turn off" handlers without removing them.
"""
def __call__(self, event):
return False

25
telethon/_events/filters/entities.py Normal file
View File

@ -0,0 +1,25 @@
from .base import Filter
class Chats:
"""
The update type must match the specified instances for the filter to return `True`.
This is most useful for raw API.
"""
def __init__(self, types):
self._types = types
def __call__(self, event):
return isinstance(event, self._types)
class Senders:
"""
The update type must match the specified instances for the filter to return `True`.
This is most useful for raw API.
"""
def __init__(self, types):
self._types = types
def __call__(self, event):
return isinstance(event, self._types)

13
telethon/_events/filters/generic.py Normal file
View File

@ -0,0 +1,13 @@
from .base import Filter
class Types:
"""
The update type must match the specified instances for the filter to return `True`.
This is most useful for raw API.
"""
def __init__(self, types):
self._types = types
def __call__(self, event):
return isinstance(event, self._types)

44
telethon/_events/filters/messages.py Normal file
View File

@ -0,0 +1,44 @@
import re
from .base import Filter
class Incoming:
"""
The update must be something the client received from another user,
and not something the current user sent.
"""
def __call__(self, event):
return not event.out
class Outgoing:
"""
The update must be something the current user sent,
and not something received from another user.
"""
def __call__(self, event):
return event.out
class Pattern:
"""
The update type must match the specified instances for the filter to return `True`.
This is most useful for raw API.
"""
def __init__(self, pattern):
self._pattern = re.compile(pattern).match
def __call__(self, event):
return self._pattern(event.text)
class Data:
"""
The update type must match the specified instances for the filter to return `True`.
This is most useful for raw API.
"""
def __init__(self, data):
self._data = re.compile(data).match
def __call__(self, event):
return self._data(event.data)

200
telethon/_events/inlinequery.py Normal file
View File

@ -0,0 +1,200 @@
import inspect
import re
import asyncio
from .base import EventBuilder
from .._misc import utils
from .. import _tl
from ..types import _custom
class InlineQuery(EventBuilder, _custom.chatgetter.ChatGetter, _custom.sendergetter.SenderGetter):
"""
Occurs whenever you sign in as a bot and a user
sends an inline query such as ``@bot query``.
Members:
query (:tl:`UpdateBotInlineQuery`):
The original :tl:`UpdateBotInlineQuery`.
Make sure to access the `text` property of the query if
you want the text rather than the actual query object.
pattern_match (`obj`, optional):
The resulting object from calling the passed ``pattern``
function, which is ``re.compile(...).match`` by default.
Example
.. code-block:: python
from telethon import events
@client.on(events.InlineQuery)
async def handler(event):
builder = event.builder
# Two options (convert user text to UPPERCASE or lowercase)
await event.answer([
builder.article('UPPERCASE', text=event.text.upper()),
builder.article('lowercase', text=event.text.lower()),
])
"""
@classmethod
def _build(cls, client, update, entities):
if not isinstance(update, _tl.UpdateBotInlineQuery):
return None
self = cls.__new__(cls)
self._client = client
self._sender = entities.get(_tl.PeerUser(update.user_id))
self._chat = entities.get(_tl.PeerUser(update.user_id))
self.query = update
self.pattern_match = None
self._answered = False
return self
@property
def id(self):
"""
Returns the unique identifier for the query ID.
"""
return self.query.query_id
@property
def text(self):
"""
Returns the text the user used to make the inline query.
"""
return self.query.query
@property
def offset(self):
"""
The string the user's client used as an offset for the query.
This will either be empty or equal to offsets passed to `answer`.
"""
return self.query.offset
@property
def geo(self):
"""
If the user location is requested when using inline mode
and the user's device is able to send it, this will return
the :tl:`GeoPoint` with the position of the user.
"""
return self.query.geo
@property
def builder(self):
"""
Returns a new `InlineBuilder
<telethon.tl.custom.inlinebuilder.InlineBuilder>` instance.
See the documentation for `builder` to know what kind of answers
can be given.
"""
return _custom.InlineBuilder(self._client)
async def answer(
self, results=None, cache_time=0, *,
gallery=False, next_offset=None, private=False,
switch_pm=None, switch_pm_param=''):
"""
Answers the inline query with the given results.
Args:
results (`list`, optional):
A list of :tl:`InputBotInlineResult` to use.
You should use `builder` to create these:
.. code-block:: python
builder = inline.builder
r1 = builder.article('Be nice', text='Have a nice day')
r2 = builder.article('Be bad', text="I don't like you")
await inline.answer([r1, r2])
You can send up to 50 results as documented in
https://core.telegram.org/bots/api#answerinlinequery.
Sending more will raise ``ResultsTooMuchError``,
and you should consider using `next_offset` to
paginate them.
cache_time (`int`, optional):
For how long this result should be cached on
the user's client. Defaults to 0 for no cache.
gallery (`bool`, optional):
Whether the results should show as a gallery (grid) or not.
next_offset (`str`, optional):
The offset the client will send when the user scrolls the
results and it repeats the request.
private (`bool`, optional):
Whether the results should be cached by Telegram
(not private) or by the user's client (private).
switch_pm (`str`, optional):
If set, this text will be shown in the results
to allow the user to switch to private messages.
switch_pm_param (`str`, optional):
Optional parameter to start the bot with if
`switch_pm` was used.
Example:
.. code-block:: python
@bot.on(events.InlineQuery)
async def handler(event):
builder = event.builder
rev_text = event.text[::-1]
await event.answer([
builder.article('Reverse text', text=rev_text),
builder.photo('/path/to/photo.jpg')
])
"""
if self._answered:
return
if results:
futures = [self._as_future(x) for x in results]
await asyncio.wait(futures)
# All futures will be in the `done` *set* that `wait` returns.
#
# Precisely because it's a `set` and not a `list`, it
# will not preserve the order, but since all futures
# completed we can use our original, ordered `list`.
results = [x.result() for x in futures]
else:
results = []
if switch_pm:
switch_pm = _tl.InlineBotSwitchPM(switch_pm, switch_pm_param)
return await self._client(
_tl.fn.messages.SetInlineBotResults(
query_id=self.query.query_id,
results=results,
cache_time=cache_time,
gallery=gallery,
next_offset=next_offset,
private=private,
switch_pm=switch_pm
)
)
@staticmethod
def _as_future(obj):
if inspect.isawaitable(obj):
return asyncio.ensure_future(obj)
f = asyncio.get_running_loop().create_future()
f.set_result(obj)
return f

39
telethon/events/messagedeleted.py → telethon/_events/messagedeleted.py
View File

@ -1,9 +1,9 @@
from .common import EventBuilder, EventCommon, name_inner_event
from ..tl import types
from .base import EventBuilder
from .. import _tl
from ..types import _custom
@name_inner_event
class MessageDeleted(EventBuilder):
class MessageDeleted(EventBuilder, _custom.chatgetter.ChatGetter):
"""
Occurs whenever a message is deleted. Note that this event isn't 100%
reliable, since Telegram doesn't always notify the clients that a message
@ -36,22 +36,17 @@ class MessageDeleted(EventBuilder):
print('Message', msg_id, 'was deleted in', event.chat_id)
"""
@classmethod
def build(cls, update, others=None, self_id=None):
if isinstance(update, types.UpdateDeleteMessages):
return cls.Event(
deleted_ids=update.messages,
peer=None
)
elif isinstance(update, types.UpdateDeleteChannelMessages):
return cls.Event(
deleted_ids=update.messages,
peer=types.PeerChannel(update.channel_id)
)
def _build(cls, client, update, entities):
if isinstance(update, _tl.UpdateDeleteMessages):
peer = None
elif isinstance(update, _tl.UpdateDeleteChannelMessages):
peer = _tl.PeerChannel(update.channel_id)
else:
return None
class Event(EventCommon):
def __init__(self, deleted_ids, peer):
super().__init__(
chat_peer=peer, msg_id=(deleted_ids or [0])[0]
)
self.deleted_id = None if not deleted_ids else deleted_ids[0]
self.deleted_ids = deleted_ids
self = cls.__new__(cls)
self._client = client
self._chat = entities.get(peer)
self.deleted_id = None if not update.messages else update.messages[0]
self.deleted_ids = update.messages
return self

19
telethon/events/messageedited.py → telethon/_events/messageedited.py
View File

@ -1,10 +1,8 @@
from .common import name_inner_event
from .newmessage import NewMessage
from ..tl import types
from .base import EventBuilder
from .. import _tl
@name_inner_event
class MessageEdited(NewMessage):
class MessageEdited(EventBuilder):
"""
Occurs whenever a message is edited. Just like `NewMessage
<telethon.events.newmessage.NewMessage>`, you should treat
@ -43,10 +41,7 @@ class MessageEdited(NewMessage):
print('Message', event.id, 'changed at', event.date)
"""
@classmethod
def build(cls, update, others=None, self_id=None):
if isinstance(update, (types.UpdateEditMessage,
types.UpdateEditChannelMessage)):
return cls.Event(update.message)
class Event(NewMessage.Event):
pass # Required if we want a different name for it
def _build(cls, client, update, entities):
if isinstance(update, (_tl.UpdateEditMessage,
_tl.UpdateEditChannelMessage)):
return cls._new(client, update.message, entities, None)

136
telethon/_events/messageread.py Normal file
View File

@ -0,0 +1,136 @@
from .base import EventBuilder
from .._misc import utils
from .. import _tl
class MessageRead(EventBuilder):
"""
Occurs whenever one or more messages are read in a chat.
Members:
max_id (`int`):
Up to which message ID has been read. Every message
with an ID equal or lower to it have been read.
outbox (`bool`):
`True` if someone else has read your messages.
contents (`bool`):
`True` if what was read were the contents of a message.
This will be the case when e.g. you play a voice note.
It may only be set on ``inbox`` events.
Example
.. code-block:: python
from telethon import events
@client.on(events.MessageRead)
async def handler(event):
# Log when someone reads your messages
print('Someone has read all your messages until', event.max_id)
@client.on(events.MessageRead(inbox=True))
async def handler(event):
# Log when you read message in a chat (from your "inbox")
print('You have read messages until', event.max_id)
"""
def __init__(self, peer=None, max_id=None, out=False, contents=False,
message_ids=None):
self.outbox = out
self.contents = contents
self._message_ids = message_ids or []
self._messages = None
self.max_id = max_id or max(message_ids or [], default=None)
super().__init__(peer, self.max_id)
@classmethod
def _build(cls, client, update, entities):
out = False
contents = False
message_ids = None
if isinstance(update, _tl.UpdateReadHistoryInbox):
peer = update.peer
max_id = update.max_id
out = False
elif isinstance(update, _tl.UpdateReadHistoryOutbox):
peer = update.peer
max_id = update.max_id
out = True
elif isinstance(update, _tl.UpdateReadChannelInbox):
peer = _tl.PeerChannel(update.channel_id)
max_id = update.max_id
out = False
elif isinstance(update, _tl.UpdateReadChannelOutbox):
peer = _tl.PeerChannel(update.channel_id)
max_id = update.max_id
out = True
elif isinstance(update, _tl.UpdateReadMessagesContents):
peer = None
message_ids = update.messages
contents = True
elif isinstance(update, _tl.UpdateChannelReadMessagesContents):
peer = _tl.PeerChannel(update.channel_id)
message_ids = update.messages
contents = True
self = cls.__new__(cls)
self._client = client
self._chat = entities.get(peer)
return self
@property
def inbox(self):
"""
`True` if you have read someone else's messages.
"""
return not self.outbox
@property
def message_ids(self):
"""
The IDs of the messages **which contents'** were read.
Use :meth:`is_read` if you need to check whether a message
was read instead checking if it's in here.
"""
return self._message_ids
async def get_messages(self):
"""
Returns the list of `Message <telethon.tl.custom.message.Message>`
**which contents'** were read.
Use :meth:`is_read` if you need to check whether a message
was read instead checking if it's in here.
"""
if self._messages is None:
chat = await self.get_input_chat()
if not chat:
self._messages = []
else:
self._messages = await self._client.get_messages(
chat, ids=self._message_ids)
return self._messages
def is_read(self, message):
"""
Returns `True` if the given message (or its ID) has been read.
If a list-like argument is provided, this method will return a
list of booleans indicating which messages have been read.
"""
if utils.is_list_like(message):
return [(m if isinstance(m, int) else m.id) <= self.max_id
for m in message]
else:
return (message if isinstance(message, int)
else message.id) <= self.max_id
def __contains__(self, message):
"""`True` if the message(s) are read message."""
if utils.is_list_like(message):
return all(self.is_read(message))
else:
return self.is_read(message)

104
telethon/_events/newmessage.py Normal file
View File

@ -0,0 +1,104 @@
import re
from .base import EventBuilder
from .._misc import utils
from .. import _tl
from ..types import _custom
class NewMessage(EventBuilder, _custom.Message):
"""
Represents the event of a new message. This event can be treated
to all effects as a `Message <telethon.tl.custom.message.Message>`,
so please **refer to its documentation** to know what you can do
with this event.
Members:
message (`Message <telethon.tl.custom.message.Message>`):
This is the only difference with the received
`Message <telethon.tl.custom.message.Message>`, and will
return the `telethon.tl.custom.message.Message` itself,
not the text.
See `Message <telethon.tl.custom.message.Message>` for
the rest of available members and methods.
pattern_match (`obj`):
The resulting object from calling the passed ``pattern`` function.
Here's an example using a string (defaults to regex match):
>>> from telethon import TelegramClient, events
>>> client = TelegramClient(...)
>>>
>>> @client.on(events.NewMessage(pattern=r'hi (\\w+)!'))
... async def handler(event):
... # In this case, the result is a ``Match`` object
... # since the `str` pattern was converted into
... # the ``re.compile(pattern).match`` function.
... print('Welcomed', event.pattern_match.group(1))
...
>>>
Example
.. code-block:: python
import asyncio
from telethon import events
@client.on(events.NewMessage(pattern='(?i)hello.+'))
async def handler(event):
# Respond whenever someone says "Hello" and something else
await event.reply('Hey!')
@client.on(events.NewMessage(outgoing=True, pattern='!ping'))
async def handler(event):
# Say "!pong" whenever you send "!ping", then delete both messages
m = await event.respond('!pong')
await asyncio.sleep(5)
await client.delete_messages(event.chat_id, [event.id, m.id])
"""
@classmethod
def _build(cls, client, update, entities):
if isinstance(update,
(_tl.UpdateNewMessage, _tl.UpdateNewChannelMessage)):
if not isinstance(update.message, _tl.Message):
return # We don't care about MessageService's here
msg = update.message
elif isinstance(update, _tl.UpdateShortMessage):
msg = _tl.Message(
out=update.out,
mentioned=update.mentioned,
media_unread=update.media_unread,
silent=update.silent,
id=update.id,
peer_id=_tl.PeerUser(update.user_id),
from_id=_tl.PeerUser(self_id if update.out else update.user_id),
message=update.message,
date=update.date,
fwd_from=update.fwd_from,
via_bot_id=update.via_bot_id,
reply_to=update.reply_to,
entities=update.entities,
ttl_period=update.ttl_period
)
elif isinstance(update, _tl.UpdateShortChatMessage):
msg = _tl.Message(
out=update.out,
mentioned=update.mentioned,
media_unread=update.media_unread,
silent=update.silent,
id=update.id,
from_id=_tl.PeerUser(self_id if update.out else update.from_id),
peer_id=_tl.PeerChat(update.chat_id),
message=update.message,
date=update.date,
fwd_from=update.fwd_from,
via_bot_id=update.via_bot_id,
reply_to=update.reply_to,
entities=update.entities,
ttl_period=update.ttl_period
)
else:
return
return cls._new(client, msg, entities, None)

23
telethon/_events/raw.py Normal file
View File

@ -0,0 +1,23 @@
from .base import EventBuilder
from .._misc import utils
class Raw(EventBuilder):
"""
Raw events are not actual events. Instead, they are the raw
:tl:`Update` object that Telegram sends. You normally shouldn't
need these.
Example
.. code-block:: python
from telethon import events
@client.on(events.Raw)
async def handler(update):
# Print all incoming updates
print(update.stringify())
"""
@classmethod
def _build(cls, client, update, entities):
return update

301
telethon/_events/userupdate.py Normal file
View File

@ -0,0 +1,301 @@
import datetime
import functools
from .base import EventBuilder
from .._misc import utils
from .. import _tl
from ..types import _custom
# TODO Either the properties are poorly named or they should be
# different events, but that would be a breaking change.
#
# TODO There are more "user updates", but bundling them all up
# in a single place will make it annoying to use (since
# the user needs to check for the existence of `None`).
#
# TODO Handle UpdateUserBlocked, UpdateUserName, UpdateUserPhone, UpdateUserPhoto
def _requires_action(function):
@functools.wraps(function)
def wrapped(self):
return None if self.action is None else function(self)
return wrapped
def _requires_status(function):
@functools.wraps(function)
def wrapped(self):
return None if self.status is None else function(self)
return wrapped
class UserUpdate(EventBuilder, _custom.chatgetter.ChatGetter, _custom.sendergetter.SenderGetter):
"""
Occurs whenever a user goes online, starts typing, etc.
Members:
status (:tl:`UserStatus`, optional):
The user status if the update is about going online or offline.
You should check this attribute first before checking any
of the seen within properties, since they will all be `None`
if the status is not set.
action (:tl:`SendMessageAction`, optional):
The "typing" action if any the user is performing if any.
You should check this attribute first before checking any
of the typing properties, since they will all be `None`
if the action is not set.
Example
.. code-block:: python
from telethon import events
@client.on(events.UserUpdate)
async def handler(event):
# If someone is uploading, say something
if event.uploading:
await client.send_message(event.user_id, 'What are you sending?')
"""
@classmethod
def _build(cls, client, update, entities):
chat_peer = None
status = None
if isinstance(update, _tl.UpdateUserStatus):
peer = _tl.PeerUser(update.user_id)
status = update.status
typing = None
elif isinstance(update, _tl.UpdateChannelUserTyping):
peer = update.from_id
chat_peer = _tl.PeerChannel(update.channel_id)
typing = update.action
elif isinstance(update, _tl.UpdateChatUserTyping):
peer = update.from_id
chat_peer = _tl.PeerChat(update.chat_id)
typing = update.action
elif isinstance(update, _tl.UpdateUserTyping):
peer = update.user_id
typing = update.action
else:
return None
self = cls.__new__(cls)
self._client = client
self._sender = entities.get(peer)
self._chat = entities.get(chat_peer or peer)
self.status = status
self.action = typing
return self
@property
def user(self):
"""Alias for `sender <telethon.tl.custom.sendergetter.SenderGetter.sender>`."""
return self.sender
async def get_user(self):
"""Alias for `get_sender <telethon.tl.custom.sendergetter.SenderGetter.get_sender>`."""
return await self.get_sender()
@property
def input_user(self):
"""Alias for `input_sender <telethon.tl.custom.sendergetter.SenderGetter.input_sender>`."""
return self.input_sender
@property
def user_id(self):
"""Alias for `sender_id <telethon.tl.custom.sendergetter.SenderGetter.sender_id>`."""
return self.sender_id
@property
@_requires_action
def typing(self):
"""
`True` if the action is typing a message.
"""
return isinstance(self.action, _tl.SendMessageTypingAction)
@property
@_requires_action
def uploading(self):
"""
`True` if the action is uploading something.
"""
return isinstance(self.action, (
_tl.SendMessageChooseContactAction,
_tl.SendMessageChooseStickerAction,
_tl.SendMessageUploadAudioAction,
_tl.SendMessageUploadDocumentAction,
_tl.SendMessageUploadPhotoAction,
_tl.SendMessageUploadRoundAction,
_tl.SendMessageUploadVideoAction
))
@property
@_requires_action
def recording(self):
"""
`True` if the action is recording something.
"""
return isinstance(self.action, (
_tl.SendMessageRecordAudioAction,
_tl.SendMessageRecordRoundAction,
_tl.SendMessageRecordVideoAction
))
@property
@_requires_action
def playing(self):
"""
`True` if the action is playing a game.
"""
return isinstance(self.action, _tl.SendMessageGamePlayAction)
@property
@_requires_action
def cancel(self):
"""
`True` if the action was cancelling other actions.
"""
return isinstance(self.action, _tl.SendMessageCancelAction)
@property
@_requires_action
def geo(self):
"""
`True` if what's being uploaded is a geo.
"""
return isinstance(self.action, _tl.SendMessageGeoLocationAction)
@property
@_requires_action
def audio(self):
"""
`True` if what's being recorded/uploaded is an audio.
"""
return isinstance(self.action, (
_tl.SendMessageRecordAudioAction,
_tl.SendMessageUploadAudioAction
))
@property
@_requires_action
def round(self):
"""
`True` if what's being recorded/uploaded is a round video.
"""
return isinstance(self.action, (
_tl.SendMessageRecordRoundAction,
_tl.SendMessageUploadRoundAction
))
@property
@_requires_action
def video(self):
"""
`True` if what's being recorded/uploaded is an video.
"""
return isinstance(self.action, (
_tl.SendMessageRecordVideoAction,
_tl.SendMessageUploadVideoAction
))
@property
@_requires_action
def contact(self):
"""
`True` if what's being uploaded (selected) is a contact.
"""
return isinstance(self.action, _tl.SendMessageChooseContactAction)
@property
@_requires_action
def document(self):
"""
`True` if what's being uploaded is document.
"""
return isinstance(self.action, _tl.SendMessageUploadDocumentAction)
@property
@_requires_action
def sticker(self):
"""
`True` if what's being uploaded is a sticker.
"""
return isinstance(self.action, _tl.SendMessageChooseStickerAction)
@property
@_requires_action
def photo(self):
"""
`True` if what's being uploaded is a photo.
"""
return isinstance(self.action, _tl.SendMessageUploadPhotoAction)
@property
@_requires_action
def last_seen(self):
"""
Exact `datetime.datetime` when the user was last seen if known.
"""
if isinstance(self.status, _tl.UserStatusOffline):
return self.status.was_online
@property
@_requires_status
def until(self):
"""
The `datetime.datetime` until when the user should appear online.
"""
if isinstance(self.status, _tl.UserStatusOnline):
return self.status.expires
def _last_seen_delta(self):
if isinstance(self.status, _tl.UserStatusOffline):
return datetime.datetime.now(tz=datetime.timezone.utc) - self.status.was_online
elif isinstance(self.status, _tl.UserStatusOnline):
return datetime.timedelta(days=0)
elif isinstance(self.status, _tl.UserStatusRecently):
return datetime.timedelta(days=1)
elif isinstance(self.status, _tl.UserStatusLastWeek):
return datetime.timedelta(days=7)
elif isinstance(self.status, _tl.UserStatusLastMonth):
return datetime.timedelta(days=30)
else:
return datetime.timedelta(days=365)
@property
@_requires_status
def online(self):
"""
`True` if the user is currently online,
"""
return self._last_seen_delta() <= datetime.timedelta(days=0)
@property
@_requires_status
def recently(self):
"""
`True` if the user was seen within a day.
"""
return self._last_seen_delta() <= datetime.timedelta(days=1)
@property
@_requires_status
def within_weeks(self):
"""
`True` if the user was seen within 7 days.
"""
return self._last_seen_delta() <= datetime.timedelta(days=7)
@property
@_requires_status
def within_months(self):
"""
`True` if the user was seen within 30 days.
"""
return self._last_seen_delta() <= datetime.timedelta(days=30)

1
telethon/extensions/__init__.py → telethon/_misc/__init__.py
View File

@ -3,4 +3,3 @@ Several extensions Python is missing, such as a proper class to handle a TCP
communication with support for cancelling the operation, and a utility class
to read arbitrary binary data in a more comfortable way, with int/strings/etc.
"""
from .binaryreader import BinaryReader

12
telethon/extensions/binaryreader.py → telethon/_misc/binaryreader.py
View File

@ -7,9 +7,9 @@ from datetime import datetime, timezone, timedelta
from io import BytesIO
from struct import unpack
from ..errors import TypeNotFoundError
from ..tl.alltlobjects import tlobjects
from ..tl.core import core_objects
from ..errors._custom import TypeNotFoundError
from .. import _tl
from ..types import _core
_EPOCH_NAIVE = datetime(*time.gmtime(0)[:6])
_EPOCH = _EPOCH_NAIVE.replace(tzinfo=timezone.utc)
@ -118,7 +118,7 @@ class BinaryReader:
def tgread_object(self):
"""Reads a Telegram object."""
constructor_id = self.read_int(signed=False)
clazz = tlobjects.get(constructor_id, None)
clazz = _tl.tlobjects.get(constructor_id, None)
if clazz is None:
# The class was None, but there's still a
# chance of it being a manually parsed value like bool!
@ -130,7 +130,7 @@ class BinaryReader:
elif value == 0x1cb5c415: # Vector
return [self.tgread_object() for _ in range(self.read_int())]
clazz = core_objects.get(constructor_id, None)
clazz = _core.core_objects.get(constructor_id, None)
if clazz is None:
# If there was still no luck, give up
self.seek(-4) # Go back
@ -139,7 +139,7 @@ class BinaryReader:
self.set_position(pos)
raise error
return clazz.from_reader(self)
return clazz._from_reader(self)
def tgread_vector(self):
"""Reads a vector (a list) of Telegram objects."""

131
telethon/_misc/enums.py Normal file
View File

@ -0,0 +1,131 @@
from enum import Enum
def _impl_op(which):
def op(self, other):
if not isinstance(other, type(self)):
return NotImplemented
return getattr(self._val(), which)(other._val())
return op
class ConnectionMode(Enum):
FULL = 'full'
INTERMEDIATE = 'intermediate'
ABRIDGED = 'abridged'
class Participant(Enum):
ADMIN = 'admin'
BOT = 'bot'
KICKED = 'kicked'
BANNED = 'banned'
CONTACT = 'contact'
class Action(Enum):
TYPING = 'typing'
CONTACT = 'contact'
GAME = 'game'
LOCATION = 'location'
STICKER = 'sticker'
RECORD_AUDIO = 'record-audio'
RECORD_VOICE = RECORD_AUDIO
RECORD_ROUND = 'record-round'
RECORD_VIDEO = 'record-video'
AUDIO = 'audio'
VOICE = AUDIO
SONG = AUDIO
ROUND = 'round'
VIDEO = 'video'
PHOTO = 'photo'
DOCUMENT = 'document'
FILE = DOCUMENT
CANCEL = 'cancel'
class Size(Enum):
"""
See https://core.telegram.org/api/files#image-thumbnail-types.
* ``'s'``. The image fits within a box of 100x100.
* ``'m'``. The image fits within a box of 320x320.
* ``'x'``. The image fits within a box of 800x800.
* ``'y'``. The image fits within a box of 1280x1280.
* ``'w'``. The image fits within a box of 2560x2560.
* ``'a'``. The image was cropped to be at most 160x160.
* ``'b'``. The image was cropped to be at most 320x320.
* ``'c'``. The image was cropped to be at most 640x640.
* ``'d'``. The image was cropped to be at most 1280x1280.
* ``'i'``. The image comes inline (no need to download anything).
* ``'j'``. Only the image outline is present (for stickers).
* ``'u'``. The image is actually a short MPEG4 animated video.
* ``'v'``. The image is actually a short MPEG4 video preview.
The sorting order is first dimensions, then ``cropped < boxed < video < other``.
"""
SMALL = 's'
MEDIUM = 'm'
LARGE = 'x'
EXTRA_LARGE = 'y'
ORIGINAL = 'w'
CROPPED_SMALL = 'a'
CROPPED_MEDIUM = 'b'
CROPPED_LARGE = 'c'
CROPPED_EXTRA_LARGE = 'd'
INLINE = 'i'
OUTLINE = 'j'
ANIMATED = 'u'
VIDEO = 'v'
def __hash__(self):
return object.__hash__(self)
__sub__ = _impl_op('__sub__')
__lt__ = _impl_op('__lt__')
__le__ = _impl_op('__le__')
__eq__ = _impl_op('__eq__')
__ne__ = _impl_op('__ne__')
__gt__ = _impl_op('__gt__')
__ge__ = _impl_op('__ge__')
def _val(self):
return self._category() * 100 + self._size()
def _category(self):
return {
Size.SMALL: 2,
Size.MEDIUM: 2,
Size.LARGE: 2,
Size.EXTRA_LARGE: 2,
Size.ORIGINAL: 2,
Size.CROPPED_SMALL: 1,
Size.CROPPED_MEDIUM: 1,
Size.CROPPED_LARGE: 1,
Size.CROPPED_EXTRA_LARGE: 1,
Size.INLINE: 4,
Size.OUTLINE: 5,
Size.ANIMATED: 3,
Size.VIDEO: 3,
}[self]
def _size(self):
return {
Size.SMALL: 1,
Size.MEDIUM: 3,
Size.LARGE: 5,
Size.EXTRA_LARGE: 6,
Size.ORIGINAL: 7,
Size.CROPPED_SMALL: 2,
Size.CROPPED_MEDIUM: 3,
Size.CROPPED_LARGE: 4,
Size.CROPPED_EXTRA_LARGE: 6,
# 0, since they're not the original photo at all
Size.INLINE: 0,
Size.OUTLINE: 0,
# same size as original or extra large (videos are large)
Size.ANIMATED: 7,
Size.VIDEO: 6,
}[self]

113
telethon/helpers.py → telethon/_misc/helpers.py
View File

@ -102,23 +102,11 @@ def strip_text(text, entities):
return text
def retry_range(retries, force_retry=True):
def retry_range(retries):
"""
Generates an integer sequence starting from 1. If `retries` is
not a zero or a positive integer value, the sequence will be
infinite, otherwise it will end at `retries + 1`.
Generates an integer sequence starting from 1, always returning once, and adding the given retries.
"""
# We need at least one iteration even if the retries are 0
# when force_retry is True.
if force_retry and not (retries is None or retries < 0):
retries += 1
attempt = 0
while attempt != retries:
attempt += 1
yield attempt
return range(1, max(retries, 0) + 2)
async def _maybe_await(value):
@ -165,34 +153,6 @@ async def _cancel(log, **tasks):
'%s (%s)', name, type(task), task)
def _sync_enter(self):
"""
Helps to cut boilerplate on async context
managers that offer synchronous variants.
"""
if hasattr(self, 'loop'):
loop = self.loop
else:
loop = self._client.loop
if loop.is_running():
raise RuntimeError(
'You must use "async with" if the event loop '
'is running (i.e. you are inside an "async def")'
)
return loop.run_until_complete(self.__aenter__())
def _sync_exit(self, *args):
if hasattr(self, 'loop'):
loop = self.loop
else:
loop = self._client.loop
return loop.run_until_complete(self.__aexit__(*args))
def _entity_type(entity):
# This could be a `utils` method that just ran a few `isinstance` on
# `utils.get_peer(...)`'s result. However, there are *a lot* of auto
@ -228,6 +188,73 @@ def _entity_type(entity):
# 'Empty' in name or not found, we don't care, not a valid entity.
raise TypeError('{} does not have any entity type'.format(entity))
def pretty_print(obj, indent=None, max_depth=float('inf')):
max_depth -= 1
if max_depth < 0:
return '...'
to_d = getattr(obj, 'to_dict', None)
if callable(to_d):
obj = to_d()
if indent is None:
if isinstance(obj, dict):
return '{}({})'.format(obj.get('_', 'dict'), ', '.join(
'{}={}'.format(k, pretty_print(v, indent, max_depth))
for k, v in obj.items() if k != '_'
))
elif isinstance(obj, str) or isinstance(obj, bytes):
return repr(obj)
elif hasattr(obj, '__iter__'):
return '[{}]'.format(
', '.join(pretty_print(x, indent, max_depth) for x in obj)
)
else:
return repr(obj)
else:
result = []
if isinstance(obj, dict):
result.append(obj.get('_', 'dict'))
result.append('(')
if obj:
result.append('\n')
indent += 1
for k, v in obj.items():
if k == '_':
continue
result.append('\t' * indent)
result.append(k)
result.append('=')
result.append(pretty_print(v, indent, max_depth))
result.append(',\n')
result.pop() # last ',\n'
indent -= 1
result.append('\n')
result.append('\t' * indent)
result.append(')')
elif isinstance(obj, str) or isinstance(obj, bytes):
result.append(repr(obj))
elif hasattr(obj, '__iter__'):
result.append('[\n')
indent += 1
for x in obj:
result.append('\t' * indent)
result.append(pretty_print(x, indent, max_depth))
result.append(',\n')
indent -= 1
result.append('\t' * indent)
result.append(']')
else:
result.append(repr(obj))
return ''.join(result)
# endregion
# region Cryptographic related utils

60
telethon/_misc/hints.py Normal file
View File

@ -0,0 +1,60 @@
import datetime
import typing
from . import helpers
from .. import _tl
from ..types import _custom
Phone = str
Username = str
PeerID = int
Dialog = typing.Union[_tl.User, _tl.Chat, _tl.Channel]
FullDialog = typing.Union[_tl.UserFull, _tl.messages.ChatFull, _tl.ChatFull, _tl.ChannelFull]
DialogLike = typing.Union[
Phone,
Username,
PeerID,
_tl.TypePeer,
_tl.TypeInputPeer,
Dialog,
FullDialog
]
DialogsLike = typing.Union[DialogLike, typing.Sequence[DialogLike]]
ButtonLike = typing.Union[_tl.TypeKeyboardButton, _custom.Button]
MarkupLike = typing.Union[
_tl.TypeReplyMarkup,
ButtonLike,
typing.Sequence[ButtonLike],
typing.Sequence[typing.Sequence[ButtonLike]]
]
TotalList = helpers.TotalList
DateLike = typing.Optional[typing.Union[float, datetime.datetime, datetime.date, datetime.timedelta]]
LocalPath = str
ExternalUrl = str
BotFileID = str
FileLike = typing.Union[
LocalPath,
ExternalUrl,
BotFileID,
bytes,
typing.BinaryIO,
_tl.TypeMessageMedia,
_tl.TypeInputFile,
_tl.TypeInputFileLocation
]
OutFileLike = typing.Union[
str,
typing.Type[bytes],
typing.BinaryIO
]
MessageLike = typing.Union[str, _tl.Message]
MessageIDLike = typing.Union[int, _tl.Message, _tl.TypeInputMessage]
ProgressCallback = typing.Callable[[int, int], None]

64
telethon/extensions/html.py → telethon/_misc/html.py
View File

@ -7,14 +7,8 @@ from html import escape
from html.parser import HTMLParser
from typing import Iterable, Optional, Tuple, List
from .. import helpers
from ..tl.types import (
MessageEntityBold, MessageEntityItalic, MessageEntityCode,
MessageEntityPre, MessageEntityEmail, MessageEntityUrl,
MessageEntityTextUrl, MessageEntityMentionName,
MessageEntityUnderline, MessageEntityStrike, MessageEntityBlockquote,
TypeMessageEntity
)
from .._misc import helpers
from .. import _tl
# Helpers from markdown.py
@ -46,15 +40,17 @@ class HTMLToTelegramParser(HTMLParser):
EntityType = None
args = {}
if tag == 'strong' or tag == 'b':
EntityType = MessageEntityBold
EntityType = _tl.MessageEntityBold
elif tag == 'em' or tag == 'i':
EntityType = MessageEntityItalic
EntityType = _tl.MessageEntityItalic
elif tag == 'u':
EntityType = MessageEntityUnderline
EntityType = _tl.MessageEntityUnderline
elif tag == 'del' or tag == 's':
EntityType = MessageEntityStrike
EntityType = _tl.MessageEntityStrike
elif tag == 'tg-spoiler':
EntityType = _tl.MessageEntitySpoiler
elif tag == 'blockquote':
EntityType = MessageEntityBlockquote
EntityType = _tl.MessageEntityBlockquote
elif tag == 'code':
try:
# If we're in the middle of a <pre> tag, this <code> tag is
@ -69,9 +65,9 @@ class HTMLToTelegramParser(HTMLParser):
except KeyError:
pass
except KeyError:
EntityType = MessageEntityCode
EntityType = _tl.MessageEntityCode
elif tag == 'pre':
EntityType = MessageEntityPre
EntityType = _tl.MessageEntityPre
args['language'] = ''
elif tag == 'a':
try:
@ -80,12 +76,12 @@ class HTMLToTelegramParser(HTMLParser):
return
if url.startswith('mailto:'):
url = url[len('mailto:'):]
EntityType = MessageEntityEmail
EntityType = _tl.MessageEntityEmail
else:
if self.get_starttag_text() == url:
EntityType = MessageEntityUrl
EntityType = _tl.MessageEntityUrl
else:
EntityType = MessageEntityTextUrl
EntityType = _tl.MessageEntityTextUrl
args['url'] = url
url = None
self._open_tags_meta.popleft()
@ -121,10 +117,10 @@ class HTMLToTelegramParser(HTMLParser):
self.entities.append(entity)
def parse(html: str) -> Tuple[str, List[TypeMessageEntity]]:
def parse(html: str) -> Tuple[str, List[_tl.TypeMessageEntity]]:
"""
Parses the given HTML message and returns its stripped representation
plus a list of the MessageEntity's that were found.
plus a list of the _tl.MessageEntity's that were found.
:param html: the message with HTML to be parsed.
:return: a tuple consisting of (clean message, [message entities]).
@ -138,14 +134,14 @@ def parse(html: str) -> Tuple[str, List[TypeMessageEntity]]:
return _del_surrogate(text), parser.entities
def unparse(text: str, entities: Iterable[TypeMessageEntity], _offset: int = 0,
def unparse(text: str, entities: Iterable[_tl.TypeMessageEntity], _offset: int = 0,
_length: Optional[int] = None) -> str:
"""
Performs the reverse operation to .parse(), effectively returning HTML
given a normal text and its MessageEntity's.
given a normal text and its _tl.MessageEntity's.
:param text: the text to be reconverted into HTML.
:param entities: the MessageEntity's applied to the text.
:param entities: the _tl.MessageEntity's applied to the text.
:return: a HTML representation of the combination of both inputs.
"""
if not text:
@ -185,19 +181,19 @@ def unparse(text: str, entities: Iterable[TypeMessageEntity], _offset: int = 0,
_offset=entity.offset, _length=length)
entity_type = type(entity)
if entity_type == MessageEntityBold:
if entity_type == _tl.MessageEntityBold:
html.append('<strong>{}</strong>'.format(entity_text))
elif entity_type == MessageEntityItalic:
elif entity_type == _tl.MessageEntityItalic:
html.append('<em>{}</em>'.format(entity_text))
elif entity_type == MessageEntityCode:
elif entity_type == _tl.MessageEntityCode:
html.append('<code>{}</code>'.format(entity_text))
elif entity_type == MessageEntityUnderline:
elif entity_type == _tl.MessageEntityUnderline:
html.append('<u>{}</u>'.format(entity_text))
elif entity_type == MessageEntityStrike:
elif entity_type == _tl.MessageEntityStrike:
html.append('<del>{}</del>'.format(entity_text))
elif entity_type == MessageEntityBlockquote:
elif entity_type == _tl.MessageEntityBlockquote:
html.append('<blockquote>{}</blockquote>'.format(entity_text))
elif entity_type == MessageEntityPre:
elif entity_type == _tl.MessageEntityPre:
if entity.language:
html.append(
"<pre>\n"
@ -208,14 +204,14 @@ def unparse(text: str, entities: Iterable[TypeMessageEntity], _offset: int = 0,
else:
html.append('<pre><code>{}</code></pre>'
.format(entity_text))
elif entity_type == MessageEntityEmail:
elif entity_type == _tl.MessageEntityEmail:
html.append('<a href="mailto:{0}">{0}</a>'.format(entity_text))
elif entity_type == MessageEntityUrl:
elif entity_type == _tl.MessageEntityUrl:
html.append('<a href="{0}">{0}</a>'.format(entity_text))
elif entity_type == MessageEntityTextUrl:
elif entity_type == _tl.MessageEntityTextUrl:
html.append('<a href="{}">{}</a>'
.format(escape(entity.url), entity_text))
elif entity_type == MessageEntityMentionName:
elif entity_type == _tl.MessageEntityMentionName:
html.append('<a href="tg://user?id={}">{}</a>'
.format(entity.user_id, entity_text))
else:

169
telethon/_misc/markdown.py Normal file
View File

@ -0,0 +1,169 @@
"""
Simple markdown parser which does not support nesting. Intended primarily
for use within the library, which attempts to handle emojies correctly,
since they seem to count as two characters and it's a bit strange.
"""
import re
import warnings
import markdown_it
from .helpers import add_surrogate, del_surrogate, within_surrogate, strip_text
from .. import _tl
from .._misc import tlobject
MARKDOWN = markdown_it.MarkdownIt().enable('strikethrough')
DELIMITERS = {
_tl.MessageEntityBlockquote: ('> ', ''),
_tl.MessageEntityBold: ('**', '**'),
_tl.MessageEntityCode: ('`', '`'),
_tl.MessageEntityItalic: ('_', '_'),
_tl.MessageEntityStrike: ('~~', '~~'),
_tl.MessageEntitySpoiler: ('||', '||'),
_tl.MessageEntityUnderline: ('# ', ''),
}
# Not trying to be complete; just enough to have an alternative (mostly for inline underline).
# The fact headings are treated as underline is an implementation detail.
TAG_PATTERN = re.compile(r'<\s*(/?)\s*(\w+)')
HTML_TO_TYPE = {
'i': ('em_close', 'em_open'),
'em': ('em_close', 'em_open'),
'b': ('strong_close', 'strong_open'),
'strong': ('strong_close', 'strong_open'),
's': ('s_close', 's_open'),
'del': ('s_close', 's_open'),
'u': ('heading_open', 'heading_close'),
'mark': ('heading_open', 'heading_close'),
}
def expand_inline_and_html(tokens):
for token in tokens:
if token.type == 'inline':
yield from expand_inline_and_html(token.children)
elif token.type == 'html_inline':
match = TAG_PATTERN.match(token.content)
if match:
close, tag = match.groups()
tys = HTML_TO_TYPE.get(tag.lower())
if tys:
token.type = tys[bool(close)]
token.nesting = -1 if close else 1
yield token
else:
yield token
def parse(message):
"""
Parses the given markdown message and returns its stripped representation
plus a list of the _tl.MessageEntity's that were found.
"""
if not message:
return message, []
def push(ty, **extra):
nonlocal message, entities, token
if token.nesting > 0:
entities.append(ty(offset=len(message), length=0, **extra))
else:
for entity in reversed(entities):
if isinstance(entity, ty):
entity.length = len(message) - entity.offset
break
parsed = MARKDOWN.parse(add_surrogate(message.strip()))
message = ''
entities = []
last_map = [0, 0]
for token in expand_inline_and_html(parsed):
if token.map is not None and token.map != last_map:
# paragraphs, quotes fences have a line mapping. Use it to determine how many newlines to insert.
# But don't inssert any (leading) new lines if we're yet to reach the first textual content, or
# if the mappings are the same (e.g. a quote then opens a paragraph but the mapping is equal).
if message:
message += '\n' + '\n' * (token.map[0] - last_map[-1])
last_map = token.map
if token.type in ('blockquote_close', 'blockquote_open'):
push(_tl.MessageEntityBlockquote)
elif token.type == 'code_block':
entities.append(_tl.MessageEntityPre(offset=len(message), length=len(token.content), language=''))
message += token.content
elif token.type == 'code_inline':
entities.append(_tl.MessageEntityCode(offset=len(message), length=len(token.content)))
message += token.content
elif token.type in ('em_close', 'em_open'):
push(_tl.MessageEntityItalic)
elif token.type == 'fence':
entities.append(_tl.MessageEntityPre(offset=len(message), length=len(token.content), language=token.info))
message += token.content[:-1] # remove a single trailing newline
elif token.type == 'hardbreak':
message += '\n'
elif token.type in ('heading_close', 'heading_open'):
push(_tl.MessageEntityUnderline)
elif token.type == 'hr':
message += '\u2015\n\n'
elif token.type in ('link_close', 'link_open'):
if token.markup != 'autolink': # telegram already picks up on these automatically
push(_tl.MessageEntityTextUrl, url=token.attrs.get('href'))
elif token.type in ('s_close', 's_open'):
push(_tl.MessageEntityStrike)
elif token.type == 'softbreak':
message += ' '
elif token.type in ('strong_close', 'strong_open'):
push(_tl.MessageEntityBold)
elif token.type == 'text':
message += token.content
return del_surrogate(message), entities
def unparse(text, entities):
"""
Performs the reverse operation to .parse(), effectively returning
markdown-like syntax given a normal text and its _tl.MessageEntity's.
Because there are many possible ways for markdown to produce a certain
output, this function cannot invert .parse() perfectly.
"""
if not text or not entities:
return text
if isinstance(entities, tlobject.TLObject):
entities = (entities,)
text = add_surrogate(text)
insert_at = []
for entity in entities:
s = entity.offset
e = entity.offset + entity.length
delimiter = DELIMITERS.get(type(entity), None)
if delimiter:
insert_at.append((s, delimiter[0]))
insert_at.append((e, delimiter[1]))
elif isinstance(entity, _tl.MessageEntityPre):
insert_at.append((s, f'```{entity.language}\n'))
insert_at.append((e, '```\n'))
elif isinstance(entity, _tl.MessageEntityTextUrl):
insert_at.append((s, '['))
insert_at.append((e, f']({entity.url})'))
elif isinstance(entity, _tl.MessageEntityMentionName):
insert_at.append((s, '['))
insert_at.append((e, f'](tg://user?id={entity.user_id})'))
insert_at.sort(key=lambda t: t[0])
while insert_at:
at, what = insert_at.pop()
# If we are in the middle of a surrogate nudge the position by -1.
# Otherwise we would end up with malformed text and fail to encode.
# For example of bad input: "Hi \ud83d\ude1c"
# https://en.wikipedia.org/wiki/UTF-16#U+010000_to_U+10FFFF
while within_surrogate(text, at):
at += 1
text = text[:at] + what + text[at:]
return del_surrogate(text)

5
telethon/extensions/messagepacker.py → telethon/_misc/messagepacker.py
View File

@ -3,9 +3,8 @@ import collections
import io
import struct
from ..tl import TLRequest
from ..tl.core.messagecontainer import MessageContainer
from ..tl.core.tlmessage import TLMessage
from .._tl import TLRequest
from ..types._core import MessageContainer, TLMessage
class MessagePacker:

14
telethon/password.py → telethon/_misc/password.py
View File

@ -1,8 +1,8 @@
import hashlib
import os
from .crypto import factorization
from .tl import types
from .._crypto import factorization
from .. import _tl
def check_prime_and_good_check(prime: int, g: int):
@ -110,7 +110,7 @@ def pbkdf2sha512(password: bytes, salt: bytes, iterations: int):
return hashlib.pbkdf2_hmac('sha512', password, salt, iterations)
def compute_hash(algo: types.PasswordKdfAlgoSHA256SHA256PBKDF2HMACSHA512iter100000SHA256ModPow,
def compute_hash(algo: _tl.PasswordKdfAlgoSHA256SHA256PBKDF2HMACSHA512iter100000SHA256ModPow,
password: str):
hash1 = sha256(algo.salt1, password.encode('utf-8'), algo.salt1)
hash2 = sha256(algo.salt2, hash1, algo.salt2)
@ -118,7 +118,7 @@ def compute_hash(algo: types.PasswordKdfAlgoSHA256SHA256PBKDF2HMACSHA512iter1000
return sha256(algo.salt2, hash3, algo.salt2)
def compute_digest(algo: types.PasswordKdfAlgoSHA256SHA256PBKDF2HMACSHA512iter100000SHA256ModPow,
def compute_digest(algo: _tl.PasswordKdfAlgoSHA256SHA256PBKDF2HMACSHA512iter100000SHA256ModPow,
password: str):
try:
check_prime_and_good(algo.p, algo.g)
@ -133,9 +133,9 @@ def compute_digest(algo: types.PasswordKdfAlgoSHA256SHA256PBKDF2HMACSHA512iter10
# https://github.com/telegramdesktop/tdesktop/blob/18b74b90451a7db2379a9d753c9cbaf8734b4d5d/Telegram/SourceFiles/core/core_cloud_password.cpp
def compute_check(request: types.account.Password, password: str):
def compute_check(request: _tl.account.Password, password: str):
algo = request.current_algo
if not isinstance(algo, types.PasswordKdfAlgoSHA256SHA256PBKDF2HMACSHA512iter100000SHA256ModPow):
if not isinstance(algo, _tl.PasswordKdfAlgoSHA256SHA256PBKDF2HMACSHA512iter100000SHA256ModPow):
raise ValueError('unsupported password algorithm {}'
.format(algo.__class__.__name__))
@ -190,5 +190,5 @@ def compute_check(request: types.account.Password, password: str):
K
)
return types.InputCheckPasswordSRP(
return _tl.InputCheckPasswordSRP(
request.srp_id, bytes(a_for_hash), bytes(M1))

35
telethon/requestiter.py → telethon/_misc/requestiter.py
View File

@ -12,9 +12,6 @@ class RequestIter(abc.ABC):
It has some facilities, such as automatically sleeping a desired
amount of time between requests if needed (but not more).
Can be used synchronously if the event loop is not running and
as an asynchronous iterator otherwise.
`limit` is the total amount of items that the iterator should return.
This is handled on this base class, and will be always ``>= 0``.
@ -31,12 +28,13 @@ class RequestIter(abc.ABC):
self.reverse = reverse
self.wait_time = wait_time
self.kwargs = kwargs
self.limit = max(float('inf') if limit is None else limit, 0)
self.limit = max(float('inf') if limit is None or limit == () else limit, 0)
self.left = self.limit
self.buffer = None
self.index = 0
self.total = None
self.last_load = 0
self.return_single = limit == 1 or limit == ()
async def _init(self, **kwargs):
"""
@ -82,12 +80,6 @@ class RequestIter(abc.ABC):
self.index += 1
return result
def __next__(self):
try:
return self.client.loop.run_until_complete(self.__anext__())
except StopAsyncIteration:
raise StopIteration
def __aiter__(self):
self.buffer = None
self.index = 0
@ -95,20 +87,20 @@ class RequestIter(abc.ABC):
self.left = self.limit
return self
def __iter__(self):
if self.client.loop.is_running():
raise RuntimeError(
'You must use "async for" if the event loop '
'is running (i.e. you are inside an "async def")'
)
return self.__aiter__()
async def collect(self):
async def collect(self, force_list=True):
"""
Create a `self` iterator and collect it into a `TotalList`
(a normal list with a `.total` attribute).
If ``force_list`` is ``False`` and ``self.return_single`` is ``True``, no list
will be returned. Instead, either a single item or ``None`` will be returned.
"""
if not force_list and self.return_single:
self.limit = 1
async for message in self:
return message
return None
result = helpers.TotalList()
async for message in self:
result.append(message)
@ -132,3 +124,6 @@ class RequestIter(abc.ABC):
def __reversed__(self):
self.reverse = not self.reverse
return self # __aiter__ will be called after, too
def __await__(self):
return self.collect(force_list=False).__await__()

122
telethon/tl/tlobject.py → telethon/_misc/tlobject.py
View File

@ -3,6 +3,7 @@ import json
import struct
from datetime import datetime, date, timedelta, timezone
import time
from .helpers import pretty_print
_EPOCH_NAIVE = datetime(*time.gmtime(0)[:6])
_EPOCH_NAIVE_LOCAL = datetime(*time.localtime(0)[:6])
@ -32,78 +33,12 @@ def _json_default(value):
class TLObject:
__slots__ = ()
CONSTRUCTOR_ID = None
SUBCLASS_OF_ID = None
@staticmethod
def pretty_format(obj, indent=None):
"""
Pretty formats the given object as a string which is returned.
If indent is None, a single line will be returned.
"""
if indent is None:
if isinstance(obj, TLObject):
obj = obj.to_dict()
if isinstance(obj, dict):
return '{}({})'.format(obj.get('_', 'dict'), ', '.join(
'{}={}'.format(k, TLObject.pretty_format(v))
for k, v in obj.items() if k != '_'
))
elif isinstance(obj, str) or isinstance(obj, bytes):
return repr(obj)
elif hasattr(obj, '__iter__'):
return '[{}]'.format(
', '.join(TLObject.pretty_format(x) for x in obj)
)
else:
return repr(obj)
else:
result = []
if isinstance(obj, TLObject):
obj = obj.to_dict()
if isinstance(obj, dict):
result.append(obj.get('_', 'dict'))
result.append('(')
if obj:
result.append('\n')
indent += 1
for k, v in obj.items():
if k == '_':
continue
result.append('\t' * indent)
result.append(k)
result.append('=')
result.append(TLObject.pretty_format(v, indent))
result.append(',\n')
result.pop() # last ',\n'
indent -= 1
result.append('\n')
result.append('\t' * indent)
result.append(')')
elif isinstance(obj, str) or isinstance(obj, bytes):
result.append(repr(obj))
elif hasattr(obj, '__iter__'):
result.append('[\n')
indent += 1
for x in obj:
result.append('\t' * indent)
result.append(TLObject.pretty_format(x, indent))
result.append(',\n')
indent -= 1
result.append('\t' * indent)
result.append(']')
else:
result.append(repr(obj))
return ''.join(result)
@staticmethod
def serialize_bytes(data):
def _serialize_bytes(data):
"""Write bytes by using Telegram guidelines"""
if not isinstance(data, bytes):
if isinstance(data, str):
@ -138,7 +73,7 @@ class TLObject:
return b''.join(r)
@staticmethod
def serialize_datetime(dt):
def _serialize_datetime(dt):
if not dt and not isinstance(dt, timedelta):
return b'\0\0\0\0'
@ -163,31 +98,32 @@ class TLObject:
def __ne__(self, o):
return not isinstance(o, type(self)) or self.to_dict() != o.to_dict()
def __repr__(self):
return pretty_print(self)
def __str__(self):
return TLObject.pretty_format(self)
return pretty_print(self, max_depth=2)
def stringify(self):
return TLObject.pretty_format(self, indent=0)
return pretty_print(self, indent=0)
def to_dict(self):
raise NotImplementedError
def to_json(self, fp=None, default=_json_default, **kwargs):
"""
Represent the current `TLObject` as JSON.
If ``fp`` is given, the JSON will be dumped to said
file pointer, otherwise a JSON string will be returned.
Note that bytes and datetimes cannot be represented
in JSON, so if those are found, they will be base64
encoded and ISO-formatted, respectively, by default.
"""
d = self.to_dict()
if fp:
return json.dump(d, fp, default=default, **kwargs)
res = {}
pre = ('', 'fn.')[isinstance(self, TLRequest)]
mod = self.__class__.__module__[self.__class__.__module__.rfind('.') + 1:]
if mod in ('_tl', 'fn'):
res['_'] = f'{pre}{self.__class__.__name__}'
else:
return json.dumps(d, default=default, **kwargs)
res['_'] = f'{pre}{mod}.{self.__class__.__name__}'
for slot in self.__slots__:
attr = getattr(self, slot)
if isinstance(attr, list):
res[slot] = [val.to_dict() if hasattr(val, 'to_dict') else val for val in attr]
else:
res[slot] = attr.to_dict() if hasattr(attr, 'to_dict') else attr
return res
def __bytes__(self):
try:
@ -197,7 +133,7 @@ class TLObject:
# provided) it will try to access `._bytes()`, which will fail
# with `AttributeError`. This occurs in fact because the type
# was wrong, so raise the correct error type.
raise TypeError('a TLObject was expected but found something else')
raise TypeError(f'a TLObject was expected but found {self!r}')
# Custom objects will call `(...)._bytes()` and not `bytes(...)` so that
# if the wrong type is used (e.g. `int`) we won't try allocating a huge
@ -206,7 +142,7 @@ class TLObject:
raise NotImplementedError
@classmethod
def from_reader(cls, reader):
def _from_reader(cls, reader):
raise NotImplementedError
@ -215,8 +151,8 @@ class TLRequest(TLObject):
Represents a content-related `TLObject` (a request that can be sent).
"""
@staticmethod
def read_result(reader):
def _read_result(reader):
return reader.tgread_object()
async def resolve(self, client, utils):
pass
async def _resolve(self, client, utils):
return self

668
telethon/utils.py → telethon/_misc/utils.py
View File

File diff suppressed because it is too large Load Diff

9
telethon/network/__init__.py → telethon/_network/__init__.py
View File

@ -5,10 +5,5 @@ with Telegram's servers and the protocol used (TCP full, abridged, etc.).
from .mtprotoplainsender import MTProtoPlainSender
from .authenticator import do_authentication
from .mtprotosender import MTProtoSender
from .connection import (
Connection,
ConnectionTcpFull, ConnectionTcpIntermediate, ConnectionTcpAbridged,
ConnectionTcpObfuscated, ConnectionTcpMTProxyAbridged,
ConnectionTcpMTProxyIntermediate,
ConnectionTcpMTProxyRandomizedIntermediate, ConnectionHttp, TcpMTProxy
)
from .connection import Connection
from . import transports

47
telethon/network/authenticator.py → telethon/_network/authenticator.py
View File

@ -2,21 +2,17 @@
This module contains several functions that authenticate the client machine
with Telegram's servers, effectively creating an authorization key.
"""
import asyncio
import functools
import os
import time
from hashlib import sha1
from ..tl.types import (
ResPQ, PQInnerData, ServerDHParamsFail, ServerDHParamsOk,
ServerDHInnerData, ClientDHInnerData, DhGenOk, DhGenRetry, DhGenFail
)
from .. import helpers
from ..crypto import AES, AuthKey, Factorization, rsa
from ..errors import SecurityError
from ..extensions import BinaryReader
from ..tl.functions import (
ReqPqMultiRequest, ReqDHParamsRequest, SetClientDHParamsRequest
)
from .. import _tl
from .._misc import helpers
from .._crypto import AES, AuthKey, Factorization, rsa
from ..errors._custom import SecurityError
from .._misc.binaryreader import BinaryReader
async def do_authentication(sender):
@ -28,8 +24,8 @@ async def do_authentication(sender):
"""
# Step 1 sending: PQ Request, endianness doesn't matter since it's random
nonce = int.from_bytes(os.urandom(16), 'big', signed=True)
res_pq = await sender.send(ReqPqMultiRequest(nonce))
assert isinstance(res_pq, ResPQ), 'Step 1 answer was %s' % res_pq
res_pq = await sender.send(_tl.fn.ReqPqMulti(nonce))
assert isinstance(res_pq, _tl.ResPQ), 'Step 1 answer was %s' % res_pq
if res_pq.nonce != nonce:
raise SecurityError('Step 1 invalid nonce from server')
@ -37,11 +33,14 @@ async def do_authentication(sender):
pq = get_int(res_pq.pq)
# Step 2 sending: DH Exchange
p, q = Factorization.factorize(pq)
p, q = await asyncio.get_running_loop().run_in_executor(
None,
functools.partial(Factorization.factorize, pq)
)
p, q = rsa.get_byte_array(p), rsa.get_byte_array(q)
new_nonce = int.from_bytes(os.urandom(32), 'little', signed=True)
pq_inner_data = bytes(PQInnerData(
pq_inner_data = bytes(_tl.PQInnerData(
pq=rsa.get_byte_array(pq), p=p, q=q,
nonce=res_pq.nonce,
server_nonce=res_pq.server_nonce,
@ -72,7 +71,7 @@ async def do_authentication(sender):
)
)
server_dh_params = await sender.send(ReqDHParamsRequest(
server_dh_params = await sender.send(_tl.fn.ReqDHParams(
nonce=res_pq.nonce,
server_nonce=res_pq.server_nonce,
p=p, q=q,
@ -81,7 +80,7 @@ async def do_authentication(sender):
))
assert isinstance(
server_dh_params, (ServerDHParamsOk, ServerDHParamsFail)),\
server_dh_params, (_tl.ServerDHParamsOk, _tl.ServerDHParamsFail)),\
'Step 2.1 answer was %s' % server_dh_params
if server_dh_params.nonce != res_pq.nonce:
@ -90,7 +89,7 @@ async def do_authentication(sender):
if server_dh_params.server_nonce != res_pq.server_nonce:
raise SecurityError('Step 2 invalid server nonce from server')
if isinstance(server_dh_params, ServerDHParamsFail):
if isinstance(server_dh_params, _tl.ServerDHParamsFail):
nnh = int.from_bytes(
sha1(new_nonce.to_bytes(32, 'little', signed=True)).digest()[4:20],
'little', signed=True
@ -98,7 +97,7 @@ async def do_authentication(sender):
if server_dh_params.new_nonce_hash != nnh:
raise SecurityError('Step 2 invalid DH fail nonce from server')
assert isinstance(server_dh_params, ServerDHParamsOk),\
assert isinstance(server_dh_params, _tl.ServerDHParamsOk),\
'Step 2.2 answer was %s' % server_dh_params
# Step 3 sending: Complete DH Exchange
@ -116,7 +115,7 @@ async def do_authentication(sender):
with BinaryReader(plain_text_answer) as reader:
reader.read(20) # hash sum
server_dh_inner = reader.tgread_object()
assert isinstance(server_dh_inner, ServerDHInnerData),\
assert isinstance(server_dh_inner, _tl.ServerDHInnerData),\
'Step 3 answer was %s' % server_dh_inner
if server_dh_inner.nonce != res_pq.nonce:
@ -157,7 +156,7 @@ async def do_authentication(sender):
raise SecurityError('g_b is not within (2^{2048-64}, dh_prime - 2^{2048-64})')
# Prepare client DH Inner Data
client_dh_inner = bytes(ClientDHInnerData(
client_dh_inner = bytes(_tl.ClientDHInnerData(
nonce=res_pq.nonce,
server_nonce=res_pq.server_nonce,
retry_id=0, # TODO Actual retry ID
@ -170,13 +169,13 @@ async def do_authentication(sender):
client_dh_encrypted = AES.encrypt_ige(client_dh_inner_hashed, key, iv)
# Prepare Set client DH params
dh_gen = await sender.send(SetClientDHParamsRequest(
dh_gen = await sender.send(_tl.fn.SetClientDHParams(
nonce=res_pq.nonce,
server_nonce=res_pq.server_nonce,
encrypted_data=client_dh_encrypted,
))
nonce_types = (DhGenOk, DhGenRetry, DhGenFail)
nonce_types = (_tl.DhGenOk, _tl.DhGenRetry, _tl.DhGenFail)
assert isinstance(dh_gen, nonce_types), 'Step 3.1 answer was %s' % dh_gen
name = dh_gen.__class__.__name__
if dh_gen.nonce != res_pq.nonce:
@ -194,7 +193,7 @@ async def do_authentication(sender):
if dh_hash != new_nonce_hash:
raise SecurityError('Step 3 invalid new nonce hash')
if not isinstance(dh_gen, DhGenOk):
if not isinstance(dh_gen, _tl.DhGenOk):
raise AssertionError('Step 3.2 answer was %s' % dh_gen)
return auth_key, time_offset

63
telethon/_network/connection.py Normal file
View File

@ -0,0 +1,63 @@
import asyncio
import socket
from .transports.transport import Transport
CHUNK_SIZE = 32 * 1024
# TODO ideally the mtproto impl would also be sans-io, but that's less pressing
class Connection:
def __init__(self, ip, port, *, transport: Transport, loggers, local_addr=None):
self._ip = ip
self._port = port
self._log = loggers[__name__]
self._local_addr = local_addr
self._sock = None
self._in_buffer = bytearray()
self._transport = transport
async def connect(self, timeout=None, ssl=None):
"""
Establishes a connection with the server.
"""
loop = asyncio.get_running_loop()
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.setblocking(False)
if self._local_addr:
sock.bind(self._local_addr)
# TODO https://github.com/LonamiWebs/Telethon/issues/1337 may be an issue again
# perhaps we just need to ignore async connect on windows and block?
await asyncio.wait_for(loop.sock_connect(sock, (self._ip, self._port)), timeout)
self._sock = sock
async def disconnect(self):
self._sock.close()
self._sock = None
async def send(self, data):
if not self._sock:
raise ConnectionError('not connected')
loop = asyncio.get_running_loop()
await loop.sock_sendall(self._sock, self._transport.pack(data))
async def recv(self):
if not self._sock:
raise ConnectionError('not connected')
loop = asyncio.get_running_loop()
while True:
try:
length, body = self._transport.unpack(self._in_buffer)
del self._in_buffer[:length]
return body
except EOFError:
self._in_buffer += await loop.sock_recv(self._sock, CHUNK_SIZE)
def __str__(self):
return f'{self._ip}:{self._port}/{self._transport.__class__.__name__}'

4
telethon/network/mtprotoplainsender.py → telethon/_network/mtprotoplainsender.py
View File

@ -5,8 +5,8 @@ in plain text, when no authorization key has been created yet.
import struct
from .mtprotostate import MTProtoState
from ..errors import InvalidBufferError
from ..extensions import BinaryReader
from ..errors._custom import InvalidBufferError
from .._misc.binaryreader import BinaryReader
class MTProtoPlainSender:

207
telethon/network/mtprotosender.py → telethon/_network/mtprotosender.py
View File

@ -1,29 +1,29 @@
import asyncio
import collections
import struct
import logging
import random
from . import authenticator
from ..extensions.messagepacker import MessagePacker
from .._misc.messagepacker import MessagePacker
from ..errors._rpcbase import _mk_error_type
from .mtprotoplainsender import MTProtoPlainSender
from .requeststate import RequestState
from .mtprotostate import MTProtoState
from ..tl.tlobject import TLRequest
from .. import helpers, utils
from ..errors import (
BadMessageError, InvalidBufferError, SecurityError,
TypeNotFoundError, rpc_message_to_error
)
from ..extensions import BinaryReader
from ..tl.core import RpcResult, MessageContainer, GzipPacked
from ..tl.functions.auth import LogOutRequest
from ..tl.functions import PingRequest, DestroySessionRequest
from ..tl.types import (
MsgsAck, Pong, BadServerSalt, BadMsgNotification, FutureSalts,
MsgNewDetailedInfo, NewSessionCreated, MsgDetailedInfo, MsgsStateReq,
MsgsStateInfo, MsgsAllInfo, MsgResendReq, upload, DestroySessionOk, DestroySessionNone,
)
from ..crypto import AuthKey
from ..helpers import retry_range
from .._misc.binaryreader import BinaryReader
from .._misc.tlobject import TLRequest
from ..types._core import RpcResult, MessageContainer, GzipPacked
from .._crypto import AuthKey
from .._misc import helpers, utils
from .. import _tl
UPDATE_BUFFER_FULL_WARN_DELAY = 15 * 60
PING_DELAY = 60
class MTProtoSender:
@ -41,10 +41,8 @@ class MTProtoSender:
A new authorization key will be generated on connection if no other
key exists yet.
"""
def __init__(self, auth_key, *, loggers,
retries=5, delay=1, auto_reconnect=True, connect_timeout=None,
auth_key_callback=None,
update_callback=None, auto_reconnect_callback=None):
def __init__(self, *, loggers, updates_queue,
retries=5, delay=1, auto_reconnect=True, connect_timeout=None,):
self._connection = None
self._loggers = loggers
self._log = loggers[__name__]
@ -52,11 +50,10 @@ class MTProtoSender:
self._delay = delay
self._auto_reconnect = auto_reconnect
self._connect_timeout = connect_timeout
self._auth_key_callback = auth_key_callback
self._update_callback = update_callback
self._auto_reconnect_callback = auto_reconnect_callback
self._updates_queue = updates_queue
self._connect_lock = asyncio.Lock()
self._ping = None
self._next_ping = None
# Whether the user has explicitly connected or disconnected.
#
@ -66,15 +63,15 @@ class MTProtoSender:
# pending futures should be cancelled.
self._user_connected = False
self._reconnecting = False
self._disconnected = asyncio.get_event_loop().create_future()
self._disconnected.set_result(None)
self._disconnected = asyncio.Queue(1)
self._disconnected.put_nowait(None)
# We need to join the loops upon disconnection
self._send_loop_handle = None
self._recv_loop_handle = None
# Preserving the references of the AuthKey and state is important
self.auth_key = auth_key or AuthKey(None)
self.auth_key = AuthKey(None)
self._state = MTProtoState(self.auth_key, loggers=self._loggers)
# Outgoing messages are put in a queue and sent in a batch.
@ -92,24 +89,27 @@ class MTProtoSender:
# is received, but we may still need to resend their state on bad salts.
self._last_acks = collections.deque(maxlen=10)
# Last time we warned about the update buffer being full
self._last_update_warn = -UPDATE_BUFFER_FULL_WARN_DELAY
# Jump table from response ID to method that handles it
self._handlers = {
RpcResult.CONSTRUCTOR_ID: self._handle_rpc_result,
MessageContainer.CONSTRUCTOR_ID: self._handle_container,
GzipPacked.CONSTRUCTOR_ID: self._handle_gzip_packed,
Pong.CONSTRUCTOR_ID: self._handle_pong,
BadServerSalt.CONSTRUCTOR_ID: self._handle_bad_server_salt,
BadMsgNotification.CONSTRUCTOR_ID: self._handle_bad_notification,
MsgDetailedInfo.CONSTRUCTOR_ID: self._handle_detailed_info,
MsgNewDetailedInfo.CONSTRUCTOR_ID: self._handle_new_detailed_info,
NewSessionCreated.CONSTRUCTOR_ID: self._handle_new_session_created,
MsgsAck.CONSTRUCTOR_ID: self._handle_ack,
FutureSalts.CONSTRUCTOR_ID: self._handle_future_salts,
MsgsStateReq.CONSTRUCTOR_ID: self._handle_state_forgotten,
MsgResendReq.CONSTRUCTOR_ID: self._handle_state_forgotten,
MsgsAllInfo.CONSTRUCTOR_ID: self._handle_msg_all,
DestroySessionOk: self._handle_destroy_session,
DestroySessionNone: self._handle_destroy_session,
_tl.Pong.CONSTRUCTOR_ID: self._handle_pong,
_tl.BadServerSalt.CONSTRUCTOR_ID: self._handle_bad_server_salt,
_tl.BadMsgNotification.CONSTRUCTOR_ID: self._handle_bad_notification,
_tl.MsgDetailedInfo.CONSTRUCTOR_ID: self._handle_detailed_info,
_tl.MsgNewDetailedInfo.CONSTRUCTOR_ID: self._handle_new_detailed_info,
_tl.NewSessionCreated.CONSTRUCTOR_ID: self._handle_new_session_created,
_tl.MsgsAck.CONSTRUCTOR_ID: self._handle_ack,
_tl.FutureSalts.CONSTRUCTOR_ID: self._handle_future_salts,
_tl.MsgsStateReq.CONSTRUCTOR_ID: self._handle_state_forgotten,
_tl.MsgResendReq.CONSTRUCTOR_ID: self._handle_state_forgotten,
_tl.MsgsAllInfo.CONSTRUCTOR_ID: self._handle_msg_all,
_tl.DestroySessionOk: self._handle_destroy_session,
_tl.DestroySessionNone: self._handle_destroy_session,
}
# Public API
@ -126,6 +126,7 @@ class MTProtoSender:
self._connection = connection
await self._connect()
self._user_connected = True
self._next_ping = asyncio.get_running_loop().time() + PING_DELAY
return True
def is_connected(self):
@ -199,16 +200,14 @@ class MTProtoSender:
self._send_queue.extend(states)
return futures
@property
def disconnected(self):
async def wait_disconnected(self):
"""
Future that resolves when the connection to Telegram
ends, either by user action or in the background.
Note that it may resolve in either a ``ConnectionError``
or any other unexpected error that could not be handled.
Wait until the client is disconnected.
Raise if the disconnection finished with error.
"""
return asyncio.shield(self._disconnected)
res = await self._disconnected.get()
if isinstance(res, BaseException):
raise res
# Private methods
@ -222,7 +221,7 @@ class MTProtoSender:
connected = False
for attempt in retry_range(self._retries):
for attempt in helpers.retry_range(self._retries):
if not connected:
connected = await self._try_connect(attempt)
if not connected:
@ -250,24 +249,23 @@ class MTProtoSender:
break # all steps done, break retry loop
else:
if not connected:
raise ConnectionError('Connection to Telegram failed {} time(s)'.format(self._retries))
raise ConnectionError('Connection to Telegram failed {} time(s)'.format(1 + self._retries))
e = ConnectionError('auth_key generation failed {} time(s)'.format(self._retries))
e = ConnectionError('auth_key generation failed {} time(s)'.format(1 + self._retries))
await self._disconnect(error=e)
raise e
loop = asyncio.get_event_loop()
self._log.debug('Starting send loop')
self._send_loop_handle = loop.create_task(self._send_loop())
self._send_loop_handle = asyncio.create_task(self._send_loop())
self._log.debug('Starting receive loop')
self._recv_loop_handle = loop.create_task(self._recv_loop())
self._recv_loop_handle = asyncio.create_task(self._recv_loop())
# _disconnected only completes after manual disconnection
# or errors after which the sender cannot continue such
# as failing to reconnect or any unexpected error.
if self._disconnected.done():
self._disconnected = loop.create_future()
while not self._disconnected.empty():
self._disconnected.get_nowait()
self._log.info('Connection to %s complete!', self._connection)
@ -290,13 +288,6 @@ class MTProtoSender:
self.auth_key.key, self._state.time_offset = \
await authenticator.do_authentication(plain)
# This is *EXTREMELY* important since we don't control
# external references to the authorization key, we must
# notify whenever we change it. This is crucial when we
# switch to different data centers.
if self._auth_key_callback:
self._auth_key_callback(self.auth_key)
self._log.debug('auth_key generation success!')
return True
except (SecurityError, AssertionError) as e:
@ -332,11 +323,8 @@ class MTProtoSender:
self._log.info('Disconnection from %s complete!', self._connection)
self._connection = None
if self._disconnected and not self._disconnected.done():
if error:
self._disconnected.set_exception(error)
else:
self._disconnected.set_result(None)
if not self._disconnected.full():
self._disconnected.put_nowait(error)
async def _reconnect(self, last_error):
"""
@ -361,12 +349,11 @@ class MTProtoSender:
# Start with a clean state (and thus session ID) to avoid old msgs
self._state.reset()
retries = self._retries if self._auto_reconnect else 0
retry_range = helpers.retry_range(self._retries) if self._auto_reconnect else range(0)
attempt = 0
ok = True
# We're already "retrying" to connect, so we don't want to force retries
for attempt in retry_range(retries, force_retry=False):
for attempt in retry_range:
try:
await self._connect()
except (IOError, asyncio.TimeoutError) as e:
@ -379,8 +366,6 @@ class MTProtoSender:
if isinstance(e, InvalidBufferError) and e.code == 404:
self._log.info('Broken authorization key; resetting')
self.auth_key.key = None
if self._auth_key_callback:
self._auth_key_callback(None)
ok = False
break
@ -396,10 +381,6 @@ class MTProtoSender:
else:
self._send_queue.extend(self._pending_state.values())
self._pending_state.clear()
if self._auto_reconnect_callback:
asyncio.get_event_loop().create_task(self._auto_reconnect_callback())
break
else:
ok = False
@ -423,17 +404,17 @@ class MTProtoSender:
# gets stuck.
# TODO It still gets stuck? Investigate where and why.
self._reconnecting = True
asyncio.get_event_loop().create_task(self._reconnect(error))
asyncio.create_task(self._reconnect(error))
def _keepalive_ping(self, rnd_id):
def _trigger_keepalive_ping(self):
"""
Send a keep-alive ping. If a pong for the last ping was not received
yet, this means we're probably not connected.
"""
# TODO this is ugly, update loop shouldn't worry about this, sender should
if self._ping is None:
self._ping = rnd_id
self.send(PingRequest(rnd_id))
self._ping = random.randrange(-2**63, 2**63)
self.send(_tl.fn.Ping(self._ping))
self._next_ping = asyncio.get_running_loop().time() + PING_DELAY
else:
self._start_reconnect(None)
@ -448,7 +429,7 @@ class MTProtoSender:
"""
while self._user_connected and not self._reconnecting:
if self._pending_ack:
ack = RequestState(MsgsAck(list(self._pending_ack)))
ack = RequestState(_tl.MsgsAck(list(self._pending_ack)))
self._send_queue.append(ack)
self._last_acks.append(ack)
self._pending_ack.clear()
@ -457,7 +438,11 @@ class MTProtoSender:
# TODO Wait for the connection send queue to be empty?
# This means that while it's not empty we can wait for
# more messages to be added to the send queue.
batch, data = await self._send_queue.get()
try:
batch, data = await asyncio.wait_for(self._send_queue.get(), self._next_ping - asyncio.get_running_loop().time())
except asyncio.TimeoutError:
self._trigger_keepalive_ping()
continue
if not data:
continue
@ -523,8 +508,6 @@ class MTProtoSender:
if isinstance(e, InvalidBufferError) and e.code == 404:
self._log.info('Broken authorization key; resetting')
self.auth_key.key = None
if self._auth_key_callback:
self._auth_key_callback(None)
await self._disconnect(error=e)
else:
@ -598,28 +581,36 @@ class MTProtoSender:
# which contain the real response right after.
try:
with BinaryReader(rpc_result.body) as reader:
if not isinstance(reader.tgread_object(), upload.File):
if not isinstance(reader.tgread_object(), _tl.upload.File):
raise ValueError('Not an upload.File')
except (TypeNotFoundError, ValueError):
self._log.info('Received response without parent request: %s', rpc_result.body)
return
if rpc_result.error:
error = rpc_message_to_error(rpc_result.error, state.request)
self._send_queue.append(
RequestState(MsgsAck([state.msg_id])))
RequestState(_tl.MsgsAck([state.msg_id])))
if not state.future.cancelled():
state.future.set_exception(error)
err_ty = _mk_error_type(
name=rpc_result.error.error_message,
code=rpc_result.error.error_code,
)
state.future.set_exception(err_ty(
rpc_result.error.error_code,
rpc_result.error.error_message,
state.request
))
else:
try:
with BinaryReader(rpc_result.body) as reader:
result = state.request.read_result(reader)
result = state.request._read_result(reader)
except Exception as e:
# e.g. TypeNotFoundError, should be propagated to caller
if not state.future.cancelled():
state.future.set_exception(e)
else:
self._store_own_updates(result)
if not state.future.cancelled():
state.future.set_result(result)
@ -641,7 +632,15 @@ class MTProtoSender:
"""
self._log.debug('Handling gzipped data')
with BinaryReader(message.obj.data) as reader:
try:
message.obj = reader.tgread_object()
except TypeNotFoundError as e:
# Received object which we don't know how to deserialize.
# This is somewhat expected while receiving updates, which
# will eventually trigger a gap error to recover from.
self._log.info('Type %08x not found, remaining data %r',
e.invalid_constructor_id, e.remaining)
else:
await self._process_message(message)
async def _handle_update(self, message):
@ -652,8 +651,30 @@ class MTProtoSender:
return
self._log.debug('Handling update %s', message.obj.__class__.__name__)
if self._update_callback:
self._update_callback(message.obj)
try:
self._updates_queue.put_nowait(message.obj)
except asyncio.QueueFull:
now = asyncio.get_running_loop().time()
if now - self._last_update_warn >= UPDATE_BUFFER_FULL_WARN_DELAY:
self._log.warning(
'Cannot dispatch update because the buffer capacity of %d was reached',
self._updates_queue.maxsize
)
self._last_update_warn = now
def _store_own_updates(self, obj, *, _update_ids=frozenset((
_tl.UpdateShortMessage.CONSTRUCTOR_ID,
_tl.UpdateShortChatMessage.CONSTRUCTOR_ID,
_tl.UpdateShort.CONSTRUCTOR_ID,
_tl.UpdatesCombined.CONSTRUCTOR_ID,
_tl.Updates.CONSTRUCTOR_ID,
_tl.UpdateShortSentMessage.CONSTRUCTOR_ID,
))):
try:
if obj.CONSTRUCTOR_ID in _update_ids:
self._updates_queue.put_nowait(obj)
except AttributeError:
pass
async def _handle_pong(self, message):
"""
@ -777,7 +798,7 @@ class MTProtoSender:
self._log.debug('Handling acknowledge for %s', str(ack.msg_ids))
for msg_id in ack.msg_ids:
state = self._pending_state.get(msg_id)
if state and isinstance(state.request, LogOutRequest):
if state and isinstance(state.request, _tl.fn.auth.LogOut):
del self._pending_state[msg_id]
if not state.future.cancelled():
state.future.set_result(True)
@ -802,7 +823,7 @@ class MTProtoSender:
Handles both :tl:`MsgsStateReq` and :tl:`MsgResendReq` by
enqueuing a :tl:`MsgsStateInfo` to be sent at a later point.
"""
self._send_queue.append(RequestState(MsgsStateInfo(
self._send_queue.append(RequestState(_tl.MsgsStateInfo(
req_msg_id=message.msg_id, info=chr(1) * len(message.obj.msg_ids)
)))
@ -817,7 +838,7 @@ class MTProtoSender:
It behaves pretty much like handling an RPC result.
"""
for msg_id, state in self._pending_state.items():
if isinstance(state.request, DestroySessionRequest)\
if isinstance(state.request, _tl.fn.DestroySession)\
and state.request.session_id == message.obj.session_id:
break
else:

15
telethon/network/mtprotostate.py → telethon/_network/mtprotostate.py
View File

@ -3,13 +3,12 @@ import struct
import time
from hashlib import sha256
from ..crypto import AES
from ..errors import SecurityError, InvalidBufferError
from ..extensions import BinaryReader
from ..tl.core import TLMessage
from ..tl.tlobject import TLRequest
from ..tl.functions import InvokeAfterMsgRequest
from ..tl.core.gzippacked import GzipPacked
from .._crypto import AES
from ..errors._custom import SecurityError, InvalidBufferError
from .._misc.binaryreader import BinaryReader
from ..types._core import TLMessage, GzipPacked
from .._misc.tlobject import TLRequest
from .. import _tl
class _OpaqueRequest(TLRequest):
@ -103,7 +102,7 @@ class MTProtoState:
# The `RequestState` stores `bytes(request)`, not the request itself.
# `invokeAfterMsg` wants a `TLRequest` though, hence the wrapping.
body = GzipPacked.gzip_if_smaller(content_related,
bytes(InvokeAfterMsgRequest(after_id, _OpaqueRequest(data))))
bytes(_tl.fn.InvokeAfterMsg(after_id, _OpaqueRequest(data))))
buffer.write(struct.pack('<qii', msg_id, seq_no, len(body)))
buffer.write(body)

0
telethon/network/requeststate.py → telethon/_network/requeststate.py
View File

4
telethon/_network/transports/__init__.py Normal file
View File

@ -0,0 +1,4 @@
from .transport import Transport
from .abridged import Abridged
from .full import Full
from .intermediate import Intermediate

43
telethon/_network/transports/abridged.py Normal file
View File

@ -0,0 +1,43 @@
from .transport import Transport
import struct
class Abridged(Transport):
def __init__(self):
self._init = False
def recreate_fresh(self):
return type(self)()
def pack(self, input: bytes) -> bytes:
if self._init:
header = b''
else:
header = b'\xef'
self._init = True
length = len(data) >> 2
if length < 127:
length = struct.pack('B', length)
else:
length = b'\x7f' + int.to_bytes(length, 3, 'little')
return header + length + data
def unpack(self, input: bytes) -> (int, bytes):
if len(input) < 4:
raise EOFError()
length = input[0]
if length < 127:
offset = 1
else:
offset = 4
length = struct.unpack('<i', input[1:4] + b'\0')[0]
length = (length << 2) + offset
if len(input) < length:
raise EOFError()
return length, input[offset:length]

41
telethon/_network/transports/full.py Normal file
View File

@ -0,0 +1,41 @@
from .transport import Transport
import struct
from zlib import crc32
class Full(Transport):
def __init__(self):
self._send_counter = 0
self._recv_counter = 0
def recreate_fresh(self):
return type(self)()
def pack(self, input: bytes) -> bytes:
# https://core.telegram.org/mtproto#tcp-transport
length = len(input) + 12
data = struct.pack('<ii', length, self._send_counter) + input
crc = struct.pack('<I', crc32(data))
self._send_counter += 1
return data + crc
def unpack(self, input: bytes) -> (int, bytes):
if len(input) < 12:
raise EOFError()
length, seq = struct.unpack('<ii', input[:8])
if len(input) < length:
raise EOFError()
if seq != self._recv_counter:
raise ValueError(f'expected sequence value {self._recv_counter!r}, got {seq!r}')
body = input[8:length - 4]
checksum = struct.unpack('<I', input[length - 4:length])[0]
valid_checksum = crc32(input[:length - 4])
if checksum != valid_checksum:
raise InvalidChecksumError(checksum, valid_checksum)
self._recv_counter += 1
return length, body

29
telethon/_network/transports/intermediate.py Normal file
View File

@ -0,0 +1,29 @@
from .transport import Transport
import struct
class Intermediate(Transport):
def __init__(self):
self._init = False
def recreate_fresh(self):
return type(self)()
def pack(self, input: bytes) -> bytes:
if self._init:
header = b''
else:
header = b'\xee\xee\xee\xee'
self._init = True
return header + struct.pack('<i', len(data)) + data
def unpack(self, input: bytes) -> (int, bytes):
if len(input) < 4:
raise EOFError()
length = struct.unpack('<i', input[:4])[0] + 4
if len(input) < length:
raise EOFError()
return length, input[4:length]

17
telethon/_network/transports/transport.py Normal file
View File

@ -0,0 +1,17 @@
import abc
class Transport(abc.ABC):
# Should return a newly-created instance of itself
@abc.abstractmethod
def recreate_fresh(self):
pass
@abc.abstractmethod
def pack(self, input: bytes) -> bytes:
pass
# Should raise EOFError if it does not have enough bytes
@abc.abstractmethod
def unpack(self, input: bytes) -> (int, bytes):
pass

0
telethon/sessions/__init__.py → telethon/_sessions/__init__.py
View File

92
telethon/_sessions/abstract.py Normal file
View File

@ -0,0 +1,92 @@
from .types import DataCenter, ChannelState, SessionState, EntityType, Entity
from abc import ABC, abstractmethod
from typing import List, Optional
class Session(ABC):
@abstractmethod
async def insert_dc(self, dc: DataCenter):
"""
Store a new or update an existing `DataCenter` with matching ``id``.
"""
raise NotImplementedError
@abstractmethod
async def get_all_dc(self) -> List[DataCenter]:
"""
Get a list of all currently-stored `DataCenter`. Should not contain duplicate ``id``.
"""
raise NotImplementedError
@abstractmethod
async def set_state(self, state: SessionState):
"""
Set the state about the current session.
"""
raise NotImplementedError
@abstractmethod
async def get_state(self) -> Optional[SessionState]:
"""
Get the state about the current session.
"""
raise NotImplementedError
@abstractmethod
async def insert_channel_state(self, state: ChannelState):
"""
Store a new or update an existing `ChannelState` with matching ``id``.
"""
raise NotImplementedError
@abstractmethod
async def get_all_channel_states(self) -> List[ChannelState]:
"""
Get a list of all currently-stored `ChannelState`. Should not contain duplicate ``id``.
"""
raise NotImplementedError
@abstractmethod
async def insert_entities(self, entities: List[Entity]):
"""
Store new or update existing `Entity` with matching ``id``.
Entities should be saved on a best-effort. It is okay to not save them, although the
library may need to do extra work if a previously-saved entity is missing, or even be
unable to continue without the entity.
"""
raise NotImplementedError
@abstractmethod
async def get_entity(self, ty: Optional[EntityType], id: int) -> Optional[Entity]:
"""
Get the `Entity` with matching ``ty`` and ``id``.
The following groups of ``ty`` should be treated to be equivalent, that is, for a given
``ty`` and ``id``, if the ``ty`` is in a given group, a matching ``hash`` with that ``id``
from within any ``ty`` in that group should be returned.
* `EntityType.USER` and `EntityType.BOT`.
* `EntityType.GROUP`.
* `EntityType.CHANNEL`, `EntityType.MEGAGROUP` and `EntityType.GIGAGROUP`.
For example, if a ``ty`` representing a bot is stored but the asking ``ty`` is a user,
the corresponding ``hash`` should still be returned.
You may use ``EntityType.canonical`` to find out the canonical type.
A ``ty`` with the value of ``None`` should be treated as "any entity with matching ID".
"""
raise NotImplementedError
@abstractmethod
async def save(self):
"""
Save the session.
May do nothing if the other methods already saved when they were called.
May return custom data when manual saving is intended.
"""
raise NotImplementedError

47
telethon/_sessions/memory.py Normal file
View File

@ -0,0 +1,47 @@
from .types import DataCenter, ChannelState, SessionState, Entity
from .abstract import Session
from .._misc import utils, tlobject
from .. import _tl
from typing import List, Optional
class MemorySession(Session):
__slots__ = ('dcs', 'state', 'channel_states', 'entities')
def __init__(self):
self.dcs = {}
self.state = None
self.channel_states = {}
self.entities = {}
async def insert_dc(self, dc: DataCenter):
self.dcs[dc.id] = dc
async def get_all_dc(self) -> List[DataCenter]:
return list(self.dcs.values())
async def set_state(self, state: SessionState):
self.state = state
async def get_state(self) -> Optional[SessionState]:
return self.state
async def insert_channel_state(self, state: ChannelState):
self.channel_states[state.channel_id] = state
async def get_all_channel_states(self) -> List[ChannelState]:
return list(self.channel_states.values())
async def insert_entities(self, entities: List[Entity]):
self.entities.update((e.id, (e.ty, e.hash)) for e in entities)
async def get_entity(self, ty: Optional[int], id: int) -> Optional[Entity]:
try:
ty, hash = self.entities[id]
return Entity(ty, id, hash)
except KeyError:
return None
async def save(self):
pass

284
telethon/_sessions/sqlite.py Normal file
View File

@ -0,0 +1,284 @@
import datetime
import os
import time
import ipaddress
from typing import Optional, List
from .abstract import Session
from .._misc import utils
from .. import _tl
from .types import DataCenter, ChannelState, SessionState, Entity
try:
import sqlite3
sqlite3_err = None
except ImportError as e:
sqlite3 = None
sqlite3_err = type(e)
EXTENSION = '.session'
CURRENT_VERSION = 8 # database version
class SQLiteSession(Session):
"""
This session contains the required information to login into your
Telegram account. NEVER give the saved session file to anyone, since
they would gain instant access to all your messages and contacts.
If you think the session has been compromised, close all the sessions
through an official Telegram client to revoke the authorization.
"""
def __init__(self, session_id=None):
if sqlite3 is None:
raise sqlite3_err
super().__init__()
self.filename = ':memory:'
self.save_entities = True
if session_id:
self.filename = os.fspath(session_id)
if not self.filename.endswith(EXTENSION):
self.filename += EXTENSION
self._conn = None
c = self._cursor()
c.execute("select name from sqlite_master "
"where type='table' and name='version'")
if c.fetchone():
# Tables already exist, check for the version
c.execute("select version from version")
version = c.fetchone()[0]
if version < CURRENT_VERSION:
self._upgrade_database(old=version)
c.execute("delete from version")
c.execute("insert into version values (?)", (CURRENT_VERSION,))
self._conn.commit()
else:
# Tables don't exist, create new ones
self._create_table(c, 'version (version integer primary key)')
self._mk_tables(c)
c.execute("insert into version values (?)", (CURRENT_VERSION,))
self._conn.commit()
# Must have committed or else the version will not have been updated while new tables
# exist, leading to a half-upgraded state.
c.close()
def _upgrade_database(self, old):
c = self._cursor()
if old == 1:
old += 1
# old == 1 doesn't have the old sent_files so no need to drop
if old == 2:
old += 1
# Old cache from old sent_files lasts then a day anyway, drop
c.execute('drop table sent_files')
self._create_table(c, """sent_files (
md5_digest blob,
file_size integer,
type integer,
id integer,
hash integer,
primary key(md5_digest, file_size, type)
)""")
if old == 3:
old += 1
self._create_table(c, """update_state (
id integer primary key,
pts integer,
qts integer,
date integer,
seq integer
)""")
if old == 4:
old += 1
c.execute("alter table sessions add column takeout_id integer")
if old == 5:
# Not really any schema upgrade, but potentially all access
# hashes for User and Channel are wrong, so drop them off.
old += 1
c.execute('delete from entities')
if old == 6:
old += 1
c.execute("alter table entities add column date integer")
if old == 7:
self._mk_tables(c)
c.execute('''
insert into datacenter (id, ipv4, ipv6, port, auth)
select dc_id, server_address, server_address, port, auth_key
from sessions
''')
c.execute('''
insert into session (user_id, dc_id, bot, pts, qts, date, seq, takeout_id)
select
0,
s.dc_id,
0,
coalesce(u.pts, 0),
coalesce(u.qts, 0),
coalesce(u.date, 0),
coalesce(u.seq, 0),
s.takeout_id
from sessions s
left join update_state u on u.id = 0
limit 1
''')
c.execute('''
insert into entity (id, hash, ty)
select
case
when id < -1000000000000 then -(id + 1000000000000)
when id < 0 then -id
else id
end,
hash,
case
when id < -1000000000000 then 67
when id < 0 then 71
else 85
end
from entities
''')
c.execute('drop table sessions')
c.execute('drop table entities')
c.execute('drop table sent_files')
c.execute('drop table update_state')
def _mk_tables(self, c):
self._create_table(
c,
'''datacenter (
id integer primary key,
ipv4 text not null,
ipv6 text,
port integer not null,
auth blob not null
)''',
'''session (
user_id integer primary key,
dc_id integer not null,
bot integer not null,
pts integer not null,
qts integer not null,
date integer not null,
seq integer not null,
takeout_id integer
)''',
'''channel (
channel_id integer primary key,
pts integer not null
)''',
'''entity (
id integer primary key,
hash integer not null,
ty integer not null
)''',
)
async def insert_dc(self, dc: DataCenter):
self._execute(
'insert or replace into datacenter values (?,?,?,?,?)',
dc.id,
str(ipaddress.ip_address(dc.ipv4)),
str(ipaddress.ip_address(dc.ipv6)) if dc.ipv6 else None,
dc.port,
dc.auth
)
async def get_all_dc(self) -> List[DataCenter]:
c = self._cursor()
res = []
for (id, ipv4, ipv6, port, auth) in c.execute('select * from datacenter'):
res.append(DataCenter(
id=id,
ipv4=int(ipaddress.ip_address(ipv4)),
ipv6=int(ipaddress.ip_address(ipv6)) if ipv6 else None,
port=port,
auth=auth,
))
return res
async def set_state(self, state: SessionState):
c = self._cursor()
try:
self._execute('delete from session')
self._execute(
'insert into session values (?,?,?,?,?,?,?,?)',
state.user_id,
state.dc_id,
int(state.bot),
state.pts,
state.qts,
state.date,
state.seq,
state.takeout_id,
)
finally:
c.close()
async def get_state(self) -> Optional[SessionState]:
row = self._execute('select * from session')
return SessionState(*row) if row else None
async def insert_channel_state(self, state: ChannelState):
self._execute(
'insert or replace into channel values (?,?)',
state.channel_id,
state.pts,
)
async def get_all_channel_states(self) -> List[ChannelState]:
c = self._cursor()
try:
return [
ChannelState(*row)
for row in c.execute('select * from channel')
]
finally:
c.close()
async def insert_entities(self, entities: List[Entity]):
c = self._cursor()
try:
c.executemany(
'insert or replace into entity values (?,?,?)',
[(e.id, e.hash, e.ty) for e in entities]
)
finally:
c.close()
async def get_entity(self, ty: Optional[int], id: int) -> Optional[Entity]:
row = self._execute('select ty, id, hash from entity where id = ?', id)
return Entity(*row) if row else None
async def save(self):
# This is a no-op if there are no changes to commit, so there's
# no need for us to keep track of an "unsaved changes" variable.
if self._conn is not None:
self._conn.commit()
@staticmethod
def _create_table(c, *definitions):
for definition in definitions:
c.execute('create table {}'.format(definition))
def _cursor(self):
"""Asserts that the connection is open and returns a cursor"""
if self._conn is None:
self._conn = sqlite3.connect(self.filename,
check_same_thread=False)
return self._conn.cursor()
def _execute(self, stmt, *values):
"""
Gets a cursor, executes `stmt` and closes the cursor,
fetching one row afterwards and returning its result.
"""
c = self._cursor()
try:
return c.execute(stmt, values).fetchone()
finally:
c.close()

45
telethon/sessions/string.py → telethon/_sessions/string.py
View File

@ -4,7 +4,7 @@ import struct
from .abstract import Session
from .memory import MemorySession
from ..crypto import AuthKey
from .types import DataCenter, ChannelState, SessionState, Entity
_STRUCT_PREFORMAT = '>B{}sH256s'
@ -34,12 +34,33 @@ class StringSession(MemorySession):
string = string[1:]
ip_len = 4 if len(string) == 352 else 16
self._dc_id, ip, self._port, key = struct.unpack(
dc_id, ip, port, key = struct.unpack(
_STRUCT_PREFORMAT.format(ip_len), StringSession.decode(string))
self._server_address = ipaddress.ip_address(ip).compressed
if any(key):
self._auth_key = AuthKey(key)
self.state = SessionState(
dc_id=dc_id,
user_id=0,
bot=False,
pts=0,
qts=0,
date=0,
seq=0,
takeout_id=0
)
if ip_len == 4:
ipv4 = int.from_bytes(ip, 'big', signed=False)
ipv6 = None
else:
ipv4 = None
ipv6 = int.from_bytes(ip, 'big', signed=False)
self.dcs[dc_id] = DataCenter(
id=dc_id,
ipv4=ipv4,
ipv6=ipv6,
port=port,
auth=key
)
@staticmethod
def encode(x: bytes) -> str:
@ -50,14 +71,18 @@ class StringSession(MemorySession):
return base64.urlsafe_b64decode(x)
def save(self: Session):
if not self.auth_key:
if not self.state:
return ''
ip = ipaddress.ip_address(self.server_address).packed
if self.dcs[self.state.dc_id].ipv6 is not None:
ip = self.dcs[self.state.dc_id].ipv6.to_bytes(16, 'big', signed=False)
else:
ip = self.dcs[self.state.dc_id].ipv4.to_bytes(4, 'big', signed=False)
return CURRENT_VERSION + StringSession.encode(struct.pack(
_STRUCT_PREFORMAT.format(len(ip)),
self.dc_id,
self.state.dc_id,
ip,
self.port,
self.auth_key.key
self.dcs[self.state.dc_id].port,
self.dcs[self.state.dc_id].auth
))

178
telethon/_sessions/types.py Normal file
View File

@ -0,0 +1,178 @@
from typing import Optional, Tuple
from dataclasses import dataclass
from enum import IntEnum
@dataclass(frozen=True)
class DataCenter:
"""
Stores the information needed to connect to a datacenter.
* id: 32-bit number representing the datacenter identifier as given by Telegram.
* ipv4 and ipv6: 32-bit or 128-bit number storing the IP address of the datacenter.
* port: 16-bit number storing the port number needed to connect to the datacenter.
* bytes: arbitrary binary payload needed to authenticate to the datacenter.
"""
__slots__ = ('id', 'ipv4', 'ipv6', 'port', 'auth')
id: int
ipv4: int
ipv6: Optional[int]
port: int
auth: bytes
@dataclass(frozen=True)
class SessionState:
"""
Stores the information needed to fetch updates and about the current user.
* user_id: 64-bit number representing the user identifier.
* dc_id: 32-bit number relating to the datacenter identifier where the user is.
* bot: is the logged-in user a bot?
* pts: 64-bit number holding the state needed to fetch updates.
* qts: alternative 64-bit number holding the state needed to fetch updates.
* date: 64-bit number holding the date needed to fetch updates.
* seq: 64-bit-number holding the sequence number needed to fetch updates.
* takeout_id: 64-bit-number holding the identifier of the current takeout session.
Note that some of the numbers will only use 32 out of the 64 available bits.
However, for future-proofing reasons, we recommend you pretend they are 64-bit long.
"""
__slots__ = ('user_id', 'dc_id', 'bot', 'pts', 'qts', 'date', 'seq', 'takeout_id')
user_id: int
dc_id: int
bot: bool
pts: int
qts: int
date: int
seq: int
takeout_id: Optional[int]
@dataclass(frozen=True)
class ChannelState:
"""
Stores the information needed to fetch updates from a channel.
* channel_id: 64-bit number representing the channel identifier.
* pts: 64-bit number holding the state needed to fetch updates.
"""
__slots__ = ('channel_id', 'pts')
channel_id: int
pts: int
class EntityType(IntEnum):
"""
You can rely on the type value to be equal to the ASCII character one of:
* 'U' (85): this entity belongs to a :tl:`User` who is not a ``bot``.
* 'B' (66): this entity belongs to a :tl:`User` who is a ``bot``.
* 'G' (71): this entity belongs to a small group :tl:`Chat`.
* 'C' (67): this entity belongs to a standard broadcast :tl:`Channel`.
* 'M' (77): this entity belongs to a megagroup :tl:`Channel`.
* 'E' (69): this entity belongs to an "enormous" "gigagroup" :tl:`Channel`.
"""
USER = ord('U')
BOT = ord('B')
GROUP = ord('G')
CHANNEL = ord('C')
MEGAGROUP = ord('M')
GIGAGROUP = ord('E')
def canonical(self):
"""
Return the canonical version of this type.
"""
return _canon_entity_types[self]
_canon_entity_types = {
EntityType.USER: EntityType.USER,
EntityType.BOT: EntityType.USER,
EntityType.GROUP: EntityType.GROUP,
EntityType.CHANNEL: EntityType.CHANNEL,
EntityType.MEGAGROUP: EntityType.CHANNEL,
EntityType.GIGAGROUP: EntityType.CHANNEL,
}
@dataclass(frozen=True)
class Entity:
"""
Stores the information needed to use a certain user, chat or channel with the API.
* ty: 8-bit number indicating the type of the entity (of type `EntityType`).
* id: 64-bit number uniquely identifying the entity among those of the same type.
* hash: 64-bit signed number needed to use this entity with the API.
The string representation of this class is considered to be stable, for as long as
Telegram doesn't need to add more fields to the entities. It can also be converted
to bytes with ``bytes(entity)``, for a more compact representation.
"""
__slots__ = ('ty', 'id', 'hash')
ty: EntityType
id: int
hash: int
@property
def is_user(self):
"""
``True`` if the entity is either a user or a bot.
"""
return self.ty in (EntityType.USER, EntityType.BOT)
@property
def is_group(self):
"""
``True`` if the entity is a small group chat or `megagroup`_.
.. _megagroup: https://telegram.org/blog/supergroups5k
"""
return self.ty in (EntityType.GROUP, EntityType.MEGAGROUP)
@property
def is_broadcast(self):
"""
``True`` if the entity is a broadcast channel or `broadcast group`_.
.. _broadcast group: https://telegram.org/blog/autodelete-inv2#groups-with-unlimited-members
"""
return self.ty in (EntityType.CHANNEL, EntityType.GIGAGROUP)
@classmethod
def from_str(cls, string: str):
"""
Convert the string into an `Entity`.
"""
try:
ty, id, hash = string.split('.')
ty, id, hash = ord(ty), int(id), int(hash)
except AttributeError:
raise TypeError(f'expected str, got {string!r}') from None
except (TypeError, ValueError):
raise ValueError(f'malformed entity str (must be T.id.hash), got {string!r}') from None
return cls(EntityType(ty), id, hash)
@classmethod
def from_bytes(cls, blob):
"""
Convert the bytes into an `Entity`.
"""
try:
ty, id, hash = struct.unpack('<Bqq', blob)
except struct.error:
raise ValueError(f'malformed entity data, got {string!r}') from None
return cls(EntityType(ty), id, hash)
def __str__(self):
return f'{chr(self.ty)}.{self.id}.{self.hash}'
def __bytes__(self):
return struct.pack('<Bqq', self.ty, self.id, self.hash)

2
telethon/_updates/__init__.py Normal file
View File

@ -0,0 +1,2 @@
from .entitycache import EntityCache
from .messagebox import MessageBox

Some files were not shown because too many files have changed in this diff Show More